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

<chapter>
	
	<title>&adminguide;</title>
	
	<section id="overview" xreflabel="Overview">
	<title>Overview</title>
	<para>Module description</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>No dependencies on other &osips; modules</emphasis>.
			</para>
			</listitem>
			</itemizedlist>
		</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:
			<itemizedlist>
			<listitem>
			<para>
				<emphasis>PostgreSQL library</emphasis> - e.g., libpq5.
			</para>
			</listitem>
			<listitem>
			<para>
				<emphasis>PostgreSQL devel library</emphasis> - to compile
				the module (e.g., libpq-dev).
			</para>
			</listitem>
			</itemizedlist>
		</para>
	</section>
	</section>

	<section id="exported_parameters" xreflabel="Exported Parameters">
	<title>Exported Parameters</title>
	<section id="param_exec_query_threshold" xreflabel="exec_query_threshold">
		<title><varname>exec_query_threshold</varname> (integer)</title>
		<para>
		If queries take longer than 'exec_query_threshold' microseconds, warning
		messages will be written to logging facility.
		</para>
		<para>
		<emphasis>
			Default value is 0 - disabled.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>exec_query_threshold</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("db_postgres", "exec_query_threshold", 60000)
...
</programlisting>
		</example>
	</section>
        <section id="param_max_db_queries" xreflabel="max_db_queries">
		<title><varname>max_db_queries</varname> (integer)</title>
		<para>
		The maximum number of database queries to be executed. 
                If this parameter is set improperly, it is set to default value. 
		</para>
		<para>
		<emphasis>
			Default value is 2.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>max_db_queries</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("db_postgres", "max_db_queries", 2)
...
</programlisting>
		</example>
	</section>
        <section id="param_timeout" xreflabel="timeout">
		<title><varname>timeout</varname> (integer)</title>
		<para>
			The number of seconds the PostgreSQL library waits to connect and query
			the server. If the connection does not succeed within the given timeout,
			the connection fails.
		</para>
		<para>
			<emphasis>Note:</emphasis>If the timeout is a negative value and
			connection does not succeed, &osips; will block until the connection
			becomes back available and gets successfully established. This is the
			default behavior of the library and is the behavior prior to the
			adition of this parameter.
		</para>
		<para>
		<emphasis>
			Default value is 5.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>timeout</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("db_postgres", "timeout", 2)
...
</programlisting>
		</example>
	</section>

        <section id="param_use_tls" xreflabel="use_tls">
		<title><varname>use_tls</varname> (integer)</title>
		<para>
		Parameter to control the way the SSL support is used when connecting
		to the Postgres server, as follows:
		</para>
		<itemizedlist>
			<listitem>
			<para>
				<emphasis>use_tls=0</emphasis> (default) - the SSL support
				is disabled and there is no attempt to use it;
			</para>
			</listitem>
			<listitem>
			<para>
				<emphasis>use_tls=1</emphasis> with "tls_domain" present
				in the DB URL - the SSL support is enabled, either 
				"require", either "verify-ca", depending on the certificate
				settings;
			</para>
			</listitem>
			<listitem>
			<para>
				<emphasis>use_tls=1</emphasis> with no "tls_domain" present
				in the DB URL - the SSL support is enabled in best effort mode
				(or "prefer"); if supported by the server, it will be used,
				otherwise it will fall back to non-SSL.
			</para>
			</listitem>
		</itemizedlist>
		<para>
		Warning: the <emphasis>tls_openssl</emphasis> module cannot be used
		when setting this parameter. Use the <emphasis>tls_wolfssl</emphasis>
		module instead if a TLS/SSL Library is required.
		</para>
		<para>
		Setting this parameter will allow you to use TLS for PostgreSQL connections.
		In order to enable TLS for a specific connection, you can use the
		"tls_domain=<emphasis>dom_name</emphasis>" URL parameter in the db_url of
		the respective OpenSIPS module. This should be placed at the end of the
		URL after the '?' character.
		</para>
		<para>
		When using this parameter, you must also ensure that
		<emphasis>tls_mgm</emphasis> is loaded and properly configured. Refer to
		the the module for additional info regarding TLS client domains.
		</para>
		<para>
		Note that if you want to use this feature, the TLS domain must be
		provisioned in the configuration file, <emphasis>NOT</emphasis> in
		the database. In case you are loading TLS certificates from the
		database, you must at least define one domain in the
		configuration script, to use for the initial connection to the DB.
		</para>
		<para>
		Also, you can <emphasis>NOT</emphasis> enable TLS for the connection
		to the database of the <emphasis>tls_mgm</emphasis> module itself.
		</para>
		<para>
		<emphasis>
			Default value is <emphasis role='bold'>0</emphasis> (not enabled)
		</emphasis>
		</para>
		<example>
		<title>Set the <varname>use_tls</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("tls_mgm", "client_domain", "dom1")
modparam("tls_mgm", "certificate", "[dom1]/etc/pki/tls/certs/opensips.pem")
modparam("tls_mgm", "private_key", "[dom1]/etc/pki/tls/private/opensips.key")
modparam("tls_mgm", "ca_list",     "[dom1]/etc/pki/tls/certs/ca.pem")
...
modparam("db_postgres", "use_tls", 1)
...
modparam("usrloc", "db_url", "postgres://root:1234@localhost/opensips?tls_domain=dom1")
...
</programlisting>
		</example>
	</section>
	</section>
	<section id="exported_functions" xreflabel="exported_functions">
	<title>Exported Functions</title>
		<para>
		NONE
		</para>
	</section>
	<section>
	<title>Installation and Running</title>
	<para>Notes about installation and running.</para>
	</section>
</chapter>

