Table of Contents
host
(str)
port
(int)
keepalive
(int)
id
(str)
username
(str)
password
(str)
will_topic
(str)
will
(str)
event_callback
(str)
ca_file
(str)
ca_path
(str)
tls_method
(str)
tls_alpn
(str)
certificate
(str)
private_key
(str)
cipher_list
(str)
verify_certificate
(str)
List of Examples
host
parameterport
parameterkeepalive
parameterid
parameterusername
parameterpassword
parameterwill_topic
parameterwill
parameterevent_callback
parameterca_file
parameterca_path
parametertls_method
parametertls_alpn
parametercertificate
parameterprivate_key
parametercipher_list
parameterverify_certificate
parametermqtt_subscribe
usagemqtt_unsubscribe
usagemqtt_publish
usageTable of Contents
host
(str)
port
(int)
keepalive
(int)
id
(str)
username
(str)
password
(str)
will_topic
(str)
will
(str)
event_callback
(str)
ca_file
(str)
ca_path
(str)
tls_method
(str)
tls_alpn
(str)
certificate
(str)
private_key
(str)
cipher_list
(str)
verify_certificate
(str)
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.
The following libraries or applications must be installed before running Kamailio with this module loaded:
libmosquitto - https://mosquitto.org
MQTT Broker IP/Hostname.
No default, this parameter is mandatory.
MQTT Broker port number.
Default value is 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.
String to use as the mqtt client id. If NULL, a random client id will be generated.
Default value is NULL.
The username to send as a string or NULL to disable authentication.
Default value is NULL (no authentication).
Must be used together with password
.
The password to send as a string or NULL to disable authentication.
Default value is NULL (no authentication).
Must be used together with username
.
The topic on which to publish the mqtt will.
Default value is NULL. Must be used together with will
.
The mqtt will payload to be published.
Default value is NULL. Must be used together with will_topic
.
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).
Example 1.9. 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 ...
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.
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.
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.
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.
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.
Example 1.14. Set certificate
parameter
... 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.
Example 1.15. Set private_key
parameter
... 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.
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.
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.
Unsubscribe to a previously subscribed topic. The mqtt broker will stop forwarding messages for this topic.
This function can be used from ANY_ROUTE.
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.
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"); } ...
$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 https://www.kamailio.org/wikidocs/.