The following libraries or applications must be installed before running Kamailio with this module loaded:

MQTT Broker IP/Hostname.

No default, this parameter is mandatory.

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

MQTT Broker port number.

Default value is 1883.

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

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.

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

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

Default value is NULL.

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

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

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

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

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

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

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

The topic on which to publish the mqtt will.

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

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

The mqtt will payload to be published.

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

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

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).

...
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
...

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.

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

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.

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

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:

Default value is NULL.

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

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.

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

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.

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

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.

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

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.

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

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.

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

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("kamailio/script", 0);
...

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("kamailio/script");
...

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("kamailio/event", "some message", 0);
...

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);
}
...

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");
}
...

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");
}
...