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

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.

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

shared_subscription_targeting round_robin/sender_hash#

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

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)

www.flashmq.org