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

<chapter>

	<title>&adminguide;</title>

	<section id="overview" xreflabel="Overview">
	<title>Overview</title>
	<para>
		This module provides an HTTP transport layer for &osips;.
	</para>
	<para>
		Implementation of httpd module's http server is based on
		libmicrohttpd library.
	</para>
	</section>

	<section id="tlssupport" xreflabel="tlssupport">
		<title>Overview</title>
		<para>
			TLS for the http server is enabled by setting  the <varname>tls_cert_file</varname>
			and <varname>tls_key_file</varname> parameters. If this is enabled, support for plain
			http is disabled.
		</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 id="dependencies_libs" xreflabel="Library Dependencies">
		<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>libmicrohttpd</emphasis>, with EPOLL support. This
					typically means a version newer than <emphasis role='bold'>0.9.50</emphasis>.
			</para>
			</listitem>
			</itemizedlist>
		</para>
		<para>
			<emphasis role='bold'>WARNING!</emphasis>  Please be aware about an
			EPOLL support regression in the <emphasis>libmicrohttpd</emphasis>
			library and packaging which affects the OpenSIPS httpd module, which
			was fixed according to the below timeline.  The effect of the
			regression is that the HTTP reply body is <emphasis>sometimes</emphasis>
			never written by the library, causing the client (e.g. opensips-cli)
			to hang indefinitely waiting for it:
		<itemizedlist>
		<listitem>
			<para>
			versions <emphasis role='bold'>0.9.51</emphasis> - <emphasis role='bold'>0.9.52</emphasis>
				have been tested and work correctly
			</para>
		</listitem>
		<listitem>
			<para>
				regression introduced in <emphasis role='bold'>0.9.53</emphasis> (Apr 2017),
				lasting until <emphasis role='bold'>0.9.71</emphasis> (May 2020)
			</para>
		</listitem>
		<listitem>
			<para>
				regression is fixed since <emphasis role='bold'>0.9.72</emphasis> (Dec 2020)
			</para>
		</listitem>
		</itemizedlist>


		</para>
	</section>
	</section>
	
	<section id="exported_parameters" xreflabel="Exported Parameters">
	<title>Exported Parameters</title>
	<section id="param_ip" xreflabel="ip">
		<title><varname>ip</varname>(string)</title>
		<para>
		The IP address used by the HTTP server to listen for incoming 
		requests.
		</para>
		<para>
		<emphasis>The default value is "*" </emphasis> (bind to all IPv6 and IPv4 interfaces).
		</para>
		<example>
		<title>Set <varname>ip</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("httpd", "ip", "127.0.0.1")
...
</programlisting>
		</example>
	</section>
	<section id="param_port" xreflabel="port">
		<title><varname>port</varname>(integer)</title>
		<para>
		The port number used by the HTTP server to listen for incoming 
		requests.
		</para>
		<para>
		<emphasis>The default value is 8888.</emphasis>
		Ports lower than 1024 are not accepted.
		</para>
		<example>
		<title>Set <varname>port</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("httpd", "port", 8000)
...
</programlisting>
		</example>
	</section>

	<section id="param_conn_timeout" xreflabel="conn_timeout">
		<title><varname>conn_timeout</varname>(integer)</title>
		<para>
		Auto-close TCP connections which are idle for more than the designated
		timeout, in seconds.  Set to zero to never close any connections.
		</para>
		<para>
		Note: the connection auto-close routine only seems to be executed
		in an "on-demand" fashion, during an HTTPD network event (e.g. on a new
		connection), which although not ideal, it should be good enough in
		practical terms.
		</para>
		<para>
		<emphasis>The default timeout is 30 seconds.</emphasis>
		</para>
		<example>
		<title>Set <varname>conn_timeout</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("httpd", "conn_timeout", 10)
...
</programlisting>
		</example>
	</section>

	<section id="param_buf_size" xreflabel="buf_size">
		<title><varname>buf_size</varname> (integer)</title>
		<para>
		It specifies the maximum length (in bytes) of the buffer
		used to write in the html response.
		</para>
		<para>
		If the size of the buffer is set to zero, it will be automatically
		set to a quarter of the size of the pkg memory.
		</para>
		<para>
		<emphasis> The default value is 0.</emphasis>
		</para>
		<example>
		<title>Set <varname>buf_size</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("httpd", "buf_size", 524288)
...
</programlisting>
		</example>
	</section>
	<section id="param_post_buf_size" xreflabel="post_buf_size">
		<title><varname>post_buf_size</varname> (integer)</title>
		<para>
		It specifies the length (in bytes) of the POST HTTP requests
		processing buffer.  For large POST request, the default value
		might require to be increased.
		</para>
		<para>
		<emphasis> The default value is 1024. The minumal value is 256.</emphasis>
		</para>
		<example>
		<title>Set <varname>post_buf_size</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("httpd", "post_buf_size", 4096)
...
</programlisting>
		</example>
	</section>
	<section id="param_tls_cert_file" xreflabel="tls_cert_file">
		<title><varname>tls_cert_file</varname> (string)</title>
		<para>
		Public certificate file for httpd. It will be used as server-side certificate for incoming TLS connections.
		</para>
		<para>
		<emphasis> The default value is ""</emphasis>
		</para>
		<example>
		<title>Set <varname>tls_cert_file</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("httpd", "tls_cert_file", "/etc/opensips/tls/server.pem")
...
</programlisting>
		</example>
	</section>
	<section id="param_tls_key_file" xreflabel="tls_key_file">
		<title><varname>tls_key_file</varname> (string)</title>
		<para>
		Private key of the above certificate. I must be kept in a safe place with tight permissions!
		</para>
		<para>
		<emphasis> The default value is ""</emphasis>
		</para>
		<example>
		<title>Set <varname>tls_key_file</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("httpd", "tls_key_file", "/etc/opensips/tls/server.key")
...
</programlisting>
		</example>
	</section>
	<section id="param_tls_ciphers" xreflabel="tls_ciphers">
		<title><varname>tls_ciphers</varname> (string)</title>
		<para>
		You can specify the list of algorithms for authentication and encryption that you allow.
		To obtain a list of ciphers
		and then choose, use the gnutls-cli application:
		</para>
		<itemizedlist>
			<listitem>
				<para>gnutls-cli -l</para>
			</listitem>
		</itemizedlist>
		<warning><para>
			Do not use the NULL algorithms (no encryption) ... never!!!
		</para></warning>

		<para>
		<emphasis> The default value is  "SECURE256:+SECURE192:-VERS-ALL:+VERS-TLS1.2"</emphasis>
		</para>
		<example>
		<title>Set <varname>tls_key_file</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("httpd", "tls_ciphers", "SECURE256:+SECURE192:-VERS-ALL:+VERS-TLS1.2")
...
</programlisting>
		</example>
	</section>
	</section>

	<section id="exported_mi_functions" xreflabel="Exported MI Functions">
	<title>Exported MI Functions</title>
		<section id="mi_httpd_list_root_path" xreflabel="httpd_list_root_path">
		<title><function moreinfo="none">httpd_list_root_path</function></title>
		<para>
		Lists all the registered http root paths into the httpd module.
		When a request comes in, if the root parth is in the list,
		the request will be sent to the module that register it.
		</para>
		<para>
		Name: <emphasis>httpd_list_root_path</emphasis>
		</para>
		<para>Parameters: none</para>
		<para>
		MI FIFO Command Format:
		</para>
		<programlisting  format="linespecific">
opensips-cli -x mi httpd_list_root_path
		</programlisting>
	</section>
	</section>

	<section id="exported_functions" xreflabel="exported_functions">
	<title>Exported Functions</title>
		<para>
		No function exported to be used from configuration file.
		</para>
	</section>

	<section>
	<title>Known issues</title>
		<para>
		Due to the fact that &osips; is a multiprocess application,
		the microhttpd library is used in "external select" mode.
		This ensures that the library is not running in
		multithread mode and the library is entirely controled
		by &osips;.  Due to this particular mode of operations,
		for now, the entire http response is built in a pre-allocated
		buffer (see buf_size parameter).
		</para>
		<para>
		Future realeases of this module will address this issue.
		</para>
		<para>
		Running the http daemon as non root on ports below 1024 is
		forbidden by default in linux (kernel>=2.6.24).
		To allow the port binding, one can use
		<emphasis>setcap</emphasis> to give
		extra privilleges to opensips binary:
		<programlisting  format="linespecific">
setcap 'cap_net_bind_service=+ep' /usr/local/sbin/opensips
		</programlisting>
		</para>
	</section>

</chapter>

