1MOSQUITTO.CONF(5) File formats and conventions MOSQUITTO.CONF(5)
2
6 mosquitto.conf - the configuration file for mosquitto
7
9 mosquitto.conf
10
12 mosquitto.conf is the configuration file for mosquitto. This file can
13 reside anywhere as long as mosquitto can read it. By default, mosquitto
14 does not need a configuration file and will use the default values
15 listed below. See mosquitto(8) for information on how to load a
16 configuration file.
17
19 All lines with a # as the very first character are treated as a
20 comment.
21 Configuration lines start with a variable name. The variable value is
23 separated from the name by a single space.
24
26 The authentication options described below allow a wide range of
27 possibilities in conjunction with the listener options. This section
28 aims to clarify the possibilities.
29 The simplest option is to have no authentication at all. This is the
31 default if no other options are given. Unauthenticated encrypted
32 support is provided by using the certificate based SSL/TLS based
33 options cafile/capath, certfile and keyfile.
34 MQTT provides username/password authentication as part of the protocol.
36 Use the password_file option to define the valid usernames and
37 passwords. Be sure to use network encryption if you are using this
38 option otherwise the username and password will be vulnerable to
39 interception. Use the per_listener_settings to control whether
40 passwords are required globally or on a per-listener basis.
41 When using certificate based encryption there are three options that
43 affect authentication. The first is require_certificate, which may be
44 set to true or false. If false, the SSL/TLS component of the client
45 will verify the server but there is no requirement for the client to
46 provide anything for the server: authentication is limited to the MQTT
47 built in username/password. If require_certificate is true, the client
48 must provide a valid certificate in order to connect successfully. In
49 this case, the second and third options, use_identity_as_username and
50 use_subject_as_username, become relevant. If set to true,
51 use_identity_as_username causes the Common Name (CN) from the client
52 certificate to be used instead of the MQTT username for access control
53 purposes. The password is not used because it is assumed that only
54 authenticated clients have valid certificates. This means that any CA
55 certificates you include in cafile or capath will be able to issue
56 client certificates that are valid for connecting to your broker. If
57 use_identity_as_username is false, the client must authenticate as
58 normal (if required by password_file) through the MQTT options. The
59 same principle applies for the use_subject_as_username option, but the
60 entire certificate subject is used as the username instead of just the
61 CN.
62 When using pre-shared-key based encryption through the psk_hint and
64 psk_file options, the client must provide a valid identity and key in
65 order to connect to the broker before any MQTT communication takes
66 place. If use_identity_as_username is true, the PSK identity is used
67 instead of the MQTT username for access control purposes. If
68 use_identity_as_username is false, the client may still authenticate
69 using the MQTT username/password if using the password_file option.
70 Both certificate and PSK based encryption are configured on a
72 per-listener basis.
73 Authentication plugins can be created to augment the password_file,
75 acl_file and psk_file options with e.g. SQL based lookups.
76 It is possible to support multiple authentication schemes at once. A
78 config could be created that had a listener for all of the different
79 encryption options described above and hence a large number of ways of
80 authenticating.
81
83 acl_file file path
84 Set the path to an access control list file. If defined, the
85 contents of the file are used to control client access to topics on
86 the broker.
87 If this parameter is defined then only the topics listed will have
89 access. Topic access is added with lines of the format:
90 topic [read|write|readwrite] <topic>
92 The access type is controlled using "read", "write" or "readwrite".
94 This parameter is optional (unless <topic> includes a space
95 character) - if not given then the access is read/write. <topic>
96 can contain the + or # wildcards as in subscriptions.
97 The first set of topics are applied to anonymous clients, assuming
99 allow_anonymous is true. User specific topic ACLs are added after a
100 user line as follows:
101 user <username>
103 The username referred to here is the same as in password_file. It
105 is not the clientid.
106 It is also possible to define ACLs based on pattern substitution
108 within the topic. The form is the same as for the topic keyword,
109 but using pattern as the keyword.
110 pattern [read|write|readwrite] <topic>
112 The patterns available for substition are:
114 · %c to match the client id of the client
116 · %u to match the username of the client
118 The substitution pattern must be the only text for that level of
120 hierarchy. Pattern ACLs apply to all users even if the "user"
121 keyword has previously been given.
122 Example:
124 pattern write sensor/%u/data
126 Allow access for bridge connection messages:
128 pattern write $SYS/broker/connection/%c/state
130 If the first character of a line of the ACL file is a # it is
132 treated as a comment.
133 Reloaded on reload signal. The currently loaded ACLs will be freed
135 and reloaded. Existing subscriptions will be affected after the
136 reload.
137 allow_anonymous [ true | false ]
139 Boolean value that determines whether clients that connect without
140 providing a username are allowed to connect. If set to false then
141 another means of connection should be created to control
142 authenticated client access.
143 Defaults to true if no other security options are set. If
145 password_file or psk_file is set, or if an authentication plugin is
146 loaded which implements username/password or TLS-PSK checks, then
147 allow_anonymous defaults to false.
148 Reloaded on reload signal.
150 allow_duplicate_messages [ true | false ]
152 If a client is subscribed to multiple subscriptions that overlap,
153 e.g. foo/# and foo/+/baz , then MQTT expects that when the broker
154 receives a message on a topic that matches both subscriptions, such
155 as foo/bar/baz, then the client should only receive the message
156 once.
157 Mosquitto keeps track of which clients a message has been sent to
159 in order to meet this requirement. This option allows this
160 behaviour to be disabled, which may be useful if you have a large
161 number of clients subscribed to the same set of topics and want to
162 minimise memory usage.
163 It can be safely set to true if you know in advance that your
165 clients will never have overlapping subscriptions, otherwise your
166 clients must be able to correctly deal with duplicate messages even
167 when then have QoS=2.
168 Defaults to true.
170 Reloaded on reload signal.
172 allow_zero_length_clientid [ true | false ]
174 MQTT 3.1.1 allows clients to connect with a zero length client id
175 and have the broker generate a client id for them. Use this option
176 to allow/disallow this behaviour. Defaults to true.
177 See also the auto_id_prefix option.
179 Reloaded on reload signal.
181 auth_opt_* value
183 Options to be passed to the auth plugin. See the specific plugin
184 instructions.
185 auth_plugin file path
187 Specify an external module to use for authentication and access
188 control. This allows custom username/password and access control
189 functions to be created.
190 Can be specified multiple times to load multiple plugins. The
192 plugins will be processed in the order that they are specified.
193 If password_file, or acl_file are used in the config file alongsize
195 auth_plugin, the plugin checks will run after the built in checks.
196 Not currently reloaded on reload signal.
198 auth_plugin_deny_special_chars [ true | false ]
200 If true then before an ACL check is made, the username/client id of
201 the client needing the check is searched for the presence of either
202 a '+' or '#' character. If either of these characters is found in
203 either the username or client id, then the ACL check is denied
204 before it is sent to the plugin.
205 This check prevents the case where a malicious user could
207 circumvent an ACL check by using one of these characters as their
208 username or client id. This is the same issue as was reported with
209 mosquitto itself as CVE-2017-7650.
210 If you are entirely sure that the plugin you are using is not
212 vulnerable to this attack (i.e. if you never use usernames or
213 client ids in topics) then you can disable this extra check and
214 hence have all ACL checks delivered to your plugin by setting this
215 option to false.
216 Defaults to true.
218 Not currently reloaded on reload signal.
220 auto_id_prefix prefix
222 If allow_zero_length_clientid is true, this option allows you to
223 set a string that will be prefixed to the automatically generated
224 client ids to aid visibility in logs. Defaults to auto-.
225 Reloaded on reload signal.
227 autosave_interval seconds
229 The number of seconds that mosquitto will wait between each time it
230 saves the in-memory database to disk. If set to 0, the in-memory
231 database will only be saved when mosquitto exits or when receiving
232 the SIGUSR1 signal. Note that this setting only has an effect if
233 persistence is enabled. Defaults to 1800 seconds (30 minutes).
234 Reloaded on reload signal.
236 autosave_on_changes [ true | false ]
238 If true, mosquitto will count the number of subscription changes,
239 retained messages received and queued messages and if the total
240 exceeds autosave_interval then the in-memory database will be saved
241 to disk. If false, mosquitto will save the in-memory database to
242 disk by treating autosave_interval as a time in seconds.
243 Reloaded on reload signal.
245 check_retain_source [ true | false ]
247 This option affects the scenario when a client subscribes to a
248 topic that has retained messages. It is possible that the client
249 that published the retained message to the topic had access at the
250 time they published, but that access has been subsequently removed.
251 If check_retain_source is set to true, the default, the source of a
252 retained message will be checked for access rights before it is
253 republished. When set to false, no check will be made and the
254 retained message will always be published.
255 This option applies globally, regardless of the
257 per_listener_settings option.
258 clientid_prefixes prefix
260 If defined, only clients that have a clientid with a prefix that
261 matches clientid_prefixes will be allowed to connect to the broker.
262 For example, setting "secure-" here would mean a client
263 "secure-client" could connect but another with clientid "mqtt"
264 couldn't. By default, all client ids are valid.
265 Reloaded on reload signal. Note that currently connected clients
267 will be unaffected by any changes.
268 connection_messages [ true | false ]
270 If set to true, the log will include entries when clients connect
271 and disconnect. If set to false, these entries will not appear.
272 Reloaded on reload signal.
274 include_dir dir
276 External configuration files may be included by using the
277 include_dir option. This defines a directory that will be searched
278 for config files. All files that end in '.conf' will be loaded as a
279 configuration file. It is best to have this as the last option in
280 the main file. This option will only be processed from the main
281 configuration file. The directory specified must not contain the
282 main configuration file.
283 The configuration files in include_dir are loaded in case sensitive
285 alphabetical order, with the upper case of each letter ordered
286 before the lower case of the same letter.
287 Example Load Order for include_dir. Given the files b.conf,
289 A.conf, 01.conf, a.conf, B.conf, and 00.conf inside include_dir,
290 the config files would be loaded in this order:
291 00.conf
293 01.conf
294 A.conf
295 a.conf
296 B.conf
297 b.conf
298 If this option is used multiple times, then each include_dir option
300 is processed completely in the order that they are written in the
301 main configuration file.
302 Example Load Order for Multiple include_dir. Assuming a directory
304 one.d containing files B.conf and C.conf, and a second directory
305 two.d containing files A.conf and D.conf, and a config:
306 include_dir one.d
308 include_dir two.d
309 Then the config files would be loaded in this order:
311 # files from one.d
313 B.conf
314 C.conf
315 # files from two.d
316 A.conf
317 D.conf
318 log_dest destinations
320 Send log messages to a particular destination. Possible
321 destinations are: stdout stderr syslog topic.
322 stdout and stderr log to the console on the named output.
324 syslog uses the userspace syslog facility which usually ends up in
326 /var/log/messages or similar and topic logs to the broker topic
327 '$SYS/broker/log/<severity>', where severity is one of D, E, W, N,
328 I, M which are debug, error, warning, notice, information and
329 message. Message type severity is used by the subscribe and
330 unsubscribe log_type options and publishes log messages at
331 $SYS/broker/log/M/subscribe and $SYS/broker/log/M/unsubscribe.
332 The file destination requires an additional parameter which is the
334 file to be logged to, e.g. "log_dest file /var/log/mosquitto.log".
335 The file will be closed and reopened when the broker receives a HUP
336 signal. Only a single file destination may be configured.
337 Use "log_dest none" if you wish to disable logging. Defaults to
339 stderr. This option may be specified multiple times.
340 Note that if the broker is running as a Windows service it will
342 default to "log_dest none" and neither stdout nor stderr logging is
343 available.
344 Reloaded on reload signal.
346 log_facility local facility
348 If using syslog logging (not on Windows), messages will be logged
349 to the "daemon" facility by default. Use the log_facility option to
350 choose which of local0 to local7 to log to instead. The option
351 value should be an integer value, e.g. "log_facility 5" to use
352 local5.
353 log_timestamp [ true | false ]
355 Boolean value, if set to true a timestamp value will be added to
356 each log entry. The default is true.
357 Reloaded on reload signal.
359 log_timestamp_format format
361 Set the format of the log timestamp. If left unset, this is the
362 number of seconds since the Unix epoch. This option is a free text
363 string which will be passed to the strftime function as the format
364 specifier. To get an ISO 8601 datetime, for example:
365 log_timestamp_format %Y-%m-%dT%H:%M:%S
367 Reloaded on reload signal.
370 log_type types
372 Choose types of messages to log. Possible types are: debug, error,
373 warning, notice, information, subscribe, unsubscribe, websockets,
374 none, all.
375 Defaults to error, warning, notice and information. This option may
377 be specified multiple times. Note that the debug type (used for
378 decoding incoming/outgoing network packets) is never logged in
379 topics.
380 Reloaded on reload signal.
382 max_inflight_bytes count
384 QoS 1 and 2 messages will be allowed in flight until this byte
385 limit is reached. Defaults to 0. (No limit) See also the
386 max_inflight_messages option.
387 Reloaded on reload signal.
389 max_inflight_messages count
391 The maximum number of QoS 1 or 2 messages that can be in the
392 process of being transmitted simultaneously. This includes messages
393 currently going through handshakes and messages that are being
394 retried. Defaults to 20. Set to 0 for no maximum. If set to 1, this
395 will guarantee in-order delivery of messages.
396 Reloaded on reload signal.
398 max_keepalive value
400 For MQTT v5 clients, it is possible to have the server send a
401 "server keepalive" value that will override the keepalive value set
402 by the client. This is intended to be used as a mechanism to say
403 that the server will disconnect the client earlier than it
404 anticipated, and that the client should use the new keepalive
405 value. The max_keepalive option allows you to specify that clients
406 may only connect with keepalive less than or equal to this value,
407 otherwise they will be sent a server keepalive telling them to use
408 max_keepalive. This only applies to MQTT v5 clients. The maximum
409 value allowable, and default value, is 65535. Do not set below 10
410 seconds.
411 Reloaded on reload signal.
413 max_packet_size value
415 For MQTT v5 clients, it is possible to have the server send a
416 "maximum packet size" value that will instruct the client it will
417 not accept MQTT packets with size greater than value bytes. This
418 applies to the full MQTT packet, not just the payload. Setting this
419 option to a positive value will set the maximum packet size to that
420 number of bytes. If a client sends a packet which is larger than
421 this value, it will be disconnected. This applies to all clients
422 regardless of the protocol version they are using, but v3.1.1 and
423 earlier clients will of course not have received the maximum packet
424 size information. Defaults to no limit.
425 Setting below 20 bytes is forbidden because it is likely to
427 interfere with normal client operation even with small payloads.
428 Reloaded on reload signal.
430 max_queued_bytes count
432 QoS 1 and 2 messages above those currently in-flight will be queued
433 (per client) until this limit is exceeded. Defaults to 0. (No
434 maximum) See also the max_queued_messages option. If both
435 max_queued_messages and max_queued_bytes are specified, packets
436 will be queued until the first limit is reached.
437 Reloaded on reload signal.
439 max_queued_messages count
441 The maximum number of QoS 1 or 2 messages to hold in the queue (per
442 client) above those messages that are currently in flight. Defaults
443 to 100. Set to 0 for no maximum (not recommended). See also the
444 queue_qos0_messages and max_queued_bytes options.
445 Reloaded on reload signal.
447 memory_limit limit
449 This option sets the maximum number of heap memory bytes that the
450 broker will allocate, and hence sets a hard limit on memory use by
451 the broker. Memory requests that exceed this value will be denied.
452 The effect will vary depending on what has been denied. If an
453 incoming message is being processed, then the message will be
454 dropped and the publishing client will be disconnected. If an
455 outgoing message is being sent, then the individual message will be
456 dropped and the receiving client will be disconnected. Defaults to
457 no limit.
458 This option is only available if memory tracking support is
460 compiled in.
461 Reloaded on reload signal. Setting to a lower value and reloading
463 will not result in memory being freed.
464 message_size_limit limit
466 This option sets the maximum publish payload size that the broker
467 will allow. Received messages that exceed this size will not be
468 accepted by the broker. The default value is 0, which means that
469 all valid MQTT messages are accepted. MQTT imposes a maximum
470 payload size of 268435455 bytes.
471 password_file file path
473 Set the path to a password file. If defined, the contents of the
474 file are used to control client access to the broker. The file can
475 be created using the mosquitto_passwd(1) utility. If mosquitto is
476 compiled without TLS support (it is recommended that TLS support is
477 included), then the password file should be a text file with each
478 line in the format "username:password", where the colon and
479 password are optional but recommended. If allow_anonymous is set to
480 false, only users defined in this file will be able to connect.
481 Setting allow_anonymous to true when password_fileis defined is
482 valid and could be used with acl_file to have e.g. read only
483 guest/anonymous accounts and defined users that can publish.
484 Reloaded on reload signal. The currently loaded username and
486 password data will be freed and reloaded. Clients that are already
487 connected will not be affected.
488 See also mosquitto_passwd(1).
490 per_listener_settings [ true | false ]
492 If true, then authentication and access control settings will be
493 controlled on a per-listener basis. The following options are
494 affected:
495 password_file, acl_file, psk_file, allow_anonymous,
497 allow_zero_length_clientid, auth_plugin, auth_opt_*,
498 auto_id_prefix.
499 Note that if set to true, then a durable client (i.e. with clean
501 session set to false) that has disconnected will use the ACL
502 settings defined for the listener that it was most recently
503 connected to.
504 The default behaviour is for this to be set to false, which
506 maintains the settings behaviour from previous versions of
507 mosquitto.
508 Reloaded on reload signal.
510 persistence [ true | false ]
512 If true, connection, subscription and message data will be written
513 to the disk in mosquitto.db at the location dictated by
514 persistence_location. When mosquitto is restarted, it will reload
515 the information stored in mosquitto.db. The data will be written to
516 disk when mosquitto closes and also at periodic intervals as
517 defined by autosave_interval. Writing of the persistence database
518 may also be forced by sending mosquitto the SIGUSR1 signal. If
519 false, the data will be stored in memory only. Defaults to false.
520 Reloaded on reload signal.
522 persistence_file file name
524 The filename to use for the persistent database. Defaults to
525 mosquitto.db.
526 Reloaded on reload signal.
528 persistence_location path
530 The path where the persistence database should be stored. Must end
531 in a trailing slash. If not given, then the current directory is
532 used.
533 Reloaded on reload signal.
535 persistent_client_expiration duration
537 This option allows persistent clients (those with clean session set
538 to false) to be removed if they do not reconnect within a certain
539 time frame. This is a non-standard option. As far as the MQTT spec
540 is concerned, persistent clients persist forever.
541 Badly designed clients may set clean session to false whilst using
543 a randomly generated client id. This leads to persistent clients
544 that will never reconnect. This option allows these clients to be
545 removed.
546 The expiration period should be an integer followed by one of h d w
548 m y for hour, day, week, month and year respectively. For example:
549 · persistent_client_expiration 2m
551 · persistent_client_expiration 14d
553 · persistent_client_expiration 1y
555 As this is a non-standard option, the default if not set is to
557 never expire persistent clients.
558 Reloaded on reload signal.
560 pid_file file path
562 Write a pid file to the file specified. If not given (the default),
563 no pid file will be written. If the pid file cannot be written,
564 mosquitto will exit. This option only has an effect is mosquitto is
565 run in daemon mode.
566 If mosquitto is being automatically started by an init script it
568 will usually be required to write a pid file. This should then be
569 configured as e.g. /var/run/mosquitto.pid
570 Not reloaded on reload signal.
572 psk_file file path
574 Set the path to a pre-shared-key file. This option requires a
575 listener to be have PSK support enabled. If defined, the contents
576 of the file are used to control client access to the broker. Each
577 line should be in the format "identity:key", where the key is a
578 hexadecimal string with no leading "0x". A client connecting to a
579 listener that has PSK support enabled must provide a matching
580 identity and PSK to allow the encrypted connection to proceed.
581 Reloaded on reload signal. The currently loaded identity and key
583 data will be freed and reloaded. Clients that are already connected
584 will not be affected.
585 queue_qos0_messages [ true | false ]
587 Set to true to queue messages with QoS 0 when a persistent client
588 is disconnected. These messages are included in the limit imposed
589 by max_queued_messages. Defaults to false.
590 Note that the MQTT v3.1.1 spec states that only QoS 1 and 2
592 messages should be saved in this situation so this is a
593 non-standard option.
594 Reloaded on reload signal.
596 retain_available [ true | false ]
598 If set to false, then retained messages are not supported. Clients
599 that send a message with the retain bit will be disconnected if
600 this option is set to false. Defaults to true.
601 Reloaded on reload signal.
603 retained_persistence [ true | false ]
605 This is a synonym of the persistence option.
606 Reloaded on reload signal.
608 set_tcp_nodelay [ true | false ]
610 If set to true, the TCP_NODELAY option will be set on client
611 sockets to disable Nagle's algorithm. This has the effect of
612 reducing latency of some messages at potentially increasing the
613 number of TCP packets being sent. Defaults to false.
614 Reloaded on reload signal.
616 store_clean_interval seconds
618 The integer number of seconds between the internal message store
619 being cleaned of messages that are no longer referenced. Lower
620 values will result in lower memory usage but more processor time,
621 higher values will have the opposite effect. Setting a value of 0
622 means the unreferenced messages will be disposed of as quickly as
623 possible. Defaults to 10 seconds.
624 Reloaded on reload signal.
626 sys_interval seconds
628 The integer number of seconds between updates of the $SYS
629 subscription hierarchy, which provides status information about the
630 broker. If unset, defaults to 10 seconds.
631 Set to 0 to disable publishing the $SYS hierarchy completely.
633 Reloaded on reload signal.
635 upgrade_outgoing_qos [ true | false ]
637 The MQTT specification requires that the QoS of a message delivered
638 to a subscriber is never upgraded to match the QoS of the
639 subscription. Enabling this option changes this behaviour. If
640 upgrade_outgoing_qos is set true, messages sent to a subscriber
641 will always match the QoS of its subscription. This is a
642 non-standard option not provided for by the spec. Defaults to
643 false.
644 Reloaded on reload signal.
646 user username
648 When run as root, change to this user and its primary group on
649 startup. If mosquitto is unable to change to this user and group,
650 it will exit with an error. The user specified must have read/write
651 access to the persistence database if it is to be written. If run
652 as a non-root user, this setting has no effect. Defaults to
653 mosquitto.
654 This setting has no effect on Windows and so you should run
656 mosquitto as the user you wish it to run as.
657 Not reloaded on reload signal.
659
661 The network ports that mosquitto listens on can be controlled using
662 listeners. The default listener options can be overridden and further
663 listeners can be created.
664 General Options
666 bind_address address
667 Listen for incoming network connections on the specified IP
668 address/hostname only. This is useful to restrict access to certain
669 network interfaces. To restrict access to mosquitto to the local
670 host only, use "bind_address localhost". This only applies to the
671 default listener. Use the listener variable to control other
672 listeners.
673 Not reloaded on reload signal.
675 bind_interface device
677 Listen for incoming network connections only on the specified
678 interface. This is similar to the bind_address option but is useful
679 when an interface has multiple addresses or the address may change.
680 It is valid to use this option together with bind_address for the
682 default listener, or the bind address/host part of the listener
683 definition. Care should be taken to ensure that the address being
684 bound to is on the interface being bound to. If you set the
685 bind_interface to be eth0, and bind_address to 127.0.0.1, then the
686 broker will start correctly but you will be unable to connect.
687 This option is currently only available on Linux, and requires
689 elevated privileges.
690 Not reloaded on reload signal.
692 http_dir directory
694 When a listener is using the websockets protocol, it is possible to
695 serve http data as well. Set http_dir to a directory which contains
696 the files you wish to serve. If this option is not specified, then
697 no normal http connections will be possible.
698 Not reloaded on reload signal.
700 listener port [bind address/host]
702 Listen for incoming network connection on the specified port. A
703 second optional argument allows the listener to be bound to a
704 specific ip address/hostname. If this variable is used and neither
705 the global bind_address nor port options are used then the default
706 listener will not be started.
707 The bind address/host option allows this listener to be bound to a
709 specific IP address by passing an IP address or hostname. For
710 websockets listeners, it is only possible to pass an IP address
711 here.
712 This option may be specified multiple times. See also the
714 mount_point option.
715 Not reloaded on reload signal.
717 max_connections count
719 Limit the total number of clients connected for the current
720 listener. Set to -1 to have "unlimited" connections. Note that
721 other limits may be imposed that are outside the control of
722 mosquitto. See e.g. limits.conf(5).
723 Not reloaded on reload signal.
725 maximum_qos count
727 Limit the QoS value allowed when using this listener. Defaults to
728 2, which means any QoS can be used. Set to 0 or 1 to limit to those
729 QoS values. This makes use of an MQTT v5 feature to notify clients
730 of the limitation. MQTT v3.1.1 clients will not be aware of the
731 limitation. Clients publshing to this listener with a too-high QoS
732 will be disconnected.
733 Not reloaded on reload signal.
735 max_topic_alias number
737 This option sets the maximum number topic aliases that an MQTT v5
738 client is allowed to create. It applies per listener. Defaults to
739 10. Set to 0 to disallow topic aliases.
740 Not reloaded on reload signal.
742 mount_point topic prefix
744 This option is used with the listener option to isolate groups of
745 clients. When a client connects to a listener which uses this
746 option, the string argument is attached to the start of all topics
747 for this client. This prefix is removed when any messages are sent
748 to the client. This means a client connected to a listener with
749 mount point example can only see messages that are published in the
750 topic hierarchy example and below.
751 Not reloaded on reload signal.
753 port port number
755 Set the network port for the default listener to listen on.
756 Defaults to 1883.
757 Not reloaded on reload signal.
759 protocol value
761 Set the protocol to accept for this listener. Can be mqtt, the
762 default, or websockets if available.
763 Websockets support is currently disabled by default at compile
765 time. Certificate based TLS may be used with websockets, except
766 that only the cafile, certfile, keyfile and ciphers options are
767 supported.
768 Not reloaded on reload signal.
770 socket_domain [ ipv4 | ipv6 ]
772 By default, a listener will attempt to listen on all supported IP
773 protocol versions. If you do not have an IPv4 or IPv6 interface you
774 may wish to disable support for either of those protocol versions.
775 In particular, note that due to the limitations of the websockets
776 library, it will only ever attempt to open IPv6 sockets if IPv6
777 support is compiled in, and so will fail if IPv6 is not available.
778 Set to ipv4 to force the listener to only use IPv4, or set to ipv6
780 to force the listener to only use IPv6. If you want support for
781 both IPv4 and IPv6, then do not use the socket_domain option.
782 Not reloaded on reload signal.
784 use_username_as_clientid [ true | false ]
786 Set use_username_as_clientid to true to replace the clientid that a
787 client connected with with its username. This allows authentication
788 to be tied to the clientid, which means that it is possible to
789 prevent one client disconnecting another by using the same
790 clientid. Defaults to false.
791 If a client connects with no username it will be disconnected as
793 not authorised when this option is set to true. Do not use in
794 conjunction with clientid_prefixes.
795 See also use_identity_as_username.
797 Not reloaded on reload signal.
799 websockets_log_level level
801 Change the websockets logging level. This is a global option, it is
802 not possible to set per listener. This is an integer that is
803 interpreted by libwebsockets as a bit mask for its lws_log_levels
804 enum. See the libwebsockets documentation for more details.
805 To use this option, log_type websockets must also be enabled.
807 Defaults to 0.
808 websockets_headers_size size
810 Change the websockets headers size. This is a global option, it is
811 not possible to set per listener. This option sets the size of the
812 buffer used in the libwebsockets library when reading HTTP headers.
813 If you are passing large header data such as cookies then you may
814 need to increase this value. If left unset, or set to 0, then the
815 default of 1024 bytes will be used.
816 Certificate based SSL/TLS Support
818 The following options are available for all listeners to configure
819 certificate based SSL support. See also "Pre-shared-key based SSL/TLS
820 support".
821 cafile file path
823 At least one of cafile or capath must be provided to allow SSL
824 support.
825 cafile is used to define the path to a file containing the PEM
827 encoded CA certificates that are trusted.
828 capath directory path
830 At least one of cafile or capath must be provided to allow SSL
831 support.
832 capath is used to define a directory that contains PEM encoded CA
834 certificates that are trusted. For capath to work correctly, the
835 certificates files must have ".pem" as the file ending and you must
836 run "openssl rehash <path to capath>" each time you add/remove a
837 certificate.
838 certfile file path
840 Path to the PEM encoded server certificate.
841 ciphers cipher:list
843 The list of allowed ciphers, each separated with a colon. Available
844 ciphers can be obtained using the "openssl ciphers" command.
845 crlfile file path
847 If you have require_certificate set to true, you can create a
848 certificate revocation list file to revoke access to particular
849 client certificates. If you have done this, use crlfile to point to
850 the PEM encoded revocation file.
851 dhparamfile file path
853 To allow the use of ephemeral DH key exchange, which provides
854 forward security, the listener must load DH parameters. This can be
855 specified with the dhparamfile option. The dhparamfile can be
856 generated with the command e.g.
857 openssl dhparam -out dhparam.pem 2048
859 keyfile file path
861 Path to the PEM encoded keyfile.
862 require_certificate [ true | false ]
864 By default an SSL/TLS enabled listener will operate in a similar
865 fashion to a https enabled web server, in that the server has a
866 certificate signed by a CA and the client will verify that it is a
867 trusted certificate. The overall aim is encryption of the network
868 traffic. By setting require_certificate to true, the client must
869 provide a valid certificate in order for the network connection to
870 proceed. This allows access to the broker to be controlled outside
871 of the mechanisms provided by MQTT.
872 tls_engine engine
874 A valid openssl engine id. These can be listed with openssl engine
875 command.
876 tls_engine_kpass_sha1 engine_kpass_sha1
878 SHA1 of the private key password when using an TLS engine. Some TLS
879 engines such as the TPM engine may require the use of a password in
880 order to be accessed. This option allows a hex encoded SHA1 hash of
881 the password to the engine directly, instead of the user being
882 prompted for the password.
883 tls_keyform [ pem | engine ]
885 Specifies the type of private key in use when making TLS
886 connections.. This can be "pem" or "engine". This parameter is
887 useful when a TPM module is being used and the private key has been
888 created with it. Defaults to "pem", which means normal private key
889 files are used.
890 tls_version version
892 Configure the version of the TLS protocol to be used for this
893 listener. Possible values are tlsv1.3, tlsv1.2 and tlsv1.1. If left
894 unset, the default of allowing all of TLS v1.3, v1.2 and v1.1 is
895 used.
896 use_identity_as_username [ true | false ]
898 If require_certificate is true, you may set
899 use_identity_as_username to true to use the CN value from the
900 client certificate as a username. If this is true, the
901 password_file option will not be used for this listener.
902 This takes priority over use_subject_as_username if both are set to
904 true.
905 See also use_subject_as_username
907 use_subject_as_username [ true | false ]
909 If require_certificate is true, you may set use_subject_as_username
910 to true to use the complete subject value from the client
911 certificate as a username. If this is true, the password_file
912 option will not be used for this listener.
913 The subject will be generated in a form similar to CN=test
915 client,OU=Production,O=Server,L=Nottingham,ST=Nottinghamshire,C=GB.
916 See also use_identity_as_username
918 Pre-shared-key based SSL/TLS Support
920 The following options are available for all listeners to configure
921 pre-shared-key based SSL support. See also "Certificate based SSL/TLS
922 support".
923 ciphers cipher:list
925 When using PSK, the encryption ciphers used will be chosen from the
926 list of available PSK ciphers. If you want to control which ciphers
927 are available, use this option. The list of available ciphers can
928 be optained using the "openssl ciphers" command and should be
929 provided in the same format as the output of that command.
930 psk_hint hint
932 The psk_hint option enables pre-shared-key support for this
933 listener and also acts as an identifier for this listener. The hint
934 is sent to clients and may be used locally to aid authentication.
935 The hint is a free form string that doesn't have much meaning in
936 itself, so feel free to be creative.
937 If this option is provided, see psk_file to define the pre-shared
939 keys to be used or create a security plugin to handle them.
940 tls_version version
942 Configure the version of the TLS protocol to be used for this
943 listener. Possible values are tlsv1.3, tlsv1.2 and tlsv1.1. If left
944 unset, the default of allowing all of TLS v1.3, v1.2 and v1.1 is
945 used.
946 use_identity_as_username [ true | false ]
948 Set use_identity_as_username to have the psk identity sent by the
949 client used as its username. The username will be checked as
950 normal, so password_file or another means of authentication
951 checking must be used. No password will be used.
952
954 Multiple bridges (connections to other brokers) can be configured using
955 the following variables.
956 Bridges cannot currently be reloaded on reload signal.
958 address address[:port] [address[:port]], addresses address[:port]
960 [address[:port]]
961 Specify the address and optionally the port of the bridge to
962 connect to. This must be given for each bridge connection. If the
963 port is not specified, the default of 1883 is used.
964 If you use an IPv6 address, then the port is not optional.
966 Multiple host addresses can be specified on the address config. See
968 the round_robin option for more details on the behaviour of bridges
969 with multiple addresses.
970 bridge_attempt_unsubscribe [ true | false ]
972 If a bridge has topics that have "out" direction, the default
973 behaviour is to send an unsubscribe request to the remote broker on
974 that topic. This means that changing a topic direction from "in" to
975 "out" will not keep receiving incoming messages. Sending these
976 unsubscribe requests is not always desirable, setting
977 bridge_attempt_unsubscribe to false will disable sending the
978 unsubscribe request. Defaults to true.
979 bridge_protocol_version version
981 Set the version of the MQTT protocol to use with for this bridge.
982 Can be one of mqttv31 or mqttv311. Defaults to mqttv31.
983 cleansession [ true | false ]
985 Set the clean session option for this bridge. Setting to false (the
986 default), means that all subscriptions on the remote broker are
987 kept in case of the network connection dropping. If set to true,
988 all subscriptions and messages on the remote broker will be cleaned
989 up if the connection drops. Note that setting to true may cause a
990 large amount of retained messages to be sent each time the bridge
991 reconnects.
992 If you are using bridges with cleansession set to false (the
994 default), then you may get unexpected behaviour from incoming
995 topics if you change what topics you are subscribing to. This is
996 because the remote broker keeps the subscription for the old topic.
997 If you have this problem, connect your bridge with cleansession set
998 to true, then reconnect with cleansession set to false as normal.
999 connection name
1001 This variable marks the start of a new bridge connection. It is
1002 also used to give the bridge a name which is used as the client id
1003 on the remote broker.
1004 keepalive_interval seconds
1006 Set the number of seconds after which the bridge should send a ping
1007 if no other traffic has occurred. Defaults to 60. A minimum value
1008 of 5 seconds is allowed.
1009 idle_timeout seconds
1011 Set the amount of time a bridge using the lazy start type must be
1012 idle before it will be stopped. Defaults to 60 seconds.
1013 local_clientid id
1015 Set the clientid to use on the local broker. If not defined, this
1016 defaults to local.<remote_clientid>. If you are bridging a broker
1017 to itself, it is important that local_clientid and remote_clientid
1018 do not match.
1019 local_password password
1021 Configure the password to be used when connecting this bridge to
1022 the local broker. This may be important when authentication and
1023 ACLs are being used.
1024 local_username username
1026 Configure the username to be used when connecting this bridge to
1027 the local broker. This may be important when authentication and
1028 ACLs are being used.
1029 notifications [ true | false ]
1031 If set to true, publish notification messages to the local and
1032 remote brokers giving information about the state of the bridge
1033 connection. Retained messages are published to the topic
1034 $SYS/broker/connection/<remote_clientid>/state unless otherwise set
1035 with notification_topics. If the message is 1 then the connection
1036 is active, or 0 if the connection has failed. Defaults to true.
1037 This uses the Last Will and Testament (LWT) feature.
1039 notifications_local_only [ true | false ]
1041 If set to true, only publish notification messages to the local
1042 broker giving information about the state of the bridge connection.
1043 Defaults to false.
1044 notification_topic topic
1046 Choose the topic on which notifications will be published for this
1047 bridge. If not set the messages will be sent on the topic
1048 $SYS/broker/connection/<remote_clientid>/state.
1049 remote_clientid id
1051 Set the client id for this bridge connection. If not defined, this
1052 defaults to 'name.hostname', where name is the connection name and
1053 hostname is the hostname of this computer.
1054 This replaces the old "clientid" option to avoid confusion with
1056 local/remote sides of the bridge. "clientid" remains valid for the
1057 time being.
1058 remote_password value
1060 Configure a password for the bridge. This is used for
1061 authentication purposes when connecting to a broker that supports
1062 MQTT v3.1 and up and requires a username and/or password to
1063 connect. This option is only valid if a remote_username is also
1064 supplied.
1065 This replaces the old "password" option to avoid confusion with
1067 local/remote sides of the bridge. "password" remains valid for the
1068 time being.
1069 remote_username name
1071 Configure a username for the bridge. This is used for
1072 authentication purposes when connecting to a broker that supports
1073 MQTT v3.1 and up and requires a username and/or password to
1074 connect. See also the remote_password option.
1075 This replaces the old "username" option to avoid confusion with
1077 local/remote sides of the bridge. "username" remains valid for the
1078 time being.
1079 restart_timeout base cap, restart_timeout constant
1081 Set the amount of time a bridge using the automatic start type will
1082 wait until attempting to reconnect.
1083 This option can be configured to use a constant delay time in
1085 seconds, or to use a backoff mechanism based on "Decorrelated
1086 Jitter", which adds a degree of randomness to when the restart
1087 occurs, starting at the base and increasing up to the cap. Set a
1088 constant timeout of 20 seconds:
1089 restart_timeout 20
1091 Set backoff with a base (start value) of 10 seconds and a cap
1093 (upper limit) of 60 seconds:
1094 restart_timeout 10 30
1096 Defaults to jitter with a base of 5 seconds and cap of 30 seconds.
1098 round_robin [ true | false ]
1100 If the bridge has more than one address given in the
1101 address/addresses configuration, the round_robin option defines the
1102 behaviour of the bridge on a failure of the bridge connection. If
1103 round_robin is false, the default value, then the first address is
1104 treated as the main bridge connection. If the connection fails, the
1105 other secondary addresses will be attempted in turn. Whilst
1106 connected to a secondary bridge, the bridge will periodically
1107 attempt to reconnect to the main bridge until successful.
1108 If round_robin is true, then all addresses are treated as equals.
1110 If a connection fails, the next address will be tried and if
1111 successful will remain connected until it fails.
1112 start_type [ automatic | lazy | once ]
1114 Set the start type of the bridge. This controls how the bridge
1115 starts and can be one of three types: automatic, lazy and once.
1116 Note that RSMB provides a fourth start type "manual" which isn't
1117 currently supported by mosquitto.
1118 automatic is the default start type and means that the bridge
1120 connection will be started automatically when the broker starts and
1121 also restarted after a short delay (30 seconds) if the connection
1122 fails.
1123 Bridges using the lazy start type will be started automatically
1125 when the number of queued messages exceeds the number set with the
1126 threshold option. It will be stopped automatically after the time
1127 set by the idle_timeout parameter. Use this start type if you wish
1128 the connection to only be active when it is needed.
1129 A bridge using the once start type will be started automatically
1131 when the broker starts but will not be restarted if the connection
1132 fails.
1133 threshold count
1135 Set the number of messages that need to be queued for a bridge with
1136 lazy start type to be restarted. Defaults to 10 messages.
1137 topic pattern [[[ out | in | both ] qos-level] local-prefix
1139 remote-prefix]
1140 Define a topic pattern to be shared between the two brokers. Any
1141 topics matching the pattern (which may include wildcards) are
1142 shared. The second parameter defines the direction that the
1143 messages will be shared in, so it is possible to import messages
1144 from a remote broker using in, export messages to a remote broker
1145 using out or share messages in both directions. If this parameter
1146 is not defined, the default of out is used. The QoS level defines
1147 the publish/subscribe QoS level used for this topic and defaults to
1148 0.
1149 The local-prefix and remote-prefix options allow topics to be
1151 remapped when publishing to and receiving from remote brokers. This
1152 allows a topic tree from the local broker to be inserted into the
1153 topic tree of the remote broker at an appropriate place.
1154 For incoming topics, the bridge will prepend the pattern with the
1156 remote prefix and subscribe to the resulting topic on the remote
1157 broker. When a matching incoming message is received, the remote
1158 prefix will be removed from the topic and then the local prefix
1159 added.
1160 For outgoing topics, the bridge will prepend the pattern with the
1162 local prefix and subscribe to the resulting topic on the local
1163 broker. When an outgoing message is processed, the local prefix
1164 will be removed from the topic then the remote prefix added.
1165 When using topic mapping, an empty prefix can be defined using the
1167 place marker "". Using the empty marker for the topic itself is
1168 also valid. The table below defines what combination of empty or
1169 value is valid. The Full Local Topic and Full Remote Topic show the
1170 resulting topics that would be used on the local and remote ends of
1171 the bridge. For example, for the first table row if you publish to
1172 L/topic on the local broker, then the remote broker will receive a
1173 message on the topic R/topic.
1174 ┌────────┬────────┬────────┬─────────────┬────────────┬─────────────┐
1176 │Pattern │ Local │ Remote │ Validity │ Full Local │ Full Remote │
1177 │ │ Prefix │ Prefix │ │ Topic │ Topic │
1178 ├────────┼────────┼────────┼─────────────┼────────────┼─────────────┤
1179 │pattern │ L/ │ R/ │ valid │ L/pattern │ R/pattern │
1180 ├────────┼────────┼────────┼─────────────┼────────────┼─────────────┤
1181 │pattern │ L/ │ "" │ valid │ L/pattern │ pattern │
1182 ├────────┼────────┼────────┼─────────────┼────────────┼─────────────┤
1183 │pattern │ "" │ R/ │ valid │ pattern │ R/pattern │
1184 ├────────┼────────┼────────┼─────────────┼────────────┼─────────────┤
1185 │pattern │ "" │ "" │ valid (no │ pattern │ pattern │
1186 │ │ │ │ remapping) │ │ │
1187 ├────────┼────────┼────────┼─────────────┼────────────┼─────────────┤
1188 │"" │ local │ remote │ valid │ local │ remote │
1189 │ │ │ │ (remap │ │ │
1190 │ │ │ │ single │ │ │
1191 │ │ │ │ local topic │ │ │
1192 │ │ │ │ to remote) │ │ │
1193 ├────────┼────────┼────────┼─────────────┼────────────┼─────────────┤
1194 │"" │ local │ "" │ invalid │ │ │
1195 ├────────┼────────┼────────┼─────────────┼────────────┼─────────────┤
1196 │"" │ "" │ remote │ invalid │ │ │
1197 ├────────┼────────┼────────┼─────────────┼────────────┼─────────────┤
1198 │"" │ "" │ "" │ invalid │ │ │
1199 └────────┴────────┴────────┴─────────────┴────────────┴─────────────┘
1200 To remap an entire topic tree, use e.g.:
1201 topic # both 2 local/topic/ remote/topic/
1203 This option can be specified multiple times per bridge.
1205 Care must be taken to ensure that loops are not created with this
1207 option. If you are experiencing high CPU load from a broker, it is
1208 possible that you have a loop where each broker is forever
1209 forwarding each other the same messages.
1210 See also the cleansession option if you have messages arriving on
1212 unexpected topics when using incoming topics.
1213 Example Bridge Topic Remapping. The configuration below connects a
1215 bridge to the broker at test.mosquitto.org. It subscribes to the
1216 remote topic $SYS/broker/clients/total and republishes the messages
1217 received to the local topic test/mosquitto/org/clients/total
1218 connection test-mosquitto-org
1220 address test.mosquitto.org
1221 cleansession true
1222 topic clients/total in 0 test/mosquitto/org $SYS/broker/
1223 try_private [ true | false ]
1225 If try_private is set to true, the bridge will attempt to indicate
1226 to the remote broker that it is a bridge not an ordinary client. If
1227 successful, this means that loop detection will be more effective
1228 and that retained messages will be propagated correctly. Not all
1229 brokers support this feature so it may be necessary to set
1230 try_private to false if your bridge does not connect properly.
1231 Defaults to true.
1233 SSL/TLS Support
1235 The following options are available for all bridges to configure
1236 SSL/TLS support.
1237 bridge_alpn alpn
1239 Configure the application layer protocol negotiation option for the
1240 TLS session. Useful for brokers that support both websockets and
1241 MQTT on the same port.
1242 bridge_cafile file path
1244 One of bridge_cafile or bridge_capath must be provided to allow
1245 SSL/TLS support.
1246 bridge_cafile is used to define the path to a file containing the
1248 PEM encoded CA certificates that have signed the certificate for
1249 the remote broker.
1250 bridge_capath file path
1252 One of bridge_capath or bridge_capath must be provided to allow
1253 SSL/TLS support.
1254 bridge_capath is used to define the path to a directory containing
1256 the PEM encoded CA certificates that have signed the certificate
1257 for the remote broker. For bridge_capath to work correctly, the
1258 certificate files must have ".crt" as the file ending and you must
1259 run "openssl rehash <path to bridge_capath>" each time you
1260 add/remove a certificate.
1261 bridge_certfile file path
1263 Path to the PEM encoded client certificate for this bridge, if
1264 required by the remote broker.
1265 bridge_identity identity
1267 Pre-shared-key encryption provides an alternative to certificate
1268 based encryption. A bridge can be configured to use PSK with the
1269 bridge_identity and bridge_psk options. This is the client identity
1270 used with PSK encryption. Only one of certificate and PSK based
1271 encryption can be used on one bridge at once.
1272 bridge_insecure [ true | false ]
1274 When using certificate based TLS, the bridge will attempt to verify
1275 the hostname provided in the remote certificate matches the
1276 host/address being connected to. This may cause problems in testing
1277 scenarios, so bridge_insecure may be set to false to disable the
1278 hostname verification.
1279 Setting this option to true means that a malicious third party
1281 could potentially inpersonate your server, so it should always be
1282 set to false in production environments.
1283 bridge_keyfile file path
1285 Path to the PEM encoded private key for this bridge, if required by
1286 the remote broker.
1287 bridge_psk key
1289 Pre-shared-key encryption provides an alternative to certificate
1290 based encryption. A bridge can be configured to use PSK with the
1291 bridge_identity and bridge_psk options. This is the pre-shared-key
1292 in hexadecimal format with no "0x". Only one of certificate and PSK
1293 based encryption can be used on one bridge at once.
1294 bridge_require_ocsp [ true | false ]
1296 When set to true, the bridge requires OCSP on the TLS connection it
1297 opens as client.
1298 bridge_tls_version version
1300 Configure the version of the TLS protocol to be used for this
1301 bridge. Possible values are tlsv1.3, tlsv1.2 and tlsv1.1. Defaults
1302 to tlsv1.2. The remote broker must support the same version of TLS
1303 for the connection to succeed.
1304
1306 mosquitto.conf
1307
1309 mosquitto bug information can be found at
1310 https://github.com/eclipse/mosquitto/issues
1311
1313 mosquitto(8), mosquitto_passwd(1), mosquitto-tls(7), mqtt(7),
1314 limits.conf(5)
1315
1317 Roger Light <roger@atchoo.org>
1318Mosquitto Project 04/30/2019 MOSQUITTO.CONF(5)