mosquitto是用C实现的MQTT服务器，并提供客户端库和工具。mosquitto的配置文件默认在/etc/mosquito/mosquito.conf，
相关的配置参数有100多个，详细说明在https://mosquitto.org/man/mosquitto-conf-5.html可以找到。但是，有些人理解英文可能有困难，所以本人将其翻译为中文。希望对大家理解这些配置参数有帮助。
File Format 文件格式
以“#”开始的行为注释行
每个配置项占一行，开始是变量名，后面是变量的值，变量名和变量值以空格分隔。
Authentication认证
认证方式有很多种，这里把所有可用的方法列出来.
最简单的选项是不配置认证项，如果不配置其他项的话，这是默认值。
非认证加密方式可以使用基于SSL/TLS的cafile/capath, certfile and keyfile配置项。
MQTT 协议提供username/password的认证方式. 可以使用 password_file 配置项定义有效的用户名和密码。 使用这个配置项时一定要确保使用网络加密，否则用户名和密码很容易被窃听。使用 per_listener_settings项来指定密码是全局的还是基于每一个listener 的.
当使用基于认证的加密方式时，一共有三个配置项：
第一个是require_certificate，它是布尔型的(true or false).
如果require_certificate为false, 客户端的SSL/TLS 组件会认证服务器端，但是客户端不会向服务器端提供认证信息 ，服务器端对client的认证只限于MQTT内置的用户名和密码。
如果 require_certificate 为true, client 必须提供一个有效的认证才能连接服务器. 这时, 第二和第三个配置项（use_identity_as_username and use_subject_as_username）才有效. 如果use_identity_as_username 为true, 来自client的Common Name (CN)将会代替 MQTT username 来做访问控制. 密码就不再用了因为只有授权的client才有有效认证. 也就是说cafile 或者 capath 中的任一CA证书都会认证client有效并允许连接到broker. 如果 use_identity_as_username 为 false, client还是要遵从正常的认证方式通过MQTT选项认证。use_subject_as_username配置也是同样的原理，只是用subject作为 username 而不是CN.
当使用基于pre-shared-key的加密方式时，需要通过psk_hint 和psk_file 配置项实现。Client必须提供有效的id和key才能连接broker，在这之前不能建立任何MQTT通信. 如果use_identity_as_username为true, 将会使用PSK identity来代替MQTT username做访问控制. 如果use_identity_as_username 为false, 并且配置了password_file选项的话 client 仍然要使用MQTT username/password做认证。
certificate 和 PSK 加密都可以基于listener 来配置。
可以创建认证插件来增加password_file, acl_file 和psk_file配置项，例如基于SQL查找。（原文为：Authentication plugins can be created to augment the password_file, acl_file and psk_file options with e.g. SQL based lookups.）
可以一次支持多种认证方式。创建一个配置文件包含上面介绍所有加密方式就可以了。
通用配置项
acl_file file path
设置访问控制文件的路径。如果配置此项，文件里的权限配置将会用来作为client访问broker中的topics的权限控制。只有参数中列出的topic才可以访问。
Topic的访问权限如下格式:
topic [read|write|readwrite] <topic>
访问类型使用"read", "write" or "readwrite". 这一参数是可选的，如果不带此参数，默认的访问权限是read/write. <topic>中可以包含 ‘+’或者’#’ 通配符。
如果allow_anonymous 为true，第一条topic的配置是给匿名client的。每个用户的访问控制添加在如下所示的用户行后面:
user <username>
这里的username 指的是 password_file中的username,并不是clientid.
也可以基于模式匹配定义访问控制。格式与topic关键字相同，只是使用’pattern’作为关键字：
pattern [read|write|readwrite] <topic>
可以用的匹配符为:
- %c 匹配client的 client id。
- %u 匹配client的username。
匹配符必须是那一级的唯一字符。模式配置访问控制应用于所有用户即使“user”关键字在前面已经定义了。
例子:
pattern write sensor/%u/data
允许访问bridge connection 消息:
pattern write $SYS/broker/connection/%c/state
‘#’ 开头的是注释。
如果per_listener_settings 为 true, 这一配置项只应用于当前的 listener. 如果 per_listener_settings 为 false, 这一配置项应用于所有的listeners.
收到reload signal重现加载配置项时，当前的所有访问控制项都会被释放然后重新加载，存在的订阅也会被影响。
allow_anonymous [ true | false ]
布尔型，指定不提供用户名的连接是否被允许。如果设此项为 false ，需要设定其他的方式来控制client的访问。默认值为true，如果没有配置其他的安全选项的话。
如果设置了 password_file 或 psk_file , 又或者实现了username/password 或 TLS-PSK 检查的认证插件被加载，那么allow_anonymous 的默认值为 false.
如果 per_listener_settings 是 true, 此项只应用于当前的 listener 。如果 per_listener_settings为 false, 此项应用于所有的 listeners.
reload signal会导致重新加载.
allow_duplicate_messages [ true | false ]
如果一个client订阅了多个topic项并且有重叠，例如foo/# 和 foo/+/baz， MQTT broker收到topic的消息并且两个订阅都匹配时（例如foo/bar/baz），broker只会发送一次消息。
Mosquitto 会记录这条消息发给了哪个client. 这个选项会关闭这个行为。当你有大量的clients订阅相同的topic时，为了节省内存，这个选项很有用。
设为 true 也是安全的，如果你事先知道client不会发送重叠的订阅,否则的话，你的client必须能够正确处理重复的消息即使QoS=2.
默认为 true. 这一选项时全局的。 reload signal会导致重新加载。
allow_zero_length_clientid [ true | false ]
MQTT 3.1.1 和 MQTT 允许client 携带长度为0的client id并让broker 为client生成一个 client id. 此选项可以打开或关闭这个行为. 默认为 true.
参见 auto_id_prefix 选项.
如果 per_listener_settings 为 true, 此项只应用于当前的 listener. 如果 per_listener_settings 为 false, 此项应用于所有的 listeners.
reload signal导致重新加载此项.
auth_opt_* value
传给auth plugin的参数. 只应用于当前配置的认证插件。
auth_plugin file path
指定外部模块用来做认证和访问控制。此项允许创建定制的用户名/密码和访问控制。
可以指定多次以加载多个插件，插件按照定义的顺序处理。
如果与auth_plugin一起， password_file, 或者 acl_file 被用在配置文件中,插件的检查将会在内置的检查之后进行。
reload signal不会重新加载.
auth_plugin_deny_special_chars [ true | false ]
如果为 true ，在访问控制检查之前，需要检查的client的username/client id 会被查找是否含有'+' 或者 '#'字符. 如果在username或者 client id中找到这些字符, 发送给插件之前，访问控制检查会被拒绝。
这一检查阻止恶意用户在它们的username or client id中使用这些字符来规避访问控制检查。
mosquitto 报过此问题，问题id为 CVE-2017-7650.
如果你能完全确定你的插件不会遭受此类攻击，你可以关闭此选项。
默认值为 true.
只应用于当前配置的认证插件。
reload signal不会导致重新加载。.
auto_id_prefix prefix
如果allow_zero_length_clientid 为 true, 此项允许你设置一个字符串作为自动生成的client id的前缀。这是为了log中好查找信息。 默认为 auto-.
如果 per_listener_settings 为 true, 此项只应用于当前 listener. 如果 per_listener_settings 为 false, 此项应用给所有listeners.
reload signal会导致重新加载。
autosave_interval seconds
mosquitto 把内存中的数据保存到磁盘的时间间隔。 如果设为0, 只有当 mosquitto 退出或者收到SIGUSR1 信号时才会将内存数据保存到磁盘。 注意，此选项只有在 persistence 为true时才生效。 默认值为 1800 秒 (30分钟).
此选项是全局的.
reload signal会导致重新加载。
autosave_on_changes [ true | false ]
如果为 true, mosquitto 将会记录订阅变化、保留消息和缓存消息的总数，如果总数超过了 autosave_interval ，内存中的数据会保存到磁盘。 如果为 false, mosquitto 会保存内存数据到磁盘按照 autosave_interval 作为时间计时.
此选项是全局的.
reload signal会导致重新加载。
check_retain_source [ true | false ]
当一个client订阅一个有遗留消息的topic时，如果check_retain_source 为 true（默认值为true），mosquitto在重新publish消息之前会检查遗留消息的源的访问权限。如果为false,不做任何检查，遗留消息总会 publish。
此选项是全局，除非配置per_listener_settings 项。
clientid_prefixes prefix
如果定义此项，只有clientid的前缀匹配这个前缀的client才被允许连接broker。例如, 设置"secure-" 意味着只有client "secure-client" 能够连接，但是clientid "mqtt" 不能连接。默认所有的client ids都是有效的。
这个选项是全局的.
reload signal会导致重新加载. 注意，当前已经连接的clients不会受配置改变的影响。
connection_messages [ true | false ]
如果为 true, 当client连接和断开连接时会在log中有记录，否则，log中不会出现这些信息。
此选项是全局的.
reload signal会导致重新加载。
include_dir dir
外部配置文件的所在目录. 此目录中所有以'.conf'结尾的文件都会被加载作为配置文件。最好将此项放在主配置文件的最后。此选项只在主配置文件中有效。指定的目录中必须不能包含主配置文件。
目录中配置文件的加载顺序以区分大小写的字母表顺序为准。
例如，目录中有 b.conf, A.conf, 01.conf, a.conf, B.conf和 00.conf ，则配置文件的加载顺序为:
00.conf01.confA.confa.confB.confb.conf
如果这个选项被配置了多次, 则按照它们在主配置文件中的书写顺序依次处理。
例如：目录 one.d 包含文件 B.conf and C.conf, 另一个目录two.d 包含文件 A.conf and D.conf, 配置项为：
include_dir one.dinclude_dir two.d这时的加载顺序为:
# files from one.dB.confC.conf# files from two.dA.confD.conf
log_dest destinations
发送log信息到指定的目的文件，可以是: stdout stderr syslog topic.
stdout 和 stderr会输出log到控制台.
syslog 一般会输出到 /var/log/messages 或类似的文件，这取决于操作系统及配置；topic logs 会发送到broker的 topic '$SYS/broker/log/<severity>', 这里的’severity’ 可以是D, E, W, N, I, M,分别代表 debug, error, warning, notice, information and message. 消息的 severity用在订阅和取消订阅的log_type 选项以及发布消息log到 $SYS/broker/log/M/subscribe 和 $SYS/broker/log/M/unsubscribe.
目的地是文件的话，需要一个额外的参数指定文件名，例如 "log_dest file /var/log/mosquitto.log". 当broker收到HUP信号时，文件会关闭和重新打开。只能配置单个文件。
如果希望禁用log的话，配置为 "log_dest none"。 默认的log到 stderr. 这个选项可以配置多次。
注意， 如果broker运行在windows系统，则默认为 "log_dest none" 并且 stdout和 stderr都不可用。
reload signal会导致重新加载此配置项
log_facility local facility
如果使用syslog (不能是 Windows), 消息会默认记录到 "daemon" facility。 使用 log_facility 选项来选择使用local0 到local7 的哪一个。值是一个整型，例如 "log_facility 5" 指定使用 local5.
log_timestamp [ true | false ]
布尔型, 如果为 true ，时间戳会加到每一条log中 。默认值是 true.
reload signal会导致重新加载此配置项。
log_timestamp_format format
指定时间戳的格式. 如果不设置, 这个值是Unix 纪元开始的秒数. 这个选项值会作为一个纯文本字符串发送给 strftime 函数作为格式串. 例如:
log_timestamp_format %Y-%m-%dT%H:%M:%Sreload signal会导致重新加载此配置项.
log_type types
选择输出到log的log类型，可以是: debug, error, warning, notice, information, subscribe, unsubscribe, websockets, none, all.
默认是 error, warning, notice and information. 这个选项可以配置多次. 注意， debug 类型 用来解码 incoming/outgoing network packets) 永远不会记录到topics.
reload signal会导致重新加载此配置项.
max_inflight_bytes count
输出的 QoS 1 和 2 消息 可以被允许传输直到字节数达到限制值. 这可以用来基于消息的大小而不是消息的个数去控制输出消息的速率。 如果值设为100, 达到100字节的消息仍然允许发送, 但是一次只能有一个消息在传输. 默认为 0(表示没有限制).
参见 max_inflight_messages 选项.
这个选项是全局的.
reload signal会导致重新加载此配置项.
max_inflight_messages count
可以同时处理的在输出的 QoS 1 或者 2 消息的最大个数 。包括正在握手的消息和重传的消息.默认值为20. 设置为0表示没有限制. 如果设置为1, 将会顺序发送消息.
这个选项是全局的.
reload signal会导致重新加载此配置项.
max_keepalive value
对于MQTT v5 的client, 可以让 server 发送一个 "server keepalive" 值来重写client自己设置的 keepalive值. 这种机制可以让server早于client期望的时间断开与client的连接， 并且 client 应该使用新的keepalive 值. 这个选项使server可以指定client使用的keepalive值必须小于等于此项配置的值, 否则client就会收到server发送的消息使用max_keepalive作为keepalive 值. 仅对 MQTT v5 clients有效. 这个选项的最大值也是默认值是 65535. 不要设置为低于10 秒。
这个选项是全局的.
reload signal会导致重新加载此配置项.
max_packet_size value
对于MQTT v5 的clients, server可以发送一个"maximum packet size" 值到client来告诉client它不会接受大于value 字节的MQTT包。 这个限制是对整个MQTT包, 不仅仅是负载数据. 如果一个client 发送的包长度大于这个value, 将会被断开连接. 这个限制会应用到所有的client，不管它用的协议是哪个版本, 但是 v3.1.1 和更老版本的clients 不会收到这个最大限制信息. 默认为没有限制.
这个选项使用于所有的clients, 不仅仅是 MQTT v5的client, 但是没有办法通知使用MQTT v3.1.1 or MQTT v3.1的client这个限制信息，也就是说虽然老版本的client不能收到此信息，如果发送了超过限制的包的话，他们仍然会被断开连接。
设置此值低于20 个字节是禁止的，因为这将会影响正常的client操作即使使用很小的负载数据.
这个选项是全局的.
reload signal会导致重新加载此配置项.
max_queued_bytes count
broker可以缓存的输出的QoS 1 和 2的消息数据大小（per client）。 如果超过了这个限制值，后续的消息会被丢弃掉. 这个选项很重要，如果发送消息的速率很高或者client处理的速度慢，又或者client掉线了。 默认为 0. (没有限制).
参见 max_queued_messages 选项. 如果 max_queued_messages 和 max_queued_bytes 都配置了值, 包将会缓存直到达到第一个限制.
这个选项是全局的.
reload signal会导致重新加载此配置项.
max_queued_messages count
可以缓存的QoS 1或 2 消息的最大个数(per client) 默认为 100. 设为0表示没有限制 (不建议这么做). 参见 queue_qos0_messages 和 max_queued_bytes 选项.
这个选项是全局的.
reload signal会导致重新加载此配置项.
memory_limit limit
设置broker可以在堆上分配的最大内存. 超过这个值时，内存请求会被拒绝。这个影响取决于什么被拒绝：如果进入的消息请求内存被拒绝，这个消息会被丢弃，发布这个消息的client会被断开连接；如果出去的消息申请内存时被拒绝，这个消息会被丢弃，接收这个消息的client会被断开连接。默认为没有限制.
这个选项仅在编译选项’memory tracking support ‘ 打开时有效。
reload signal会导致重新加载此配置项. 设置为一个很小的值然后重新加载配置项，不会导致已经分配的内存被释放。
message_size_limit limit
设置broker允许的可以发布消息的最大负载数据长度. 超过这个长度限制的消息会被broker拒绝。这就是说此消息不会被发送到订阅此消息的client, 但是QoS 1 或者 QoS 2消息的QoS 流会完成整个流程。 使用QoS 1 或者QoS 2的MQTT v5的 clients 会收到一个 PUBACK or PUBREC 带有 "implementation specific error" 的错误原因.
默认值为0, 表示没有限制. MQTT支持的最大负载长度为 268435455字节.
这个选项是全局的.
reload signal会导致重新加载此配置项.
password_file file path
设置密码文件的路径. 如果定义了此文件, 里面的内容会被用来控制client的访问。这个文件可以使用mosquitto_passwd(1)工具创建. 如果 mosquitto 编译时没有支持 TLS (建议打开 TLS支持项), 那么密码文件必须是文本文件并按照下面的格式 "username:password", 这里的’:’he和password是可选的. 如果 allow_anonymous 设为 false, 只有定义在这个文件中的用户可以连接broker. 需要设置 allow_anonymous 为true 当 定义了password_file 文件并且acl_file 文件中有只读的guest/anonymous 账户而且定义了可以发布消息的用户。
如果 per_listener_settings 为true, 此项应用于当前 listener， 如果 per_listener_settings 为 false, 此项应用于所有的listeners.
reload signal会导致重新加载此配置项. 当前加载的用户名和密码会被释放，然后重新加载。已经连接的client没有影响.
per_listener_settings [ true | false ]
如果为 true, 认证和访问控制将是per-listener的. 下面的选项会受到影响:
password_file, acl_file, psk_file, allow_anonymous, allow_zero_length_clientid, auth_plugin, auth_opt_*, auto_id_prefix.
注意，如果设为 true, 持久连接的client (例如clean session为false) 断掉连接后将会使用它最近刚连接过的listener的访问控制配置。
默认行为是设为false.
reload signal会导致重新加载此配置项.
persistence [ true | false ]
如果为 true, 连接, 订阅和消息数据将会写到磁盘文件mosquitto.db中，存放在persistence_location指定的目录. 当 mosquitto重启时, 它会重新加载mosquitto.db的信息. 数据会被写到磁盘当mosquitto 关闭或者到了autosave_interval定义的周期. 发送一个SIGUSR1信号也会强制mosquitto 写数据到磁盘。如果为 false, 数据只会存在内存中，默认为 false.
在新版本中，文件的格式可能会发生改变。Broker能够读老的格式，但是只能保存数据到新格式，所以升级是安全的。但是，保险起见，在装新版本之前，先保存老的文件，这样，就可以在需要的时候回退到老版本。
这个选项是全局的.
reload signal会导致重新加载此配置项.
persistence_file file name
持久文件数据库的名字. 默认为 mosquitto.db.
这个选项是全局的.
reload signal会导致重新加载此配置项.
persistence_location path
持久文件数据库存放的路径. 结尾必须带’/’. 如果不带，将会使用当前目录。
这个选项是全局的.
reload signal会导致重新加载此配置项.
persistent_client_expiration duration
这个选项允许持久clients (clean session 设为 false) 可以被删除掉如果他们在一定的时间内没有重新连接. 这是一个非标准选项. MQTT协议规范定义持久client永远持久。
设计不好的clients可能设置 clean session 为 false 同时使用随机产生的client id. 这会导致持久client永远不重连. 这个选项可以删除这样的clients.
超时时间是一个整型值跟一个h d w m y 分别表示 hour, day, week, month 和 year。例如:
- persistent_client_expiration 2m
- persistent_client_expiration 14d
- persistent_client_expiration 1y
因为这是一个非标准选项，不设置的默认行为是永不超时。
这个选项是全局的.
reload signal会导致重新加载此配置项.
pid_file file path
把 pid 写到指定的文件中.如果不配值 (默认), 不会写pid文件. 如果 pid 文件不能写入, mosquitto 会退出. 这个选项在mosquitto运行于daemon模式时会产生影响。
如果 mosquitto 是被初始化脚本自动拉起来的，它会要求写到pid文件， 例如 /var/run/mosquitto.pid
reload signal不会重新加载.
psk_file file path
设置 pre-shared-key 文件路径. 这个选项需要 listener打开 PSK 支持. 如果定义，文件的内容会用来控制client连接broker。 每一行的格式为"identity:key", key是一个十六进制传不带 "0x"头. Client连接支持PSK的listener时，必须提供一个匹配的identity and PSK.
如果 per_listener_settings 为 true, t此项只应用在当前listener。如果 per_listener_settings 为 false, 此项应用到所有的listeners.
reload signal导致重新加载此项. 当前已经加载的identity 和 key 数据会被释放并重新加载. 已经连接的客户端不受影响.
queue_qos0_messages [ true | false ]
设为 true来缓存 QoS 0 的message当一个持久client断掉连接. 这些消息包含在 max_queued_messages定义的限制中. 默认为 false.
注意， MQTT v3.1.1 标准规定只有 QoS 1 and 2 消息在这种情况下才能保存，所以这是一个非标准选项。
这个选项是全局的.
reload signal会导致重新加载此配置项.
retain_available [ true | false ]
如果设为false, retained messages 不被支持. 如果client发送带有retain bit 的消息，将会被断掉连接. 默认为 true.
这个选项是全局的.
reload signal会导致重新加载此配置项.
retained_persistence [ true | false ]
与 persistence 选项同一个意义.
reload signal会导致重新加载此配置项.
set_tcp_nodelay [ true | false ]
如果设为 true, client socket的TCP_NODELAY 将会被设置来关闭Nagle算法. 这会降低延时当发送的TCP包有显著增加时。默认为 false.
这个选项是全局的.
reload signal会导致重新加载此配置项.
sys_interval seconds
更新 $SYS定于层级的间隔秒数, 它提供broke的状态信息. 如果不设置，默认为 10 秒。
设为 0以关闭发布$SYS 层级.
这个选项是全局的.
reload signal会导致重新加载此配置项.
upgrade_outgoing_qos [ true | false ]
MQTT 规范规定发送一个消息给订阅者的QoS永远不能达到发布器消息的QoS. 打开此选项可以改变这个行为. 如果 upgrade_outgoing_qos 设为 true, 消息发送给订阅者的QoS总是会匹配发布的QoS。这是一个非标准的选项. 默认为 false.
这个选项是全局的.
reload signal会导致重新加载此配置项.
user username
当以root运行时, 启动时，更为为此配置的user 和它所在的组 。如果mosquitto不能更改用户和组, 它将报错并退出. 配置的用户必须有持久数据库的读写权限和certificate, password, ACL文件的读权限. 如果以非root用户运行，这个选项不起作用.默认为 mosquitto.
这个选项对windows不起作用。
reload signal不会导致重新加载.
