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

<chapter>
	

	<title>&adminguide;</title>
	
	<section id="overview" xreflabel="Overview">
	  <title>Overview</title>
	    <para> 
		The module enable &osips; to register itself on a remote SIP registrar.
	    </para>
	    <para>
		At startup, the registrant records are loaded into
		a hash table in memory and a timer is started.
		The hash index is computed over the AOR field.
		</para>
		<para>
		The timer interval for checking records in a hash bucket is computed
		by dividing the timer_interval module param by the number of hash buckets.
		When the timer fires for the first time, the first hash bucket will be checked and
		REGISTERs will be sent out for each record that is found.
		On the next timeout fire, the second hash bucket will be checked and so on.
		If the configured timer_interval module param is lower then the number of buckets,
		the module will fail to start.
	    </para>
	    <para>
	    Example: setting the timer_interval module to 8 with a hash_size of 2, will result
	    in having 4 hash buckets (2^2=4) and buckets will be checked one by one every 2s (8/4=2).
	    </para>
	    <para>
	    Each registrant has it's own state.
	    Registrant's status can be inspected via "reg_list" MI comand.
	    </para>
	    <para>
		UAC registrant states:
		<itemizedlist>
			<listitem>
			<para><emphasis>0</emphasis>
				- NOT_REGISTERED_STATE -
				the initial state (no REGISTER has been sent out yet);</para>
			</listitem>
			<listitem>
			<para><emphasis>1</emphasis>
				- REGISTERING_STATE - waiting for a reply from the registrar
				after a REGISTER without authentication header was sent;</para>
			</listitem>
			<listitem>
			<para><emphasis>2</emphasis>
				- AUTHENTICATING_STATE - waiting for a reply from the registrar
			 	after a REGISTER with authentication header was sent;</para>
			</listitem>
			<listitem>
			<para><emphasis>3</emphasis>
				- REGISTERED_STATE - the uac is successfully registered;</para>
			</listitem>
			<listitem>
			<para><emphasis>4</emphasis>
				- REGISTER_TIMEOUT_STATE :
				no reply received from the registrar;</para>
			</listitem>
			<listitem>
			<para><emphasis>5</emphasis>
				- INTERNAL_ERROR_STATE -
				some errors were found/encountered during the
				processing of a reply;</para>
			</listitem>
			<listitem>
			<para><emphasis>6</emphasis>
				- WRONG_CREDENTIALS_STATE -
				credentials rejected by the registrar;</para>
			</listitem>
			<listitem>
			<para><emphasis>7</emphasis>
				- REGISTRAR_ERROR_STATE -
				error reply received from the registrar;</para>
			</listitem>
			<listitem>
			<para><emphasis>8</emphasis>
				- UNREGISTERING_STATE - waiting for a reply from the registrar
				after an unREGISTER without authentication header was sent;</para>
			</listitem>
			<listitem>
			<para><emphasis>9</emphasis>
				- AUTHENTICATING_UNREGISTER_STATE - waiting for a reply from the registrar
				after an unREGISTER with authentication header was sent;</para>
			</listitem>
		</itemizedlist>
	    </para>
	</section>

	<section id="dependencies" xreflabel="Dependencies">
	  <title>Dependencies</title>
	  <section>
	  <title>&osips; Modules</title>
		<para>
		The following modules must be loaded before this module:
		<itemizedlist>
		<listitem>
		<para>
			<emphasis>uac_auth - UAC authentication module</emphasis>
		</para>
		</listitem>
		</itemizedlist>
		</para>
	  </section>

	  <section>
		<title>External Libraries or Applications</title>
		<para>None.</para>
	  </section>
	</section>
	
	<section id="exported_parameters" xreflabel="Exported Parameters">
	<title>Exported Parameters</title>
        <section id="param_hash_size" xreflabel="hash_size">
		<title><varname>hash_size</varname> (integer)</title>
		<para>
		The size of the hash table internally used to keep the registrants.
		A larger table distributes better the registration load in time but consumes more memory.
		The hash size is a power of number two. 
		</para>
		<para>
		<emphasis>
			Default value is 1.
		</emphasis>
                </para>
		<example>
		<title>Set <varname>hash_size</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("uac_registrant", "hash_size", 2)
...
</programlisting>
		</example>
	</section>

	<section id="param_timer_interval" xreflabel="timer_interval">
		<title><varname>timer_interval</varname> (integer)</title>
		<para>
		Defines the periodic timer for checking the registrations status.
		</para>
		<para>
		<emphasis>
			Default value is 100.
		</emphasis>
                </para>
		<example>
		<title>Set <varname>timer_interval</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("uac_registrant", "timer_interval", 120)
...
</programlisting>
		</example>
	</section>

	<section id="param_failure_retry_interval" xreflabel="failure_retry_interval">
		<title><varname>failure_retry_interval</varname> (integer)</title>
		<para>
		Defines a custom interval to retry the registration upon error/failure.
		Normally, after any kind of failure (timeout, credentials, internal 
		error), the registration is re-taken after "expires" seconds. The 
		parameter here, if set, overrides that value.
		</para>
		<para>
		<emphasis>
			Default value is 0 (not set).
		</emphasis>
                </para>
		<example>
		<title>Set <varname>failure_retry_interval</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("uac_registrant", "failure_retry_interval", 3600)
...
</programlisting>
		</example>
	</section>

	<section id="param_enable_clustering" xreflabel="enable_clustering">
		<title><varname>enable_clustering</varname> (integer)</title>
		<para>
		This parameter enables the clustering support in the module. This is
		used to share this registration between all the nodes in the cluster.
		When using this option, you should define (for each registrant record)
		a sharing tag - this sharing tag will control at the cluster level
		which node is entitled to perform the registation (only the node having
		that tag as active will do the registation, the onther nodes being
		idle).
		</para>
		<para>
		<emphasis>
			Default value is 0 / off.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>enable_clustering</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("uac_registrant", "enable_clustering", 1)
...
</programlisting>
		</example>
	</section>

	<section id="param_db_url" xreflabel="db_url">
		<title><varname>db_url</varname> (string)</title>
		<para>
		Database where to load the registrants from.
		</para>
		<para>
		<emphasis>
			Default value is <quote>NULL</quote> (use default DB URL from core).
		</emphasis>
		</para>
		<example>
		<title>Set <quote>db_url</quote> parameter</title>
		<programlisting format="linespecific">
...
modparam("uac_registrant", "db_url", "mysql://user:passw@localhost/database")
...
</programlisting>
		</example>
	</section>

	<section id="param_table_name" xreflabel="table_name">
		<title><varname>table_name</varname> (string)</title>
		<para>
		The database table that holds the registrant records.
		</para>
		<para>
		<emphasis>
			Default value is <quote>registrant</quote>.
		</emphasis>
		</para>
		<example>
		<title>Set <quote>table_name</quote> parameter</title>
		<programlisting format="linespecific">
...
modparam("uac_registrant", "table_name", "my_registrant")
...
</programlisting>
		</example>
	</section>
	<section id="param_registrar_column" xreflabel="registrar_column">
		<title><varname>registrar_column</varname> (string)</title>
		<para>
		The column's name in the database storing the
		URI pointing to the remote registrar (mandatory field).
		&osips; expects a valid URI.
		</para>
		<para>
		<emphasis>
			Default value is <quote>registrar</quote>.
		</emphasis>
		</para>
		<example>
		<title>Set <quote>registrar_column</quote> parameter</title>
		<programlisting format="linespecific">
...
modparam("uac_registrant", "registrar_column", "registrant_uri")
...
</programlisting>
		</example>
	</section>
	<section id="param_proxy_column" xreflabel="proxy_column">
		<title><varname>proxy_column</varname> (string)</title>
		<para>
		The column's name in the database storing the
		URI pointing to the outbond proxy (not mandatory field).
		An empty or NULL value means no outbound proxy,
		otherwise &osips; expects a valid URI.
		</para>
		<para>
		<emphasis>
			Default value is <quote>proxy</quote>.
		</emphasis>
		</para>
		<example>
		<title>Set <quote>proxy_column</quote> parameter</title>
		<programlisting format="linespecific">
...
modparam("uac_registrant", "proxy_column", "proxy_uri")
...
</programlisting>
		</example>
	</section>
	<section id="param_aor_column" xreflabel="aor_column">
		<title><varname>aor_column</varname> (string)</title>
		<para>
		The column's name in the database storing the
		URI defining the address of record (mandatory field).
		The URI stored here will be used in the To URI of the REGISTER.
		&osips; expects a valid URI.
		</para>
		<para>
		<emphasis>
			Default value is <quote>aor</quote>.
		</emphasis>
		</para>
		<example>
		<title>Set <quote>aor_column</quote> parameter</title>
		<programlisting format="linespecific">
...
modparam("uac_registrant", "aor_column", "to_uri")
...
</programlisting>
		</example>
	</section>
	<section id="param_third_party_registrant_column" xreflabel="third_party_registrant_column">
		<title><varname>third_party_registrant_column</varname> (string)</title>
		<para>
		The column's name in the database storing the
		URI defining the third party registrant (not mandatory field).
		The URI stored here will be used in the From URI of the REGISTER.
		An empty or NULL value means no third party registration
		(the From URI will be identical to To URI),
		otherwise &osips; expects a valid URI.
		</para>
		<para>
		<emphasis>
			Default value is <quote>third_party_registrant</quote>.
		</emphasis>
		</para>
		<example>
		<title>Set <quote>third_party_registrant_column</quote> parameter</title>
		<programlisting format="linespecific">
...
modparam("uac_registrant", "third_party_registrant_column", "from_uri")
...
</programlisting>
		</example>
	</section>
	<section id="param_username_column" xreflabel="username_column">
		<title><varname>username_column</varname> (string)</title>
		<para>
		The column's name in the database storing the
		username for authentication (mandatory if the registrar requires authentication).
		</para>
		<para>
		<emphasis>
			Default value is <quote>username</quote>.
		</emphasis>
		</para>
		<example>
		<title>Set <quote>username_column</quote> parameter</title>
		<programlisting format="linespecific">
...
modparam("uac_registrant", "username_column", "auth_username")
...
</programlisting>
		</example>
	</section>
	<section id="param_password_column" xreflabel="password_column">
		<title><varname>password_column</varname> (string)</title>
		<para>
		The column's name in the database storing the
		password for authentication (mandatory if the registrar requires authntication).
		</para>
		<para>
		<emphasis>
			Default value is <quote>password</quote>.
		</emphasis>
		</para>
		<example>
		<title>Set <quote>password_column</quote> parameter</title>
		<programlisting format="linespecific">
...
modparam("uac_registrant", "password_column", "auth_passowrd")
...
</programlisting>
		</example>
	</section>
	<section id="param_binding_URI_column" xreflabel="binding_URI_column">
		<title><varname>binding_URI_column</varname> (string)</title>
		<para>
		The column's name in the database storing the
		binding URI in REGISTER (mandatory field).
		The URI stored here will be used in the Contact URI of the REGISTER.
		&osips; expects a valid URI.
		</para>
		<para>
		<emphasis>
			Default value is <quote>binding_URI</quote>.
		</emphasis>
		</para>
		<example>
		<title>Set <quote>binding_URI_column</quote> parameter</title>
		<programlisting format="linespecific">
...
modparam("uac_registrant", "binding_URI_column", "contact_uri")
...
</programlisting>
		</example>
	</section>
	<section id="param_binding_params_column" xreflabel="binding_params_column">
		<title><varname>binding_params_column</varname> (string)</title>
		<para>
		The column's name in the database storing the
		binding params in REGISTER (not mandatory field).
		If not NULL or not empty, the string stored here will be added
		as params to the Contact URI in REGISTER (it MUST start with <quote>;</quote>.
		</para>
		<para>
		If the following two params are present, then the binding will be enforced
		to be unique (if two bindings are received in a 200ok, a complete binding
		removal will be performed before re-registering):
		<itemizedlist>
		<listitem><para><emphasis>reg-id</emphasis></para></listitem>
		<listitem><para><emphasis>+sip.instance</emphasis></para></listitem>
		</itemizedlist>
		Example of params that will force unique binding:
		<programlisting format="linespecific">
;reg-id=1;+sip.instance=&quot;&lt;urn:uuid:11111111-AABBCCDDEEFF&gt;&quot;
		</programlisting>
		</para>
		<para>
		<emphasis>
			Default value is <quote>binding_params</quote>.
		</emphasis>
		</para>
		<example>
		<title>Set <quote>binding_params_column</quote> parameter</title>
		<programlisting format="linespecific">
...
modparam("uac_registrant", "binding_params_column", "contact_params")
...
</programlisting>
		</example>
	</section>

	<section id="param_expiry_column" xreflabel="expiry_column">
		<title><varname>expiry_column</varname> (string)</title>
		<para>
		The column's name in the database storing the
		expiration time (not mandatory).
		</para>
		<para>
		<emphasis>
			Default value is <quote>expiry</quote>.
		</emphasis>
		</para>
		<example>
		<title>Set <quote>expiry_column</quote> parameter</title>
		<programlisting format="linespecific">
...
modparam("uac_registrant", "expiry_column", "registration_timeout")
...
</programlisting>
		</example>
	</section>

	<section id="param_forced_socket_column" xreflabel="forced_socket_column">
		<title><varname>forced_socket_column</varname> (string)</title>
		<para>
		The column's name in the database storing the
		socket for sending the REGISTER (not mandatory).
		If a forced socket is provided, the socket MUST be
		explicitely set as a global listening socket in the config
		(see <quote>listen</quote> core parameter).
		</para>
		<para>
		<emphasis>
			Default value is <quote>forced_socket</quote>.
		</emphasis>
		</para>
		<example>
		<title>Set <quote>forced_socket_column</quote> parameter</title>
		<programlisting format="linespecific">
...
modparam("uac_registrant", "forced_socket_column", "fs")
...
</programlisting>
		</example>
	</section>

	<section id="param_cluster_shtag_column" xreflabel="cluster_shtag_column">
		<title><varname>cluster_shtag_column</varname> (string)</title>
		<para>
		The column's name in the database storing the
		cluster sharing tag in [tag_name/cluster_id] format (not mandatory).
		If a cluster sharing tag is provided, the REGISTER requests will
		be fired out only when the tag is active.
		</para>
		<para>
		<emphasis>
			Default value is <quote>cluster_shtag</quote>.
		</emphasis>
		</para>
		<example>
		<title>Set <quote>cluster_shtag_column</quote> parameter</title>
		<programlisting format="linespecific">
...
modparam("uac_registrant", "cluster_shtag_column", "sh")
...
</programlisting>
		</example>
	</section>

	<section id="param_state_column" xreflabel="state_column">
		<title><varname>state_column</varname> (string)</title>
		<para>
		The column's name in the database storing the current state of the
		registrant. When a registrant is disabled, OpenSIPS will no longer send
		REGISTERs for it. A value of <emphasis>0</emphasis> for this column means
		enabled and <emphasis>1</emphasis> disabled.
		</para>
		<para>
		<emphasis>
			Default value is <quote>state</quote>.
		</emphasis>
		</para>
		<example>
		<title>Set <quote>state_column</quote> parameter</title>
		<programlisting format="linespecific">
...
modparam("uac_registrant", "state_column", "status")
...
</programlisting>
		</example>
	</section>

	</section>

	<section id="exported_functions" xreflabel="exported_functions">
	<title>Exported Functions</title>
	      <para>None to be used in configuration file.</para>
	</section>

	<section id="exported_mi_functions" xreflabel="Exported MI Functions">
	<title>Exported MI Functions</title>
	<section id="mi_reg_list" xreflabel="reg_list">
	<title><function moreinfo="none">reg_list</function></title>
		<para>Lists the registrant records and their status.</para>
		<para>Name: <emphasis>reg_list</emphasis></para>
		<para>Parameters: </para>
		<itemizedlist>
			<listitem><para>
				<emphasis>aor</emphasis> (optional) - URI defining the address
				of record. If provided, <emphasis>contact</emphasis> and
				<emphasis>registrar</emphasis> parameters are also required and
				only a specific record will be listed.
			</para></listitem>
			<listitem><para>
				<emphasis>contact</emphasis> (optional) - Contact URI. If 
				provided,
				<emphasis>aor</emphasis> and <emphasis>registrar</emphasis>
				parameters are also required and only a specific record will
				be listed.
			</para></listitem>
			<listitem><para>
				<emphasis>registrar</emphasis> (optional) - URI pointing to the
				remote registrar. If provided, <emphasis>aor</emphasis> and
				<emphasis>contact</emphasis> parameters are also required and
				only a specific record will be listed.
			</para></listitem>
		</itemizedlist>
		<para>MI FIFO Command Format:</para>
		<programlisting  format="linespecific">
opensips-cli -x mi reg_list
...
opensips-cli -x mi reg_list sip:alice@opensips.org  sip:alice@127.0.0.1:5060 sip:opensips.org
		</programlisting>
	</section>
	<section id="mi_reg_reload" xreflabel="reg_reload">
	<title><function moreinfo="none">reg_reload</function></title>
		<para>Reloads the registrant records from the database.</para>
		<para>Name: <emphasis>reg_reload</emphasis></para>
		<para>Parameters: <emphasis>none</emphasis></para>
		<itemizedlist>
			<listitem><para>
				<emphasis>aor</emphasis> (optional) - URI defining the address
				of record. If provided, <emphasis>contact</emphasis> and
				<emphasis>registrar</emphasis> parameters are also required and
				only a specific record will be reloaded.
			</para></listitem>
			<listitem><para>
				<emphasis>contact</emphasis> (optional) - Contact URI. If 
				provided,
				<emphasis>aor</emphasis> and <emphasis>registrar</emphasis>
				parameters are also required and only a specific record will
				be reloaded.
			</para></listitem>
			<listitem><para>
				<emphasis>registrar</emphasis> (optional) - URI pointing to the
				remote registrar. If provided, <emphasis>aor</emphasis> and
				<emphasis>contact</emphasis> parameters are also required and
				only a specific record will be reloaded.
			</para></listitem>
		</itemizedlist>
		<para>MI FIFO Command Format:</para>
		<programlisting  format="linespecific">
opensips-cli -x mi reg_reload
...
opensips-cli -x mi reg_leload sip:alice@opensips.org  sip:alice@127.0.0.1:5060 sip:opensips.org
		</programlisting>
	</section>

	<section id="mi_reg_enable" xreflabel="reg_enable">
	<title><function moreinfo="none">reg_enable</function></title>
		<para>Enables a specific registrant. OpenSIPS will immediately send
		a REGISTER if the registrant was previously disabled and will update
		the state in the database.</para>
		<para>Name: <emphasis>reg_enable</emphasis></para>
		<para>Parameters: <emphasis>none</emphasis></para>
		<itemizedlist>
			<listitem><para>
				<emphasis>aor</emphasis> - URI defining the address of record.
			</para></listitem>
			<listitem><para>
				<emphasis>contact</emphasis> - Contact URI.
			</para></listitem>
			<listitem><para>
				<emphasis>registrar</emphasis> - URI pointing to the remote registrar.
			</para></listitem>
		</itemizedlist>
		<para>MI FIFO Command Format:</para>
		<programlisting  format="linespecific">
opensips-cli -x mi reg_enable sip:alice@opensips.org  sip:alice@127.0.0.1:5060 sip:opensips.org
		</programlisting>
	</section>

	<section id="mi_reg_disable" xreflabel="reg_disable">
	<title><function moreinfo="none">reg_disable</function></title>
		<para>Disables a specific registrant. OpenSIPS will immediately send
		an unREGISTER if the registrant was previously enabled and will update
		the state in the database.</para>
		<para>Name: <emphasis>reg_disable</emphasis></para>
		<para>Parameters: <emphasis>none</emphasis></para>
		<itemizedlist>
			<listitem><para>
				<emphasis>aor</emphasis> - URI defining the address
				of record. If provided, <emphasis>contact</emphasis> and
				<emphasis>registrar</emphasis> parameters are also required and
				only a specific record will be disabled.
			</para></listitem>
			<listitem><para>
				<emphasis>contact</emphasis> - Contact URI. If provided,
				<emphasis>aor</emphasis> and <emphasis>registrar</emphasis>
				parameters are also required and only a specific record will
				be disabled.
			</para></listitem>
			<listitem><para>
				<emphasis>registrar</emphasis> - URI pointing to the remote
				registrar. If provided, <emphasis>aor</emphasis> and
				<emphasis>contact</emphasis> parameters are also required and
				only a specific record will be disabled.
			</para></listitem>
		</itemizedlist>
		<para>MI FIFO Command Format:</para>
		<programlisting  format="linespecific">
opensips-cli -x mi reg_disable sip:alice@opensips.org  sip:alice@127.0.0.1:5060 sip:opensips.org
		</programlisting>
	</section>

	<section id="mi_reg_force_register" xreflabel="reg_force_register">
	<title><function moreinfo="none">reg_force_register</function></title>
		<para>Forces the re-registration (or registation) of a specific 
		registrant (depending on its state). Note that the registrant must be
		enabled.</para>
		<para>Name: <emphasis>reg_force_register</emphasis></para>
		<para>Parameters:</para>
		<itemizedlist>
			<listitem><para>
				<emphasis>aor</emphasis> - URI defining the address
				of record. If provided, <emphasis>contact</emphasis> and
				<emphasis>registrar</emphasis> parameters are also required and
				only a specific record will be forced to re-register.
			</para></listitem>
			<listitem><para>
				<emphasis>contact</emphasis> - Contact URI. If provided,
				<emphasis>aor</emphasis> and <emphasis>registrar</emphasis>
				parameters are also required and only a specific record will be
				forced to re-register.
			</para></listitem>
			<listitem><para>
				<emphasis>registrar</emphasis> - URI pointing to the remote
				registrar. If provided, <emphasis>aor</emphasis> and
				<emphasis>contact</emphasis> parameters are also required and
				only a specific record will be forced to re-register.
			</para></listitem>
		</itemizedlist>
		<para>MI FIFO Command Format:</para>
		<programlisting  format="linespecific">
opensips-cli -x mi reg_force_register sip:alice@opensips.org  sip:alice@127.0.0.1:5060 sip:opensips.org
		</programlisting>
	</section>

	</section>
</chapter>

