broker new database ?option value ...?

broker create name database ?option value ...?

The broker new and broker create commands create an MQTT server instance, either with an auto-generated or a user specified name. That instance can subsequently be used to handle MQTT client connections.

The database argument is usually just the name of a disk file in which the database is stored. If the name of the database is the special name ":memory:" then a new database is created in memory. If the name of the database is an empty string, then the database is created in an empty file that is automatically deleted when the server instance is destroyed.

The option value pairs configure some options associated with the broker instance. See the section Configuration options below for a full list of options supported and their effects.

broker log prefix

The broker log command configures a command prefix for handling log messages. Whenever the library has something to report, the log message is appended as an extra argument to prefix and the resulting command is executed.

Example: Print all log messages to standard output:

mqtt log puts

For each client instance created with the broker command, a new Tcl command is created. This command may be used to invoke various mqtt related operations.

The valid forms of this command are:

cmd configure ?option? ?value ...?

Query or modify the configuration options of the instance. If one or more option-value pairs are specified, then the command modifies the given instance option(s) to have the given value(s); in this case the command returns an empty string. If option is specified with no value, then the command returns the current value of the option. If no option is specified, it returns a list of all available options and their values.

See the section Configuration options below for a full list of options supported and their effects.

cmd clientadd clientid

Add the specified client ID to the database. If any client IDs are stored in the database, only those clients will be allowed to connect to the broker. By default, all client IDs are valid.

cmd clientdel clientid

Remove the specified client ID from the database. Trying to remove a non-existent client ID is not considered an error.

cmd listen ?port?

Start accepting MQTT client connections on the specified TCP port. The default port is 1883.

cmd useradd username ?password?

Add the specified user to the database. If any users are stored in the database, only those users will be allowed to connect to the broker. By default, no username is required and if a username is provided when connecting, any name is accepted. If the password argument is specified, the user must provide the given password when connecting. By default, no password is required and if a password is provided when connecting, any value is accepted.

cmd userdel username

Remove the specified user from the database. Trying to remove a non-existent user is not considered an error.

The following options, supported by the broker new, broker create, and cmd configure commands, control how the MQTT broker behaves:

-aliasmax count

The maximum number of topic aliases each client is allowed to use (default: 100).

-keepalive seconds

Rate at which to send keepalive messages (default: 60)

-retransmit milliseconds

When to retransmit a message if no confirmation has been received (default: 5000)

-socketcmd prefix

The command prefix to use when creating a socket. This allows the use of encrypted connections (default: socket)

The library provides very basic support for identification and authentication: If any client IDs have been added to the database using the clientadd method, only a client matching one of the provisioned IDs is accepted. Similarly, if any users have been added, only those users will be allowed to connect, if they provide the stored password.

If more sophisticated control is needed, the application can install a custom authorize method by overriding the default authorize method, or by mixing in a class that provides an authorize method.

Upon a new connection from a client, the authorize method will be called with four arguments: The client ID, the username and password, if they were provided by the client, and a key-value list of properties. The method should generate an exit code indicating whether the connection is allowed or that further authentication steps are required. Any value returned by the method should be a key-value list of properties.

Example: To only allow clients with a client ID containing the prefix "secure-", the following code may be used in the application:

package require broker

oo::class create brokerauth {
    method authorize {client username password properties} {
        if {![string match secure-* $client]} {
            # 133: Client Identifier not valid
            return -code 133
        }
        # Continue with the standard checks
        next $client $username $password $properties
    }
}
oo::define broker mixin brokerauth