# &adminguide;

## Overview

The MQTT module allows bidirectional publish/subscribe communication by connecting &kamailio; to a MQTT Broker.

Messages can be published from any point in the routing script. Also the subscriptions can be fully controlled by scripting commands.

## Dependencies

### External Libraries or Applications

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

- libev - http://software.schmorp.de/pkg/libev

- libmosquitto - https://mosquitto.org

## Parameters

### `host` (str)

MQTT Broker IP/Hostname.

No default, this parameter is mandatory.

#### Set `host` parameter

    ...
    modparam("mqtt", "host", "1.2.3.4")
    ...

### `port` (int)

MQTT Broker port number.

Default value is 1883.

#### Set `port` parameter

    ...
    modparam("mqtt", "port", 1883)
    ...

### `keepalive` (int)

The number of seconds after which the broker should send a PING message to the kamailio if no other messages have been exchanged in that time.

Default value is 5.

#### Set `keepalive` parameter

    ...
    modparam("mqtt", "keepalive", 5)
    ...

### `id` (str)

String to use as the mqtt client id. If NULL, a random client id will be generated.

Default value is NULL.

#### Set `id` parameter

    ...
    modparam("mqtt", "id", "kamailio123")
    ...

### `username` (str)

The username to send as a string or NULL to disable authentication.

Default value is NULL (no authentication). Must be used together with `password`.

#### Set `username` parameter

    ...
    modparam("mqtt", "username", "kamailio-user")
    ...

### `password` (str)

The password to send as a string or NULL to disable authentication.

Default value is NULL (no authentication). Must be used together with `username`.

#### Set `password` parameter

    ...
    modparam("mqtt", "password", "supers3cre7")
    ...

### `will_topic` (str)

The topic on which to publish the mqtt will.

Default value is NULL. Must be used together with `will`.

#### Set `will_topic` parameter

    ...
    modparam("mqtt", "will_topic", "kamailio123")
    ...

### `will` (str)

The mqtt will payload to be published.

Default value is NULL. Must be used together with `will_topic`.

#### Set `will` parameter

    ...
    modparam("mqtt", "will", "gone")
    ...

### `event_callback` (str)

The name of the function in the kemi configuration file (embedded scripting language such as Lua, Python, ...) to be executed instead of event_route[...] blocks.

The function receives a string parameter with the name of the event, the values are: 'mqtt:connected', 'mqtt:disconnected', 'mqtt:message'.

Default value is 'empty' (no function is executed for events).

#### Set `event_callback` parameter

    ...
    modparam("mqtt", "event_callback", "ksr_mqtt_event")
    ...
    -- event callback function implemented in Lua
    function ksr_mqtt_event(evname)
    	KSR.info("===== mqtt module triggered event: " .. evname .. "\n");
    	return 1;
    end

    -- event callback function implemented in Python
    function ksr_mqtt_event(self, msg, evname)
    	KSR.info("===== mqtt module triggered event: %s\n" % evname);
    	return 1;
    end
    ...

### `ca_file` (str)

Path to a file containing the PEM encoded trusted CA certificate files.

Default value is NULL. Set either this parameter or `ca_path` if you want to connect via TLS.

#### Set `ca_file` parameter

    ...
    modparam("mqtt", "ca_file", "/etc/ssl/certs/myca.pem")
    ...

### `ca_path` (str)

Used to define a directory that contains PEM encoded CA certificates that are trusted. For `ca_path` to work correctly, the certificates files must have ".pem" as the file ending and you must run "openssl rehash /your/ca_path" each time you add/remove a certificate.

Default value is NULL. Set either this parameter or `ca_file` if you want to connect via TLS. `ca_file` and `ca_path` are mutual exclusive.

#### Set `ca_path` parameter

    ...
    modparam("mqtt", "ca_path", "/etc/ssl/certs")
    ...

### `tls_method` (str)

The version of the SSL/TLS protocol to use as a string. If NULL, the default value is used. The default value and the available values depend on the version of openssl that libmosquitto was compiled against.

Possible values:

- tlsv1.3 is available with openssl >= 1.1.1 together with libmosquitto v1.6.8 and newer.

- For openssl >= 1.0.1, the available options are tlsv1.2, tlsv1.1 and tlsv1, with tlv1.2 as the default.

- For openssl < 1.0.1, only tlsv1 is available.

Default value is NULL.

#### Set `tls_method` parameter

    ...
    modparam("mqtt", "tls_method", "tlsv1.3")
    ...

### `tls_alpn` (str)

Used to set the TLS ALPN option for cases where one TLS port is used to share multiple services. Prominent example is AWS IoT, where you have to set the `tls_alpn` to "mqtt" to be able to connect via MQTT.

Default value is NULL, where no ALPN is set on the TLS connection.

#### Set `tls_alpn` parameter

    ...
    modparam("mqtt", "tls_alpn", "mqtt")
    ...

### `certificate` (str)

Path to a file containing the PEM encoded certificate file for a TLS client connection.

Default value is NULL. If NULL, `private_key` must also be NULL and no client certificate will be used.

#### Set `certificate` parameter

    ...
    modparam("mqtt", "certificate", "/etc/ssl/certs/myclient.pem")
    ...

### `private_key` (str)

Path to a file containing the PEM encoded private key for a TLS client connection.

Default value is NULL. If NULL, `certificate` must also be NULL and no client certificate will be used.

#### Set `private_key` parameter

    ...
    modparam("mqtt", "private_key", "/etc/ssl/private/myclient.key")
    ...

### `cipher_list` (str)

A string describing the ciphers available for use. See the cipher(1) OpenSSL man page. If NULL, the libssl default ciphers will be used.

Default value is NULL.

#### Set `cipher_list` parameter

    ...
    modparam("mqtt", "cipher_list", "HIGH")
    ...

### `verify_certificate` (str)

Configure verification of the server certificate. If value is set to 0, it is impossible to guarantee that the host you are connecting to is not impersonating your server.

This can be useful in initial server testing, but makes it possible for a malicious third party to impersonate your server through DNS spoofing, for example.

Do not disable verification in a real system as it makes the connection encryption pointless.

Default value is 1.

#### Set `verify_certificate` parameter

    ...
    modparam("mqtt", "verify_certificate", "0")
    ...

## Functions

### `mqtt_subscribe(topic, qos)`

Subscribe to the given topic. Mqtt qos levels 0, 1 and 2 can be used.

The function is passing the task to mqtt dispatcher process, therefore the SIP worker process is not blocked.

Incoming messages for this topic are then handled by the same process and exposed to the event_route[mqtt:message].

This function can be used from ANY_ROUTE.

#### `mqtt_subscribe` usage

    ...
    mqtt_subscribe("kamailio/script", 0);
    ...

### `mqtt_unsubscribe(topic)`

Unsubscribe to a previously subscribed topic. The mqtt broker will stop forwarding messages for this topic.

This function can be used from ANY_ROUTE.

#### `mqtt_unsubscribe` usage

    ...
    mqtt_unsubscribe("kamailio/script");
    ...

### `mqtt_publish(topic, message, qos)`

Send out a message to a topic with a specified mqtt qos level (0, 1, 2). Again the actual sending is done in a mqtt dispatcher process and will not block the SIP worker.

#### `mqtt_publish` usage

    ...
    mqtt_publish("kamailio/event", "some message", 0);
    ...

## Event routes

### `mqtt:connected`

If defined, the module calls event_route[mqtt:connected] when an outgoing broker connection is established.

MQTT subscriptions are not durable, so you should use this event route to manage your subscriptions.

    ...
    event_route[mqtt:connected] {
            xlog("mqtt connected !\n");
            mqtt_subscribe("kamailio/script", 0);
    }
    ...

### `mqtt:disconnected`

If defined, the module calls event_route[mqtt:disconnected] when the broker connection is lost.

The module will automatically try to reconnect to the broker every 3 seconds.

    ...
    event_route[mqtt:disconnected] {
        xlog("Lost mqtt connection !\n");
    }
    ...

### `mqtt:message`

If defined, the module calls event_route[mqtt:message] when a message is received from the broker.

All incoming messages are handled in a single mqtt dispatcher process.

    ...
    event_route[mqtt:message] {
    	xlog("mqtt message received: $mqtt(topic) -> $mqtt(msg) !\n");
    }
    ...

## Exported pseudo-variables

- $mqtt(topic) - Received topic (only in mqtt:message)

- $mqtt(msg) - Received message (only in mqtt:message)

- $mqtt(qos) - The received message QOS level: 0, 1 ,2 (only in mqtt:message)

Exported pseudo-variables are documented at &kamwikilink;.