1MOSQUITTO.CONF(5)        File formats and conventions        MOSQUITTO.CONF(5)
2
3
4

NAME

6       mosquitto.conf - the configuration file for mosquitto
7

SYNOPSIS

9       mosquitto.conf
10

DESCRIPTION

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

FILE FORMAT

19       All lines with a # as the very first character are treated as a
20       comment.
21
22       Configuration lines start with a variable name. The variable value is
23       separated from the name by a single space.
24

AUTHENTICATION

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
30       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
35       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
42       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
63       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
71       Both certificate and PSK based encryption are configured on a
72       per-listener basis.
73
74       Authentication plugins can be created to augment the password_file,
75       acl_file and psk_file options with e.g. SQL based lookups.
76
77       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

GENERAL OPTIONS

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
88           If this parameter is defined then only the topics listed will have
89           access. Topic access is added with lines of the format:
90
91           topic [read|write|readwrite] <topic>
92
93           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
98           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
102           user <username>
103
104           The username referred to here is the same as in password_file. It
105           is not the clientid.
106
107           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
111           pattern [read|write|readwrite] <topic>
112
113           The patterns available for substition are:
114
115           ·   %c to match the client id of the client
116
117           ·   %u to match the username of the client
118
119           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
123           Example:
124
125           pattern write sensor/%u/data
126
127           Allow access for bridge connection messages:
128
129           pattern write $SYS/broker/connection/%c/state
130
131           If the first character of a line of the ACL file is a # it is
132           treated as a comment.
133
134           Reloaded on reload signal. The currently loaded ACLs will be freed
135           and reloaded. Existing subscriptions will be affected after the
136           reload.
137
138       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
144           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
149           Reloaded on reload signal.
150
151       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
158           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
164           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
169           Defaults to true.
170
171           Reloaded on reload signal.
172
173       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
178           See also the auto_id_prefix option.
179
180           Reloaded on reload signal.
181
182       auth_opt_* value
183           Options to be passed to the auth plugin. See the specific plugin
184           instructions.
185
186       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
191           Can be specified multiple times to load multiple plugins. The
192           plugins will be processed in the order that they are specified.
193
194           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
197           Not currently reloaded on reload signal.
198
199       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
206           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
211           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
217           Defaults to true.
218
219           Not currently reloaded on reload signal.
220
221       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
226           Reloaded on reload signal.
227
228       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
235           Reloaded on reload signal.
236
237       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
244           Reloaded on reload signal.
245
246       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
256           This option applies globally, regardless of the
257           per_listener_settings option.
258
259       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
266           Reloaded on reload signal. Note that currently connected clients
267           will be unaffected by any changes.
268
269       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
273           Reloaded on reload signal.
274
275       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
284           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
288           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
292               00.conf
293               01.conf
294               A.conf
295               a.conf
296               B.conf
297               b.conf
298
299           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
303           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
307               include_dir one.d
308               include_dir two.d
309
310           Then the config files would be loaded in this order:
311
312               # files from one.d
313               B.conf
314               C.conf
315               # files from two.d
316               A.conf
317               D.conf
318
319       log_dest destinations
320           Send log messages to a particular destination. Possible
321           destinations are: stdout stderr syslog topic.
322
323           stdout and stderr log to the console on the named output.
324
325           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
333           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
338           Use "log_dest none" if you wish to disable logging. Defaults to
339           stderr. This option may be specified multiple times.
340
341           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
345           Reloaded on reload signal.
346
347       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
354       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
358           Reloaded on reload signal.
359
360       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
366               log_timestamp_format %Y-%m-%dT%H:%M:%S
367
368
369           Reloaded on reload signal.
370
371       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
376           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
381           Reloaded on reload signal.
382
383       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
388           Reloaded on reload signal.
389
390       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
397           Reloaded on reload signal.
398
399       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
412           Reloaded on reload signal.
413
414       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
426           Setting below 20 bytes is forbidden because it is likely to
427           interfere with normal client operation even with small payloads.
428
429           Reloaded on reload signal.
430
431       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
438           Reloaded on reload signal.
439
440       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
446           Reloaded on reload signal.
447
448       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
459           This option is only available if memory tracking support is
460           compiled in.
461
462           Reloaded on reload signal. Setting to a lower value and reloading
463           will not result in memory being freed.
464
465       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
472       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
485           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
489           See also mosquitto_passwd(1).
490
491       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
496           password_file, acl_file, psk_file, allow_anonymous,
497           allow_zero_length_clientid, auth_plugin, auth_opt_*,
498           auto_id_prefix.
499
500           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
505           The default behaviour is for this to be set to false, which
506           maintains the settings behaviour from previous versions of
507           mosquitto.
508
509           Reloaded on reload signal.
510
511       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
521           Reloaded on reload signal.
522
523       persistence_file file name
524           The filename to use for the persistent database. Defaults to
525           mosquitto.db.
526
527           Reloaded on reload signal.
528
529       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
534           Reloaded on reload signal.
535
536       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
542           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
547           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
550           ·   persistent_client_expiration 2m
551
552           ·   persistent_client_expiration 14d
553
554           ·   persistent_client_expiration 1y
555
556           As this is a non-standard option, the default if not set is to
557           never expire persistent clients.
558
559           Reloaded on reload signal.
560
561       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
567           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
571           Not reloaded on reload signal.
572
573       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
582           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
586       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
591           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
595           Reloaded on reload signal.
596
597       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
602           Reloaded on reload signal.
603
604       retained_persistence [ true | false ]
605           This is a synonym of the persistence option.
606
607           Reloaded on reload signal.
608
609       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
615           Reloaded on reload signal.
616
617       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
625           Reloaded on reload signal.
626
627       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
632           Set to 0 to disable publishing the $SYS hierarchy completely.
633
634           Reloaded on reload signal.
635
636       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
645           Reloaded on reload signal.
646
647       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
655           This setting has no effect on Windows and so you should run
656           mosquitto as the user you wish it to run as.
657
658           Not reloaded on reload signal.
659

LISTENERS

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
665   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
674           Not reloaded on reload signal.
675
676       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
681           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
688           This option is currently only available on Linux, and requires
689           elevated privileges.
690
691           Not reloaded on reload signal.
692
693       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
699           Not reloaded on reload signal.
700
701       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
708           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
713           This option may be specified multiple times. See also the
714           mount_point option.
715
716           Not reloaded on reload signal.
717
718       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
724           Not reloaded on reload signal.
725
726       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
734           Not reloaded on reload signal.
735
736       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
741           Not reloaded on reload signal.
742
743       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
752           Not reloaded on reload signal.
753
754       port port number
755           Set the network port for the default listener to listen on.
756           Defaults to 1883.
757
758           Not reloaded on reload signal.
759
760       protocol value
761           Set the protocol to accept for this listener. Can be mqtt, the
762           default, or websockets if available.
763
764           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
769           Not reloaded on reload signal.
770
771       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
779           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
783           Not reloaded on reload signal.
784
785       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
792           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
796           See also use_identity_as_username.
797
798           Not reloaded on reload signal.
799
800       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
806           To use this option, log_type websockets must also be enabled.
807           Defaults to 0.
808
809       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
817   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
822       cafile file path
823           At least one of cafile or capath must be provided to allow SSL
824           support.
825
826           cafile is used to define the path to a file containing the PEM
827           encoded CA certificates that are trusted.
828
829       capath directory path
830           At least one of cafile or capath must be provided to allow SSL
831           support.
832
833           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
839       certfile file path
840           Path to the PEM encoded server certificate.
841
842       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
846       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
852       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
858               openssl dhparam -out dhparam.pem 2048
859
860       keyfile file path
861           Path to the PEM encoded keyfile.
862
863       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
873       tls_engine engine
874           A valid openssl engine id. These can be listed with openssl engine
875           command.
876
877       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
884       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
891       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
897       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
903           This takes priority over use_subject_as_username if both are set to
904           true.
905
906           See also use_subject_as_username
907
908       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
914           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
917           See also use_identity_as_username
918
919   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
924       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
931       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
938           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
941       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
947       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

CONFIGURING BRIDGES

954       Multiple bridges (connections to other brokers) can be configured using
955       the following variables.
956
957       Bridges cannot currently be reloaded on reload signal.
958
959       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
965           If you use an IPv6 address, then the port is not optional.
966
967           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
971       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
980       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
984       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
993           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
1000       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
1005       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
1010       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
1014       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
1020       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
1025       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
1030       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
1038           This uses the Last Will and Testament (LWT) feature.
1039
1040       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
1045       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
1050       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
1055           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
1059       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
1066           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
1070       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
1076           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
1080       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
1084           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
1090               restart_timeout 20
1091
1092           Set backoff with a base (start value) of 10 seconds and a cap
1093           (upper limit) of 60 seconds:
1094
1095               restart_timeout 10 30
1096
1097           Defaults to jitter with a base of 5 seconds and cap of 30 seconds.
1098
1099       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
1109           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
1113       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
1119           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
1124           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
1130           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
1134       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
1138       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
1150           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
1155           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
1161           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
1166           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
1175           ┌────────┬────────┬────────┬─────────────┬────────────┬─────────────┐
1176PatternLocalRemoteValidityFull LocalFull Remote
1177           │        │ PrefixPrefix │             │ TopicTopic
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
1202               topic # both 2 local/topic/ remote/topic/
1203
1204           This option can be specified multiple times per bridge.
1205
1206           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
1211           See also the cleansession option if you have messages arriving on
1212           unexpected topics when using incoming topics.
1213
1214           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
1219               connection test-mosquitto-org
1220               address test.mosquitto.org
1221               cleansession true
1222               topic clients/total in 0 test/mosquitto/org $SYS/broker/
1223
1224       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
1232           Defaults to true.
1233
1234   SSL/TLS Support
1235       The following options are available for all bridges to configure
1236       SSL/TLS support.
1237
1238       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
1243       bridge_cafile file path
1244           One of bridge_cafile or bridge_capath must be provided to allow
1245           SSL/TLS support.
1246
1247           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
1251       bridge_capath file path
1252           One of bridge_capath or bridge_capath must be provided to allow
1253           SSL/TLS support.
1254
1255           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
1262       bridge_certfile file path
1263           Path to the PEM encoded client certificate for this bridge, if
1264           required by the remote broker.
1265
1266       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
1273       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
1280           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
1284       bridge_keyfile file path
1285           Path to the PEM encoded private key for this bridge, if required by
1286           the remote broker.
1287
1288       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
1295       bridge_require_ocsp [ true | false ]
1296           When set to true, the bridge requires OCSP on the TLS connection it
1297           opens as client.
1298
1299       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

FILES

1306       mosquitto.conf
1307

BUGS

1309       mosquitto bug information can be found at
1310       https://github.com/eclipse/mosquitto/issues
1311

SEE ALSO

1313       mosquitto(8), mosquitto_passwd(1), mosquitto-tls(7), mqtt(7),
1314       limits.conf(5)
1315

AUTHOR

1317       Roger Light <roger@atchoo.org>
1318
1319
1320
1321Mosquitto Project                 04/26/2019                 MOSQUITTO.CONF(5)
Impressum