MyQttD Administrator manual (reference manual)

Manual

Section 1: Installation notes

Section 2: MyQttD configuration

Section 3: MyQttD module management

Section 4: Modules documentation

2.1 MyQttD configuration

2.2 Where myqttd is configured (configuration file location)

MyQttD is configured through XML 1.0 files. The intention is provide an easy and extensible way to configure myqttd, allowing third parties to build tools to update/reconfigure it.

According to your installation, the main myqttd configuration file should be found at the location provided by the following command:

>> myqttd --conf-location
[..various indications..]
Default configuration file: /etc/myqtt/myqtt.conf

Alternatively you can provide your own configuration file by using the –config option:

>> myqttd --conf my-myqttd.conf

If you are installing for the first time, you will not have that file but instead /etc/myqtt/myqtt.example.conf You can move it, review it and then restart the server like this:

>> mv /etc/myqtt/myqtt.example.conf /etc/myqtt/myqtt.conf
# review it (for now, leave it like this if you still have no preference)

Now, if you are installing from source code, have a copy of the following file doc/myqtt-init.d (for debian/ubuntu) or doc/myqtt-rpm-init.d (for CentOS/Redhat) into /etc/init.d. For example, for debian systems it would be something like:

>> cp ${myqtt_sources}/doc/myqtt-init.d /etc/init.d/myqtt

After that, you should be eable to restart/start/stop your MyQttD server:

>> /etc/init.d/myqtt restart

2.3 How myqttd is configured

MyQttD main configuration file includes several global sections:

  1. <global-settings>: This main section includes several run time configuration for the MQTT server: TCP ports, listener address, log files, crash handling, etc.

  2. <modules>: Under this section is mainly configured directories holding modules.

  3. <domain-settings>: Under this section are configured the group of settings that represent each domain-setting. MyQttD server allows to deliver a different set of configurations to limit each domain (conn-limit, message-size-limit, storage-messages-limit, etc). Each of the these groups have a name that is later used when a new MyQttD domain is declared.

    For example, if you have a set of users with basic needs, you can configure them the following group set:

    <domain-setting name="basic" >
       <conn-limit value="5" />
       <!--  amount of concurrent connections  -->
       <message-size-limit value="32768" />
       <!--  32k max message size allowed, use -1 for no limits (256MB)  -->
       <storage-messages-limit value="10000" />
       <!--  max amount of messages in storage, use -1 for no limits  -->
       <storage-quota-limit value="102400" />
       <!--  max amount of space used (100MB)  -->
    </domain-setting>
    

    At the same time, if you a have a different set of users with more advanced needs, you can configuring the following group set:

    <domain-setting name="standard" >
       <conn-limit value="10" />
       <!--  amount of concurrent connections  -->
       <message-size-limit value="65536" />
       <!--  32k max message size allowed, use -1 for no limits (256MB)  -->
       <storage-messages-limit value="20000" />
       <!--  max amount of messages in storage, use -1 for no limits  -->
       <storage-quota-limit value="204800" />
       <!--  max amount of space used (200MB), value in KB  -->
    </domain-setting>
    

  4. <myqtt-domains>: The last section includes all domains that are recognized by your MyQttd server. Each domain can have a separate storage location, a separate user's database and a different domain-settings configuration. Here is an example:

    <domain use-settings="basic" 
            users-db="/var/lib/myqtt-dbs/example.com" 
            storage="/var/lib/myqtt/example.com" 
            name="example.com" />
    

    Of course, if you declare a new domain, you have to ensure that the folders pointed by users-db and storage attributes exists and are writable for the user that is running the myqttd process.

    You can configure the running user inside the global section:

    <running-user gid="myqttd" uid="myqttd" />
    

2.4 MyQttD addresses and ports used

Ports and addresses used by MyQttD to listen are configured at the <global-settings> section. Here is an example:

<global-settings>
   <!--  port allocation configuration  -->
   <ports>
      <!--  <port [bind-addr='0.0.0.0'] [proto='mqtt']>__port_num__</port>  -->
      <!--  iana registered port for plain MQTT  -->
      <port proto="mqtt" >
1883</port>
      <!--  iana registered port for TLS MQTT  -->
      <port proto="mqtt-tls" >
8883</port>
      <!--  declaration for MQTT over WebSocket  -->
      <!--  <port proto="mqtt-ws">80</port>   -->
      <!--  declaration for MQTT over TLS/SSL WebSocket  -->
      <!--  <port proto="mqtt-wss">443</port>   -->
   </ports>
   <!--  .. more declarations...  -->
</global-settings>

Previous example will make MyQttD to listen on ports 1883 running MQTT protocol (proto=mqtt) and 8883 running MQTT over TLS protocol (proto=mqtt-tls). Of cource, to have MQTT over TLS running, you will have to configure the right set of certificates. If they are not present, even though the port is declared, the listener will not start on that port. See how to configure those certificates in the following page: MyQttd mod-ssl configuration

2.5 MyQttD bad signal handling

When it is found a myqttd bug or a third part module is causing problems, it is handy to configure the default action to take on server crash (bad signal received). This is done by configuring the following under the global-settings:

<global-settings>
   <!--  crash settings 
       [*] hold:   lock the current instance so a developer can attach to the
                   process  to debug what's happening.

       [*] ignore: just ignore the signal, and try to keep running.

       [*] quit,exit: terminates myqtt execution.

       [*] backtrace: allows to produce a backtrace located on a
       file. 

       All these values can be combined with mail-to to send a report.
      -->
   <on-bad-signal mail-to="default" action="hold" />
   <!--  .. more declarations...  -->
</global-settings>

The "hold" option is really useful for real time debugging because it hangs right after the signal is received. This allows to launch the debugger and attach to the process to see what's happening.

Another useful option is "backtrace" which produces a backtrace report (of the current process) saving it into a file. This allows to save some error evidences and then let the process to finish. This option combined with mail-to attribute is a powerful debug option.

Inside production environment it is recommended "ignore".

2.6 Receiving SMTP notification on failures and error conditions

MyQttD includes a small SMTP client that allows to report critical or interesting conditions. For example, this is used to report backtraces on critical signal received.

This configuration is found and declarted at the <global-settings> section. Here is an example:

<global-settings>
   <!--  general smtp servers and accounts that will be used to
         produce notifications. The account declaration <smtp-server>
         with is-default="yes" will be used as default system
         notification.  -->
   <notify-failures>
      <smtp-server is-default="yes" 
                   mail-to="test@example.com" 
                   mail-from="myqtt@example.com" 
                   port="25" 
                   server="localhost" 
                   id="default" />
   </notify-failures>
   <!--  .. more declarations...  -->
</global-settings>

It is possible to have more than one <smtp-server> declared. They are later used/referenced either through id attribute or because the declaration is flagged with an is-default=yes.

2.6 Configuring myqttd log files

MyQttD logs is sent to a set of files that are configured at the <global-settings> section:

<global-settings>
   <!--  log reporting configuration: if use-syslog=yes then the rest
         of the logs are disabled and everything is sent to syslog  -->
   <log-reporting use-syslog="yes" enabled="yes" >
      <general-log file="/var/log/myqtt/main.log" />
      <error-log file="/var/log/myqtt/error.log" />
      <access-log file="/var/log/myqtt/access.log" />
      <myqtt-log file="/var/log/myqtt/myqtt.log" />
   </log-reporting>
   <!--  .. more declarations...  -->
</global-settings>

Log reporting in MyQttD works under two modes:

If the administrator configures the second case, these files hold logs for general information (<general-log>), error information (<error-log>), client peer access information (<access-log>) and myqtt engine log produced by its execution (<myqtt-log>).

Apart from the myqtt log (<myqtt-log>) the rest of files contains the information that is produced by all calls done to the following library functions: msg, msg2, wrn and error.

By default, MyQttD server is started with no console output. All log is sent to previous log files. The second destination available is the console output.

Four command line options controls logs produced to the console by MyQttD and tools associated:

  1. –debug: activates the console log, showing main messages. MyQttD tools have this option implicitly activated.

  2. –debug2: activates implicitly the –debug option and shows previous messages plus new messages that are considered to have more details.

  3. –debug3: makes log output activated to include more details at the place it was launched (file and line), process pid, etc.

  4. –color-debug: whenever previous options are activated, if this one is used, the console log is colored according to the kind of message reported: green (messages), red (error messages), yellow (warning messages).

If previous options are used MyQttD will register a log into the appropriate file but also will send the same log to the console.

In the case you want to handle all logs through syslog, just declare as follows. Note that once syslog is enabled, general-log, error-log, access-log and myqtt-log declarations will be ignored, making all information to be sent to syslog.

<global-settings>
   <!--  Send all to syslog  -->
   <log-reporting use-syslog="yes" enabled="yes" >
      <!--  logs declared here are ignored  -->
</log-reporting>
   <!--  .. more declarations...  -->
</global-settings>

2.7 Alter default myqttd base system paths

By default MyQttD has 3 built-in system paths used to locate configuration files (sysconfdir), find data files (datadir) and directories used at run time (runtime datadir) to implement internal functions.

To show default values configured on your myqttd use:

>> myqttd --conf-location

However, these three system paths can also be overrided by a configuration placed at the global section. Here is an example:

<system-paths>   <!--  override runtime-datadir configuration: by default /var/lib  -->
   <!--  <path name="runtime_datadir" value="/var/lib" />  -->
   <!--  override runtime-datadir configuration: by default /etc  -->
   <!--  <path name="sysconfdir" value="/etc" />  -->
   <!--  override datadir configuration: by default /usr/share  -->
   <!--  <path name="datadir" value="/usr/share" />  -->
</system-paths>

Currently, accepted system paths are:

Additionally modules inside MyQttD and Myqtt Library find configuration and data files by calling to myqtt_support_domain_find_data_file. That function works by finding the provided file under a particular search domain. Each module has it own search domain. To add new search elements into a particular domain to make your files available to each particular module then use the syntax found in the example above.

2.8 Splitting myqttd configuration

As we saw, myqttd has a main configuration file which is myqttd.conf. However, it is possible to split this file into several files or even directories with additional files.

In the case you want to move some configuration into a separate file, just place the following:

<include src="file-with-config.conf" />

Then the <include /> node will be replaced with the content found inside file-with-config.conf.

NOTE: even having this feature, the resuling myqttd.conf file after replacing all includes must be a properly formated myqttd.conf file.

At the same time, you have the same features but for including files in a directory. For that use the following example:

<include dir="/etc/myqtt/conf.d" />

3.1 MyQttD modules configuration

Modules loaded by myqttd are found at the directories configured in the <modules> section. Here is an example:

<modules>
   <!--  directory where to find modules to load  -->
   <directory src="/etc/myqtt/mods-enabled" />
   <!--  alternative directory  -->
   <!--  <directory src="../mods-enabled" />   -->
   <no-load>
      <!--  signal modules to be not loaded even being available the
           directories configured. The name configured can be the name
           that is reporting the module or the module file name, like
           mod_skipped (don't add .so). The difference is that
           providing the file name will module from the loaded into
           memory while providing a name will cause the module to be
           loaded and then checked its name.  -->
      <module name="mod-skipped" />
   </no-load>
</modules>

Every directory configured contains myqttd xml module pointers having the following content:

<mod-myqttd location="/usr/lib/myqtt/modules/mod-ssl.so" />

Each module have its own configuration file, which should use XML as default configuration format.

3.2 MyQttD module filtering

It is possible to configure MyQttD to skip some module so it is not loaded. This is done by adding a <no-load /> declaration with the set of modules to be skipped. This is done inside <modules /> section. See example above about mod-skipped

3.3 Enable a myqttd module

To enable a myqttd module, just make the module pointer file to be available in one of the directories listed inside <modules>. This is usually done as follows: