<!-- Module User's Guide -->

<chapter>
	
	<title>&adminguide;</title>
	
	<section id="overview" xreflabel="Overview">
	<title>Overview</title>
	<para>
		This module is an implementation of a cache system designed to work with a 
		memcached server. It uses libmemcached client library to connect to several memcached
		servers that store data. It uses the Key-Value interface exported from the core.
	</para>
	<para>
	</para>
	</section>


	<section>
	<title>Advantages</title>
	<para>
		<itemizedlist>
			<listitem>
			<para>
				<emphasis>memory costs are no longer on the server
				</emphasis>
			</para>
			</listitem>

			<listitem>
			<para>
				<emphasis>many servers may be used so the memory
				is virtually unlimited</emphasis>
			</para>
			</listitem>

			<listitem>
			<para>
				<emphasis>the cache is persistent so a restart
				of the server will not affect the cache</emphasis>
			</para>
			</listitem>

			<listitem>
			<para>
				<emphasis>memcached is an open-source project so
				it can be used to exchange data
				 with various other applications</emphasis>
			</para>
			</listitem>

			<listitem>
			<para>
				<emphasis>servers may be grouped together
				(e.g. for security purposes : some can be
				 inside a private network, some can be in
				 a public one)</emphasis>
			</para>
			</listitem>

		</itemizedlist>
	</para>
	<para>
	</para>
	</section>

	<section>
	<title>Limitations</title>
	
		
		<para>
			<itemizedlist>
			<listitem>
			<para>
			<emphasis>
		keys (in key:value pairs) may not contain spaces or control characters
		</emphasis>
			</para>
			</listitem>

		</itemizedlist>
		</para>
	</section>

	<section id="dependencies" xreflabel="Dependencies">
	<title>Dependencies</title>
	<section>
		<title>&osips; Modules</title>
		<para>
		None.
		</para>
	</section>
	
	<section>
		<title>External Libraries or Applications</title>
		<para>
		The following libraries or applications must be installed before running
		&osips; with this module loaded:
		</para>
			<itemizedlist>
			<listitem>
			<para>
				<emphasis>libmemcached:</emphasis>
			</para>
			
			<para>
				libmemcached can be downloaded from: http://tangent.org/552/libmemcached.html.
				Download the archive, extract sources, run ./configure, make,sudo make install.
			</para>
			<para>
											
				<literallayout>
				...
				wget http://download.tangent.org/libmemcached-0.31.tar.gz 
				tar -xzvf libmemcached-0.31.tar.gz
				cd libmemcached-0.31
				./configure
				make
				sudo make install
				...</literallayout>
			</para>
			
			</listitem>
			</itemizedlist>
	</section>
	</section>
	
	<section id="exported_parameters" xreflabel="Exported Parameters">
		<title>Exported Parameters</title>
		<section id="param_cachedb_url" xreflabel="cachedb_url">
		<title><varname>cachedb_url</varname> (string)</title>
		<para>
			The urls of the server groups that OpenSIPS will connect to in order
			to use the from script cache_store,cache_fetch, etc operations.
			It can be set more than one time.
			The prefix part of the URL will be the identifier that will be used
			from the script.
		</para>
		
		<example>
		<title>Set <varname>cachedb_url</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("cachedb_memcached", "cachedb_url","memcached:group1://localhost:9999,127.0.0.1/");
modparam("cachedb_memcached", "cachedb_url","memcached:y://random_url:8888/");
...
	</programlisting>
		</example>
		
		<example>
		<title>Use memcached servers </title>
		<programlisting format="linespecific">
...
cache_store("memcached:group1","key","$ru value");
cache_fetch("memcached:y","key",$avp(10));
cache_remove("memcached:group1","key");
...
	</programlisting>
		</example>
	</section>
	
		<section id="param_exec_threshold" xreflabel="exec_threshold">
		<title><varname>exec_threshold</varname> (int)</title>
		<para>
			The maximum number of microseconds that a local cache query can last.
			Anything above the threshold will trigger a warning message to the log
		</para>
		<para>
		<emphasis>Default value is <quote>0 ( unlimited - no warnings )</quote>.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>exec_threshold</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("cachedb_memcached", "exec_threshold", 100000)
...
	</programlisting>
		</example>
	</section>

	<section id="exported_functions" xreflabel="exported_functions">
		<title>Exported Functions</title>
		<para>The module does not export functions to be used
		in configuration script.</para>
	</section>	


</section>

</chapter>

