# &adminguide;

## Overview

RabbitMQ (http://www.rabbitmq.com/) is an open source messaging server. It's purpose is to manage received messages in queues, taking advantage of the flexible AMQP protocol.

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.

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

## RabbitMQ events syntax

The raised events will follow the following grammar:

- event = event_name (argument '\n')*

- event_name = non-quoted_string'\n'

- argument = ((arg_name '::')? arg_value)? | (arg_value)

- arg_name = not-quoted_string

- arg_value = not-quoted_string | '"' string '"'

- not-quoted_string = string - {',",\n,\r}

The event name can contain any non-quoted string character, but it is recommended to follow the syntax: E_MODULE_NAME_EXTRA_NAME

## RabbitMQ socket syntax

'rabbitmq:' [user[':'password] '@' host [':' port] '/' [exchange '?'] routing_key

Meanings:

- 'rabbitmq:' - informs the Event Interface that the events sent to this subscriber should be handled by the event_rabbitmq module.

- user - username used for RabbitMQ server authentication. The default value is 'guest'.

- password - password used for RabbitMQ server authentication. The default value is 'guest'.

- host - host name of the RabbitMQ server.

- port - port of the RabbitMQ server. The default value is '5672'.

- exchange - exchange of the RabbitMQ server. The default value is ''.

- routing_key - this is the routing key used by the AMQP protocol and it is used to identify the queue where the event should be sent.

  NOTE: if the queue does not exist, this module will not try to create it.

## Dependencies

### &osips; Modules

The following modules must be loaded before this module:

- No dependencies on other &osips; modules.

### External Libraries or Applications

The following libraries or applications must be installed before running &osips; with this module loaded:

- librabbitmq-dev

## Exported Parameters

### `heartbeat` (integer)

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.

Default value is 0 (disabled).

#### Set `heartbeat` parameter

    ...
    modparam("event_rabbitmq", "heartbeat", 3)
    ...

### `sync_mode` (integer)

Specifies whether an event raise operates synchronous or asynchronous relative to the process where the raise is triggered.In synchronous mode the process waits for the status of the raise from the actual worker process.In asynchronous mode the process continues its operation without receiving any confirmation.

Default value is 0 (asynchronous).

#### Set `sync_mode` parameter

    ...
    modparam("event_rabbitmq", "sync_mode", 1)
    ...

## Exported Functions

No function exported to be used from configuration file.

## Example

This is an example of an event raised by the pike module when it decides an ip should be blocked:

### E_PIKE_BLOCKED event

    	E_PIKE_BLOCKED
    	ip::192.168.2.11

### RabbitMQ socket

    	rabbitmq:guest:guest@127.0.0.1:5672/pike

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

## Installation and Running

### &osips; config file

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.

#### &osips; config script - sample event_rabbitmq usage

    ...
    &rabbitmqcfg;
    ...