flashmq.conf (5)

To set a parameter, its name must appear on a single line, followed by whitespace, followed by the parameter value.

parameter-name parameter-value

To configure the listeners, use listen blocks, defined by { and }. See EXAMPLE LISTENERS for details.

Lines beginning with the hash character (“#”) and empty lines are ignored. Thus, a line can be commented out by prepending a “#” to it.

plugin /path/to/plugin.so#

FlashMQ supports an ELF shared object (.so file) plugin interface to add functionality, authorization and authentication, because it’s hard to provide a declarative mechanism that works for everybody. See flashmq_plugin.h for the API and its documentation. It’s written in C++ for ease of passing FlashMQ internals without conversion to C, but you can basically just use a C++ compiler and program like it was C; the C++ constructs are simple.

FlashMQ will auto-detect which plugin interface you’re trying to load (Mosquitto version 2 or FlashMQ native). Keep in mind that each thread initializes the plugin, inline with multi-core programming (minimize shared data and interaction between threads). You could use static variables with thread synchronization if you really want to. And of course, any Mosquitto plugin that uses global and/or static variables instead of initializing memory in its init() method, will not be thread-safe and won’t work.

You can only have one plugin active, but you can combine it with mosquitto_password_file and mosquitto_acl_file. The password and ACL file take precedence, and on a ‘deny’, will not ask the plugin.

plugin_opt_* value#

Options passed to the plugin init() function.

plugin_serialize_init yes/no#

There could be circumstances where the plugin code is mostly thread-safe, but not on initialization. Libmysqlclient for instance, needs a one-time initialization. To add to the confusion, Qt hides that away.

The plugin should preferrably be written with proper synchronization like that, but as a last resort, you can use this to synchronize initialization.

Default value: true

plugin_serialize_auth_checks yes/no#

Like plugin_serialize_init, but then for all login and ACL checks.

This option may be dropped at some point, because it negates much of the multi-core design. One may as well run with only one thread then.

Default value: false

plugin_timer_period seconds#

The FlashMQ auth plugin interface has a function that is called periodically this amount of seconds. This can be used to refresh state, commit data, etc.

See flashmq_plugin.h for details.

Default value: 60

log_file /path/to/flashmq.log#

This configuration parameter sets the path to FlashMQ's log file. If you omit the, the output will go to stdout.

Default value: /var/log/flashmq/flashmq.log

log_debug yes/no#

Debug logging obviously creates a lot of log noise, so should only be done to diagnose problems.

Default value: false

log_subscriptions yes/no#

Default value: false

allow_unsafe_clientid_chars yes/no#

If you have topics with client IDs in it, people can possibly manipulate your ACL checking by saying their client ID is 'John+foobar'. Audit your security before you allow this.

Default value: false

allow_unsafe_username_chars yes/no#

If you have topics with usernames in it, people can possibly manipulate your ACL checking by saying their username is 'John+foobar'. Audit your security before you allow this.

Default value: false

max_packet_size bytes#

MQTT packets are 256 MB max, approximately. This memory will (temporarily) be allocated upon arrival of such packets, so there may be cause to set it lower.

Default value: 268435461

mosquitto_password_file /foo/bar/mosquitto_password_file#

File with usernames and hashed+salted passwords as generated by Mosquitto's mosquitto_passwd.

Mosquitto up to version 1.6 uses the sha512 algorithm. Newer version use sha512-pbkdf2. Both are supported.

mosquitto_acl_file /foo/bar/mosquitto_acl_file#

ACL (access control lists) for users, anonymous users and patterns expandable with %u (username) and %c (clientid). Format is Mosquitto's acl_file.

allow_anonymous yes/no#

Default value: false

rlimit_nofile number#

The general Linux default of 1024 can be overridden. Note: systemd blocks you from setting it, so it needs to be set on the unit. The default systemd unit file sets LimitNOFILE=infinity. You may also need to set sysctl -w fs.file-max=10000000

Default value: 1000000

expire_sessions_after_seconds seconds#

Expire sessions after this time. Setting to 0 disables it and is (MQTT3) standard-compliant. But, existing sessions cause load on the server (because they cost memory and are still subscribers), so keeping sessions after any client that connects with a random ID doesn't make sense.

Default value: 1209600

quiet yes/no#

Don't log LOG_INFO and LOG_NOTICE. This is useful when you have a lot of foot traffic, because otherwise the log gets filled with connect/disconnect notices.

Default value: false

storage_dir /path/to/dir#

Location to store sessions, subscriptions and retained messages. Not specifying this will turn off persistence.

max_qos_msg_pending_per_client

max_qos_bytes_pending_per_client#

There is a limit to how many QoS packets can be stored in a session, so you can define a maximum amount of messages and bytes. If any of these is exceeded, the packet is dropped.

These are essentially superfluous for MQTT >= 3.1.1 clients with cleansession=true (MQTT 3) / session expirty = 0 (MQTT 5). Because queues would get destroyed upon client disconnect, there is no point in actually queuing them. In those cases, it just allows 65536 'in flight' packets.

Defaults:

max_qos_msg_pending_per_client 512

max_qos_bytes_pending_per_client 65536

max_incoming_topic_alias_value number#

Is communicated towards MQTT5 clients. It is then up to them to decide to set them or not.

Changing this setting and reloading the config only has effect on new clients, because existing clients would otherwise exceed the limit they think applies.

Default value: 65535

max_outgoing_topic_alias_value number#

FlashMQ will make this many aliases per MQTT5 client, if they ask for aliases (with the connect property TopicAliasMaximum).

Default value: 65535

thread_count number#

If you want to have a different amount of worker threads then CPUs, you can set this value. Typically you don't need to set this.

Default value: auto-detect

wills_enabled yes/no#

When disabled, the server will not set last will and testament specified by connecting clients.

Default value: true

retained_messages_mode enabled/downgrade/drop/disconnect_with_error#

Retained messages can be a strain on the server you may not need. You can set various ways of dealing with them:

enabled. This is normal operation.

downgrade. The retain flag is removed and treated like a normal publish.

drop. Messages with retain set are dropped.

disconnect_with_error. Disconnect clients who try to set them.

Default value: enabled

expire_retained_messages_after_seconds seconds#

Use this to limit the life time of retained messages. Without this, the amount of retained messages may never decrease.

Default value: 4294967296

expire_retained_messages_time_budget_ms milliseconds#

When purging the retained messages tree, spend a maximum of this many milliseconds on it. The purge requires a write lock, so you don't want to hold up everything too long.

Currently, the purge frequency is 3949193 milliseconds, but this is subject to change.

Default value: 200

Listen parameters can only be used within listen { } blocks.

port#

The default port depends on the protocol parameter and whether or not fullchain and privkey parameters are supplied:

For unencrypted MQTT, the default port is 1883

For encrypted MQTT, the default port is 8883

For plain HTTP websockets, the default port is 8080

For encrypted HTTPS websockets, the default port is 4443

protocol#

Valid values: mqtt , websockets

inet_protocol#

Valid values: ip4_ip6 , ip4 , ip6

Default: ip4_ip6

inet4_bind_address inet4address#

Default: 0.0.0.0

inet6_bind_address inet6address#

Default: ::0

fullchain /foobar/server.crt#

Specifying a chain makes the listener SSL, and also requires the privkey to be set.

privkey /foobar/server.key#

Specifying a private key makes the listener SSL, and also requires the fullchain to be set.

haproxy yes/no#

Setting the listener to haproxy makes it expect the PROXY protocol and set client source address to the original client. Make sure this listener is private / firewalled, otherwise anybody can set a different source address.

Note that HAProxy's server health checks only started using the 'local' specifier as of version 2.4. This means earlier version will pretend to be a client and break the connection, causing log spam.

See haproxy.org.

listen {
  protocol mqtt
  inet_protocol ip4_ip6
  inet4_bind_address 127.0.0.1
  inet6_bind_address ::1
  fullchain /foobar/server.crt
  privkey /foobar/server.key

  # default = 8883
  port 8883
}
listen {
  protocol mqtt
  inet_protocol ip4

  # default = 1883
  port 1883
}
listen {
  protocol websockets
  fullchain /foobar/server.crt
  privkey /foobar/server.key

  # default = 4443
  port 4443
}
listen {
  protocol websockets

  # default = 8080
  port 8080
}
listen {
  port 2883
  haproxy on
}

Wiebe Cazemier contact@flashmq.org.

flashmq(1)