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

<chapter>
	
	<title>&adminguide;</title>
	
	<section id="overview" xreflabel="Overview">
	<title>Overview</title>
	<para>
		<emphasis>RabbitMQ</emphasis>
		(<ulink url='http://www.rabbitmq.com/'>http://www.rabbitmq.com/</ulink>) 
		is an open source messaging server. It's purpose is to
		manage received messages in queues, taking advantage of
		the flexible AMQP protocol.
	</para>

	<para>
		This module provides the implementation of a RabbitMQ client for the
		Event Interface. It is used to send AMQP messages to a RabbitMQ server
		each time the Event Interface triggers an event subscribed for.
	</para>

	<para>
		The AMQP protocol is only used as the transport layer for notifications.
		The content of a message is presented in the next section.
	</para>
	</section>

	<section>
	<title>RabbitMQ events syntax</title>
	<para>
		The event payload is formated as a JSON-RPC notification, with the event
		name as the <emphasis>method</emphasis> field and the event parameters as
		the <emphasis>params</emphasis> field.
	</para>
	</section>
	
	<section id="socket_syntax" xreflabel="RabbitMQ socket syntax">
	<title>RabbitMQ socket syntax</title>
	<para>
		<para><emphasis>'rabbitmq:' [user[':'password] '@' host [':' port] '/' [params '?'] routing_key</emphasis></para>
	</para>
	<para>
		Meanings:
		<itemizedlist>
			<listitem><para>
					<emphasis>'rabbitmq:'</emphasis> - informs the Event Interface that the
					events sent to this subscriber should be handled by the
					<emphasis>event_rabbitmq</emphasis> module.
			</para>	</listitem>
			<listitem><para>
					<emphasis>user</emphasis> - username used for RabbitMQ server
					authentication. The default value is 'guest'.
			</para>	</listitem>
			<listitem><para>
					<emphasis>password</emphasis> - password used for RabbitMQ server
					authentication. The default value is 'guest'.
			</para>	</listitem>
			<listitem><para>
					<emphasis>host</emphasis> - host name of the RabbitMQ server.
			</para>	</listitem>
			<listitem><para>
					<emphasis>port</emphasis> - port of the RabbitMQ server. The
					default value is '5672'.
			</para>	</listitem>
			<listitem><para>
					<emphasis>params</emphasis> - extra parameters specified as
					<emphasis>key[=value]</emphasis>, separated by ';':
					<itemizedlist>
						<listitem><para>
						<emphasis>exchange</emphasis> - exchange of the RabbitMQ server.
						The default value is ''.
						</para></listitem>
						<listitem><para>
						<emphasis>tls_domain</emphasis> - indicates which TLS domain (as
						defined using the <emphasis>tls_mgm</emphasis> module) to use for
						this connection. The <xref linkend="param_use_tls"/> module parameter
						must be enabled.
						</para></listitem>
						<listitem><para>
						<emphasis>persistent</emphasis> - indicates that the message should be
						published as persistent <emphasis>delivery_mode=2</emphasis>. This
						parameter does not have a value.
						</para></listitem>
					</itemizedlist>
			</para></listitem>
			<listitem><para>
					<emphasis>routing_key</emphasis> - this is the routing key
					used by the AMQP protocol and it is used to identify the queue
					where the event should be sent.
					<para>NOTE: if the queue does not exist, this module will not 
						try to create it.</para>
			</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>tls_mgm</emphasis> if <xref linkend="param_use_tls"/> is enabled.
		</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>librabbitmq-dev</emphasis>
			</para>
			</listitem>
			</itemizedlist>
		</para>
	</section>
	</section>

	<section id="exported_parameters" xreflabel="Exported Parameters">
	<title>Exported Parameters</title>
	<section id="param_heartbeat" xreflabel="heartbeat">
		<title><varname>heartbeat</varname> (integer)</title>
		<para>
			Enables heartbeat support for the AMQP communication. If the
			client does not receive a heartbeat from server within the
			specified interval, the socket is automatically closed by the
			rabbitmq-client. This prevents OpenSIPS from blocking while
			waiting for a response from a dead rabbitmq-server. The value
			represents the heartbit interval in seconds.
		</para>
		<para>
		<emphasis>
			Default value is <quote>0 (disabled)</quote>.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>heartbeat</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("event_rabbitmq", "heartbeat", 3)
...
</programlisting>
		</example>
	</section>
		<section id="param_connect_timeout" xreflabel="connect_timeout">
			<title><varname>connect_timeout</varname> (integer)</title>
			<para>
			The maximally allowed duration (in milliseconds) for the establishment
			of a TCP connection with a RabbitMQ server.
			</para>
			<para>
			<emphasis>
				Default value is <quote>500</quote> (milliseconds).
			</emphasis>
			</para>
			<example>
			<title>Setting the <varname>connect_timeout</varname> parameter</title>
			<programlisting format="linespecific">
...
modparam("event_rabbitmq", "connect_timeout", 1000)
...
	</programlisting>
			</example>
		</section>

		<section id="param_use_tls" xreflabel="use_tls">
		<title><varname>use_tls</varname> (integer)</title>
		<para>
		Setting this parameter will allow you to use TLS for broker connections.
		In order to enable TLS for a specific connection, you can use the
		"tls_domain=<emphasis>dom_name</emphasis>" parameter in the configuration
		specified through the <xref linkend="socket_syntax"/>.
		</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>
		<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", "rmq")
modparam("tls_mgm", "certificate", "[rmq]/etc/pki/tls/certs/rmq.pem")
modparam("tls_mgm", "private_key", "[rmq]/etc/pki/tls/private/rmq.key")
modparam("tls_mgm", "ca_list",     "[rmq]/etc/pki/tls/certs/ca.pem")
...
modparam("event_rabbitmq", "use_tls", 1)
...
</programlisting>
		</example>
	</section>

	<section id="param_timeout" xreflabel="timeout">
		<title><varname>timeout</varname> (integer)</title>
		<para>
		Indicates the timeout (in milliseconds) of any command (i.e. publish)
		sent to the RabbitMQ server.
		</para>
		<para>
		<emphasis>NOTE</emphasis> that this parameter is available only starting with
		RabbitMQ library version <emphasis>0.9.0</emphasis>; setting it when using an
		earlier version will have no effect, and the publish command will run in
		blocking mode.
		</para>
		<para>
		<emphasis>
			Default value is <emphasis role='bold'>0</emphasis> (no timeout - blocking mode)
		</emphasis>
		</para>
		<example>
		<title>Set the <varname>timeout</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("event_rabbitmq", "timeout", 1000) # timeout after 1s
...
</programlisting>
		</example>
	</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>Example</title>
		<para>
			This is an example of an event raised by the pike module
			when it decides an ip should be blocked:
		</para>
		<example>
		<title>E_PIKE_BLOCKED event</title>
		<programlisting format="linespecific">
<![CDATA[
{
  "jsonrpc": "2.0",
  "method": "E_PIKE_BLOCKED",
  "params": {
    "ip": "192.168.2.11"
  }
}
]]>
</programlisting>
		</example>

		<example>
		<title>RabbitMQ socket</title>
		<programlisting format="linespecific">

	rabbitmq:guest:guest@127.0.0.1:5672/pike

	# same socket can be written as
	rabbitmq:127.0.0.1/pike

	# TLS broker connection
	rabbitmq:127.0.0.1/tls_domain=rmq?pike
</programlisting>
		</example>

	</section>
	<section>
		<title>Installation and Running</title>
	<section>
		<title>&osips; config file</title>
		<para>
			This configuration file presents the usage of the event_rabbitmq
			module. In this scenario, a message is sent to a RabbitMQ server
			everytime &osips; receives a MESSAGE request. The parameters 
			passed to the server are the R-URI username and the message
			body.
		</para>
		<example>
			<title>&osips; config script - sample event_rabbitmq usage</title>
			<programlisting format="linespecific">
...
&rabbitmqcfg;
...
</programlisting>
		</example>
		</section>
	</section>
</chapter>

