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
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
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=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
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
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.
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)