flashmq.conf (5)
FlashMQ configuration file format
Synopsis
The flashmq.conf
file is the configuration used for configuring the FlashMQ MQTT broker. It doesn't necessarily have to be called flashmq.conf
; the flashmq
daemon program sports a --config-file parameter.
File format#
To set a parameter, its name must appear on a single line, followed by whitespace, followed by the parameter value.
parameter-name parameter-value
When setting boolean values, yes/no
, true/false
and on/off
can all be used.
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.
Global parameters#
- 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. Seeflashmq_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
true/false
# -
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
true/false
# -
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
true/false
# -
Debug logging obviously creates a lot of log noise, so should only be done to diagnose problems.
Default value:
false
- log_subscriptions
true/false
# -
Default value:
false
- allow_unsafe_clientid_chars
true/false
# -
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
true/false
# -
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 have a maximum size of about 256 MB. This memory will (temporarily) be allocated upon arrival of such packets, so there may be cause to set it lower.
This option works in conjunction with client_max_write_buffer_size to limit memory use.
Default value:
268435461
- client_max_write_buffer_size
bytes
# -
The client's write buffer is where packets are stored before the event loop has the chance to flush them out. Any time a client's connection is bad and bytes can't be flushed, this buffer fills. So, there's good reason to limit this to something sensible. A good indication is your average packet size (or better yet, a configured max_packet_size) multiplied by the amount of packets you want to be able to buffer.
Note that it's an approximate value and not a hard limit. Buffer sizes only grow by powers of two, and buffers are always allowed to grow to make place for ping packets. Additionally, upon arrival of large packets (up to max_packet_size bytes), room will be made up to twice their size. So, you may also want to reduce max_packet_size from the default.
Default value is
1048576
(1 MB) - 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
true/false
# -
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=10000000Default 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
true/false
# -
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
true/false
# -
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
- websocket_set_real_ip_from
inet4_address/inet6_address
# -
HTTP proxies in front of the websocket listeners can set the
X-Real-IP
header to identify the original connecting client. With websocket_set_real_ip_from you can mark IP networks as trusted. By default, clients are not trusted, to avoid spoofing.You can repeat the option to allow for multiple addresses. Valid notations are
1.2.3.4
,1.2.3.4/16
,1.2.0.0/16
,2a01:1337::1
,2a01:1337::1/64
, etc.The header
X-Forwarded-For
is not used, because that's designed to contain a list of addresses, if applicable.As a side note about using a proxy on your listener; you can only have an absolute max of 65535 connections between two IP addresses (and the practical limit is lower), so if you need more, you'll have to use multiple IP addresses.
-
When having multiple subscribers on a shared subscription (like '$share/myshare/jane/doe'), select how the messages should be distributed over the subscribers.
round_robin
. Select the next subscriber for each message. There is still some amount of randomness to it because the counter for this is not thread safe. Using an atomic/mutexed counter for it would just be too slow to justify.sender_hash
. Selects a receiver deterministically based on the hash of the client ID of the sender. The selected subscriber will depend on how many subscribers there are, so if some disconnect, the distribution will change. Moreover, the selection may also change when FlashMQ cleans up empty spaces in the list of shared subscribers.Default:
round_robin
Listen parameters
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
true/false
# -
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.
Example listeners#
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 }
Author
Wiebe Cazemier contact@flashmq.org.
See also
flashmq(1)