mod_mosquitto is a FreeSWITCH interface to an MQTT broker using the Eclipse Mosquitto project C client library. MQTT is a lightweight protocol to send or receive messages using a publish/subscribe (pub/sub) design pattern. Eclipse Mosquitto is an open source message broker that implements the MQTT protocol.
mod_mosquitto is able to publish and/or subscribe to one or more MQTT message brokers. A FreeSWITCH bgapi or originate command may be executed if a properly formatted message is received.
More information can be found here:
FreeSWITCH Modular Media Switching Software Library / Soft-Switch Application Copyright (C) 2005-2012, Anthony Minessale II anthm@freeswitch.org
Version: MPL 1.1
The contents of this file are subject to the Mozilla Public License Version 1.1 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.mozilla.org/MPL/
Software distributed under the License is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License for the specific language governing rights and limitations under the License.
The Original Code is FreeSWITCH Modular Media Switching Software Library / Soft-Switch Application
The Initial Developer of the Original Code is Anthony Minessale II anthm@freeswitch.org Portions created by the Initial Developer are Copyright (C) the Initial Developer. All Rights Reserved.
- Norm Brandinger n.brandinger@gmail.com
Global Settings
Multiple Profiles
Multiple MQTT broker connections
Multiple Subscribers
Multiple Publishers
Multiple Topics
TLS Support
Last Will and Testament (Will) support
Publish one or more FreeSWITCH events to one or more Topics
Subscribe to FreeSWITCH bgapi or originate requestsmod_mosquitto requires libmosquitto-dev to build on DebianChange to a directory where the FreeSWITCH sources will be compiled
cd /usr/srcClone the FreeSWITCH repository into the above directory
git clone https://github.com/signalwire/freeswitch.gitPerform an initial bootstrap of FreeSWITCH so that a modules.conf file is created
./bootstrap.shAdd the mod_mosquitto to modules.conf so that an out-of-source build will be performed
mod_mosquitto|https://github.com/freeswitch/mod_mosquitto.git -b masterConfigure, build and install FreeSWITCH
./configure
make
make installThe following commands will build and install only mod_mosquitto
make mod_mosquitto
make mod_mosquitto-installTo run mod_mosquitto within FreeSWITCH, perform the following two steps
Add mod_mosquito to freeswitch/conf/autoload/modules.conf.xml
Add mosquitto.conf.xml to freeswitch/conf/autoloadConfiguration settings are located in the mosquitto.conf.xml file that is located in freeswitch/conf/autoload_configs
The configuration follows the standard way all other FreeSWITCH modules are configured.
At a high level, the configuration file is organized as follows:
- Global settings are specified first.
- One or more Profiles are then defined.
- Within each Profile, there can be one or more Connections, Publishers and Pubscribers defined.
- Within each Publisher or Subscriber, there can be one or more Topics defined.
- Publisher Topics can have one or more event parameters.
- Subscriber Topics can be authorized to execute
bgapiororiginatecommands.
Configuration parameter details
Global Settings
<settings>
log-enable - Is logging enabled (true) / disabled (false)
log-details - Is logging of message details enabled (true) / disabled (false)
log-level - Log severity level is one of:
debug,info,notice,warning,error,critical,alert,console
log-dir - Directory where the log file(s) will be written.
Defaults to 'freeswitch/log'
log-file - Name of the log file where mod_mosquitto messages will written.
Defaults to 'mosquitto.log'
enable-profiles - Default setting if unspecified in the configuration file
enable-publishers - Default setting if unspecified in the configuration file
enable-subscribers - Default setting if unspecified in the configuration file
enable-connections - Default setting if unspecified in the configuration file
enable-topics - Default setting if unspecified in the configuration file
event-queue-size - Number of pending events that the event queue can hold
unique-string-length - Length of random characters added to
FreeSWITCH-Switchname-Unique / FreeSWITCH-Hostname-Unique
</settings>Profile Settings
<profile>
name - Name of the profile. Each profile must have a unique name.
enable - Is this profile enabled (true) / disabled (false).
log-enable - Is logging enabled (true) / disabled (false) for this profile
log-details - Is logging of message details enabled (true) / disabled (false)
log-level - Log severity level is one of:
debug,info,notice,warning,error,critical,alert,console
log-dir - Directory where the log file(s) will be written.
Defaults to 'freeswitch/log'
log-file - Name of the log file where mod_mosquitto messages will written.
Defaults to the profile name + '.log'.
</profile>Connection Settings
<connection>
name - Name of this connection.
Each connection within a profile must have unique name.
enable - Is this connection enabled (true) / disabled (false).
receive_maximum - The maximum number of incoming QoS1 and QoS2 messages
to be processed at once.
send_maximum - The maximum number of 'in-flight' QoS1 and QoS2 messages
to be processed at once.
host - The hostname (FQDN) of the MQTT broker to connect to.
port - The port on the MQTT broker to connect to.
bind_address - the hostname or IP address of the local network interface to bind to.
srv - Should SRV lookups be performed (true/false).
keepalive - The MQTT keepalive value.
username - The username used by the MQTT broker to authorize the connection.
password - The password used by the MQTT broker to authenticate the connection.
client_id - The client id to use. If not specified a
random client id will be generated.
'FreeSWITCH-Switchname': Use the switchname as the client id.
'FreeSWITCH-Switchname-Unique': Use the switchname with random characters
appended as the client id.
'FreeSWITCH-Hostname': Use the hostname as the client id.
'FreeSWITCH-Hostname-Unique': Use the hostname with random characters
appended as the client id.
WARNING: Do not use the same client_id more than once per MQTT broker,
this includes across profiles
clean_session - The MQTT clean sesson flag (frue/false)
retries - The maximum number of reconnect retries.
reconnect_delay - The number of seconds to wait between reconnects.
reconnect_delay_max - The maximum number of seconds to taie between reconnects.
reconnect_exponsntial_backoff - Use exponential backoff between
reconnect attempts (true/false).
<tls>
enable - Enabled (true) / disabled (false):
Should SSL/TLS be enabled for this connection
support - 'certificate': The connection will be configured for
certificate based SSL/TLS support.
'pks': The connection will be configured for
pre-shared-key based TLS support.
If not specified, the connection will NOT be configured
for SSL/TLS and none of the settings below will have any effect.
port - Overrides the connection port
cafile - Path to a file containing the PEM encoded trusted CA certificate files.
Either cafile or capath must be specified.
capath - Path to a directory containing the PEM encoded trusted CA certificate files.
Either cafile or capath must be specified.
certfile - Path to a file containing the PEM encoded certificate file for this client.
If NULL, keyfile must also be NULL and no client certificate will be used.
keyfile - Path to a file containing the PEM encoded private key for this client.
If NULL, certfile must also be NULL and no client certificate will be used.
advanced_options - enabled (true) / disabled (false) When enabled:
'cert_reqs', 'version', and 'opts_ciphers' are set for the connection.
cert_reqs - Verification requirements the connection will impose on the server
'SSL_VERIFY_NONE': The server will not be verified in any way.
'SSL_VERIFY_PEER': The server certificate will be verified and
the connection aborted if the verification fails.
The default and recommended value is SSL_VERIFY_PEER.
Using SSL_VERIFY_NONE provides no security.
opts_ciphers - A string describing the ciphers available for use.
See the “openssl ciphers” tool for more information.
If NULL, the default ciphers will be used.
version - 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 the library was compiled against.
For OpenSSL >= 1.0.1, the available options are tlsv1.2, tlsv1.1 and tlsv1
with tlv1.2 is the default.
For OpenSSL < 1.0.1, only tlsv1 is available.
psk - The pre-shared-key in hex format with no leading “0x”.
identity - The identity of this client. May be used as the username depending on the server settings.
psk_ciphers - A string describing the PSK ciphers available for use.
See the “openssl ciphers” tool for more information.
If NULL, the default ciphers will be used.
</tls>
<will>
enable - Enable (true) or disable (false) the will associated with this connection.
- The topic/payload of the will are published when the connection is closed.
topic - The topic name associated with this connecton.
payload - The payload data that will be published to the topic when the connection is closed.
qos - Message delivery Quality of Service
0: At most once - Best effort delivery.
Message may not be delivered to the receiver.
1: At least once - Guarantees that the mesage will be delivered at
least one time to the receiver (duplicates possible).
2: Exactly once - Guarentees that the message is received
only once by the receiver.
retain - (true/false) The MQTT broker stores the last retained message
and the corresponding QoS for that topic.
</will>
</connection>Publisher Settings
<publisher>
name - Name of this publisher.
Each publisher within a profile must have unique name.
enable - Is this publisher enabled (true) / disabled (false).
</publisher>Publisher Topic Settings
<topic>
name - Name of this topic.
Each topic within a profile/publisher must have unique name.
enable - Is this topic enabled (true) / disabled (false).
connection_name - The connection name associated with this topic.
The connection name must be defined within the same profile.
event - The FreeSWITCH event name that will be published to this topic.
Multiple events can be specified, one per param.
Allowed values: https://docs.freeswitch.org/switch__types_8h.html#ac9614049b0344bb672df9d23a7ec4a09
pattern - Pattern used to classify and filter different MQTT messages.
For example: FreeSWITCH/command or FreeSWITCH/heartbeat.
qos - Message delivery Quality of Service
0: At most once - Best effort delivery.
Message may not be delivered to the receiver.
1: At least once - Guarantees that the mesage will be delivered at
least one time to the receiver (duplicates possible).
2: Exactly once - Guarentees that the message is received
only once by the receiver.
retain - (true/false) The MQTT broker stores the last retained message
and the corresponding QoS for that topic.
</topic>Subscriber Settings
<subscriber>
name - Name of this subscriber.
Each subscriber within a profile must have unique name.
enable - Is this subscriber enabled (true) / disabled (false).
</subscriber>Subscriber Topic Settings
<topic>
name - Name of this topic.
Each topic within a profile/subscriber must have unique name.
enable - Is this topic enabled (true) / disabled (false).
connection_name - The connection name associated with this topic.
The connection name must be defined within the same profile.
pattern - Pattern used to classify and filter different MQTT messages.
For example: FreeSWITCH/command or FreeSWITCH/heartbeat.
qos - The requested Quality of Service for this subscription.
0: At most once - Best effort delivery.
Message may not be delivered to the receiver.
1: At least once - Guarantees that the mesage will be delivered at
least one time to the receiver (duplicates possible).
2: Exactly once - Guarentees that the message is received
only once by the receiver.
originate_authorized - Are originate commands authorized (true) / not authorized (false)
bgapi_authorized - Are bgapi commands authorized (true) / not authorized (false)
</topic>Below is an example of an empty configuration file showing the structure:
Note: Multiple profiles, connections, publishers, subscribers and topics are allowed.
<configuration>
<settings>
</settings>
<profiles>
<profile>
<connections>
<connection>
<tls>
</tls>
<will>
</will>
</connection>
</connections>
<publishers>
<publisher>
<topics>
<topic>
</topic>
</topics>
</publisher>
</publishers>
<subscribers>
<subscriber>
<topics>
<topic>
</topic>
</topics>
</subscriber>
</subscribers>
</profile>
</profiles>
</configuration>An example configuration file:
<configuration name="mosquitto.conf" description="mod_mosquitto">
<settings>
<param name="log-enable" value="true"/>
<param name="log-level" value="debug"/>
<param name="log-dir" value="/usr/local/freeswitch/log"/>
<param name="log-file" value="mosquitto.log"/>
<param name="enable-profiles" value="true"/>
<param name="enable-publishers" value="true"/>
<param name="enable-subscribers" value="true"/>
<param name="enable-connections" value="true"/>
<param name="enable-topics" value="true"/>
<param name="event-queue-size" value="5000"/>
<param name="unique-string-length" value="10"/>
</settings>
<profiles>
<profile name="default">
<param name="enable" value="true"/>
<param name="log-enable" value="true"/>
<param name="log-level" value="debug"/>
<param name="log-dir" value="/usr/local/freeswitch/log"/>
<param name="log-file" value=""/>
<connections>
<param name="send_maximum" value="10"/>
<param name="bind_address" value=""/>
<connection name="broker1">
<param name="enable" value="true"/>
<param name="receive_maximum" value="20"/>
<param name="send_maximum" value="20"/>
<param name="host" value="broker1.example.com"/>
<param name="port" value="1883"/>
<param name="keepalive" value="10"/>
<param name="username" value="[REDACTED]"/>
<param name="password" value="[REDACTED]"/>
<param name="client_id" value="FreeSWITCH-Switchname-Unique"/>
<param name="clean_session" value="false"/>
<param name="retries" value="3"/>
<param name="reconnect_delay" value="1"/>
<param name="reconnect_delay_max" value="10"/>
<param name="reconnect_exponential_backoff" value="false"/>
<tls>
<param name="enable" value="true"/>
<param name="enable" value="certificate"/>
<param name="advanced_options" value="true"/>
<param name="port" value="8883"/>
<param name="cafile" value=""/>
<param name="capath" value="/etc/ssl/certs/"/>
<param name="certfile" value=""/>
<param name="keyfile" value=""/>
<param name="cert_reqs" value=""/>
<param name="version" value=""/>
<param name="opts_ciphers" value=""/>
<param name="psk" value=""/>
<param name="identity" value=""/>
<param name="psk_ciphers" value=""/>
</tls>
<will>
<param name="enable" value="true"/>
<param name="topic" value="FreeSWITCH/will"/>
<param name="payload" value="broker1 connection has been closed"/>
<param name="qos" value="0"/>
<param name="retain" value="true"/>
</will>
</connection>
<connection name="broker2">
<param name="host" value="broker2.example.com"/>
<param name="port" value="1883"/>
<param name="username" value="[REDACTED]"/>
<param name="password" value="[REDACTED]"/>
</connection>
</connections>
<publishers>
<publisher name="primary_publisher">
<param name="enable" value="true"/>
<topics>
<topic name="Background Job">
<param name="enable" value="true"/>
<param name="connection_name" value="broker1"/>
<param name="event" value="BACKGROUND_JOB"/>
<param name="pattern" value="FreeSWITCH/BACKGROUND_JOB"/>
<param name="qos" value="0"/>
<param name="retain" value="false"/>
</topic>
<topic name="Multiple">
<param name="enable" value="false"/>
<param name="connection_name" value="broker2"/>
<param name="event" value="CHANNEL_ANSWER"/>
<param name="event" value="CHANNEL_HANGUP"/>
<param name="pattern" value="FreeSWITCH/MULTIPLE"/>
<param name="qos" value="0"/>
<param name="retain" value="false"/>
</topic>
</topics>
</publisher>
</publishers>
<subscribers>
<subscriber name="primary_subscriber">
<param name="enable" value="true"/>
<topics>
<topic name="primary_subscribed_topic_01">
<param name="enable" value="true"/>
<param name="connection_name" value="broker1"/>
<param name="pattern" value="FreeSWITCH/command"/>
<param name="qos" value="0"/>
<!-- WARNING: THE FOLLOWING TWO SETTINGS WILL ALLOW THE MQTT BROKER TO INITIATE PHONE CALLS -->
<!-- WARNING: Setting either of these permissons to true WILL allow phone calls to be initiated by the MQTT broker to FreeSWITCH. -->
<!-- WARNING: If the connected MQTT broker is not locked down, toll fraud WILL HAPPEN by bad actors. -->
<!-- WARNING: REPEATED: If the connected MQTT broker is not locked down, toll fraud WILL HAPPEN by bad actors. -->
<!-- WARNING: REPEATED A THIRD TIME: If the connected MQTT broker is not locked down, toll fraud WILL HAPPEN by bad actors. -->
<param name="originate_authorized" value="false"/>
<param name="bgapi_authorized" value="false"/>
</topic>
<topic name="test_subscriber">
<param name="enable" value="true"/>
<param name="connection_name" value="broker2"/>
<param name="pattern" value="FreeSWITCH/test"/>
<param name="qos" value="0"/>
</topic>
</topics>
</subscriber>
</subscribers>
</profile>
</profiles>
</configuration>BGAPI
-
Set up mod_mosquitto to publish the
BACKGROUND_JOBevent to a topic, for example:FreeSWITCH/BACKGROUND_JOB. -
With your MQTT client subscribe to the above topic.
-
Set up mod_mosquitto to subscribe to a topic with the
bgapi_authorizedpermissions set, for example:FreeSWITCH/command. -
With your MQTT client, publish to a topic mod_mosquitto is subscribed to, for example:
FreeSWITCH/command.The content of the published message should start with
bgapi, for example:bgapi version bgapi show registrations
-
The responses will be published to the above topic, for example
FreeSWITCH/BACKGROUND_JOB.
ORIGINATE
-
With your MQTT client, publish to a topic mod_mosquitto is subscribed to, for example:
FreeSWITCH/command. -
Set up mod_mosquitto to subscribe to a topic with the
originate_authorizedpermissions set, for example:FreeSWITCH/command. -
With your MQTT client, publish to a topic mod_mosquitto is subscribed to, for example:
FreeSWITCH/command.The content of the published message should start with
originate, for example:originate {origination_caller_id_number=19005551212}sofia/internal/sip:1000@192.168.1.1:58289 9386 XML default originate {origination_caller_id_number=9005551212}sofia/default/whatever@wherever 19005551212 XML default originate {origination_caller_id_number=1000}sofia/external/sip:1000@192,168,1,1:49603 5000 XML default originate sofia/external/sip:1000@192.168.1.1:49603 5000 XML default
-
Note: Depending on the FreeSWITCH events being published, the result of the
originatecommand may, or may not be sent to the MQTT client.
SUBSCRIBE to a topic
Example of the the topic configuration to subscribe to a topic (and allowing both bgapi and originate commands):
Notes
- The topic
namemust be unique within a profile. - The topic can be enabled or disabled by setting the
enableparam. - The connection
namemust reference a connection previously defined in the configuration file. - The
patternmust comply with MQTT standards. - The
qosvalue must comply with MQTT standards. Value 0, 1 or 2 indicating the Quality of Service to be used. - The
originate_authorized/bgapi_authorizedpermission flags.
WARNING: Allowing either originate_authorized or bgapi_authorized settings WILL allow phone calls to be initiated by the MQTT broker to FreeSWITCH.
WARNING: If the connected MQTT broker is not locked down, toll fraud WILL HAPPEN by bad actors.
WARNING: REPEATED: If the connected MQTT broker is not locked down, toll fraud WILL HAPPEN by bad actors.
WARNING: REPEATED A THIRD TIME: If the connected MQTT broker is not locked down, toll fraud WILL HAPPEN by bad actors.<subscriber>
<topics>
<topic name="command">
<param name="enable" value="true"/>
<param name="connection_name" value="mqtt_broker"/>
<param name="pattern" value="FreeSWITCH/command"/>
<param name="qos" value="0"/>
<!-- WARNING EITHER OF THESE TWO SETTINGS WILL ALLOW THE MQTT BROKER TO INITIATE PHONE CALLS -->
<param name="originate_authorized" value="false"/>
<param name="bgapi_authorized" value="false"/>
</topic>
</topics>
</subscriber>PUBLISH an event to a topic:
Notes
- The topic
namemust be unique within a profile. - The topic can be enabled or disabled by setting the
enableparam. - The connection
namemust reference a connection previously defined in the configuration file. - The pattern must comply with MQTT standards.
- The
qosvalue must comply with MQTT standards. Value 0, 1 or 2 indicating the Quality of Service to be used. - The
retainboolean must be eithertrueorfalse. - The
eventparameter must contain a single FreeSWITCH supported event. Multipleeventparameters be be added to a topic.
The example below configures mod_mosquitto to publish the single event type, HEARTBEAT to a topic named Heartbeat.
In addition, mod_mosquitto will publish two event types, HEARTBEAT and RE_SCHEDULE to a topic named Multiple.
The list of valid FreeSWITCH event types can be found here: https://docs.freeswitch.org/switch__types_8h.html#ac9614049b0344bb672df9d23a7ec4a09
If the above link doesn't work, search the FreeSWITCH documentaton for switch_event_types_t.
The event names used here are the same as those defined in switch_event_types_t with the removal of the SWITCH_EVENT prefix.
<publisher>
<topics>
<topic name="Heartbeat">
<param name="enable" value="true"/>
<param name="connection_name" value="mqtt_broker"/>
<param name="event" value="HEARTBEAT"/>
<param name="pattern" value="FreeSWITCH/HEARTBEAT"/>
<param name="qos" value="0"/>
<param name="retain" value="false"/>
</topic>
<topic name="Multiple">
<param name="enable" value="false"/>
<param name="connection_name" value="mqtt_broker"/>
<param name="event" value="CHANNEL_ANSWER"/>
<param name="event" value="CHANNEL_HANGUP"/>
<param name="pattern" value="FreeSWITCH/MULTIPLE"/>
<param name="qos" value="0"/>
<param name="retain" value="false"/>
</topic>
</topics>
</publisher>The following mod_mosquitto commands can be entered in the FreeSWITCH console (fs_api):
mosquitto [help]
mosquitto status
mosquitto loglevel [debug|info|notice|warning|error|critical|alert|console]
mosquitto enable profile <profile-name> [connection|publisher|subscriber] <name>
mosquitto disable profile <profile-name> [connection|publisher|subscriber] <name>
mosquitto remove profile <profile-name> [connection|publisher|subscriber] <name>
mosquitto connect profile <profile-name> connection <name>
mosquitto disconnect profile <profile-name> connection <name>
mosquitto bgapi <command> [<arg>]The file EVENT_TYPES located in this repository is a list of the FreeSWITCH events that can be published. This list is accurate at the time mod_mosquitto was created.
The list of available bgapi commands are available by entering show api in the FreeSWITCH console (fs_cli).
Possible TODO items:
MQTT V5 support
Throttle (circuit-breaker) support
Enhanced security around command execution
Enhanced CLI functionality
Enhanced logging / statisticsCompile problems may result if Debian Stretch is not being used. If this is the case, please add the Stretch version of mosquitto to APT as follows:
In /etc/apt/sources.list.d create a file called mosquitto.list and add this line to it
deb http://repo.mosquitto.org/debian stretch mainThen perform an apt update and try to compile mod_mosquitto again.