-
Notifications
You must be signed in to change notification settings - Fork 2.4k
/
mosquitto.conf.5.xml
1551 lines (1522 loc) · 67.2 KB
/
mosquitto.conf.5.xml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<?xml version='1.0' encoding='UTF-8'?>
<?xml-stylesheet type="text/xsl" href="manpage.xsl"?>
<refentry xml:id="mosquitto.conf" xmlns:xlink="https://www.w3.org/1999/xlink">
<refmeta>
<refentrytitle>mosquitto.conf</refentrytitle>
<manvolnum>5</manvolnum>
<refmiscinfo class="source">Mosquitto Project</refmiscinfo>
<refmiscinfo class="manual">File formats and conventions</refmiscinfo>
</refmeta>
<refnamediv>
<refname>mosquitto.conf</refname>
<refpurpose>the configuration file for mosquitto</refpurpose>
</refnamediv>
<refsynopsisdiv>
<cmdsynopsis>
<command>mosquitto.conf</command>
</cmdsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para><command>mosquitto.conf</command> is the configuration file for
mosquitto. This file can reside anywhere as long as mosquitto can read
it. By default, mosquitto does not need a configuration file and will
use the default values listed below. See
<citerefentry><refentrytitle>mosquitto</refentrytitle><manvolnum>8</manvolnum></citerefentry>
for information on how to load a configuration file.</para>
</refsect1>
<refsect1>
<title>File Format</title>
<para>All lines with a # as the very first character are treated as a
comment.</para>
<para>Configuration lines start with a variable name. The variable
value is separated from the name by a single space.</para>
</refsect1>
<refsect1>
<title>Authentication</title>
<para>The authentication options described below allow a wide range of
possibilities in conjunction with the listener options. This
section aims to clarify the possibilities.</para>
<para>The simplest option is to have no authentication at all. This is
the default if no other options are given. Unauthenticated
encrypted support is provided by using the certificate based
SSL/TLS based options cafile/capath, certfile and keyfile.</para>
<para>MQTT provides username/password authentication as part of the
protocol. Use the password_file option to define the valid
usernames and passwords. Be sure to use network encryption if you
are using this option otherwise the username and password will be
vulnerable to interception. Use the
<option>per_listener_settings</option> to control whether passwords
are required globally or on a per-listener basis.</para>
<para>When using certificate based encryption there are three options
that affect authentication. The first is require_certificate, which
may be set to true or false. If false, the SSL/TLS component of the
client will verify the server but there is no requirement for the
client to provide anything for the server: authentication is
limited to the MQTT built in username/password. If
require_certificate is true, the client must provide a valid
certificate in order to connect successfully. In this case, the
second and third options, use_identity_as_username and
use_subject_as_username, become relevant. If set to true,
use_identity_as_user causes the Common Name (CN) from the client
certificate to be used instead of the MQTT username for access
control purposes. The password is not replaced because it is
assumed that only authenticated clients have valid certificates. If
use_identity_as_username is false, the client must authenticate as
normal (if required by password_file) through the MQTT options. The
same principle applies for the use_subject_as_username option, but
the entire certificate subject is used as the username instead of
just the CN.</para>
<para>When using pre-shared-key based encryption through the psk_hint
and psk_file options, the client must provide a valid identity and
key in order to connect to the broker before any MQTT communication
takes place. If use_identity_as_username is true, the PSK identity
is used instead of the MQTT username for access control purposes.
If use_identity_as_username is false, the client may still
authenticate using the MQTT username/password if using the
password_file option.</para>
<para>Both certificate and PSK based encryption are configured on a
per-listener basis.</para>
<para>Authentication plugins can be created to augment the
password_file, acl_file and psk_file options with e.g. SQL based
lookups.</para>
<para>It is possible to support multiple authentication schemes at
once. A config could be created that had a listener for all of the
different encryption options described above and hence a large
number of ways of authenticating.</para>
</refsect1>
<refsect1>
<title>General Options</title>
<variablelist>
<varlistentry>
<term><option>acl_file</option> <replaceable>file path</replaceable></term>
<listitem>
<para>Set the path to an access control list file. If
defined, the contents of the file are used to control
client access to topics on the broker.</para>
<para>If this parameter is defined then only the topics
listed will have access. Topic access is added with
lines of the format:</para>
<para><code>topic [read|write|readwrite] <topic></code></para>
<para>The access type is controlled using "read", "write" or
"readwrite". This parameter is optional (unless
<topic> includes a space character) - if not
given then the access is read/write. <topic> can
contain the + or # wildcards as in
subscriptions.</para>
<para>The first set of topics are applied to anonymous
clients, assuming <option>allow_anonymous</option> is
true. User specific topic ACLs are added after a user
line as follows:</para>
<para><code>user <username></code></para>
<para>The username referred to here is the same as in
<option>password_file</option>. It is not the
clientid.</para>
<para>It is also possible to define ACLs based on pattern
substitution within the topic. The form is the same as
for the topic keyword, but using pattern as the
keyword.</para>
<para><code>pattern [read|write|readwrite] <topic></code></para>
<para>The patterns available for substition are:</para>
<itemizedlist mark="circle">
<listitem><para>%c to match the client id of the client</para></listitem>
<listitem><para>%u to match the username of the client</para></listitem>
</itemizedlist>
<para>The substitution pattern must be the only text for
that level of hierarchy. Pattern ACLs apply to all
users even if the "user" keyword has previously been
given.</para>
<para>Example:</para>
<para><code>pattern write sensor/%u/data</code></para>
<para>Allow access for bridge connection messages:</para>
<para><code>pattern write $SYS/broker/connection/%c/state</code></para>
<para>If the first character of a line of the ACL file is a
# it is treated as a comment.</para>
<para>Reloaded on reload signal. The currently loaded ACLs
will be freed and reloaded. Existing subscriptions will
be affected after the reload.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>allow_anonymous</option> [ true | false ]</term>
<listitem>
<para>Boolean value that determines whether clients that
connect without providing a username are allowed to
connect. If set to <replaceable>false</replaceable>
then another means of connection should be created to
control authenticated client access.</para>
<para>Defaults to <replaceable>true</replaceable> if no
other security options are set. If any other
authentication options are set, then
<option>allow_anonymous</option> defaults to
<replaceable>false</replaceable>.</para>
<para>Reloaded on reload signal.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>allow_duplicate_messages</option> [ true | false ]</term>
<listitem>
<para>If a client is subscribed to multiple subscriptions
that overlap, e.g. foo/# and foo/+/baz , then MQTT
expects that when the broker receives a message on a
topic that matches both subscriptions, such as
foo/bar/baz, then the client should only receive the
message once.</para>
<para>Mosquitto keeps track of which clients a message has
been sent to in order to meet this requirement. This
option allows this behaviour to be disabled, which may
be useful if you have a large number of clients
subscribed to the same set of topics and want to
minimise memory usage.</para>
<para>It can be safely set to
<replaceable>true</replaceable> if you know in advance
that your clients will never have overlapping
subscriptions, otherwise your clients must be able to
correctly deal with duplicate messages even when then
have QoS=2.</para>
<para>Defaults to <replaceable>true</replaceable>.</para>
<para>Reloaded on reload signal.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>auth_opt_*</option> <replaceable>value</replaceable></term>
<listitem>
<para>Options to be passed to the auth plugin. See the
specific plugin instructions. </para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>auth_plugin</option> <replaceable>file path</replaceable></term>
<listitem>
<para>Specify an external module to use for authentication
and access control. This allows custom
username/password and access control functions to be
created.</para>
<para>Can be specified multiple times to load multiple
plugins. The plugins will be processed in the order
that they are specified.</para>
<para>If <option>password_file</option>, or
<option>acl_file</option> are used in the config file
alongsize <option>auth_plugin</option>, the plugin
checks will run after the build in checks.</para>
<para>Not currently reloaded on reload signal.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>auth_plugin_deny_special_chars</option> [ true | false ]</term>
<listitem>
<para>If <replaceable>true</replaceable> then before an ACL
check is made, the username/client id of the client
needing the check is searched for the presence of
either a '+' or '#' character. If either of these
characters is found in either the username or client
id, then the ACL check is denied before it is sent to
the plugin.</para>
<para>This check prevents the case where a malicious user
could circumvent an ACL check by using one of these
characters as their username or client id. This is the
same issue as was reported with mosquitto itself as
CVE-2017-7650.</para>
<para>If you are entirely sure that the plugin you are
using is not vulnerable to this attack (i.e. if you
never use usernames or client ids in topics) then you
can disable this extra check and hence have all ACL
checks delivered to your plugin by setting this option
to <replaceable>false</replaceable>.</para>
<para>Defaults to <replaceable>true</replaceable>.</para>
<para>Not currently reloaded on reload signal.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>autosave_interval</option> <replaceable>seconds</replaceable></term>
<listitem>
<para>The number of seconds that mosquitto will wait
between each time it saves the in-memory database to
disk. If set to 0, the in-memory database will only be
saved when mosquitto exits or when receiving the
SIGUSR1 signal. Note that this setting only has an
effect if persistence is enabled. Defaults to 1800
seconds (30 minutes).</para>
<para>Reloaded on reload signal.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>autosave_on_changes</option> [ true | false ]</term>
<listitem>
<para>If <replaceable>true</replaceable>, mosquitto will
count the number of subscription changes, retained
messages received and queued messages and if the total
exceeds <option>autosave_interval</option> then the
in-memory database will be saved to disk. If
<replaceable>false</replaceable>, mosquitto will save
the in-memory database to disk by treating
<option>autosave_interval</option> as a time in
seconds.</para>
<para>Reloaded on reload signal.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>clientid_prefixes</option> <replaceable>prefix</replaceable></term>
<listitem>
<para>If defined, only clients that have a clientid with a
prefix that matches clientid_prefixes will be allowed
to connect to the broker. For example, setting
"secure-" here would mean a client "secure-client"
could connect but another with clientid "mqtt"
couldn't. By default, all client ids are valid.</para>
<para>Reloaded on reload signal. Note that currently
connected clients will be unaffected by any
changes.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>connection_messages</option> [ true | false ]</term>
<listitem>
<para>If set to <replaceable>true</replaceable>, the log
will include entries when clients connect and
disconnect. If set to <replaceable>false</replaceable>,
these entries will not appear.</para>
<para>Reloaded on reload signal.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>include_dir</option> <replaceable>dir</replaceable></term>
<listitem>
<para>External configuration files may be included by using
the include_dir option. This defines a directory that
will be searched for config files. All files that end
in '.conf' will be loaded as a configuration file. It
is best to have this as the last option in the main
file. This option will only be processed from the main
configuration file. The directory specified must not
contain the main configuration file.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>log_dest</option> <replaceable>destinations</replaceable></term>
<listitem>
<para>Send log messages to a particular destination.
Possible destinations are: <option>stdout</option>
<option>stderr</option> <option>syslog</option>
<option>topic</option>.</para>
<para><option>stdout</option> and
<option>stderr</option> log to the console on the
named output.</para>
<para><option>syslog</option> uses the userspace syslog
facility which usually ends up in /var/log/messages or
similar and topic logs to the broker topic
'$SYS/broker/log/<severity>', where severity is
one of D, E, W, N, I, M which are debug, error,
warning, notice, information and message. Message type
severity is used by the subscribe and unsubscribe
log_type options and publishes log messages at
$SYS/broker/log/M/subscribe and
$SYS/broker/log/M/unsubscribe.</para>
<para>The <option>file</option> destination requires an
additional parameter which is the file to be logged to,
e.g. "log_dest file /var/log/mosquitto.log". The file
will be closed and reopened when the broker receives a
HUP signal. Only a single file destination may be
configured.</para>
<para>Use "log_dest none" if you wish to disable logging.
Defaults to stderr. This option may be specified
multiple times.</para>
<para>Note that if the broker is running as a Windows
service it will default to "log_dest none" and neither
stdout nor stderr logging is available.</para>
<para>Reloaded on reload signal.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>log_facility</option> <replaceable>local facility</replaceable></term>
<listitem>
<para>If using syslog logging (not on Windows), messages
will be logged to the "daemon" facility by default. Use
the <option>log_facility</option> option to choose
which of local0 to local7 to log to instead. The option
value should be an integer value, e.g. "log_facility 5"
to use local5.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>log_timestamp</option> [ true | false ]</term>
<listitem>
<para>Boolean value, if set to
<replaceable>true</replaceable> a timestamp value will
be added to each log entry. The default is
<replaceable>true</replaceable>.</para>
<para>Reloaded on reload signal.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>log_type</option> <replaceable>types</replaceable></term>
<listitem>
<para>Choose types of messages to log. Possible types are:
<replaceable>debug</replaceable>,
<replaceable>error</replaceable>,
<replaceable>warning</replaceable>,
<replaceable>notice</replaceable>,
<replaceable>information</replaceable>,
<replaceable>subscribe</replaceable>,
<replaceable>unsubscribe</replaceable>,
<replaceable>websockets</replaceable>,
<replaceable>none</replaceable>,
<replaceable>all</replaceable>.</para>
<para>Defaults to <replaceable>error</replaceable>,
<replaceable>warning</replaceable>, <replaceable>notice
</replaceable>and
<replaceable>information</replaceable>. This option
may be specified multiple times. Note that the
<replaceable>debug </replaceable>type (used for
decoding incoming/outgoing network packets) is never
logged in topics.</para>
<para>Reloaded on reload signal.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>max_inflight_bytes</option> <replaceable>count</replaceable></term>
<listitem>
<para>QoS 1 and 2 messages will be allowed in flight until this byte
limit is reached. Defaults to 0. (No limit)
See also the <option>max_inflight_messages</option> option.
</para>
<para>Reloaded on reload signal.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>max_inflight_messages</option> <replaceable>count</replaceable></term>
<listitem>
<para>The maximum number of QoS 1 or 2 messages that can be
in the process of being transmitted simultaneously.
This includes messages currently going through
handshakes and messages that are being retried.
Defaults to 20. Set to 0 for no maximum. If set to 1,
this will guarantee in-order delivery of
messages.</para>
<para>Reloaded on reload signal.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>max_queued_bytes</option> <replaceable>count</replaceable></term>
<listitem>
<para>QoS 1 and 2 messages above those currently in-flight will be
queued (per client) until this limit is exceeded.
Defaults to 0. (No maximum) See also the
<option>max_queued_messages</option> option.
If both max_queued_messages and max_queued_bytes are specified,
packets will be queued until the first limit is reached.
</para>
<para>Reloaded on reload signal.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>max_queued_messages</option> <replaceable>count</replaceable></term>
<listitem>
<para>The maximum number of QoS 1 or 2 messages to hold in the
queue (per client) above those messages that are currently
in flight. Defaults to 100. Set to 0 for no maximum (not
recommended). See also the
<option>queue_qos0_messages</option> and
<option>max_queued_bytes</option> options.
</para>
<para>Reloaded on reload signal.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>message_size_limit</option> <replaceable>limit</replaceable></term>
<listitem>
<para>This option sets the maximum publish payload size
that the broker will allow. Received messages that
exceed this size will not be accepted by the broker.
The default value is 0, which means that all valid MQTT
messages are accepted. MQTT imposes a maximum payload
size of 268435455 bytes.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>password_file</option> <replaceable>file path</replaceable></term>
<listitem>
<para>Set the path to a password file. If defined, the
contents of the file are used to control client access
to the broker. The file can be created using the
<citerefentry><refentrytitle>mosquitto_passwd</refentrytitle><manvolnum>1</manvolnum></citerefentry>
utility. If mosquitto is compiled without TLS support
(it is recommended that TLS support is included), then
the password file should be a text file with each line
in the format "username:password", where the colon and
password are optional but recommended. If
<option>allow_anonymous</option> is set to
<replaceable>false</replaceable>, only users defined in
this file will be able to connect. Setting
<option>allow_anonymous</option> to
<replaceable>true</replaceable> when
<replaceable>password_file</replaceable>is defined is
valid and could be used with acl_file to have e.g. read
only guest/anonymous accounts and defined users that
can publish.</para>
<para>Reloaded on reload signal. The currently loaded
username and password data will be freed and reloaded.
Clients that are already connected will not be
affected.</para>
<para>See also
<citerefentry><refentrytitle>mosquitto_passwd</refentrytitle><manvolnum>1</manvolnum></citerefentry>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>per_listener_settings</option> [ true | false ]</term>
<listitem>
<para>If <replaceable>true</replaceable>, then
authentication and access control settings will be
controlled on a per-listener basis. The following
options are affected:</para>
<para><option>password_file</option>,
<option>acl_file</option>, <option>psk_file</option>,
<option>allow_anonymous</option>,
<option>allow_zero_length_clientid</option>,
<option>auth_plugin</option>,
<option>auth_opt_*</option>,
<option>auto_id_prefix</option>.</para>
<para>The default behaviour is for this to be set to
<replaceable>false</replaceable>, which maintains the
settings behaviour from previous versions of
mosquitto.</para>
<para>Reloaded on reload signal.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>persistence</option> [ true | false ]</term>
<listitem>
<para>If <replaceable>true</replaceable>, connection,
subscription and message data will be written to the
disk in mosquitto.db at the location dictated by
persistence_location. When mosquitto is restarted, it
will reload the information stored in mosquitto.db. The
data will be written to disk when mosquitto closes and
also at periodic intervals as defined by
autosave_interval. Writing of the persistence database
may also be forced by sending mosquitto the SIGUSR1
signal. If <replaceable>false</replaceable>, the data
will be stored in memory only. Defaults to
<replaceable>false</replaceable>.</para>
<para>Reloaded on reload signal.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>persistence_file</option> <replaceable>file name</replaceable></term>
<listitem>
<para>The filename to use for the persistent database.
Defaults to mosquitto.db.</para>
<para>Reloaded on reload signal.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>persistence_location</option> <replaceable>path</replaceable></term>
<listitem>
<para>The path where the persistence database should be
stored. Must end in a trailing slash. If not given,
then the current directory is used.</para>
<para>Reloaded on reload signal.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>persistent_client_expiration</option> <replaceable>duration</replaceable></term>
<listitem>
<para>This option allows persistent clients (those with
clean session set to false) to be removed if they do
not reconnect within a certain time frame. This is a
non-standard option. As far as the MQTT spec is
concerned, persistent clients persist forever.</para>
<para>Badly designed clients may set clean session to false
whilst using a randomly generated client id. This leads
to persistent clients that will never reconnect. This
option allows these clients to be removed.</para>
<para>The expiration period should be an integer followed
by one of h d w m y for hour, day, week, month and year
respectively. For example:</para>
<itemizedlist mark="circle">
<listitem><para>persistent_client_expiration 2m</para></listitem>
<listitem><para>persistent_client_expiration 14d</para></listitem>
<listitem><para>persistent_client_expiration 1y</para></listitem>
</itemizedlist>
<para>As this is a non-standard option, the default if not
set is to never expire persistent clients.</para>
<para>Reloaded on reload signal.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>pid_file</option> <replaceable>file path</replaceable></term>
<listitem>
<para>Write a pid file to the file specified. If not given
(the default), no pid file will be written. If the pid
file cannot be written, mosquitto will exit. This
option only has an effect is mosquitto is run in daemon
mode.</para>
<para>If mosquitto is being automatically started by an
init script it will usually be required to write a pid
file. This should then be configured as e.g.
/var/run/mosquitto.pid</para>
<para>Not reloaded on reload signal.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>psk_file</option> <replaceable>file path</replaceable></term>
<listitem>
<para>Set the path to a pre-shared-key file. This option
requires a listener to be have PSK support enabled. If
defined, the contents of the file are used to control
client access to the broker. Each line should be in the
format "identity:key", where the key is a hexadecimal
string with no leading "0x". A client connecting to a
listener that has PSK support enabled must provide a
matching identity and PSK to allow the encrypted
connection to proceed.</para>
<para>Reloaded on reload signal. The currently loaded
identity and key data will be freed and reloaded.
Clients that are already connected will not be
affected.</para>
</listitem> </varlistentry>
<varlistentry>
<term><option>queue_qos0_messages</option> [ true | false ]</term>
<listitem>
<para>Set to <replaceable>true</replaceable> to queue
messages with QoS 0 when a persistent client is
disconnected. These messages are included in the limit
imposed by max_queued_messages. Defaults to
<replaceable>false</replaceable>.</para>
<para>Note that the MQTT v3.1.1 spec states that only QoS 1
and 2 messages should be saved in this situation so
this is a non-standard option.</para>
<para>Reloaded on reload signal.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>retained_persistence</option> [ true | false ]</term>
<listitem>
<para>This is a synonym of the <option>persistence</option>
option.</para>
<para>Reloaded on reload signal.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>set_tcp_nodelay</option> [ true | false ]</term>
<listitem>
<para>If set to true, the TCP_NODELAY option will be set on
client sockets to disable Nagle's algorithm. This
has the effect of reducing latency of some messages
at potentially increasing the number of TCP packets
being sent. Defaults to false.</para>
<para>Reloaded on reload signal.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>store_clean_interval</option> <replaceable>seconds</replaceable></term>
<listitem>
<para>The integer number of seconds between the internal
message store being cleaned of messages that are no
longer referenced. Lower values will result in lower
memory usage but more processor time, higher values
will have the opposite effect. Setting a value of 0
means the unreferenced messages will be disposed of as
quickly as possible. Defaults to 10 seconds.</para>
<para>Reloaded on reload signal.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>sys_interval</option> <replaceable>seconds</replaceable></term>
<listitem>
<para>The integer number of seconds between updates of the
$SYS subscription hierarchy, which provides status
information about the broker. If unset, defaults to 10
seconds.</para>
<para>Set to 0 to disable publishing the $SYS hierarchy
completely.</para>
<para>Reloaded on reload signal.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>upgrade_outgoing_qos</option> [ true | false ]</term>
<listitem>
<para>The MQTT specification requires that the QoS of a
message delivered to a subscriber is never upgraded to
match the QoS of the subscription. Enabling this option
changes this behaviour. If
<option>upgrade_outgoing_qos</option> is set
<replaceable>true</replaceable>, messages sent to a
subscriber will always match the QoS of its
subscription. This is a non-standard option not
provided for by the spec. Defaults to
<replaceable>false</replaceable>.</para>
<para>Reloaded on reload signal.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>user</option> <replaceable>username</replaceable></term>
<listitem>
<para>When run as root, change to this user and its primary
group on startup. If mosquitto is unable to change to
this user and group, it will exit with an error. The
user specified must have read/write access to the
persistence database if it is to be written. If run as
a non-root user, this setting has no effect. Defaults
to mosquitto.</para>
<para>This setting has no effect on Windows and so you
should run mosquitto as the user you wish it to run
as.</para>
<para>Not reloaded on reload signal.</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Listeners</title>
<para>The network ports that mosquitto listens on can be controlled
using listeners. The default listener options can be overridden and
further listeners can be created.</para>
<refsect2>
<title>General Options</title>
<variablelist>
<varlistentry>
<term><option>bind_address</option> <replaceable>address</replaceable></term>
<listitem>
<para>Listen for incoming network connections on the
specified IP address/hostname only. This is useful
to restrict access to certain network interfaces.
To restrict access to mosquitto to the local host
only, use "bind_address localhost". This only
applies to the default listener. Use the listener
variable to control other listeners.</para>
<para>Not reloaded on reload signal.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>http_dir</option> <replaceable>directory</replaceable></term>
<listitem>
<para>When a listener is using the websockets protocol,
it is possible to serve http data as well. Set
<option>http_dir</option> to a directory which
contains the files you wish to serve. If this
option is not specified, then no normal http
connections will be possible.</para>
<para>Not reloaded on reload signal.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>listener</option> <replaceable>port</replaceable> <replaceable><optional>bind address/host</optional></replaceable></term>
<listitem>
<para>Listen for incoming network connection on the
specified port. A second optional argument allows
the listener to be bound to a specific ip
address/hostname. If this variable is used and
neither the global <option>bind_address</option>
nor <option>port</option> options are used then the
default listener will not be started.</para>
<para>The <option>bind address/host</option> option
allows this listener to be bound to a specific IP
address by passing an IP address or hostname. For
websockets listeners, it is only possible to pass
an IP address here.</para>
<para>This option may be specified multiple times. See
also the <option>mount_point</option>
option.</para>
<para>Not reloaded on reload signal.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>max_connections</option> <replaceable>count</replaceable></term>
<listitem>
<para>Limit the total number of clients connected for
the current listener. Set to <literal>-1</literal>
to have "unlimited" connections. Note that other
limits may be imposed that are outside the control
of mosquitto. See e.g.
<citerefentry><refentrytitle>limits.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
<para>Not reloaded on reload signal.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>mount_point</option> <replaceable>topic prefix</replaceable></term>
<listitem>
<para>This option is used with the listener option to
isolate groups of clients. When a client connects
to a listener which uses this option, the string
argument is attached to the start of all topics for
this client. This prefix is removed when any
messages are sent to the client. This means a
client connected to a listener with mount point
<replaceable>example</replaceable> can only see
messages that are published in the topic hierarchy
<replaceable>example</replaceable> and below.</para>
<para>Not reloaded on reload signal.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>port</option> <replaceable>port number</replaceable></term>
<listitem>
<para>Set the network port for the default listener to
listen on. Defaults to 1883.</para>
<para>Not reloaded on reload signal.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>protocol</option> <replaceable>value</replaceable></term>
<listitem>
<para>Set the protocol to accept for this listener. Can
be <option>mqtt</option>, the default, or
<option>websockets</option> if available.</para>
<para>Websockets support is currently disabled by
default at compile time. Certificate based TLS may be used
with websockets, except that only the
<option>cafile</option>, <option>certfile</option>,
<option>keyfile</option> and
<option>ciphers</option> options are
supported.</para>
<para>Not reloaded on reload signal.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>use_username_as_clientid</option> [ true | false ]</term>
<listitem>
<para>Set <option>use_username_as_clientid</option> to
true to replace the clientid that a client
connected with with its username. This allows
authentication to be tied to the clientid, which
means that it is possible to prevent one client
disconnecting another by using the same
clientid. Defaults to false.</para>
<para>If a client connects with no username it will be
disconnected as not authorised when this option is
set to true. Do not use in conjunction with
<option>clientid_prefixes</option>.</para>
<para>See also
<option>use_identity_as_username</option>.</para>
<para>Not reloaded on reload signal.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>websockets_log_level</option> <replaceable>level</replaceable></term>
<listitem>
<para>Change the websockets logging level. This is a
global option, it is not possible to set per
listener. This is an integer that is interpreted by
libwebsockets as a bit mask for its lws_log_levels
enum. See the libwebsockets documentation for more
details.</para>
<para>To use this option, <option>log_type
websockets</option> must also be enabled.
Defaults to 0.</para>
</listitem>
</varlistentry>
</variablelist>
</refsect2>
<refsect2>
<title>Certificate based SSL/TLS Support</title>
<para>The following options are available for all listeners to
configure certificate based SSL support. See also
"Pre-shared-key based SSL/TLS support".</para>
<variablelist>
<varlistentry>
<term><option>cafile</option> <replaceable>file path</replaceable></term>
<listitem>
<para>At least one of <option>cafile</option> or
<option>capath</option> must be provided to allow
SSL support.</para>
<para><option>cafile</option> is used to define the
path to a file containing the PEM encoded CA
certificates that are trusted.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>capath</option> <replaceable>directory path</replaceable></term>
<listitem>
<para>At least one of <option>cafile</option> or
<option>capath</option> must be provided to allow
SSL support.</para>
<para><option>capath</option> is used to define a
directory that contains PEM encoded CA certificates
that are trusted. For <option>capath</option> to
work correctly, the certificates files must have
".pem" as the file ending and you must run
"openssl rehash <path to capath>" each time you
add/remove a certificate.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>certfile</option> <replaceable>file path</replaceable></term>
<listitem>
<para>Path to the PEM encoded server certificate.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>ciphers</option> <replaceable>cipher:list</replaceable></term>
<listitem>
<para>The list of allowed ciphers, each separated with
a colon. Available ciphers can be obtained using
the "openssl ciphers" command.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>crlfile</option> <replaceable>file path</replaceable></term>
<listitem>
<para>If you have <option>require_certificate</option>
set to <replaceable>true</replaceable>, you can
create a certificate revocation list file to revoke
access to particular client certificates. If you
have done this, use crlfile to point to the PEM
encoded revocation file.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>keyfile</option> <replaceable>file path</replaceable></term>
<listitem>
<para>Path to the PEM encoded keyfile.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>require_certificate</option> [ true | false ]</term>
<listitem>
<para>By default an SSL/TLS enabled listener will
operate in a similar fashion to a https enabled web
server, in that the server has a certificate signed
by a CA and the client will verify that it is a
trusted certificate. The overall aim is encryption
of the network traffic. By setting
<option>require_certificate</option> to
<replaceable>true</replaceable>, the client must
provide a valid certificate in order for the
network connection to proceed. This allows access
to the broker to be controlled outside of the
mechanisms provided by MQTT.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>tls_version</option> <replaceable>version</replaceable></term>
<listitem>
<para>Configure the version of the TLS protocol to be
used for this listener. Possible values are
<replaceable>tlsv1.2</replaceable>,
<replaceable>tlsv1.1</replaceable> and
<replaceable>tlsv1</replaceable>. If left unset,
the default of allowing all of TLS v1.2, v1.1 and
v1.0 is used.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>use_identity_as_username</option> [ true | false ]</term>
<listitem>
<para>If <option>require_certificate</option> is
<replaceable>true</replaceable>, you may set
<option>use_identity_as_username</option> to
<replaceable>true</replaceable> to use the CN value
from the client certificate as a username. If this
is <replaceable>true</replaceable>, the
<option>password_file</option> option will not be
used for this listener.</para>
<para>This takes priority over
<option>use_subject_as_username</option> if both
are set to <replaceable>true</replaceable>.</para>
<para>See also
<option>use_subject_as_username</option></para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>use_subject_as_username</option> [ true | false ]</term>
<listitem>
<para>If <option>require_certificate</option> is
<replaceable>true</replaceable>, you may set
<option>use_subject_as_username</option> to
<replaceable>true</replaceable> to use the complete subject value
from the client certificate as a username. If this
is <replaceable>true</replaceable>, the
<option>password_file</option> option will not be
used for this listener.</para>
<para>The subject will be generated in a form similar
to <option>CN=test client,OU=Production,O=Server,L=Nottingham,ST=Nottinghamshire,C=GB</option>.</para>
<para>See also
<option>use_identity_as_username</option></para>
</listitem>
</varlistentry>
</variablelist>
</refsect2>
<refsect2>
<title>Pre-shared-key based SSL/TLS Support</title>
<para>The following options are available for all listeners to
configure pre-shared-key based SSL support. See also
"Certificate based SSL/TLS support".</para>
<variablelist>
<varlistentry>
<term><option>ciphers</option> <replaceable>cipher:list</replaceable></term>
<listitem>
<para>When using PSK, the encryption ciphers used will
be chosen from the list of available PSK ciphers.
If you want to control which ciphers are available,
use this option. The list of available ciphers can
be optained using the "openssl ciphers" command and
should be provided in the same format as the output
of that command.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>psk_hint</option> <replaceable>hint</replaceable></term>
<listitem>
<para>The <option>psk_hint</option> option enables
pre-shared-key support for this listener and also
acts as an identifier for this listener. The hint
is sent to clients and may be used locally to aid
authentication. The hint is a free form string that
doesn't have much meaning in itself, so feel free
to be creative.</para>
<para>If this option is provided, see
<option>psk_file</option> to define the pre-shared
keys to be used or create a security plugin to
handle them.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>tls_version</option> <replaceable>version</replaceable></term>
<listitem>
<para>Configure the version of the TLS protocol to be
used for this listener. Possible values are
<replaceable>tlsv1.2</replaceable>,
<replaceable>tlsv1.1</replaceable> and
<replaceable>tlsv1</replaceable>. If left unset,
the default of allowing all of TLS v1.2, v1.1 and