diff --git a/man/common/option-bind.xml b/man/common/option-bind.xml new file mode 100644 index 00000000..63d8a599 --- /dev/null +++ b/man/common/option-bind.xml @@ -0,0 +1,10 @@ + + + + + Bind the outgoing connection to a local ip address/hostname. Use + this argument if you need to restrict network communication to a + particular interface. + + + diff --git a/man/common/option-clean-session.xml b/man/common/option-clean-session.xml new file mode 100644 index 00000000..12da70ce --- /dev/null +++ b/man/common/option-clean-session.xml @@ -0,0 +1,25 @@ + + + + + + Disable 'clean session' / enable persistent client mode. When this + argument is used, the broker will be instructed not to clean + existing sessions for the same client id when the client connects, + and sessions will never expire when the client disconnects. MQTT v5 + clients can change their session expiry interval with the + argument. + + + When a session is persisted on the broker, the subscriptions for the + client will be maintained after it disconnects, along with + subsequent QoS 1 and QoS 2 messages that arrive. When the client + reconnects and does not clean the session, it will receive all of + the queued messages. + + + If using this option, the client id must be set manually with + . + + + diff --git a/man/common/option-clientid-prefix.xml b/man/common/option-clientid-prefix.xml new file mode 100644 index 00000000..bf570c6e --- /dev/null +++ b/man/common/option-clientid-prefix.xml @@ -0,0 +1,12 @@ + + + + + + Provide a prefix that the client id will be built from by appending + the process id of the client. This is useful where the broker is + using the clientid_prefixes option. Cannot be used at the same time + as the argument. + + + diff --git a/man/common/option-clientid.xml b/man/common/option-clientid.xml new file mode 100644 index 00000000..15a2d8ab --- /dev/null +++ b/man/common/option-clientid.xml @@ -0,0 +1,15 @@ + + + + + + The id to use for this client. If not given, a client id will be + generated depending on the MQTT version being used. For v3.1.1/v3.1, + the client generates a client id in the format + , where the + are replaced with random alphanumeric characters. For v5.0, the client + sends a zero length client id, and the server will generate a client + id for the client. + + + diff --git a/man/common/option-debug.xml b/man/common/option-debug.xml new file mode 100644 index 00000000..b0a50dc1 --- /dev/null +++ b/man/common/option-debug.xml @@ -0,0 +1,9 @@ + + + + + + Enable debug messages. + + + diff --git a/man/common/option-format-no-eol.xml b/man/common/option-format-no-eol.xml new file mode 100644 index 00000000..e279bc6a --- /dev/null +++ b/man/common/option-format-no-eol.xml @@ -0,0 +1,11 @@ + + + + + Do not append an end of line character to the payload when printing. + This allows streaming of payload data from multiple messages + directly to another application unmodified. Only really makes sense + when not using . + + + diff --git a/man/common/option-format-pretty.xml b/man/common/option-format-pretty.xml new file mode 100644 index 00000000..bde25f0b --- /dev/null +++ b/man/common/option-format-pretty.xml @@ -0,0 +1,10 @@ + + + + + When using the JSON output format %j or %J, the default is to print + in an unformatted fashion. Specifying + prints messages in a prettier, more human readable format. + + + diff --git a/man/common/option-format-verbose.xml b/man/common/option-format-verbose.xml new file mode 100644 index 00000000..6c78f6b4 --- /dev/null +++ b/man/common/option-format-verbose.xml @@ -0,0 +1,14 @@ + + + + + + Print received messages verbosely. With this argument, messages will + be printed as "topic payload". When this argument is not given, the + messages are printed as "payload". + + + See also . + + + diff --git a/man/common/option-format.xml b/man/common/option-format.xml new file mode 100644 index 00000000..42dfd2f4 --- /dev/null +++ b/man/common/option-format.xml @@ -0,0 +1,15 @@ + + + + + Specify output printing format. This option allows you to choose + what information from each message is printed to the screen. See the + Output Format section below for + full details. + + + This option overrides the option, but does not + override the option. + + + diff --git a/man/common/option-help.xml b/man/common/option-help.xml new file mode 100644 index 00000000..3194e3e0 --- /dev/null +++ b/man/common/option-help.xml @@ -0,0 +1,8 @@ + + + + + Display usage information. + + + diff --git a/man/common/option-hide-retain.xml b/man/common/option-hide-retain.xml new file mode 100644 index 00000000..5aa693c3 --- /dev/null +++ b/man/common/option-hide-retain.xml @@ -0,0 +1,15 @@ + + + + + If this argument is given, messages that are received that have the + retain bit set will not be printed. Messages with retain set are + "stale", in that it is not known when they were originally + published. When subscribing to a wildcard topic there may be a large + number of retained messages. This argument suppresses their display. + + + See also . + + + diff --git a/man/common/option-host.xml b/man/common/option-host.xml new file mode 100644 index 00000000..d4385380 --- /dev/null +++ b/man/common/option-host.xml @@ -0,0 +1,9 @@ + + + + + + Specify the host to connect to. Defaults to localhost. + + + diff --git a/man/common/option-keepalive.xml b/man/common/option-keepalive.xml new file mode 100644 index 00000000..2491aa34 --- /dev/null +++ b/man/common/option-keepalive.xml @@ -0,0 +1,11 @@ + + + + + + The number of seconds between sending PING commands to the broker + for the purposes of informing it we are still connected and + functioning. Defaults to 60 seconds. + + + diff --git a/man/common/option-no-tls.xml b/man/common/option-no-tls.xml new file mode 100644 index 00000000..ba652c63 --- /dev/null +++ b/man/common/option-no-tls.xml @@ -0,0 +1,10 @@ + + + + + Disable all use of TLS encryption. This is useful if you specify TLS + options in a configuration file but want to disable those options. + It also stops the automatic use of TLS when connecting to port 8883. + + + diff --git a/man/common/option-nodelay.xml b/man/common/option-nodelay.xml new file mode 100644 index 00000000..add3bb47 --- /dev/null +++ b/man/common/option-nodelay.xml @@ -0,0 +1,11 @@ + + + + + Disable Nagle's algorithm for the socket. This means that latency of + sent messages is reduced, which is particularly noticeable for + small, reasonably infrequent messages. Using this option may result + in more packets being sent than would normally be necessary. + + + diff --git a/man/common/option-password.xml b/man/common/option-password.xml new file mode 100644 index 00000000..5c638543 --- /dev/null +++ b/man/common/option-password.xml @@ -0,0 +1,14 @@ + + + + + + Provide a password to be used for authenticating with + the broker. Using this argument without also specifying + a username is invalid when using MQTT v3.1 or v3.1.1. + + + See also the option. + + + diff --git a/man/common/option-payload-file.xml b/man/common/option-payload-file.xml new file mode 100644 index 00000000..ec001014 --- /dev/null +++ b/man/common/option-payload-file.xml @@ -0,0 +1,9 @@ + + + + + + Send the contents of a file as the message. + + + diff --git a/man/common/option-payload-message.xml b/man/common/option-payload-message.xml new file mode 100644 index 00000000..5ba08e69 --- /dev/null +++ b/man/common/option-payload-message.xml @@ -0,0 +1,9 @@ + + + + + + Send a single request message from the command line. + + + diff --git a/man/common/option-payload-null.xml b/man/common/option-payload-null.xml new file mode 100644 index 00000000..89ce959c --- /dev/null +++ b/man/common/option-payload-null.xml @@ -0,0 +1,9 @@ + + + + + + Send a null (zero length) message. + + + diff --git a/man/common/option-payload-stdin-file.xml b/man/common/option-payload-stdin-file.xml new file mode 100644 index 00000000..12a70d60 --- /dev/null +++ b/man/common/option-payload-stdin-file.xml @@ -0,0 +1,10 @@ + + + + + + Send a request message read from stdin, sending the entire content + as a single message. + + + diff --git a/man/common/option-port.xml b/man/common/option-port.xml new file mode 100644 index 00000000..de437908 --- /dev/null +++ b/man/common/option-port.xml @@ -0,0 +1,10 @@ + + + + + + Connect to the port specified. If not given, the default of 1883 for + plain MQTT or 8883 for MQTT over TLS will be used. + + + diff --git a/man/common/option-property.xml b/man/common/option-property.xml new file mode 100644 index 00000000..030ee5a6 --- /dev/null +++ b/man/common/option-property.xml @@ -0,0 +1,38 @@ + + + + + + Set MQTT v5 properties for with this client. If you use this option, + the client will be set to be an MQTT v5 client. This option has two + forms: + + + + + is the MQTT command/packet identifier and + can be one of CONNECT, PUBLISH, PUBACK, PUBREC, PUBCOMP, SUBSCRIBE, + UNSUBSCRIBE, DISCONNECT, AUTH, or WILL. The properties available + for each command are listed in the Properties section. + + + + is the name of the property to add. + This is as described in the specification, but with '-' as a + word separator. For example: . + More details are in the Properties + section. + + + + is the value of the property to add, with a + data type that is property specific. + + + + is only used for the + property as the first of the two strings in the string pair. In that + case, is the second of the strings in the pair. + + + diff --git a/man/common/option-protocol-version.xml b/man/common/option-protocol-version.xml new file mode 100644 index 00000000..f1282736 --- /dev/null +++ b/man/common/option-protocol-version.xml @@ -0,0 +1,15 @@ + + + + + + Specify which version of the MQTT protocol should be + used when connecting to the remote broker. Can be + , , + , or the more verbose + , , or + . + Defaults to . + + + diff --git a/man/common/option-proxy.xml b/man/common/option-proxy.xml new file mode 100644 index 00000000..5986b0ec --- /dev/null +++ b/man/common/option-proxy.xml @@ -0,0 +1,32 @@ + + + + + Specify a SOCKS5 proxy to connect through. "None" and "username" + authentication types are supported. The + must be of the form . + The protocol prefix means that hostnames + are resolved by the proxy. The symbols %25, %3A and %40 are URL + decoded into %, : and @ respectively, if present in the username or + password. + + + + If username is not given, then no authentication is attempted. + If the port is not given, then the default of 1080 is used. + + + + If the host is given as an IPv6 address, it must be enclosed in + square brackets, e.g. . + Note that square brackets have special meaning in some shells, so + the proxy url may need quoting in double or single quotes. + + + + More SOCKS versions may be available in the future, depending on + demand, and will use different protocol prefixes as described in + curl1 . + + + diff --git a/man/common/option-qos-incoming.xml b/man/common/option-qos-incoming.xml new file mode 100644 index 00000000..ef9a0d81 --- /dev/null +++ b/man/common/option-qos-incoming.xml @@ -0,0 +1,16 @@ + + + + + + Specify the quality of service desired for the incoming messages, + from 0, 1 and 2. Defaults to 0. See + mqtt7 + for more information on QoS. + + + The QoS applies to all topics subscribed to in a single instance of + this client. + + + diff --git a/man/common/option-quiet.xml b/man/common/option-quiet.xml new file mode 100644 index 00000000..36ffd007 --- /dev/null +++ b/man/common/option-quiet.xml @@ -0,0 +1,10 @@ + + + + + If this argument is given, no runtime errors will be printed. This + excludes any error messages given in case of invalid user input + (e.g. using without a port). + + + diff --git a/man/common/option-session-expiry-interval.xml b/man/common/option-session-expiry-interval.xml new file mode 100644 index 00000000..14a10ac6 --- /dev/null +++ b/man/common/option-session-expiry-interval.xml @@ -0,0 +1,17 @@ + + + + + Set the session-expiry-interval property on the CONNECT packet. If + you use this option, the client will be set to be an MQTT v5 client. + Set to 0-4294967294 to specify the session will expire in that many + seconds after the client disconnects, or use -1, 4294967295, or ∞ + for a session that does not expire. Defaults to -1 if -c is also + given, or 0 if -c not given. + + + If the session is set to never expire, either with -x or -c, then a + client id must be provided. + + + diff --git a/man/common/option-srv.xml b/man/common/option-srv.xml new file mode 100644 index 00000000..de3ea0ae --- /dev/null +++ b/man/common/option-srv.xml @@ -0,0 +1,11 @@ + + + + + Use SRV lookups to determine which host to connect to. + Performs lookups to + when used in conjunction with , + otherwise uses . + + + diff --git a/man/common/option-timeout.xml b/man/common/option-timeout.xml new file mode 100644 index 00000000..1a8932c2 --- /dev/null +++ b/man/common/option-timeout.xml @@ -0,0 +1,11 @@ + + + + + Provide a timeout as an integer number of seconds. The client will + stop processing messages and disconnect after this number of seconds + has passed. The timeout starts just after the client has connected + to the broker. + + + diff --git a/man/common/option-tls-alpn.xml b/man/common/option-tls-alpn.xml new file mode 100644 index 00000000..69010b8f --- /dev/null +++ b/man/common/option-tls-alpn.xml @@ -0,0 +1,10 @@ + + + + + Provide a protocol to use when connecting to a broker that has + multiple protocols available on a single port, e.g. MQTT and + WebSockets. + + + diff --git a/man/common/option-tls-cafile.xml b/man/common/option-tls-cafile.xml new file mode 100644 index 00000000..9519aabe --- /dev/null +++ b/man/common/option-tls-cafile.xml @@ -0,0 +1,12 @@ + + + + + Define the path to a file containing PEM encoded CA certificates + that are trusted. Used to enable SSL communication. + + + See also + + + diff --git a/man/common/option-tls-capath.xml b/man/common/option-tls-capath.xml new file mode 100644 index 00000000..6b23edb2 --- /dev/null +++ b/man/common/option-tls-capath.xml @@ -0,0 +1,20 @@ + + + + + Define the path to a directory containing PEM encoded CA + certificates that are trusted. Used to enable SSL communication. + + + + For to work correctly, the certificate + files must have ".crt" as the file ending and you must run + "openssl rehash <path to capath>" each time you add/remove + a certificate. + + + + See also + + + diff --git a/man/common/option-tls-cert.xml b/man/common/option-tls-cert.xml new file mode 100644 index 00000000..a34d7f2c --- /dev/null +++ b/man/common/option-tls-cert.xml @@ -0,0 +1,14 @@ + + + + + Define the path to a file containing a PEM encoded certificate for + this client, if required by the server. + + + + See also and the Encrypted Connections + section. + + + diff --git a/man/common/option-tls-ciphers.xml b/man/common/option-tls-ciphers.xml new file mode 100644 index 00000000..92018e24 --- /dev/null +++ b/man/common/option-tls-ciphers.xml @@ -0,0 +1,11 @@ + + + + + An openssl compatible list of TLS ciphers to support in the + client. See + ciphers1 + for more information. + + + diff --git a/man/common/option-tls-engine-kpass-sha1.xml b/man/common/option-tls-engine-kpass-sha1.xml new file mode 100644 index 00000000..7961b62f --- /dev/null +++ b/man/common/option-tls-engine-kpass-sha1.xml @@ -0,0 +1,15 @@ + + + + + SHA1 of the private key password when using an TLS engine. Some TLS + engines such as the TPM engine may require the use of a password in + order to be accessed. This option allows a hex encoded SHA1 hash of + the password to the engine directly, instead of the user being + prompted for the password. + + + See also . + + + diff --git a/man/common/option-tls-engine.xml b/man/common/option-tls-engine.xml new file mode 100644 index 00000000..de381547 --- /dev/null +++ b/man/common/option-tls-engine.xml @@ -0,0 +1,12 @@ + + + + + A valid openssl engine id. These can be listed with the + openssl engine command. + + + See also . + + + diff --git a/man/common/option-tls-insecure.xml b/man/common/option-tls-insecure.xml new file mode 100644 index 00000000..97d11f25 --- /dev/null +++ b/man/common/option-tls-insecure.xml @@ -0,0 +1,15 @@ + + + + + When using certificate based encryption, this option disables + verification of the server hostname in the server certificate. This + can be useful when testing initial server configurations but makes + it possible for a malicious third party to impersonate your server + through DNS spoofing, for example. Use this option in testing + only. If you need to resort to using this option in a production + environment, your setup is at fault and there is no point using + encryption. + + + diff --git a/man/common/option-tls-key.xml b/man/common/option-tls-key.xml new file mode 100644 index 00000000..9fedc90d --- /dev/null +++ b/man/common/option-tls-key.xml @@ -0,0 +1,12 @@ + + + + + Define the path to a file containing a PEM encoded private key for + this client, carrying out mutual TLS with the server. + + + See also and the Encrypted Connections section. + + + diff --git a/man/common/option-tls-keyform.xml b/man/common/option-tls-keyform.xml new file mode 100644 index 00000000..c082ca8d --- /dev/null +++ b/man/common/option-tls-keyform.xml @@ -0,0 +1,16 @@ + + + + + Specifies the type of private key in use when making TLS + connections.. This can be "pem" or "engine". This parameter is + useful when a TPM module is being used and the private key has been + created with it. Defaults to "pem", which means normal private key + files are used. + + + See also . + + + + diff --git a/man/common/option-tls-keylog.xml b/man/common/option-tls-keylog.xml new file mode 100644 index 00000000..493ddd0d --- /dev/null +++ b/man/common/option-tls-keylog.xml @@ -0,0 +1,17 @@ + + file + + + Log TLS connection information to file. + This option allows tools such as tcpdump, + wireshark and mqttshark + to decrypt TLS traffic and inspect the MQTT traffic. In Wireshark + this can be done by setting the + option for the + protocol. + + + This option should be used for debugging only. + + + diff --git a/man/common/option-tls-psk-identity.xml b/man/common/option-tls-psk-identity.xml new file mode 100644 index 00000000..bb6822fa --- /dev/null +++ b/man/common/option-tls-psk-identity.xml @@ -0,0 +1,9 @@ + + + + + The client identity to use with TLS-PSK support. This may be used + instead of a username if the broker is configured to do so. + + + diff --git a/man/common/option-tls-psk.xml b/man/common/option-tls-psk.xml new file mode 100644 index 00000000..77ac0ad7 --- /dev/null +++ b/man/common/option-tls-psk.xml @@ -0,0 +1,10 @@ + + + + + Provide the hexadecimal (no leading 0x) pre-shared-key matching the + one used on the broker to use TLS-PSK encryption support. + must also be provided to enable TLS-PSK. + + + diff --git a/man/common/option-tls-use-os-certs.xml b/man/common/option-tls-use-os-certs.xml new file mode 100644 index 00000000..816463f4 --- /dev/null +++ b/man/common/option-tls-use-os-certs.xml @@ -0,0 +1,14 @@ + + + + + If used, this will load and trust the OS provided CA + certificates. This can be used in conjunction with + and + and can be used on its own to enable TLS mode. This + will be set by default if + is used, or if port is 8883 and no other certificate + options are used. + + + diff --git a/man/common/option-tls-version.xml b/man/common/option-tls-version.xml new file mode 100644 index 00000000..9a102920 --- /dev/null +++ b/man/common/option-tls-version.xml @@ -0,0 +1,11 @@ + + + + + Choose which TLS protocol version to use when communicating with the + broker. Valid options are and + . The default value is . + Must match the protocol version used by the broker. + + + diff --git a/man/common/option-unix-socket.xml b/man/common/option-unix-socket.xml new file mode 100644 index 00000000..e30ccd95 --- /dev/null +++ b/man/common/option-unix-socket.xml @@ -0,0 +1,16 @@ + + + + + Connect to a broker through a local unix domain socket + instead of a TCP socket. This is a replacement for + and . For example: + + + + See the option in + mosquitto.conf5 + to configure Mosquitto to listen on a unix socket. + + + diff --git a/man/common/option-url.xml b/man/common/option-url.xml new file mode 100644 index 00000000..fc4a15d4 --- /dev/null +++ b/man/common/option-url.xml @@ -0,0 +1,16 @@ + + + + + + Specify specify user, password, hostname, port and topic at once as + a URL. The URL must be in the form: + mqtt(s)://[username[:password]@]host[:port]/topic or + ws(s)://[username[:password]@]host[:port]/path + + + Depending on the scheme, the port will default to different values. + mqtt:// - 1883, mqtts:// - 8883, ws:// - 80, wss:// - 443. + + + diff --git a/man/common/option-username.xml b/man/common/option-username.xml new file mode 100644 index 00000000..6a9d0ce6 --- /dev/null +++ b/man/common/option-username.xml @@ -0,0 +1,14 @@ + + + + + + Provide a username to be used for authenticating with + the broker. + + + See also the argument. + + + + diff --git a/man/common/option-websockets.xml b/man/common/option-websockets.xml new file mode 100644 index 00000000..b63f2b74 --- /dev/null +++ b/man/common/option-websockets.xml @@ -0,0 +1,8 @@ + + + + + Connect using WebSockets instead of plain TCP. + + + diff --git a/man/common/option-will-payload.xml b/man/common/option-will-payload.xml new file mode 100644 index 00000000..62a3c3ac --- /dev/null +++ b/man/common/option-will-payload.xml @@ -0,0 +1,10 @@ + + + + + Specify a message that will be stored by the broker and sent out if + this client disconnects unexpectedly. This must be used in + conjunction with . + + + diff --git a/man/common/option-will-qos.xml b/man/common/option-will-qos.xml new file mode 100644 index 00000000..a3f562c8 --- /dev/null +++ b/man/common/option-will-qos.xml @@ -0,0 +1,9 @@ + + + + + The QoS to use for the Will. Defaults to 0. This must be used in + conjunction with . + + + diff --git a/man/common/option-will-retain.xml b/man/common/option-will-retain.xml new file mode 100644 index 00000000..97e3b63d --- /dev/null +++ b/man/common/option-will-retain.xml @@ -0,0 +1,10 @@ + + + + + If given, if the client disconnects unexpectedly the message sent + out will be treated as a retained message. This must be used in + conjunction with . + + + diff --git a/man/common/option-will-topic.xml b/man/common/option-will-topic.xml new file mode 100644 index 00000000..b08b70c5 --- /dev/null +++ b/man/common/option-will-topic.xml @@ -0,0 +1,9 @@ + + + + + The topic on which to send a Will, in the event that the client + disconnects unexpectedly. + + + diff --git a/man/common/section-bugs.xml b/man/common/section-bugs.xml new file mode 100644 index 00000000..bfd24795 --- /dev/null +++ b/man/common/section-bugs.xml @@ -0,0 +1,7 @@ + + Bugs + + mosquitto bug information can be found at + + + diff --git a/man/common/section-encrypted-connections.xml b/man/common/section-encrypted-connections.xml new file mode 100644 index 00000000..7b3ce6be --- /dev/null +++ b/man/common/section-encrypted-connections.xml @@ -0,0 +1,24 @@ + + Encrypted Connections + + This client supports TLS encrypted connections. It is strongly + recommended that you use an encrypted connection for anything more than + the most basic setup. + + + To enable TLS connections when using x509 certificates, one of + either or can + be provided as an option. + + + Alternatively, if the option is used + then the OS provided certificates will be loaded and neither + or are + needed. + + + To enable TLS connections when using TLS-PSK, you must use the + and the + options. + + diff --git a/man/common/section-exit-status.xml b/man/common/section-exit-status.xml new file mode 100644 index 00000000..23d6bcdf --- /dev/null +++ b/man/common/section-exit-status.xml @@ -0,0 +1,62 @@ + + Exit Status + + Zero on success, or non-zero on error. If the connection is refused + by the broker at the MQTT level, then the exit code is the CONNACK + reason code. If another error occurs, the exit code is a + libmosquitto return value. + + + MQTT v3.1.1 CONNACK codes: + + Success + Connection refused: Bad protocol version + Connection refused: Identifier rejected + Connection refused: Server unavailable + Connection refused: Bad username/password + Connection refused: Not authorized + + + MQTT v5 CONNACK codes: + + Success + Unspecified error + Malformed packet + Protocol error + Implementation specific error + Unsupported protocol version + Client ID not valid + Bad username or password + Not authorized + Server unavailable + Server busy + Banned + Server shutting down + Bad authentication method + Keep alive timeout + Session taken over + Topic filter invalid + Topic name invalid + Receive maximum exceeded + Topic alias invalid + Packet too large + Message rate too high + Quota exceeded + Administrative action + Payload format invalid + Retain not supported + QoS not supported + Use another server + Server moved + Shared subscriptions not supported + Connection rate exceeded + Maximum connect time + Subscription IDs not supported + Wildcard subscriptions not supported + + + Other codes: + + Timed out waiting for message + + diff --git a/man/common/section-output-format.xml b/man/common/section-output-format.xml new file mode 100644 index 00000000..21392de9 --- /dev/null +++ b/man/common/section-output-format.xml @@ -0,0 +1,237 @@ + + Output Format + + There are three ways of formatting the printed output. In all cases a + new-line character is appended for each message received unless the + argument is given. + + + Payload-only is the default output format and will print the payload + exactly as it is received. + + + Verbose mode is activated with and prints the + message topic and the payload, separated by a space. + + + The final option is formatted output, which allows the user to + define a custom output format. The behaviour is controlled with + the option. The format string is + a free text string where interpreted sequences are replaced by + different parameters. The available interpreted sequences are + described below. + + + Three characters are used to start an interpreted sequence: + , and . + Sequences starting with are either parameters + related to the MQTT message being printed, or are helper sequences + to avoid the need to type long date format strings for example. + Sequences starting with are passed to the + strftime3 + function (with the @ replaced with a % - note that only the + character immediately after the @ is passed to strftime). This + allows the construction of a wide variety of time based outputs. + The output options for strftime vary from platform to platform, so + please check what is available for your platform. One extension to + strftime is provided which is , which can be + used to obtain the number of nanoseconds passed in the current + second. The resolution of this option varies depending on the + platform. The final sequence character is , + which is used to input some characters that would otherwise be + difficult to enter. + + + + Flag characters + + The parameters %A, %C, %d, %E, %F, %f, %I, %l, %m, %p, %R, %S, %t, + %x, and %X can have optional flags immediately after the % + character. + + + + + + + The value should be zero padded. This applies to the + parameters %A, %E, %d, %F, %f, %l, %m, %S, %X, and %x. + It will be ignored for other parameters. If used with + the flag, the + flag will be ignored. + + + + + + + + + The value will be left aligned to the field width, + padded with blanks. The default is right alignment, with + either 0 or blank padding. + + + + + + + + Field width + + Some of the MQTT related parameters can be formatted with an + option to set their field width in a similar way to regular + printf style formats, i.e. this sets the minimum width when + printing this parameter. If the output length is smaller than + this width, the field will be padded to meet this width. This + applies to the options %A, %C, %d, %E, %F, %f, %I, %l, %m, %p, + %R, %S, %t, %x, %X. + + + For example would set the minimum topic + field width to 10 characters. + + + + + Maximum width + + Some of the MQTT related parameters can be formatted with an + option to set a maximum field width in a similar way to regular + printf style formats, for example for a + maximum width of 20. This applies to the options %C, %I, %R, %t. + + + For example would set the minimum topic + field width to 10 characters, and the maximum topic width to + 10 characters, i.e. the field will always be exactly 10 + characters long. + + + + + Hexadecimal binary field width + + The %x and %X parameters output the payload as a single + hexadecimal string by default. It is also possible to split the + hexadecimal payload into fields by a chosen length of nibbles. + For example, would split the payload into + two nibble or one byte values, separated by spaces and might produce + an output of 18 83. + + + The separator character is a space by default, but can be changed + to one of + by adding that character after the binary field width. For example + might produce an output of + 18:83. + + + + + Floating point number printing consideration + + The output format supports only the IEEE 754 floating point standard + as described in Annex F of ISO/IEC 9899:1999. Don't try to use %f or + %d if the platform of the publisher uses a different floating point + representation standard than IEEE 754 or you will get invalid data. + If you are unsure what floating representation your platform is + using, then it is most likely IEEE 754. If you get malformed or + unexpected values, check if the floating point number in the payload + from the publisher is encoded in IEEE 754. + + + If want to print floats, make sure you only subscribe to topics that + send only IEEE 754 formatted floats. The processing is very strict + about floats and if anything that is not a float is received, an + error message will be printed. + + + + + MQTT related parameters + + a literal %. + the MQTT v5 topic-alias property, if present. + the MQTT v5 content-type property, if present. + the MQTT v5 correlation-data property, if present. Note that this + property is specified as binary data, so may produce non-printable characters. + the payload treated as an 8 byte IEEE 754 float (double). + the MQTT v5 message-expiry-interval property, if present. + the MQTT v5 payload-format-indicator property, if present. + the payload treated as an 4 byte IEEE 754 float. + the length of the payload in bytes. + the message id (only relevant for messages with QoS>0). + the MQTT v5 user-property property, if present. This will be printed in the + form key:value. It is possible for any number of user properties to be attached to a message, and to + have duplicate keys. + the payload raw bytes (may produce non-printable characters depending on the payload). + the message QoS. + the MQTT v5 response-topic property, if present. + the retained flag for the message. + the MQTT v5 subscription-identifier property, if present. + the message topic. + the payload with each byte as a hexadecimal number (lower case). + the payload with each byte as a hexadecimal number (upper case). + + + + + Helpers + + ISO-8601 format date and time, e.g. 2016-08-10T09:47:38+0100 + JSON output of message + parameters and timestamp, with a quoted and escaped + payload. For example + {"tst":"2020-05-06T22:12:00.000000+0100","topic":"greeting","qos":0,"retain":0,"payload":"hello world"} + + JSON output of message + parameters and timestamp, with a non-quoted and + non-escaped payload - this means the payload must + itself be valid JSON. For example: + {"tst":"2020-05-06T22:12:00.000000+0100","topic":"foo","qos":0,"retain":0,"payload":{"temperature":27.0,"humidity":57}}. + + + If the payload is not valid JSON, then the error message + "Error: Message payload is not valid JSON on topic + <topic>" will be printed to stderr. + + + Unix timestamp with nanoseconds, e.g. 1470818943.786368637 + + + + + Time related parameters + + a literal @. + pass the character represented + by to the strftime function as + . The options supported are platform + dependent. + the number of nanoseconds that + have passed in the current second, with varying timing + resolution depending on platform. + + + + + Escape characters + + a literal \. + a null character. Can be used + to separate different parameters that may contain spaces + (e.g. topic, payload) so that processing with tools such as + xargs1 + is easier. + alert/bell. + the escape sequence, which can + be used with ANSI colour codes to provide coloured output + for example. + end of line. + carriage return. + horizontal tab. + vertical tab. + + + diff --git a/man/common/section-properties-connect.xml b/man/common/section-properties-connect.xml new file mode 100644 index 00000000..d875a4c9 --- /dev/null +++ b/man/common/section-properties-connect.xml @@ -0,0 +1,14 @@ + + Connect + + (binary data - note treated as a string) + (UTF-8 string pair) + (32-bit unsigned integer) + (16-bit unsigned integer) + (8-bit unsigned integer) + (8-bit unsigned integer) + (32-bit unsigned integer, note use instead) + (16-bit unsigned integer) + (UTF-8 string pair) + + diff --git a/man/common/section-properties-disconnect.xml b/man/common/section-properties-disconnect.xml new file mode 100644 index 00000000..41d27aa7 --- /dev/null +++ b/man/common/section-properties-disconnect.xml @@ -0,0 +1,7 @@ + + Disconnect + + (32-bit unsigned integer) + (UTF-8 string pair) + + diff --git a/man/common/section-properties-publish.xml b/man/common/section-properties-publish.xml new file mode 100644 index 00000000..6915c0b3 --- /dev/null +++ b/man/common/section-properties-publish.xml @@ -0,0 +1,12 @@ + + Publish + + (UTF-8 string) + (binary data - note treated as a string) + (32-bit unsigned integer) + (8-bit unsigned integer) + (UTF-8 string) + (16-bit unsigned integer) + (UTF-8 string pair) + + diff --git a/man/common/section-properties-subscribe.xml b/man/common/section-properties-subscribe.xml new file mode 100644 index 00000000..72f0e2ce --- /dev/null +++ b/man/common/section-properties-subscribe.xml @@ -0,0 +1,6 @@ + + Subscribe + + (UTF-8 string pair) + + diff --git a/man/common/section-properties-unsubscribe.xml b/man/common/section-properties-unsubscribe.xml new file mode 100644 index 00000000..3d94c9da --- /dev/null +++ b/man/common/section-properties-unsubscribe.xml @@ -0,0 +1,6 @@ + + Unsubscribe + + (UTF-8 string pair) + + diff --git a/man/common/section-properties-will.xml b/man/common/section-properties-will.xml new file mode 100644 index 00000000..bff162c7 --- /dev/null +++ b/man/common/section-properties-will.xml @@ -0,0 +1,12 @@ + + Will properties + + (UTF-8 string) + (binary data - note treated as a string) + (32-bit unsigned integer) + (8-bit unsigned integer) + (UTF-8 string) + (UTF-8 string pair) + (32-bit unsigned integer) + + diff --git a/man/common/section-wills.xml b/man/common/section-wills.xml new file mode 100644 index 00000000..5222147e --- /dev/null +++ b/man/common/section-wills.xml @@ -0,0 +1,19 @@ + + Wills + + The client can register a message with the broker that will be sent out + if it disconnects unexpectedly. See + mqtt7 + for more information. + + + The minimum requirement for this is to use + to specify which topic the will should be sent out on. This will result + in a non-retained, zero length message with QoS 0. + + + Use the , + and arguments to modify the other will + parameters. + + diff --git a/man/common/synopsis-will.xml b/man/common/synopsis-will.xml new file mode 100644 index 00000000..40c0893e --- /dev/null +++ b/man/common/synopsis-will.xml @@ -0,0 +1,6 @@ + + topic + payload + qos + + diff --git a/man/mosquitto-tls.7.xml b/man/mosquitto-tls.7.xml index c1b5dc79..7f9dea1d 100644 --- a/man/mosquitto-tls.7.xml +++ b/man/mosquitto-tls.7.xml @@ -16,23 +16,28 @@ Description - mosquitto provides SSL support for encrypted + + mosquitto provides SSL support for encrypted network connections and authentication. This manual describes how - to create the files needed. - It is important to use different certificate subject - parameters for your CA, server and clients. If the certificates - appear identical, even though generated separately, the - broker/client will not be able to distinguish between them and - you will experience difficult to diagnose errors. + to create the files needed. + + + It is important to use different certificate subject + parameters for your CA, server and clients. If the certificates + appear identical, even though generated separately, the + broker/client will not be able to distinguish between them and + you will experience difficult to diagnose errors. + Generating certificates - The sections below give the openssl commands that can be used to + + The sections below give the openssl commands that can be used to generate certificates, but without any context. The asciicast at - https://asciinema.org/a/201826 - gives a full run through of how to use those commands. + https://asciinema.org/a/201826 + gives a full run through of how to use those commands. + diff --git a/man/mosquitto.8.xml b/man/mosquitto.8.xml index 86c6bf7d..50790f32 100644 --- a/man/mosquitto.8.xml +++ b/man/mosquitto.8.xml @@ -31,7 +31,10 @@ Description - mosquitto is a broker for the MQTT protocol version 5.0/3.1.1/3.1. + + mosquitto is a broker for the MQTT protocol + version 5.0/3.1.1/3.1. + It is part of the overall mosquitto project. See mosquitto7 @@ -365,79 +368,97 @@ Broker Status - Clients can find information about the broker by subscribing to - topics in the $SYS hierarchy as follows. Topics marked as static are - only sent once per client on subscription. All other topics are updated - every seconds. If - is 0, then updates are not sent. - Note that if you are using a command line client to interact with the + + Clients can find information about the broker by subscribing to + topics in the $SYS hierarchy as follows. Topics marked as static are + only sent once per client on subscription. All other topics are updated + every seconds. If + is 0, then updates are not sent. + + + Note that if you are using a command line client to interact with the $SYS topics and your shell interprets $ as an environment variable, you need to place the topic in single quotes '$SYS/...' or to escape the dollar symbol: \$SYS/... otherwise the $SYS will be - treated as an environment variable. + treated as an environment variable. + - The total number of bytes received since the broker - started. + + The total number of bytes received since the broker started. + - The total number of bytes sent since the broker - started. + + The total number of bytes sent since the broker started. + (deprecated) - The number of currently connected clients. + + The number of currently connected clients. + - The number of disconnected persistent clients that - have been expired and removed through the - persistent_client_expiration option. + + The number of disconnected persistent clients that have been + expired and removed through the persistent_client_expiration + option. + (deprecated) - The total number of persistent clients (with clean - session disabled) that are registered at the broker but are - currently disconnected. + + The total number of persistent clients (with clean session + disabled) that are registered at the broker but are + currently disconnected. + - The maximum number of clients that have been - connected to the broker at the same time. + + The maximum number of clients that have been connected to + the broker at the same time. + - The total number of connected and disconnected client sessions - currently registered on the broker. + + The total number of connected and disconnected client + sessions currently registered on the broker. + - When bridges are configured to/from the broker, + + When bridges are configured to/from the broker, common practice is to provide a status topic that indicates the state of the connection. This is provided within $SYS/broker/connection/ by default. If the value of the topic is 1 the connection is active, if 0 then it is not active. See the Bridges section below for - more information on bridges. + more information on bridges. + @@ -453,115 +474,137 @@ - The current size of the heap memory in use by - mosquitto. Note that this topic may be unavailable - depending on compile time options. + + The current size of the heap memory in use by + mosquitto. Note that this topic may be unavailable + depending on compile time options. + - The largest amount of heap memory used by - mosquitto. Note that this topic may be unavailable - depending on compile time options. + + The largest amount of heap memory used by + mosquitto. Note that this topic may be unavailable + depending on compile time options. + - The moving average of the number of CONNECT packets + + The moving average of the number of CONNECT packets received by the broker over different time intervals. The final "+" of the hierarchy can be 1min, 5min or 15min. The value returned represents the number of connections received in 1 minute, averaged over 1, 5 or - 15 minutes. + 15 minutes. + - The moving average of the number of bytes received by + + The moving average of the number of bytes received by the broker over different time intervals. The final "+" of the hierarchy can be 1min, 5min or 15min. The value returned represents the number of bytes received in 1 - minute, averaged over 1, 5 or 15 minutes. + minute, averaged over 1, 5 or 15 minutes. + - The moving average of the number of bytes sent by the + + The moving average of the number of bytes sent by the broker over different time intervals. The final "+" of the hierarchy can be 1min, 5min or 15min. The value returned represents the number of bytes sent in 1 - minute, averaged over 1, 5 or 15 minutes. + minute, averaged over 1, 5 or 15 minutes. + - The moving average of the number of all types of MQTT + + The moving average of the number of all types of MQTT messages received by the broker over different time - intervals. The final "+" of the hierarchy can be 1min, + intervals. The final "+" of the hierarchy can be 1min, 5min or 15min. The value returned represents the number of messages received in 1 minute, averaged over 1, 5 or - 15 minutes. + 15 minutes. + - The moving average of the number of all types of MQTT + + The moving average of the number of all types of MQTT messages sent by the broker over different time intervals. The final "+" of the hierarchy can be 1min, 5min or 15min. The value returned represents the number of messages send in 1 minute, averaged over 1, 5 or 15 - minutes. + minutes. + - The moving average of the number of publish messages + + The moving average of the number of publish messages dropped by the broker over different time intervals. This shows the rate at which durable clients that are disconnected are losing messages. The final "+" of the hierarchy can be 1min, 5min or 15min. The value returned represents the number of messages dropped in 1 - minute, averaged over 1, 5 or 15 minutes. + minute, averaged over 1, 5 or 15 minutes. + - The moving average of the number of publish messages + + The moving average of the number of publish messages received by the broker over different time intervals. The final "+" of the hierarchy can be 1min, 5min or 15min. The value returned represents the number of publish messages received in 1 minute, averaged over 1, - 5 or 15 minutes. + 5 or 15 minutes. + - The moving average of the number of publish messages + + The moving average of the number of publish messages sent by the broker over different time intervals. The final "+" of the hierarchy can be 1min, 5min or 15min. The value returned represents the number of publish messages sent in 1 minute, averaged over 1, 5 or 15 - minutes. + minutes. + - The moving average of the number of socket + + The moving average of the number of socket connections opened to the broker over different time intervals. The final "+" of the hierarchy can be 1min, 5min or 15min. The value returned represents the number of socket connections in 1 minute, averaged over 1, 5 - or 15 minutes. + or 15 minutes. + @@ -803,11 +846,13 @@ Wildcard Topic Subscriptions - In addition to allowing clients to subscribe to specific topics, - mosquitto also allows the use of two wildcards in subscriptions. - is the wildcard used to match a single level of - hierarchy. For example, for a topic of "a/b/c/d", the following example - subscriptions will match: + + In addition to allowing clients to subscribe to specific topics, + mosquitto also allows the use of two wildcards in subscriptions. + is the wildcard used to match a single level of + hierarchy. For example, for a topic of "a/b/c/d", the following example + subscriptions will match: + a/b/c/d +/b/c/d @@ -815,15 +860,19 @@ a/+/+/d +/+/+/+ - The following subscriptions will not match: + + The following subscriptions will not match: + a/b/c b/+/c/d +/+/+ - The second wildcard is and is used to match - all subsequent levels of hierarchy. With a topic of "a/b/c/d", the - following example subscriptions will match: + + The second wildcard is and is used to match + all subsequent levels of hierarchy. With a topic of "a/b/c/d", the + following example subscriptions will match: + a/b/c/d # @@ -832,29 +881,35 @@ a/b/c/# +/b/c/# - The $SYS hierarchy does not match a subscription of - "#". If you want to observe the entire $SYS hierarchy, subscribe to - $SYS/#. - Note that the wildcards must be only ever used on their own, so a - subscription of "a/b+/c" is not valid use of a wildcard. The - wildcard must only ever be used as the final - character of a subscription. + + The $SYS hierarchy does not match a subscription of "#". If you want + to observe the entire $SYS hierarchy, subscribe to $SYS/#. + + + Note that the wildcards must be only ever used on their own, so a + subscription of "a/b+/c" is not valid use of a wildcard. The + wildcard must only ever be used as the final + character of a subscription. + Bridges - Multiple brokers can be connected together with the bridging - functionality. This is useful where it is desirable to share - information between locations, but where not all of the information - needs to be shared. An example could be where a number of users are - running a broker to help record power usage and for a number of other - reasons. The power usage could be shared through bridging all of the - user brokers to a common broker, allowing the power usage of all - users to be collected and compared. The other information would remain - local to each - broker. - For information on configuring bridges, see - mosquitto.conf5. + + Multiple brokers can be connected together with the bridging + functionality. This is useful where it is desirable to share + information between locations, but where not all of the information + needs to be shared. An example could be where a number of users are + running a broker to help record power usage and for a number of + other reasons. The power usage could be shared through bridging all + of the user brokers to a common broker, allowing the power usage of + all users to be collected and compared. The other information would + remain local to each broker. + + + For information on configuring bridges, see + mosquitto.conf5. + @@ -868,15 +923,19 @@ SIGHUP - Upon receiving the SIGHUP signal, mosquitto will - attempt to reload configuration file data, assuming that - the argument was provided when - mosquitto was started. Not all configuration parameters can - be reloaded without restarting. See - mosquitto.conf5 - for details. - If TLS certificates are in use, then mosquitto will - also reload certificate on receiving a SIGHUP. + + Upon receiving the SIGHUP signal, mosquitto will + attempt to reload configuration file data, assuming that + the argument was provided when + mosquitto was started. Not all configuration parameters can + be reloaded without restarting. See + mosquitto.conf5 + for details. + + + If TLS certificates are in use, then mosquitto will + also reload certificate on receiving a SIGHUP. + The logs will also be closed and reopened. @@ -894,18 +953,22 @@ SIGUSR1 - Upon receiving the SIGUSR1 signal, mosquitto will - write the persistence database to disk. This signal is only - acted upon if persistence is enabled. + + Upon receiving the SIGUSR1 signal, mosquitto will + write the persistence database to disk. This signal is only + acted upon if persistence is enabled. + SIGUSR2 - The SIGUSR2 signal causes mosquitto to print out the - current subscription tree, along with information about - where retained messages exist. This is intended as a - testing feature only and may be removed at any time. + + The SIGUSR2 signal causes mosquitto to print out the + current subscription tree, along with information about + where retained messages exist. This is intended as a + testing feature only and may be removed at any time. + @@ -936,11 +999,7 @@ - - Bugs - mosquitto bug information can be found at - - + See Also diff --git a/man/mosquitto.conf.5.xml b/man/mosquitto.conf.5.xml index 8918c5a0..a8130282 100644 --- a/man/mosquitto.conf.5.xml +++ b/man/mosquitto.conf.5.xml @@ -22,17 +22,20 @@ Description - mosquitto.conf 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 - mosquitto8 - for information on how to load a configuration file. - Mosquitto can be instructed to reload the configuration file by sending - a SIGHUP signal as described in the Signals section of + mosquitto.conf 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 + mosquitto8 + for information on how to load a configuration file. + + + Mosquitto can be instructed to reload the configuration file by + sending a SIGHUP signal as described in the Signals section of mosquitto8. - Not all configuration options can be reloaded, as detailed in the options below. + Not all configuration options can be reloaded, as detailed in + the options below. @@ -106,35 +109,48 @@ File Format - All lines with a # as the very first character are treated as a - comment. - Configuration lines start with a variable name. The variable - value is separated from the name by a single space. + + All lines with a # as the very first character are treated as a + comment. + + + Configuration lines start with a variable name. The variable value + is separated from the name by a single space. + Authentication - The authentication options described below allow a wide range of + + The authentication options described below allow a wide range of possibilities in conjunction with the listener options. This - section aims to clarify the possibilities. An overview is also available at - - The simplest option is to have no authentication at all. This is + section aims to clarify the possibilities. An overview is also + available at + + + + 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 certfile and keyfile. - MQTT provides username/password authentication as part of the + SSL/TLS based options certfile and keyfile. + + + 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 to control whether passwords - are required globally or on a per-listener basis. - Mosquitto provides the Dynamic Security plugin which handles + are required globally or on a per-listener basis. + + + Mosquitto provides the Dynamic Security plugin which handles username/password authentication and access control in a much more flexible way than a password file. See - - When using certificate based encryption there are three options + + + 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 @@ -154,24 +170,33 @@ 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. - When using pre-shared-key based encryption through the psk_hint + subject is used as the username instead of just the CN. + + + 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. - Both certificate and PSK based encryption are configured on a - per-listener basis. - Authentication plugins can be created to augment the + password_file option. + + + Both certificate and PSK based encryption are configured on a + per-listener basis. + + + Authentication plugins can be created to augment the password_file, acl_file and psk_file options with e.g. SQL based - lookups. - It is possible to support multiple authentication schemes at + lookups. + + + 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. + number of ways of authenticating. + @@ -188,76 +213,105 @@ without the need for the deprecated option. - Set the path to an access control list file. If + + 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. - If this parameter is defined then only the topics + client access to topics on the broker. + + + If this parameter is defined then only the topics listed will have access. Topic access is added with - lines of the format: + lines of the format: + - topic [read|write|readwrite|deny] <topic> + + topic [read|write|readwrite|deny] <topic> + - The access type is controlled using "read", "write", + + The access type is controlled using "read", "write", "readwrite" or "deny". This parameter is optional (unless <topic> includes a space character) - if not - given then the access is read/write. <topic> can + given then the access is read/write. <topic> can contain the + or # wildcards as in subscriptions. The "deny" option can used to explicitly deny access to a topic that would otherwise be granted by a broader read/write/readwrite statement. Any "deny" - topics are handled before topics that grant read/write access. + topics are handled before topics that grant read/write access. + - The first set of topics are applied to anonymous + + The first set of topics are applied to anonymous clients, assuming is true. User specific topic ACLs are added after a user - line as follows: + line as follows: + - user <username> + + user <username> + - The username referred to here is the same as in + + The username referred to here is the same as in . It is not the - clientid. + clientid. + - It is also possible to define ACLs based on pattern + + 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. - pattern [read|write|readwrite|deny] <topic> + keyword. + + + pattern [read|write|readwrite|deny] <topic> + - The patterns available for substitution are: + + The patterns available for substitution are: + %c to match the client id of the client %u to match the username of the client - The substitution pattern must be the only text for + + 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. + given. + Example: pattern write sensor/%u/data Allow access for bridge connection messages: pattern write $SYS/broker/connection/%c/state - If the first character of a line of the ACL file is a - # it is treated as a comment. + + If the first character of a line of the ACL file is a + # it is treated as a comment. + - If is + + If is true, this option applies to the current listener being configured only. If is false, this option applies - to all listeners. + to all listeners. + Note: In general it is not possible to grant write access to topics in the $SYS topic tree. The exception is $SYS/broker/connection/+/state. - Reloaded on reload signal. The currently loaded ACLs + + Reloaded on reload signal. The currently loaded ACLs will be freed and reloaded. Existing subscriptions will - be affected after the reload. - See also + be affected after the reload. + + + See also @@ -401,7 +455,7 @@ 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 + effect if persistence is enabled. Defaults to 1800 seconds (30 minutes). This option applies globally. @@ -719,7 +773,7 @@ log_timestamp_format %Y-%m-%dT%H:%M:%S Defaults to error, warning, notice and - information. This option + information. This option may be specified multiple times. Note that the debug type (used for decoding incoming/outgoing network packets) is never @@ -734,7 +788,7 @@ log_timestamp_format %Y-%m-%dT%H:%M:%S limit is reached. This allows control of outgoing message rate based on message size rather than message count. If the limit is set to 100, messages of over 100 bytes are still allowed, but only a single message - can be in flight at once. Defaults to 0. (No limit). + can be in flight at once. Defaults to 0. (No limit). See also the option. This option applies globally. @@ -763,7 +817,7 @@ log_timestamp_format %Y-%m-%dT%H:%M:%S For MQTT v5 clients, it is possible to have the server send a "server keepalive" value that will - override the keepalive value set by the client. This + override the keepalive value set by the client. This is intended to be used as a mechanism to say that the server will disconnect the client earlier than it anticipated, and that the client should use the new @@ -835,11 +889,11 @@ log_timestamp_format %Y-%m-%dT%H:%M:%S queued (per client) by the broker. Once this limit has been reached, subsequent messages will be silently dropped. This is an important option if you are sending messages at a high rate and/or have clients who are slow to respond or may be offline - for extended periods of time. Defaults to 0. (No maximum). + for extended periods of time. Defaults to 0. (No maximum). See also the option. If both max_queued_messages and max_queued_bytes are specified, - packets will be queued until the first limit is reached. + packets will be queued until the first limit is reached. This option applies globally. @@ -1036,7 +1090,7 @@ log_timestamp_format %Y-%m-%dT%H:%M:%S Badly designed clients may set clean session to false whilst using a randomly generated client id. This leads to persistent clients that connect once and - never reconnect. This option allows these clients to be removed. This option + never reconnect. This option allows these clients to be removed. 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. @@ -1119,7 +1173,7 @@ log_timestamp_format %Y-%m-%dT%H:%M:%S true, this plugin will be loaded for the current listener only. - See also + See also and the option. @@ -1163,7 +1217,7 @@ log_timestamp_format %Y-%m-%dT%H:%M:%S disconnected. When bridges topics are configured with QoS level 1 or 2 incoming QoS 0 messages for these topics are also queued. These messages are included in the limit - imposed by max_queued_messages. Defaults to + imposed by max_queued_messages. Defaults to false. Note that the MQTT v3.1.1 spec states that only QoS 1 and 2 messages should be saved in this situation so @@ -1357,7 +1411,7 @@ accept_protocol_versions 3, 4 - [ 2 | 1 ] + [ 2 | 1 ] Enable PROXY protocol support for this listener. @@ -1503,7 +1557,7 @@ accept_protocol_versions 3, 4 the current listener. Set to -1 to have "unlimited" connections. Note that other limits may be imposed that are outside the control - of mosquitto. See e.g. + of mosquitto. See e.g. limits.conf. Not reloaded on reload signal. @@ -1571,7 +1625,7 @@ accept_protocol_versions 3, 4 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 + messages are sent to the client. This means a client connected to a listener with mount point example can only see messages that are published in the topic hierarchy @@ -1874,8 +1928,8 @@ openssl dhparam -out dhparam.pem 2048 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 + trusted certificate. The overall aim is encryption + of the network traffic. By setting to true, a client connecting to this listener must provide a valid certificate in @@ -1895,9 +1949,9 @@ openssl dhparam -out dhparam.pem 2048 engine_kpass_sha1 SHA1 of the private key password when using an - TLS engine. Some TLS engines such as the TPM + TLS engine. Some TLS engines such as the TPM engine may require the use of a password in order - to be accessed. This option allows a hex encoded + to be accessed. This option allows a hex encoded SHA1 hash of the password to the engine directly, instead of the user being prompted for the password. @@ -1980,7 +2034,7 @@ openssl dhparam -out dhparam.pem 2048 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 + use this option. The list of available ciphers can be obtained using the "openssl ciphers" command and should be provided in the same format as the output of that command. @@ -2022,7 +2076,7 @@ openssl dhparam -out dhparam.pem 2048 Set to have the psk identity sent by the client used as - its username. The username will be checked as + its username. The username will be checked as normal, so or another means of authentication checking must be used. No password will be used. @@ -2216,7 +2270,7 @@ openssl dhparam -out dhparam.pem 2048 you may get unexpected behaviour from incoming topics if you change what topics you are subscribing to. This is because the remote broker keeps the subscription for - the old topic. If you have this problem, connect your + the old topic. If you have this problem, connect your bridge with set to true, then reconnect with cleansession set to false as @@ -2295,7 +2349,7 @@ openssl dhparam -out dhparam.pem 2048 connection. Retained messages are published to the topic $SYS/broker/connection/<remote_clientid>/state unless otherwise set with - s. If the message + s. If the message is 1 then the connection is active, or 0 if the connection has failed. Defaults to true. @@ -2597,7 +2651,7 @@ topic clients/total in 0 test/mosquitto/org/ $SYS/broker/ alpn Configure the application layer protocol negotiation - option for the TLS session. Useful for brokers that support + option for the TLS session. Useful for brokers that support both websockets and MQTT on the same port. @@ -2644,7 +2698,7 @@ topic clients/total in 0 test/mosquitto/org/ $SYS/broker/ to certificate based encryption. A bridge can be configured to use PSK with the and - options. This is the + options. This is the client identity used with PSK encryption. Only one of certificate and PSK based encryption can be used on one bridge at once. @@ -2682,7 +2736,7 @@ topic clients/total in 0 test/mosquitto/org/ $SYS/broker/ to certificate based encryption. A bridge can be configured to use PSK with the and - options. This is the + options. This is the pre-shared-key in hexadecimal format with no "0x". Only one of certificate and PSK based encryption can be used on one bridge at once. @@ -2751,11 +2805,7 @@ topic clients/total in 0 test/mosquitto/org/ $SYS/broker/ mosquitto.conf - - Bugs - mosquitto bug information can be found at - - + See Also diff --git a/man/mosquitto_ctrl.1.xml b/man/mosquitto_ctrl.1.xml index 1c6a0be6..a3be4827 100644 --- a/man/mosquitto_ctrl.1.xml +++ b/man/mosquitto_ctrl.1.xml @@ -85,26 +85,36 @@ Description - mosquitto_ctrl is a tool for helping configure a Mosquitto broker instance. - It can be run primarily as a straightforward command line tool, as described here, or as an interactive shell as described in - - mosquitto_ctrl_shell - 1 - . The interactive shell makes most operations very straightforward and is recommended for ease of use. + + mosquitto_ctrl is a tool for helping configure + a Mosquitto broker instance. + + + It can be run primarily as a straightforward command line tool, as + described here, or as an interactive shell as described in + mosquitto_ctrl_shell 1 . + The interactive shell makes most operations very straightforward + and is recommended for ease of use. Encrypted Connections - mosquitto_ctrl supports TLS encrypted + + mosquitto_ctrl supports TLS encrypted connections. It is strongly recommended that you use an encrypted - connection for all remote use of mosquitto_ctrl. - To enable TLS connections when using x509 certificates, one of + connection for all remote use of mosquitto_ctrl. + + + To enable TLS connections when using x509 certificates, one of either or must - be provided as an option. - To enable TLS connections when using TLS-PSK, you must use the + be provided as an option. + + + To enable TLS connections when using TLS-PSK, you must use the and the - options. + options. + @@ -126,7 +136,8 @@ - mosquitto_ctrl has the ability to load + + mosquitto_ctrl has the ability to load external modules in the form of shared libraries. For example using the module name will try to load the external module @@ -142,14 +153,19 @@ Connection Options - The options below may be given on the command line, but may also + + The options below may be given on the command line, but may also be placed in a config file located at or - . - The config file may be specified manually with the + . + + + The config file may be specified manually with the - option. - The config file should have one pair of + option. + + + The config file should have one pair of per line. The values in the config file will be used as defaults and can be overridden by using the command line. The exceptions to @@ -157,190 +173,30 @@ specified. Note also that currently some options cannot be negated, e.g. . Config file lines that have a as the first character are treated as comments - and not processed any further. + and not processed any further. + - - - - Bind the outgoing connection to a local ip - address/hostname. Use this argument if you need to - restrict network communication to a particular - interface. - - - - - - Define the path to a file containing PEM encoded CA - certificates that are trusted. Used to enable SSL - communication. - See also - - - - - - Define the path to a directory containing PEM encoded CA - certificates that are trusted. Used to enable SSL - communication. - For to work correctly, the - certificate files must have ".crt" as the file ending - and you must run "openssl rehash <path to capath>" each - time you add/remove a certificate. - See also - - - - - - Define the path to a file containing a PEM encoded - certificate for this client, if required by the - server. - See also . - - - - - - An openssl compatible list of TLS ciphers to support - in the client. See - ciphers1 - for more information. - - - - - - - Enable debug messages. - - - - - - - Use an MQTT v5 property with this publish. If you use - this option, the client will be set to be an MQTT v5 - client. This option has two forms: - - - is the MQTT command/packet - identifier and can be one of CONNECT, PUBLISH, PUBREL, - DISCONNECT, AUTH, or WILL. The properties available for - each command are listed in the - Properties - section. - - is the name of the - property to add. This is as described in the - specification, but with '-' as a word separator. For - example: - . More details - are in the Properties - section. - - is the value of the property - to add, with a data type that is property - specific. - - is only used for the - property as the first of - the two strings in the string pair. In that case, - is the second of the strings in - the pair. - - - - - - Display usage information. - - - - - - - Specify the host to connect to. Defaults to localhost. - - - - - - - The id to use for this client. If not given, a client id will - be generated depending on the MQTT version being used. For v3.1.1/v3.1, - the client generates a client id in the format - , where the - are replaced with random alphanumeric - characters. For v5.0, the client sends a zero length client id, and the - server will generate a client id for the client. - - This option cannot be used at the same time as the - argument. - - - - - - When using certificate based encryption, this option - disables verification of the server hostname in the - server certificate. This can be useful when testing - initial server configurations but makes it possible for - a malicious third party to impersonate your server - through DNS spoofing, for example. Use this option in - testing only. If you need to - resort to using this option in a production - environment, your setup is at fault and there is no - point using encryption. - - - - - - Define the path to a file containing a PEM encoded - private key for this client, if required by the - server. - See also . - - - - - - Specifies the type of private key in use when making - TLS connections.. This can be "pem" or "engine". This - parameter is useful when a TPM module is being used and - the private key has been created with it. Defaults to - "pem", which means normal private key files are - used. - See also . - - - - - - - Specify specify user, password, hostname, port and - topic at once as a URL. The URL must be in the form: - mqtt(s)://[username[:password]@]host[:port]/topic - If the scheme is mqtt:// then the port defaults to - 1883. If the scheme is mqtts:// then the port defaults - to 8883. - - - - - - Disable Nagle's algorithm for the socket. This means - that latency of sent messages is reduced, which is - particularly noticeable for small, reasonably infrequent - messages. Using this option may result in more packets - being sent than would normally be necessary. - - + + + + + + + + + + + + + + + config-file - Provide a path to a config file to load options from. The config file should have one pair of + + Provide a path to a config file to load options from. + The config file should have one pair of per line. The values in the config file will be used as defaults and can be overridden by using the command line. The exceptions to @@ -348,304 +204,70 @@ specified. Note also that currently some options cannot be negated, e.g. . Config file lines that have a as the first character are treated as comments - and not processed any further. - - - - - - - Connect to the port specified. If not given, the - default of 1883 for plain MQTT or 8883 for MQTT over - TLS will be used. - - - - - - - Provide a password to be used for authenticating with - the broker. Using this argument without also specifying - a username is invalid when using MQTT v3.1 or v3.1.1. - See also the option. - - - - - - Specify a SOCKS5 proxy to connect through. "None" and - "username" authentication types are supported. The - must be of the form - . - The protocol prefix means that - hostnames are resolved by the proxy. The symbols %25, - %3A and %40 are URL decoded into %, : and @ - respectively, if present in the username or - password. - If username is not given, then no authentication is - attempted. If the port is not given, then the default - of 1080 is used. - - If the host is given as an IPv6 address, it must be enclosed in - square brackets, e.g. . - Note that square brackets have special meaning in some shells, - so the proxy url may need quoting in double or single quotes. + and not processed any further. - More SOCKS versions may be available in the future, - depending on demand, and will use different protocol - prefixes as described in - curl - 1 . - - - - - - Provide the hexadecimal (no leading 0x) - pre-shared-key matching the one used on the broker to - use TLS-PSK encryption support. - must also be provided - to enable TLS-PSK. - - - - - - The client identity to use with TLS-PSK support. This - may be used instead of a username if the broker is - configured to do so. + + + + + - - Specify the quality of service to use for messages, from 0, 1 and 2. Defaults to 1. - - - - - - If this argument is given, no runtime errors will be - printed. This excludes any error messages given in case of - invalid user input (e.g. using without a - port). - - - - - - Provide a protocol to use when connecting to a broker - that has multiple protocols available on a single port, - e.g. MQTT and WebSockets. - - - - - - A valid openssl engine id. These can be listed with - openssl engine command. - See also . - - - - - - SHA1 of the private key password when using an TLS - engine. Some TLS engines such as the TPM engine may - require the use of a password in order to be accessed. - This option allows a hex encoded SHA1 hash of the - password to the engine directly, instead of the user - being prompted for the password. - See also . - - - - - If used, this will load and trust the OS provided CA - certificates. This can be used in conjunction with - and - and can be used on its own to enable TLS mode. This - will be set by default if - is used, or if port is 8883 and no other certificate - options are used. + Specify the quality of service to use for messages, from 0, 1 and 2. Defaults to 1. - - - - - Choose which TLS protocol version to use when - communicating with the broker. Valid options are - and . - The default value is . - Must match the protocol version used by the broker. - - - - - - - - Provide a username to be used for authenticating with - the broker. See also the - argument. - - + + + + + + + - Connect to a broker through a local unix domain socket + + Connect to a broker through a local unix domain socket instead of a TCP socket. This is a replacement for and . For example: - See the option in + + See the option in mosquitto.conf 5 - to configure Mosquitto to listen on a unix socket. - - - - - - - Specify which version of the MQTT protocol should be - used when connecting to the remote broker. Can be - , , - , or the more verbose - , , or - . - Defaults to . + to configure Mosquitto to listen on a unix socket. + + Properties - The / option + + The / option allows adding properties to different stages of the mosquitto_ctrl run. The properties supported for each command are as - follows: + follows: + - - Connect - - (binary data - note treated as a string in mosquitto_ctrl) - (UTF-8 string pair) - (32-bit unsigned integer) - (16-bit unsigned integer) - (8-bit unsigned integer) - (8-bit unsigned integer) - (32-bit unsigned integer, note use instead) - (16-bit unsigned integer) - (UTF-8 string pair) - - - - - Publish - - (UTF-8 string) - (binary data - note treated as a string in mosquitto_ctrl) - (32-bit unsigned integer) - (8-bit unsigned integer) - (UTF-8 string) - (16-bit unsigned integer) - (UTF-8 string pair) - - - - - Disconnect - - (32-bit unsigned integer) - (UTF-8 string pair) - - - - - Will properties - - (UTF-8 string) - (binary data - note treated as a string in mosquitto_ctrl) - (32-bit unsigned integer) - (8-bit unsigned integer) - (UTF-8 string) - (UTF-8 string pair) - (32-bit unsigned integer) - - + + + + - - Exit Status - - mosquitto_sub returns zero on success, or non-zero on error. If - the connection is refused by the broker at the MQTT level, then - the exit code is the CONNACK reason code. If another error - occurs, the exit code is a libmosquitto return value. - - - MQTT v3.1.1 CONNACK codes: - - Success - Connection refused: Bad protocol version - Connection refused: Identifier rejected - Connection refused: Server unavailable - Connection refused: Bad username/password - Connection refused: Not authorized - - - MQTT v5 CONNACK codes: - - Success - Unspecified error - Malformed packet - Protocol error - Implementation specific error - Unsupported protocol version - Client ID not valid - Bad username or password - Not authorized - Server unavailable - Server busy - Banned - Server shutting down - Bad authentication method - Keep alive timeout - Session taken over - Topic filter invalid - Topic name invalid - Receive maximum exceeded - Topic alias invalid - Packet too large - Message rate too high - Quota exceeded - Administrative action - Payload format invalid - Retain not supported - QoS not supported - Use another server - Server moved - Shared subscriptions not supported - Connection rate exceeded - Maximum connect time - Subscription IDs not supported - Wildcard subscriptions not supported - - - - - Bugs - mosquitto bug information can be found at - - + + See Also diff --git a/man/mosquitto_ctrl_dynsec.1.xml b/man/mosquitto_ctrl_dynsec.1.xml index 26fead58..172714ac 100644 --- a/man/mosquitto_ctrl_dynsec.1.xml +++ b/man/mosquitto_ctrl_dynsec.1.xml @@ -26,8 +26,9 @@ Description - This page describes the dynsec module for - mosquitto_ctrl + + This page describes the dynsec module for + mosquitto_ctrl 1. See the mosquitto_ctrl man page for details of the options for connecting to remote brokers, in particular since this module works with authentication and access @@ -47,11 +48,7 @@ - - Bugs - mosquitto bug information can be found at - - + See Also diff --git a/man/mosquitto_ctrl_shell.1.xml b/man/mosquitto_ctrl_shell.1.xml index b30ffa55..f373071f 100644 --- a/man/mosquitto_ctrl_shell.1.xml +++ b/man/mosquitto_ctrl_shell.1.xml @@ -69,7 +69,8 @@ mosquitto_ctrl on the command line - this also allows custom CA certificates to be used. - Client certificates may be used for additional security. To + + Client certificates may be used for additional security. To enable this, use the and options. @@ -255,126 +256,27 @@ OK Connection Options The options below may be given on the command line - - - - Define the path to a file containing PEM encoded CA - certificates that are trusted. Used to enable SSL - communication. - See also - - - - - - Define the path to a directory containing PEM encoded CA - certificates that are trusted. Used to enable SSL - communication. - For to work correctly, the - certificate files must have ".crt" as the file ending - and you must run "openssl rehash <path to capath>" each - time you add/remove a certificate. - See also - - - - - - Define the path to a file containing a PEM encoded - certificate for this client, if required by the - server. - See also . - - - - - - Display usage information. - - - - - - - Specify the host to connect to. Defaults to localhost. - - - - - - - - The id to use for this client. If not given, a client id will be - generated depending on the MQTT version being used. For v3.1.1/v3.1, - the client generates a client id in the format - , where the - are replaced with random alphanumeric characters. For v5.0, the - client sends a zero length client id, and the server will generate a - client id for the client. - - - - - - - - Define the path to a file containing a PEM encoded - private key for this client, if required by the - server. - - See also . - - - - - - - - Connect to the port specified. If not given, the - default of 1883 for plain MQTT or 8883 for MQTT over - TLS will be used. - - - - - - - - - Provide a password to be used for authenticating with - the broker. Using this argument without also specifying - a username is invalid when using MQTT v3.1 or v3.1.1. - See also the option. - - - - - - - - - Provide a username to be used for authenticating with - the broker. See also the argument. - - - + + + + + + + + + + Exit Status - mosquitto_sub returns zero on success, or non-zero on error. + mosquitto_ctrl returns zero on success, or non-zero on error. - - Bugs - - mosquitto bug information can be found at - - - + See Also diff --git a/man/mosquitto_passwd.1.xml b/man/mosquitto_passwd.1.xml index dd2cf96e..39f912c8 100644 --- a/man/mosquitto_passwd.1.xml +++ b/man/mosquitto_passwd.1.xml @@ -46,11 +46,15 @@ Description - mosquitto_passwd is a tool for managing - password files for the mosquitto MQTT broker. - Usernames must not contain ":". Passwords are stored in a similar + + mosquitto_passwd is a tool for managing + password files for the mosquitto MQTT broker. + + + Usernames must not contain ":". Passwords are stored in a similar format to - crypt3. + crypt3. + @@ -59,11 +63,13 @@ - Run in batch mode. This allows the password to be + + Run in batch mode. This allows the password to be provided at the command line which can be convenient but should be used with care because the password will be visible on the command line and in command - history. + history. + @@ -81,34 +87,39 @@ - Delete the specified user from the password - file. + + Delete the specified user from the password file. + - Choose the hash to use. Can be one of + + Choose the hash to use. Can be one of argon2id, sha512-pbkdf2, or sha512. Defaults to argon2id. The sha512 option is provided for creating password files for use with Mosquitto 1.6 - and earlier. + and earlier. + - This option can be used to upgrade/convert a password + + This option can be used to upgrade/convert a password file with plain text passwords into one using hashed passwords. It will modify the specified file. It does not detect whether passwords are already hashed, so using it on a password file that already contains hashed passwords will generate new hashes based on the old hashes and render the password file - unusable. + unusable. + @@ -136,59 +147,8 @@ Exit Status - mosquitto_sub returns zero on success, or non-zero on error. If - the connection is refused by the broker at the MQTT level, then - the exit code is the CONNACK reason code. If another error - occurs, the exit code is a libmosquitto return value. + mosquitto_passwd returns zero on success or non-zero on error. - - MQTT v3.1.1 CONNACK codes: - - Success - Connection refused: Bad protocol version - Connection refused: Identifier rejected - Connection refused: Server unavailable - Connection refused: Bad username/password - Connection refused: Not authorized - - - MQTT v5 CONNACK codes: - - Success - Unspecified error - Malformed packet - Protocol error - Implementation specific error - Unsupported protocol version - Client ID not valid - Bad username or password - Not authorized - Server unavailable - Server busy - Banned - Server shutting down - Bad authentication method - Keep alive timeout - Session taken over - Topic filter invalid - Topic name invalid - Receive maximum exceeded - Topic alias invalid - Packet too large - Message rate too high - Quota exceeded - Administrative action - Payload format invalid - Retain not supported - QoS not supported - Use another server - Server moved - Shared subscriptions not supported - Connection rate exceeded - Maximum connect time - Subscription IDs not supported - Wildcard subscriptions not supported - @@ -219,11 +179,7 @@ - - Bugs - mosquitto bug information can be found at - - + See Also diff --git a/man/mosquitto_pub.1.xml b/man/mosquitto_pub.1.xml index 618b5bc6..190a5b44 100644 --- a/man/mosquitto_pub.1.xml +++ b/man/mosquitto_pub.1.xml @@ -70,12 +70,7 @@ session-expiry-interval protocol-version - - topic - payload - qos - - + output-options: @@ -115,27 +110,13 @@ Description - mosquitto_pub is a simple MQTT version 5/3.1.1 - client that will publish a single message on a topic and - exit. + + mosquitto_pub is a simple MQTT version 5/3.1.1 + client that will publish a single message on a topic and exit. + - - Encrypted Connections - mosquitto_pub supports TLS encrypted - connections. It is strongly recommended that you use an encrypted - connection for anything more than the most basic setup. - To enable TLS connections when using x509 certificates, one of - either or can - be provided as an option. - Alternatively, if the option is used - then the OS provided certificates will be loaded and neither - or are - needed - To enable TLS connections when using TLS-PSK, you must use the - and the - options. - + Options @@ -178,355 +159,53 @@ on the command line. - - - - Bind the outgoing connection to a local ip - address/hostname. Use this argument if you need to - restrict network communication to a particular - interface. - - - - - - - Disable 'clean session' / enable persistent client mode. - When this argument is used, the broker will be instructed - not to clean existing sessions for the same client id when - the client connects, and sessions will never expire when - the client disconnects. MQTT v5 clients can change their - session expiry interval with the argument. - - When a session is persisted on the broker, the subscriptions - for the client will be maintained after it disconnects, along - with subsequent QoS 1 and QoS 2 messages that arrive. When the - client reconnects and does not clean the session, it will - receive all of the queued messages. - If using this option, the client id must be set - manually with - - - - - - Define the path to a file containing PEM encoded CA - certificates that are trusted. Used to enable SSL - communication. - See also - - - - - - Define the path to a directory containing PEM encoded CA - certificates that are trusted. Used to enable SSL - communication. - For to work correctly, the - certificate files must have ".crt" as the file ending - and you must run "openssl rehash <path to capath>" each - time you add/remove a certificate. - See also - - - - - - Define the path to a file containing a PEM encoded - certificate for this client, if required by the - server. - See also and the Encrypted Connections section. - - - - - - An openssl compatible list of TLS ciphers to support - in the client. See - ciphers1 - for more information. - - - - - - - Enable debug messages. - - - - - - - Use an MQTT v5 property with this publish. If you use - this option, the client will be set to be an MQTT v5 - client. This option has two forms: - - - is the MQTT command/packet - identifier and can be one of CONNECT, PUBLISH, PUBREL, - DISCONNECT, AUTH, or WILL. The properties available for - each command are listed in the - Properties - section. - - is the name of the - property to add. This is as described in the - specification, but with '-' as a word separator. For - example: - . More details - are in the Properties - section. - - is the value of the property - to add, with a data type that is property - specific. - - is only used for the - property as the first of - the two strings in the string pair. In that case, - is the second of the strings in - the pair. - - - - - - - Send the contents of a file as the message. - - - - - - Display usage information. - - - - - - - Specify the host to connect to. Defaults to localhost. - - - - - - - The id to use for this client. If not given, a client id will - be generated depending on the MQTT version being used. For v3.1.1/v3.1, - the client generates a client id in the format - , where the - are replaced with random alphanumeric - characters. For v5.0, the client sends a zero length client id, and the - server will generate a client id for the client. - - This option cannot be used at the same time as the - argument. - - - - - - - Provide a prefix that the client id will be built - from by appending the process id of the client. This is - useful where the broker is using the clientid_prefixes - option. Cannot be used at the same time as the - argument. - - - - - - When using certificate based encryption, this option - disables verification of the server certificate. This - can be useful when testing initial server configurations - but means there are no guarantees whatsoever about - whether the server you are connecting to is the server - you expect. Use this option in testing - only. If you need to resort to using - this option in a production environment, your setup is at - fault and there is little point using encryption. - - - - - - - - The number of seconds between sending PING commands - to the broker for the purposes of informing it we are still - connected and functioning. Defaults to 60 seconds. - - - - - - Define the path to a file containing a PEM encoded - private key for this client, if required by the - server. - See also and the Encrypted Connections section. - - - - - - Specifies the type of private key in use when making - TLS connections.. This can be "pem" or "engine". This - parameter is useful when a TPM module is being used and - the private key has been created with it. Defaults to - "pem", which means normal private key files are - used. - See also . - - - - - - - - Specify specify user, password, hostname, port and - topic at once as a URL. The URL must be in the form: - mqtt(s)://[username[:password]@]host[:port]/topic - or ws(s)://[username[:password]@]host[:port]/path - - - Depending on the scheme, the port will default to - different values. mqtt:// - 1883, mqtts:// - 8883, - ws:// - 80, wss:// - 443. - - - + + + + + + + + + + + + + + + + + + - - Send messages read from stdin, splitting separate lines into separate messages. - - - - - - - Send a single message from the command line. - - - - - - - Send a null (zero length) message. - - - - - - Disable Nagle's algorithm for the socket. This means - that latency of sent messages is reduced, which is - particularly noticeable for small, reasonably infrequent - messages. Using this option may result in more packets - being sent than would normally be necessary. - - - - - Disable all use of TLS encryption. This is useful if you - specify TLS options in a configuration file but want to - disable those options. It also stops the automatic use - of TLS when connecting to port 8883. + Send messages read from stdin, splitting separate lines into separate messages. - - - - - - Connect to the port specified. If not given, the - default of 1883 for plain MQTT or 8883 for MQTT over - TLS will be used. - - - See the if you want to use - port 8883 without TLS. - - - - - - - - Provide a password to be used for authenticating with - the broker. Using this argument without also specifying - a username is invalid when using MQTT v3.1 or v3.1.1. - See also the option. - - - - - - Specify a SOCKS5 proxy to connect through. "None" and - "username" authentication types are supported. The - must be of the form - . - The protocol prefix means that - hostnames are resolved by the proxy. The symbols %25, - %3A and %40 are URL decoded into %, : and @ - respectively, if present in the username or - password. - If username is not given, then no authentication is - attempted. If the port is not given, then the default - of 1080 is used. - - If the host is given as an IPv6 address, it must be enclosed in - square brackets, e.g. . - Note that square brackets have special meaning in some shells, - so the proxy url may need quoting in double or single quotes. - - More SOCKS versions may be available in the future, - depending on demand, and will use different protocol - prefixes as described in - curl - 1 . - - - - - - Provide the hexadecimal (no leading 0x) - pre-shared-key matching the one used on the broker to - use TLS-PSK encryption support. - must also be provided - to enable TLS-PSK. - - - - - - The client identity to use with TLS-PSK support. This - may be used instead of a username if the broker is - configured to do so. - - + + + + + + + + + - Specify the quality of service to use for the message, from 0, 1 and 2. Defaults to 0. - - - - - - If this argument is given, no runtime errors will be - printed. This excludes any error messages given in case of - invalid user input (e.g. using without a - port). + + Specify the quality of service to use for the message, + from 0, 1 and 2. Defaults to 0. + + @@ -545,350 +224,86 @@ - If the publish mode is, + + If the publish mode is, , or (i.e. the modes where only a single message is sent), then can be used to specify that the - message will be published multiple times. - See also . + message will be published multiple times. + + + See also . + - If using , then the default + + If using , then the default behaviour is to publish repeated messages as soon as the previous message is delivered. Use to specify the number of seconds to wait after the previous message was delivered before publishing the next. Does not need to be an integer - number of seconds. - Note that there is no guarantee as to the actual interval + number of seconds. + + + Note that there is no guarantee as to the actual interval between messages, this option simply defines the minimum time from delivery of one message to the start of the - publish of the next. - - - - - - - Send a message read from stdin, sending the entire content as a single message. - - - - - - Use SRV lookups to determine which host to connect - to. Performs lookups to - when used in - conjunction with , otherwise uses - . + publish of the next. + + + - - The MQTT topic on which to publish the message. See mqtt7 for more information on MQTT topics. - - - - - - Provide a protocol to use when connecting to a broker - that has multiple protocols available on a single port, - e.g. MQTT and WebSockets. - - - - - - A valid openssl engine id. These can be listed with - openssl engine command. - See also . - - - - - - SHA1 of the private key password when using an TLS - engine. Some TLS engines such as the TPM engine may - require the use of a password in order to be accessed. - This option allows a hex encoded SHA1 hash of the - password to the engine directly, instead of the user - being prompted for the password. - See also . - - - - file - Log TLS connection information to file. - This option allows tools such as tcpdump, - wireshark and mqttshark - to decrypt TLS traffic and inspect the MQTT traffic. In Wireshark - this can be done by setting the - option for the - protocol. - - - This option should be used for debugging only. + The MQTT topic on which to publish the message. See + mqtt7 + for more information on MQTT topics. - - - - - If used, this will load and trust the OS provided CA - certificates. This can be used in conjunction with - and - and can be used on its own to enable TLS mode. This - will be set by default if - is used, or if port is 8883 and no other certificate - options are used. - - - - - - - - Choose which TLS protocol version to use when - communicating with the broker. Valid options are - and . - The default value is . - Must match the protocol version used by the broker. - - - - - - - - Provide a username to be used for authenticating with - the broker. See also the - argument. - - - - - - Connect to a broker through a local unix domain socket - instead of a TCP socket. This is a replacement for - and . For example: - - - See the option in - - mosquitto.conf - 5 - to configure Mosquitto to listen on a unix socket. - - - - - - - Specify which version of the MQTT protocol should be - used when connecting to the remote broker. Can be - , , - , or the more verbose - , , or - . - Defaults to . - - - - - - Specify a message that will be stored by the broker - and sent out if this client disconnects unexpectedly. This - must be used in conjunction with . - - - - - - The QoS to use for the Will. Defaults to 0. This must - be used in conjunction with . - - - - - - If given, if the client disconnects unexpectedly the - message sent out will be treated as a retained message. - This must be used in conjunction with . - Note that zero length payloads are never retained. If you send a zero length - payload retained message it will clear any retained - message on the topic. - - - - - - - The topic on which to send a Will, in the event that - the client disconnects unexpectedly. - - - - - - - Connect using WebSockets instead of plain TCP. - - - - - - - Set the session-expiry-interval property on the CONNECT packet. - If you use this option, the client will be set to be an MQTT v5 - client. Set to 0-4294967294 to specify - the session will expire in that many seconds after the client - disconnects, or use -1, 4294967295, or ∞ for a session that does - not expire. Defaults to -1 if -c is also given, or 0 if -c not - given. - If the session is set to never expire, either with -x or -c, then - a client id must be provided. - - + + + + + + + + + + + + + + + - - Wills - mosquitto_pub can register a message with the broker that will be - sent out if it disconnects unexpectedly. See - mqtt7 - for more information. - The minimum requirement for this is to use to - specify which topic the will should be sent out on. This will result in - a non-retained, zero length message with QoS 0. - Use the , - and - arguments to modify the other will parameters. - + Properties - The / option + + The / option allows adding properties to different stages of the mosquitto_pub - run. The properties supported for each command are as - follows: + run. The properties supported for each command are as follows: + - - Connect - - (binary data - note treated as a string in mosquitto_pub) - (UTF-8 string pair) - (32-bit unsigned integer) - (16-bit unsigned integer) - (8-bit unsigned integer) - (8-bit unsigned integer) - (32-bit unsigned integer, note use instead) - (16-bit unsigned integer) - (UTF-8 string pair) - - - - - Publish - - (UTF-8 string) - (binary data - note treated as a string in mosquitto_pub) - (32-bit unsigned integer) - (8-bit unsigned integer) - (UTF-8 string) - (16-bit unsigned integer) - (UTF-8 string pair) - - - - - Disconnect - - (32-bit unsigned integer) - (UTF-8 string pair) - - - - - Will properties - - (UTF-8 string) - (binary data - note treated as a string in mosquitto_pub) - (32-bit unsigned integer) - (8-bit unsigned integer) - (UTF-8 string) - (UTF-8 string pair) - (32-bit unsigned integer) - - + + + + - - Exit Status - - mosquitto_pub returns zero on success, or non-zero on error. If - the connection is refused by the broker at the MQTT level, then - the exit code is the CONNACK reason code. If another error - occurs, the exit code is a libmosquitto return value. - - - MQTT v3.1.1 CONNACK codes: - - Success - Connection refused: Bad protocol version - Connection refused: Identifier rejected - Connection refused: Server unavailable - Connection refused: Bad username/password - Connection refused: Not authorized - - - MQTT v5 CONNACK codes: - - Success - Unspecified error - Malformed packet - Protocol error - Implementation specific error - Unsupported protocol version - Client ID not valid - Bad username or password - Not authorized - Server unavailable - Server busy - Banned - Server shutting down - Bad authentication method - Keep alive timeout - Session taken over - Topic filter invalid - Topic name invalid - Receive maximum exceeded - Topic alias invalid - Packet too large - Message rate too high - Quota exceeded - Administrative action - Payload format invalid - Retain not supported - QoS not supported - Use another server - Server moved - Shared subscriptions not supported - Connection rate exceeded - Maximum connect time - Subscription IDs not supported - Wildcard subscriptions not supported - - + Examples @@ -926,17 +341,15 @@ $HOME/.config/mosquitto_pub $HOME/snap/mosquitto/current/.config/mosquitto_pub (for snap installs) - Configuration file for default options. + + Configuration file for default options. + - - Bugs - mosquitto bug information can be found at - - + See Also diff --git a/man/mosquitto_rr.1.xml b/man/mosquitto_rr.1.xml index a417a14f..9bd8afb3 100644 --- a/man/mosquitto_rr.1.xml +++ b/man/mosquitto_rr.1.xml @@ -27,8 +27,8 @@ auth-options connection-options - mqtt-options misc-options + mqtt-options output-options tls-certificate-options @@ -42,7 +42,7 @@ password - connection-options + connection-options: @@ -54,6 +54,7 @@ URL + bind-address @@ -75,16 +76,11 @@ client-id-prefix keepalive-time message-QoS - protocol-version always | new | never + protocol-version session-expiry-interval - - topic - payload - qos - - + output-options: @@ -119,33 +115,23 @@ Description - mosquitto_rr is an MQTT version 5/3.1.1 - client that can be used to publish a request message and wait for a - response. When using MQTT v5, which is the default, - mosquitto_rr will use the Request-Response - feature. - The important options are , , + + mosquitto_rr is an MQTT version 5/3.1.1 client + that can be used to publish a request message and wait for a + response. When using MQTT v5, which is the default, mosquitto_rr + will use the Request-Response feature. + + + The important options are , , and one of , , , - and . - Example: mosquitto_rr -t request-topic -e response-topic -m message + and . + + + Example: mosquitto_rr -t request-topic -e response-topic -m message + - - Encrypted Connections - mosquitto_rr supports TLS encrypted - connections. It is strongly recommended that you use an encrypted - connection for anything more than the most basic setup. - To enable TLS connections when using x509 certificates, one of - either or can - be provided as an option. - Alternatively, if the option is used - then the OS provided certificates will be loaded and neither - or are - needed - To enable TLS connections when using TLS-PSK, you must use the - and the - options. - + Options @@ -188,244 +174,33 @@ on the command line. - - - - Bind the outgoing connection to a local ip - address/hostname. Use this argument if you need to - restrict network communication to a particular - interface. - - - - - - - Disable 'clean session' / enable persistent client mode. - When this argument is used, the broker will be instructed - not to clean existing sessions for the same client id when - the client connects, and sessions will never expire when - the client disconnects. MQTT v5 clients can change their - session expiry interval with the argument. - - When a session is persisted on the broker, the subscriptions - for the client will be maintained after it disconnects, along - with subsequent QoS 1 and QoS 2 messages that arrive. When the - client reconnects and does not clean the session, it will - receive all of the queued messages. - If using this option, the client id must be set - manually with - - - - - - Define the path to a file containing PEM encoded CA - certificates that are trusted. Used to enable SSL - communication. - See also - - - - - - Define the path to a directory containing PEM encoded CA - certificates that are trusted. Used to enable SSL - communication. - For to work correctly, the - certificate files must have ".crt" as the file ending - and you must run "openssl rehash <path to capath>" each - time you add/remove a certificate. - See also - - - - - - Define the path to a file containing a PEM encoded - certificate for this client, if required by the - server. - See also and the Encrypted Connections section. - - - - - - An openssl compatible list of TLS ciphers to support - in the client. See - ciphers1 - for more information. - - - - - - - Enable debug messages. - - - - - - - Use an MQTT v5 property with this publish. If you use - this option, the client will be set to be an MQTT v5 - client. This option has two forms: - - - is the MQTT command/packet - identifier and can be one of CONNECT, PUBACK, PUBREC, - PUBCOMP, SUBSCRIBE, UNSUBSCRIBE, DISCONNECT, AUTH, or - WILL. The properties available for each command are - listed in the Properties section. - - is the name of the - property to add. This is as described in the - specification, but with '-' as a word separator. For - example: - . More details - are in the Properties - section. - - is the value of the property - to add, with a data type that is property - specific. - - is only used for the - property as the first of - the two strings in the string pair. In that case, - is the second of the strings in - the pair. - - + + + + + + + + - - Response topic. The client will subscribe to this topic to wait for a response. - - - - - - - Send the contents of a file as the request message. - - - - - - Specify output printing format. This option allows - you to choose what information from each message is - printed to the screen. See the Output Format section - below for full details. - This option overrides the option, - but does not override the - option. - - - - - - Display usage information. - - - - - - - Specify the host to connect to. Defaults to localhost. - - - - - - - The id to use for this client. If not given, a client id will - be generated depending on the MQTT version being used. For v3.1.1/v3.1, - the client generates a client id in the format - , where the - are replaced with random alphanumeric - characters. For v5.0, the client sends a zero length client id, and the - server will generate a client id for the client. - - This option cannot be used at the same time as the - argument. - - - - - - - Provide a prefix that the client id will be built - from by appending the process id of the client. This is - useful where the broker is using the clientid_prefixes - option. Cannot be used at the same time as the - argument. - - - - - - When using certificate based encryption, this option - disables verification of the server certificate. This - can be useful when testing initial server configurations - but means there are no guarantees whatsoever about - whether the server you are connecting to is the server - you expect. Use this option in testing - only. If you need to resort to using - this option in a production environment, your setup is at - fault and there is little point using encryption. - - - - - - - - The number of seconds between sending PING commands - to the broker for the purposes of informing it we are still - connected and functioning. Defaults to 60 seconds. - - - - - - Define the path to a file containing a PEM encoded - private key for this client, if required by the - server. - See also and the Encrypted Connections section. - - - - - - Specifies the type of private key in use when making - TLS connections.. This can be "pem" or "engine". This - parameter is useful when a TPM module is being used and - the private key has been created with it. Defaults to - "pem", which means normal private key files are - used. - See also . - - - - - - Specify specify user, password, hostname, port and - topic at once as a URL. The URL must be in the form: - mqtt(s)://[username[:password]@]host[:port]/topic - or ws(s)://[username[:password]@]host[:port]/path - - - Depending on the scheme, the port will default to - different values. mqtt:// - 1883, mqtts:// - 8883, - ws:// - 80, wss:// - 443. + Response topic. The client will subscribe to this topic to wait for a response. + + + + + + + + + + + @@ -448,593 +223,73 @@ - - - - - Send a single request message from the command line. - - - - - - Do not append an end of line character to the payload - when printing. This allows streaming of payload data - from multiple messages directly to another application - unmodified. Only really makes sense when not using - . - - - - - - - Send a null (zero length) request message. - - - - - - Disable Nagle's algorithm for the socket. This means - that latency of sent messages is reduced, which is - particularly noticeable for small, reasonably infrequent - messages. Using this option may result in more packets - being sent than would normally be necessary. - - - - - - - Disable all use of TLS encryption. This is useful if you - specify TLS options in a configuration file but want to - disable those options. It also stops the automatic use - of TLS when connecting to port 8883. - - - - - - - - - Connect to the port specified. If not given, the - default of 1883 for plain MQTT or 8883 for MQTT over - TLS will be used. - - - See the if you want to use - port 8883 without TLS. - - - - - - - - Provide a password to be used for authenticating with - the broker. Using this argument without also specifying - a username is invalid when using MQTT v3.1 or v3.1.1. - See also the option. - - - - - - - When using the JSON output format %j or %J, the default - is to print in an unformatted fashion. Specifying - prints messages in a prettier, - more human readable format. - - - - - - - Specify a SOCKS5 proxy to connect through. "None" and - "username" authentication types are supported. The - must be of the form - . - The protocol prefix means that - hostnames are resolved by the proxy. The symbols %25, - %3A and %40 are URL decoded into %, : and @ - respectively, if present in the username or - password. - If username is not given, then no authentication is - attempted. If the port is not given, then the default - of 1080 is used. - - If the host is given as an IPv6 address, it must be enclosed in - square brackets, e.g. . - Note that square brackets have special meaning in some shells, - so the proxy url may need quoting in double or single quotes. - - More SOCKS versions may be available in the future, - depending on demand, and will use different protocol - prefixes as described in - curl - 1 . - - - - - - Provide the hexadecimal (no leading 0x) - pre-shared-key matching the one used on the broker to - use TLS-PSK encryption support. - must also be provided - to enable TLS-PSK. - - - - - - The client identity to use with TLS-PSK support. This - may be used instead of a username if the broker is - configured to do so. - - - - - - - Specify the quality of service desired for the - incoming messages, from 0, 1 and 2. Defaults to 0. See - mqtt7 - for more information on QoS. - The QoS is identical for all topics subscribed to in - a single instance of mosquitto_rr. - - - - - - If this argument is given, no runtime errors will be - printed. This excludes any error messages given in case of - invalid user input (e.g. using without a - port). - - - - - - If this argument is given, messages that are received - that have the retain bit set will not be printed. - Messages with retain set are "stale", in that it is not - known when they were originally published. When - subscribing to a wildcard topic there may be a large - number of retained messages. This argument suppresses - their display. - - + + + + + + + + + + + + + + - - - - Use SRV lookups to determine which host to connect - to. Performs lookups to - when used in - conjunction with , otherwise uses - . - - - - - - - Send a request message read from stdin, sending the entire content as a single message. - - + + - - The MQTT topic where the request message will be sent. - - - - - - Provide a protocol to use when connecting to a broker - that has multiple protocols available on a single port, - e.g. MQTT and WebSockets. - - - - - - A valid openssl engine id. These can be listed with - openssl engine command. - See also . - - - - - - SHA1 of the private key password when using an TLS - engine. Some TLS engines such as the TPM engine may - require the use of a password in order to be accessed. - This option allows a hex encoded SHA1 hash of the - password to the engine directly, instead of the user - being prompted for the password. - See also . - - - - file - Log TLS connection information to file. - This option allows tools such as tcpdump, - wireshark and mqttshark - to decrypt TLS traffic and inspect the MQTT traffic. In Wireshark - this can be done by setting the - option for the - protocol. - - - This option should be used for debugging only. + The MQTT topic where the request message will be sent. - - - - - If used, this will load and trust the OS provided CA - certificates. This can be used in conjunction with - and - and can be used on its own to enable TLS mode. This - will be set by default if - is used, or if port is 8883 and no other certificate - options are used. - - - - - - - - Choose which TLS protocol version to use when - communicating with the broker. Valid options are - and . - The default value is . - Must match the protocol version used by the broker. - - - - - - - - Provide a username to be used for authenticating with - the broker. See also the - argument. - - - - - - Connect to a broker through a local unix domain socket - instead of a TCP socket. This is a replacement for - and . For example: - - - See the option in - - mosquitto.conf - 5 - to configure Mosquitto to listen on a unix socket. - - - - - - - Print received messages verbosely. With this - argument, messages will be printed as "topic payload". When - this argument is not given, the messages are printed as - "payload". - - - - - - - Specify which version of the MQTT protocol should be - used when connecting to the remote broker. Can be - , , - , or the more verbose - , , or - . - Defaults to . - - - - - - Provide a timeout as an integer number of seconds. - mosquitto_sub will stop processing messages and - disconnect after this number of seconds has - passed. The timeout starts just after the client has - connected to the broker. - - - - - - Specify a message that will be stored by the broker - and sent out if this client disconnects unexpectedly. This - must be used in conjunction with . - - - - - - The QoS to use for the Will. Defaults to 0. This must - be used in conjunction with . - - - - - - If given, if the client disconnects unexpectedly the - message sent out will be treated as a retained message. - This must be used in conjunction with . - - - - - - The topic on which to send a Will, in the event that - the client disconnects unexpectedly. - - - - - - - Connect using WebSockets instead of plain TCP. - - - - - - - Set the session-expiry-interval property on the CONNECT packet. - If you use this option, the client will be set to be an MQTT v5 - client. Set to 0-4294967294 to specify - the session will expire in that many seconds after the client - disconnects, or use -1, 4294967295, or ∞ for a session that does - not expire. Defaults to -1 if -c is also given, or 0 if -c not - given. - If the session is set to never expire, either with -x or -c, then - a client id must be provided. - - + + + + + + + + + + + + + + + + + - - Output format - There are three ways of formatting the output from mosquitto_rr. - In all cases a new-line character is appended for each message - received unless the argument is passed to - mosquitto_rr. - Payload-only is the default output format and will - print the payload exactly as it is received. - Verbose mode is activated with and prints the - message topic and the payload, separated by a space. - The final option is formatted output, which allows the user to - define a custom output format. The behaviour is controlled with - the option. The format string is - a free text string where interpreted sequences are replaced by - different parameters. The available interpreted sequences are - described below. - Three characters are used to start an interpreted sequence: - , and . - Sequences starting with are either parameters - related to the MQTT message being printed, or are helper sequences - to avoid the need to type long date format strings for example. - Sequences starting with are passed to the - strftime3 - function (with the @ replaced with a % - note that only the - character immediately after the @ is passed to strftime). This - allows the construction of a wide variety of time based outputs. - The output options for strftime vary from platform to platform, so - please check what is available for your platform. mosquitto_rr - does provide one extension to strftime which is - , which can be used to obtain the number of - nanoseconds passed in the current second. The resolution of this - option varies depending on the platform. The final sequence - character is , which is used to input some - characters that would otherwise be difficult to enter. - - - MQTT related parameters - - a literal %. - the MQTT v5 topic-alias property, if present. - the MQTT v5 content-type property, if present. - the MQTT v5 correlation-data property, if present. Note that this - property is specified as binary data, so may produce non-printable characters. - the MQTT v5 message-expiry-interval property, if present. - the MQTT v5 payload-format-indicator property, if present. - the length of the payload in bytes. - the message id (only relevant for messages with QoS>0). - the MQTT v5 user-property property, if present. This will be printed in the - form key:value. It is possible for any number of user properties to be attached to a message, and to - have duplicate keys. - the payload raw bytes (may produce non-printable characters depending on the payload). - the message QoS. - the MQTT v5 response-topic property, if present. - the retained flag for the message. - the MQTT v5 subscription-identifier property, if present. - the message topic. - the payload with each byte as a hexadecimal number (lower case). - the payload with each byte as a hexadecimal number (upper case). - - - - - Helpers - - ISO-8601 format date and time, e.g. 2016-08-10T09:47:38+0100 - JSON output of message - parameters and timestamp, with a quoted and escaped - payload. For example - {"tst":"2020-05-06T22:12:00.000000+0100","topic":"greeting","qos":0,"retain":0,"payload":"hello - world"} - JSON output of message - parameters and timestamp, with a non-quoted and - non-escaped payload - this means the payload must - itself be valid JSON. For example: - {"tst":"2020-05-06T22:12:00.000000+0100","topic":"foo","qos":0,"retain":0,"payload":{"temperature":27.0,"humidity":57}}. - If the payload is not valid JSON, then the error message "Error: Message payload is not valid JSON on topic - <topic>" will be printed to stderr. - ISO-8601 format date and time, e.g. 2016-08-10T09:47:38+0100 - Unix timestamp with nanoseconds, e.g. 1470818943.786368637 - - - - - Time related parameters - - a literal @. - pass the character represented - by to the strftime function as - . The options supported are platform - dependent. - the number of nanoseconds that - have passed in the current second, with varying timing - resolution depending on platform. - - - - - Escape characters - - a literal \. - a null character. Can be used - to separate different parameters that may contain spaces - (e.g. topic, payload) so that processing with tools such as - xargs1 - is easier. - alert/bell. - the escape sequence, which can - be used with ANSI colour codes to provide coloured output - for example. - end of line. - carriage return. - horizontal tab. - vertical tab. - - - - - - Wills - mosquitto_rr can register a message with the broker that will be - sent out if it disconnects unexpectedly. See - mqtt7 - for more information. - The minimum requirement for this is to use to - specify which topic the will should be sent out on. This will result in - a non-retained, zero length message with QoS 0. - Use the , and arguments to - modify the other will parameters. - + + Properties - The / option + + The / option allows adding properties to different stages of the mosquitto_rr run. The properties supported for each command are as - follows: + follows: + - - Connect - - (binary data - note treated as a string in mosquitto_rr) - (UTF-8 string pair) - (32-bit unsigned integer) - (16-bit unsigned integer) - (8-bit unsigned integer) - (8-bit unsigned integer) - (32-bit unsigned integer, note use instead) - (16-bit unsigned integer) - (UTF-8 string pair) - - - - - Publish - - (UTF-8 string) - (binary data - note treated as a string in mosquitto_rr) - (32-bit unsigned integer) - (8-bit unsigned integer) - (UTF-8 string) - (16-bit unsigned integer) - (UTF-8 string pair) - - - - - Subscribe - - (UTF-8 string pair) - - - - - Unsubscribe - - (UTF-8 string pair) - - - - - Disconnect - - (32-bit unsigned integer) - (UTF-8 string pair) - - - - - Will properties - - (UTF-8 string) - (binary data - note treated as a string in mosquitto_pub) - (32-bit unsigned integer) - (8-bit unsigned integer) - (UTF-8 string) - (UTF-8 string pair) - (32-bit unsigned integer) - - + + + + + + - - Exit Values - - - - Success - - - - Timed out waiting for message - - - - Unspecified failure - - - + Files @@ -1044,17 +299,15 @@ $HOME/.config/mosquitto_rr $HOME/snap/mosquitto/current/.config/mosquitto_rr (for snap installs) - Configuration file for default options. + + Configuration file for default options. + - - Bugs - mosquitto bug information can be found at - - + See Also diff --git a/man/mosquitto_signal.1.xml b/man/mosquitto_signal.1.xml index f0f960ba..9016e341 100644 --- a/man/mosquitto_signal.1.xml +++ b/man/mosquitto_signal.1.xml @@ -162,12 +162,7 @@ - - - Bugs - mosquitto bug information can be found at - - + See Also diff --git a/man/mosquitto_sub.1.xml b/man/mosquitto_sub.1.xml index 0027977c..28391d3a 100644 --- a/man/mosquitto_sub.1.xml +++ b/man/mosquitto_sub.1.xml @@ -82,12 +82,7 @@ protocol-version session-expiry-interval - - topic - payload - qos - - + output-options: @@ -124,33 +119,22 @@ Description - mosquitto_sub is a simple MQTT version 5/3.1.1 + + mosquitto_sub is a simple MQTT version 5/3.1.1 client that will subscribe to topics and print the messages that - it receives. - In addition to subscribing to topics, + it receives. + + + In addition to subscribing to topics, mosquitto_sub can filter out received messages so they are not printed (see the option) or unsubscribe from topics (see the option). Unsubscribing from topics is useful for clients connecting with - clean session set to false. + clean session set to false. + - - Encrypted Connections - mosquitto_sub supports TLS encrypted - connections. It is strongly recommended that you use an encrypted - connection for anything more than the most basic setup. - To enable TLS connections when using x509 certificates, one of - either or can - be provided as an option. - Alternatively, if the option is used - then the OS provided certificates will be loaded and neither - or are - needed - To enable TLS connections when using TLS-PSK, you must use the - and the - options. - + Options @@ -193,256 +177,54 @@ on the command line. - - - - Bind the outgoing connection to a local ip - address/hostname. Use this argument if you need to - restrict network communication to a particular - interface. - - - - - - - Disable 'clean session' / enable persistent client mode. - When this argument is used, the broker will be instructed - not to clean existing sessions for the same client id when - the client connects, and sessions will never expire when - the client disconnects. MQTT v5 clients can change their - session expiry interval with the argument. - - When a session is persisted on the broker, the subscriptions - for the client will be maintained after it disconnects, along - with subsequent QoS 1 and QoS 2 messages that arrive. When the - client reconnects and does not clean the session, it will - receive all of the queued messages. - If using this option, the client id must be set - manually with - - - - - - Define the path to a file containing PEM encoded CA - certificates that are trusted. Used to enable SSL - communication. - See also - - - - - - Define the path to a directory containing PEM encoded CA - certificates that are trusted. Used to enable SSL - communication. - For to work correctly, the - certificate files must have ".crt" as the file ending - and you must run "openssl rehash <path to capath>" each - time you add/remove a certificate. - See also - - - - - - Define the path to a file containing a PEM encoded - certificate for this client, if required by the - server. - See also and the Encrypted Connections section. - - - - - - An openssl compatible list of TLS ciphers to support - in the client. See - ciphers1 - for more information. - - + + + + + + - Disconnect and exit the program immediately after - the given count of messages have been received. This - may be useful in shell scripts where on a single status - value is required, for example. - Combine with to print only the - first set of fresh messages (i.e. that does not have - the retained flag set), or with to - filter which topics are processed. - - - - - - - Enable debug messages. - - - - - - - Use an MQTT v5 property with this publish. If you use - this option, the client will be set to be an MQTT v5 - client. This option has two forms: - - - is the MQTT command/packet - identifier and can be one of CONNECT, PUBACK, PUBREC, - PUBCOMP, SUBSCRIBE, UNSUBSCRIBE, DISCONNECT, AUTH, or - WILL. The properties available for each command are - listed in the Properties section. - - is the name of the - property to add. This is as described in the - specification, but with '-' as a word separator. For - example: - . More details - are in the Properties - section. - - is the value of the property - to add, with a data type that is property - specific. - - is only used for the - property as the first of - the two strings in the string pair. In that case, - is the second of the strings in - the pair. + + Disconnect and exit the program immediately after the + given count of messages have been received. This may be + useful in shell scripts where on a single status value + is required, for example. + + + Combine with or + to print only the first set of fresh messages (i.e. that + does not have the retained flag set), or with + to filter which topics are processed. + + + - - If this option is given, - mosquitto_sub will exit immediately - that all of its subscriptions have been acknowledged by - the broker. In conjunction with - this allows a durable client session to be initialised - on the broker for future use without requiring any - messages to be received. - - - - - - Specify output printing format. This option allows - you to choose what information from each message is - printed to the screen. See the Output Format section - below for full details. - This option overrides the option, - but does not override the - option. - - - - - - Display usage information. - - - - - - - Specify the host to connect to. Defaults to localhost. - - - - - - - The id to use for this client. If not given, a client id will - be generated depending on the MQTT version being used. For v3.1.1/v3.1, - the client generates a client id in the format - , where the - are replaced with random alphanumeric - characters. For v5.0, the client sends a zero length client id, and the - server will generate a client id for the client. - - This option cannot be used at the same time as the - argument. - - - - - - - Provide a prefix that the client id will be built - from by appending the process id of the client. This is - useful where the broker is using the clientid_prefixes - option. Cannot be used at the same time as the - argument. - - - - - - When using certificate based encryption, this option - disables verification of the server certificate. This - can be useful when testing initial server configurations - but means there are no guarantees whatsoever about - whether the server you are connecting to is the server - you expect. Use this option in testing - only. If you need to resort to using - this option in a production environment, your setup is at - fault and there is little point using encryption. - - - - - - - - The number of seconds between sending PING commands - to the broker for the purposes of informing it we are still - connected and functioning. Defaults to 60 seconds. - - - - - - Define the path to a file containing a PEM encoded - private key for this client, if required by the - server. - See also and the Encrypted Connections section. - - - - - - Specifies the type of private key in use when making - TLS connections.. This can be "pem" or "engine". This - parameter is useful when a TPM module is being used and - the private key has been created with it. Defaults to - "pem", which means normal private key files are - used. - See also . - - - - - - Specify specify user, password, hostname, port and - topic at once as a URL. The URL must be in the form: - mqtt(s)://[username[:password]@]host[:port]/topic - or ws(s)://[username[:password]@]host[:port]/path - - - Depending on the scheme, the port will default to - different values. mqtt:// - 1883, mqtts:// - 8883, - ws:// - 80, wss:// - 443. + If this option is given, mosquitto_sub + will exit immediately that all of its subscriptions have + been acknowledged by the broker. In conjunction with + this allows a durable client session + to be initialised on the broker for future use without + requiring any messages to be received. + + + + + + + + + + @@ -454,364 +236,160 @@ - - - - Do not append an end of line character to the payload - when printing. This allows streaming of payload data - from multiple messages directly to another application - unmodified. Only really makes sense when not using - . - - - - - - Disable Nagle's algorithm for the socket. This means - that latency of sent messages is reduced, which is - particularly noticeable for small, reasonably infrequent - messages. Using this option may result in more packets - being sent than would normally be necessary. - - - - - - - Disable all use of TLS encryption. This is useful if you - specify TLS options in a configuration file but want to - disable those options. It also stops the automatic use - of TLS when connecting to port 8883. - - - - - - - - - Connect to the port specified. If not given, the - default of 1883 for plain MQTT or 8883 for MQTT over - TLS will be used. - - - See the if you want to use - port 8883 without TLS. - - - - - - - - Provide a password to be used for authenticating with - the broker. Using this argument without also specifying - a username is invalid when using MQTT v3.1 or v3.1.1. - See also the option. - - - - - - - When using the JSON output format %j or %J, the default - is to print in an unformatted fashion. Specifying - prints messages in a prettier, - more human readable format. - - - - - - Specify a SOCKS5 proxy to connect through. "None" and - "username" authentication types are supported. The - must be of the form - . - The protocol prefix means that - hostnames are resolved by the proxy. The symbols %25, - %3A and %40 are URL decoded into %, : and @ - respectively, if present in the username or - password. - If username is not given, then no authentication is - attempted. If the port is not given, then the default - of 1080 is used. - - If the host is given as an IPv6 address, it must be enclosed in - square brackets, e.g. . - Note that square brackets have special meaning in some shells, - so the proxy url may need quoting in double or single quotes. - - More SOCKS versions may be available in the future, - depending on demand, and will use different protocol - prefixes as described in - curl - 1 . - - - - - - Provide the hexadecimal (no leading 0x) - pre-shared-key matching the one used on the broker to - use TLS-PSK encryption support. - must also be provided - to enable TLS-PSK. - - - - - - The client identity to use with TLS-PSK support. This - may be used instead of a username if the broker is - configured to do so. - - - - - - - Specify the quality of service desired for the - incoming messages, from 0, 1 and 2. Defaults to 0. See - mqtt7 - for more information on QoS. - The QoS is identical for all topics subscribed to in - a single instance of mosquitto_sub. - - - - - - If this argument is given, no runtime errors will be - printed. This excludes any error messages given in case of - invalid user input (e.g. using without a - port). - - - - - - If this argument is given, messages that are received - that have the retain bit set will not be printed. - Messages with retain set are "stale", in that it is not - known when they were originally published. When - subscribing to a wildcard topic there may be a large - number of retained messages. This argument suppresses - their display. - - + + + + + + + + + + + + - This option can be used to reduce the proportion of - messages that mosquitto_sub prints. The default behaviour - is to print all incoming messages. Setting the + + This option can be used to reduce the proportion of + messages that mosquitto_sub prints. The default + behaviour is to print all incoming messages. Setting the chance to a floating point value between 0.1 and 100.0 will ensure that on average that - percentage of messages will be printed. + percentage of messages will be printed. + - If this argument is given, the when mosquitto_sub + + If this argument is given, then when mosquitto_sub receives a message with the retained bit set, it will send a message to the broker to clear that retained message. This applies to all received messages except those that are filtered out by the option. This option still takes effect even if - is used. See also the + is used. See also the and - options. + options. + - - Remove all retained messages on the server, - assuming we have access to do so, and then exit: + + + Remove all retained messages on the server, + assuming we have access to do so, and then exit: + mosquitto_sub -t '#' --remove-retained --retained-only - Remove a whole tree, with the exception of a - single topic: + + Remove a whole tree, with the exception of a + single topic: + mosquitto_sub -t 'bbc/#' -T bbc/bbc1 --remove-retained - + - If this argument is given, only messages that are + + If this argument is given, only messages that are received that have the retain bit set will be printed. Messages with retain set are "stale", in that it is not known when they were originally published. With this argument in use, the receipt of the first non-stale message will cause the client to exit. See also the - option. + option. + - If this argument is given, the subscriptions will + + If this argument is given, the subscriptions will have the "retain as published" option set. This means that the retain flag on an incoming message will be exactly as set by the publishing client, rather than - indicating whether the message is fresh/stale. - This option is not valid for MQTT v3.1/v3.1.1 - clients. + indicating whether the message is fresh/stale. + + + This option is not valid for MQTT v3.1/v3.1.1 + clients. + - - - - Use SRV lookups to determine which host to connect - to. Performs lookups to - when used in - conjunction with , otherwise uses - . - - + - The MQTT topic to subscribe to. See - mqtt7 - for more information on MQTT topics. - This option may be repeated to subscribe to multiple topics. + + The MQTT topic to subscribe to. See + mqtt7 + for more information on MQTT topics. + + This option may be repeated to subscribe to multiple topics. + - Suppress printing of topics that match the filter. - This allows subscribing to a wildcard topic and only - printing a partial set of the wildcard - hierarchy. - For example, subscribe to the BBC tree, but suppress output from Radio 3: + + Suppress printing of topics that match the filter. This + allows subscribing to a wildcard topic and only printing + a partial set of the wildcard hierarchy. + + + For example, subscribe to the BBC tree, but suppress + output from Radio 3: + mosquitto_sub -t bbc/# -T bbc/radio3 - This option may be repeated to filter out multiple - topics or topic trees. - - - - - - Provide a protocol to use when connecting to a broker - that has multiple protocols available on a single port, - e.g. MQTT and WebSockets. - - - - - - A valid openssl engine id. These can be listed with - openssl engine command. - See also . - - - - - - SHA1 of the private key password when using an TLS - engine. Some TLS engines such as the TPM engine may - require the use of a password in order to be accessed. - This option allows a hex encoded SHA1 hash of the - password to the engine directly, instead of the user - being prompted for the password. - See also . - - - - file - - Log TLS connection information to file. - This option allows tools such as tcpdump, - wireshark and mqttshark - to decrypt TLS traffic and inspect the MQTT traffic. In Wireshark - this can be done by setting the - option for the - protocol. - - - This option should be used for debugging only. + This option may be repeated to filter out multiple + topics or topic trees. - - - - - If used, this will load and trust the OS provided CA - certificates. This can be used in conjunction with - and - and can be used on its own to enable TLS mode. This - will be set by default if - is used, or if port is 8883 and no other certificate - options are used. - - - - - - - - Choose which TLS protocol version to use when - communicating with the broker. Valid options are - and . - The default value is . - Must match the protocol version used by the broker. - - - - - - - - Provide a username to be used for authenticating with - the broker. See also the - argument. - - - - - - Connect to a broker through a local unix domain socket - instead of a TCP socket. This is a replacement for - and . For example: - - - See the option in - - mosquitto.conf - 5 - to configure Mosquitto to listen on a unix socket. - - + + + + + + + + - A topic that will be unsubscribed from. This may be - used on its own or in conjunction with the - option and only makes sense - when used in conjunction with - . - If used with then - subscriptions will be processed before - unsubscriptions. - Note that it is only possible to unsubscribe from + + A topic that will be unsubscribed from. This may be used + on its own or in conjunction with the + option and only makes sense when used in conjunction with + . + + + If used with then subscriptions + will be processed before unsubscriptions. + + + Note that it is only possible to unsubscribe from subscriptions that have previously been made. It is not possible to punch holes in wildcard subscriptions. For example, subscribing to and @@ -819,53 +397,27 @@ mosquitto_sub -t 'bbc/#' -T bbc/bbc1 --remove-retained as shown below will still result in messages matching the being delivered - to the client. + to the client. + mosquitto_sub -t sensors/# -U sensors/+/temperature -v - Note also that because retained messages are - published by the broker on receipt of a SUBSCRIBE - command, subscribing and unsubscribing to the same - topic may result in messages being received at the - client. + + Note also that because retained messages are published + by the broker on receipt of a SUBSCRIBE command, + subscribing and unsubscribing to the same topic may + result in messages being received at the client. + - This option may be repeated to unsubscribe from multiple topics. - - - - - - - Print received messages verbosely. With this - argument, messages will be printed as "topic payload". When - this argument is not given, the messages are printed as - "payload". - - - - - - - Specify which version of the MQTT protocol should be - used when connecting to the remote broker. Can be - , , - , or the more verbose - , , or - . - Defaults to . - - - - - - Provide a timeout as an integer number of seconds. - mosquitto_sub will stop processing messages and - disconnect after this number of seconds has - passed. The timeout starts just after the client has - connected to the broker. + + This option may be repeated to unsubscribe from multiple topics. + + + + @@ -885,461 +437,86 @@ mosquitto_sub -t 'bbc/#' -T bbc/bbc1 --remove-retained - - - - Specify a message that will be stored by the broker - and sent out if this client disconnects unexpectedly. This - must be used in conjunction with . - - - - - - The QoS to use for the Will. Defaults to 0. This must - be used in conjunction with . - - - - - - If given, if the client disconnects unexpectedly the - message sent out will be treated as a retained message. - This must be used in conjunction with . - - - - - - The topic on which to send a Will, in the event that - the client disconnects unexpectedly. - - - - - - - Connect using WebSockets instead of plain TCP. - - - - - - - Set the session-expiry-interval property on the CONNECT packet. - If you use this option, the client will be set to be an MQTT v5 - client. Set to 0-4294967294 to specify - the session will expire in that many seconds after the client - disconnects, or use -1, 4294967295, or ∞ for a session that does - not expire. Defaults to -1 if -c is also given, or 0 if -c not - given. - If the session is set to never expire, either with -x or -c, then - a client id must be provided. - - + + + + + + - - Output Format - There are three ways of formatting the output from mosquitto_sub. - In all cases a new-line character is appended for each message - received unless the argument is passed to - mosquitto_sub. - Payload-only is the default output format and will - print the payload exactly as it is received. - Verbose mode is activated with and prints the - message topic and the payload, separated by a space. - The final option is formatted output, which allows the user to - define a custom output format. The behaviour is controlled with - the option. The format string is - a free text string where interpreted sequences are replaced by - different parameters. The available interpreted sequences are - described below. - Three characters are used to start an interpreted sequence: - , and . - Sequences starting with are either parameters - related to the MQTT message being printed, or are helper sequences - to avoid the need to type long date format strings for example. - Sequences starting with are passed to the - strftime3 - function (with the @ replaced with a % - note that only the - character immediately after the @ is passed to strftime). This - allows the construction of a wide variety of time based outputs. - The output options for strftime vary from platform to platform, so - please check what is available for your platform. mosquitto_sub - does provide one extension to strftime which is - , which can be used to obtain the number of - nanoseconds passed in the current second. The resolution of this - option varies depending on the platform. The final sequence - character is , which is used to input some - characters that would otherwise be difficult to enter. - - - Flag characters - The parameters %A, %C, %d, %E, %F, %f, %I, %l, %m, %p, %R, %S, %t, %x, and %X can have optional flags immediately after the % character. - - - - The value should be zero padded. - This applies to the parameters %A, %E, %d, %F, %f, %l, %m, %S, %X, and %x. - It will be ignored for other parameters. If used with the - flag, the flag will be - ignored. - - - - - The value will be left aligned to the field width, - padded with blanks. The default is right alignment, with either 0 - or blank padding. - - - - - - Field width - - Some of the MQTT related parameters can be formatted with an - option to set their field width in a similar way to regular - printf style formats, i.e. this sets the minimum width when - printing this parameter. If the output length is smaller than - this width, the field will be padded to meet this width. This - applies to the options %A, %C, %d, %E, %F, %f, %I, %l, %m, %p, - %R, %S, %t, %x, %X. - - - For example would set the minimum topic - field width to 10 characters. - - - - - Maximum width - - Some of the MQTT related parameters can be formatted with an - option to set a maximum field width in a similar way to regular - printf style formats, for example for a - maximum width of 20. This applies to the options %C, %I, %R, %t. - - - For example would set the minimum topic - field width to 10 characters, and the maximum topic width to - 10 characters, i.e. the field will always be exactly 10 - characters long. - - - - - Hexadecimal binary field width - - The %x and %X parameters output the payload as a single - hexadecimal string by default. It is also possible to split the - hexadecimal payload into fields by a chosen length of nibbles. - For example, would split the payload into - two nibble or one byte values, separated by spaces and might produce - an output of 18 83. - - - The separator character is a space by default, but can be changed - to one of - by adding that character after the binary field width. For example - might produce an output of - 18:83. - - - - - Floating point number printing consideration - - mosquitto_sub supports only the IEEE 754 floating point standard as - described in Annex F of ISO/IEC 9899:1999. Don't try to - use %f or %d if the platform of the publisher uses a different - floating point representation standard than IEEE 754 or you - will get invalid data. If you are unsure what floating - representation your platform is using, then it is most - likely IEEE 754. If you get malformed or unexpected values, - check if the floating point number in the payload from the - publisher is encoded in IEEE 754. - - - If want to print floats, make sure you only subscribe - to topics that send only IEEE 754 formatted floats. - mosquitto_sub is very strict about floats and if anything - that is not a float is received, an error message will - be printed. - - - - - MQTT related parameters - - a literal %. - the MQTT v5 topic-alias property, if present. - the MQTT v5 content-type property, if present. - the MQTT v5 correlation-data property, if present. Note that this - property is specified as binary data, so may produce non-printable characters. - the payload treated as an 8 byte IEEE 754 float (double). - the MQTT v5 message-expiry-interval property, if present. - the MQTT v5 payload-format-indicator property, if present. - the payload treated as an 4 byte IEEE 754 float. - the length of the payload in bytes. - the message id (only relevant for messages with QoS>0). - the MQTT v5 user-property property, if present. This will be printed in the - form key:value. It is possible for any number of user properties to be attached to a message, and to - have duplicate keys. - the payload raw bytes (may produce non-printable characters depending on the payload). - the message QoS. - the MQTT v5 response-topic property, if present. - the retained flag for the message. - the MQTT v5 subscription-identifier property, if present. - the message topic. - the payload with each byte as a hexadecimal number (lower case). - the payload with each byte as a hexadecimal number (upper case). - - - - - Helpers - - ISO-8601 format date and time, e.g. 2016-08-10T09:47:38+0100 - JSON output of message - parameters and timestamp, with a quoted and escaped - payload. For example - {"tst":"2020-05-06T22:12:00.000000+0100","topic":"greeting","qos":0,"retain":0,"payload":"hello - world"} - JSON output of message - parameters and timestamp, with a non-quoted and - non-escaped payload - this means the payload must - itself be valid JSON. For example: - {"tst":"2020-05-06T22:12:00.000000+0100","topic":"foo","qos":0,"retain":0,"payload":{"temperature":27.0,"humidity":57}}. - If the payload is not valid JSON, then the error message "Error: Message payload is not valid JSON on topic - <topic>" will be printed to stderr. - - Unix timestamp with nanoseconds, e.g. 1470818943.786368637 - - - - - Time related parameters - - a literal @. - pass the character represented - by to the strftime function as - . The options supported are platform - dependent. - the number of nanoseconds that - have passed in the current second, with varying timing - resolution depending on platform. - - - - - Escape characters - - a literal \. - a null character. Can be used - to separate different parameters that may contain spaces - (e.g. topic, payload) so that processing with tools such as - xargs1 - is easier. - alert/bell. - the escape sequence, which can - be used with ANSI colour codes to provide coloured output - for example. - end of line. - carriage return. - horizontal tab. - vertical tab. - - - - - - Wills - mosquitto_sub can register a message with the broker that will be - sent out if it disconnects unexpectedly. See - mqtt7 - for more information. - The minimum requirement for this is to use to - specify which topic the will should be sent out on. This will result in - a non-retained, zero length message with QoS 0. - Use the , and arguments to - modify the other will parameters. - + + Properties - The / option + + The / option allows adding properties to different stages of the mosquitto_sub - run. The properties supported for each command are as - follows: + run. The properties supported for each command are as follows: + - - Connect - - (binary data - note treated as a string in mosquitto_sub) - (UTF-8 string) - (32-bit unsigned integer) - (16-bit unsigned integer) - (8-bit unsigned integer) - (8-bit unsigned integer) - (32-bit unsigned integer, note use instead) - (16-bit unsigned integer) - (UTF-8 string pair) - - - - - Subscribe - - (Variable byte integer) - (UTF-8 string pair) - - - - - Unsubscribe - - (UTF-8 string pair) - - - - - Disconnect - - (32-bit unsigned integer) - (UTF-8 string pair) - - - - - Will properties - - (UTF-8 string) - (binary data - note treated as a string in mosquitto_sub) - (32-bit unsigned integer) - (8-bit unsigned integer) - (UTF-8 string) - (UTF-8 string pair) - (32-bit unsigned integer) - - + + + + + - - Exit Status - - mosquitto_sub returns zero on success, or non-zero on error. If - the connection is refused by the broker at the MQTT level, then - the exit code is the CONNACK reason code. If another error - occurs, the exit code is a libmosquitto return value. - - - MQTT v3.1.1 CONNACK codes: - - Success - Connection refused: Bad protocol version - Connection refused: Identifier rejected - Connection refused: Server unavailable - Connection refused: Bad username/password - Connection refused: Not authorized - - - MQTT v5 CONNACK codes: - - Success - Unspecified error - Malformed packet - Protocol error - Implementation specific error - Unsupported protocol version - Client ID not valid - Bad username or password - Not authorized - Server unavailable - Server busy - Banned - Server shutting down - Bad authentication method - Keep alive timeout - Session taken over - Topic filter invalid - Topic name invalid - Receive maximum exceeded - Topic alias invalid - Packet too large - Message rate too high - Quota exceeded - Administrative action - Payload format invalid - Retain not supported - QoS not supported - Use another server - Server moved - Shared subscriptions not supported - Connection rate exceeded - Maximum connect time - Subscription IDs not supported - Wildcard subscriptions not supported - - + Examples - Note that these really are examples - the subscriptions will work - if you run them as shown, but there must be something publishing - messages on those topics for you to receive anything. - Subscribe to temperature information on localhost with QoS 1: + + Note that these really are examples - the subscriptions will work if + you run them as shown, but there must be something publishing + messages on those topics for you to receive anything. + + + Subscribe to temperature information on localhost with QoS 1: + mosquitto_sub -t sensors/temperature -q 1 - Subscribe to hard drive temperature updates on multiple - machines/hard drives. This expects each machine to be publishing its - hard drive temperature to - sensors/machines/HOSTNAME/temperature/HD_NAME. + + Subscribe to hard drive temperature updates on multiple + machines/hard drives. This expects each machine to be publishing its + hard drive temperature to + sensors/machines/HOSTNAME/temperature/HD_NAME. + mosquitto_sub -t sensors/machines/+/temperature/+ - Subscribe to all broker status messages: + + Subscribe to all broker status messages: + mosquitto_sub -v -t \$SYS/# - Specify the output format as "ISO-8601 date : topic : payload in hex" + + Specify the output format as "ISO-8601 date : topic : payload in hex" + mosquitto_sub -F '@Y-@m-@dT@H:@M:@S@z : %t : %x' -t '#' - Specify the output format as "seconds since epoch.nanoseconds : retained flag : qos : mid : payload length" + + Specify the output format as "seconds since epoch.nanoseconds : retained flag : qos : mid : payload length" + mosquitto_sub -F '%@s.@N : %r : %q : %m : %l' -q 2 -t '#' - Topic and payload output, but with colour where supported. + + Topic and payload output, but with colour where supported. + mosquitto_sub -F '\e[92m%t \e[96m%p\e[0m' -q 2 -t '#' - - Exit Values - - - - Success - - - - Timed out waiting for message - - - - Unspecified failure - - - - Files @@ -1354,11 +531,7 @@ mosquitto_sub -t 'bbc/#' -T bbc/bbc1 --remove-retained - - Bugs - mosquitto bug information can be found at - - + See Also diff --git a/man/mqtt.7.xml b/man/mqtt.7.xml index dc06582a..1464bc6a 100644 --- a/man/mqtt.7.xml +++ b/man/mqtt.7.xml @@ -22,52 +22,64 @@ Description - MQTT is a lightweight publish/subscribe - messaging protocol. It is useful for use with low power sensors, but - is applicable to many scenarios. This manual describes - some of the features of MQTT version 3.1.1/3.1, to assist end users in - getting the most out of the protocol. For more complete information on - MQTT, see http://mqtt.org/. + + MQTT is a lightweight publish/subscribe + messaging protocol. It is useful for use with low power sensors, but + is applicable to many scenarios. This manual describes + some of the features of MQTT version 3.1.1/3.1, to assist end users in + getting the most out of the protocol. For more complete information on + MQTT, see https://mqtt.org/. + Publish/Subscribe - The MQTT protocol is based on the principle of publishing - messages and subscribing to topics, or "pub/sub". Multiple clients - connect to a broker and subscribe to topics that they are interested - in. Clients also connect to the broker and publish messages to topics. - Many clients may subscribe to the same topics and do with the - information as they please. The broker and MQTT act as a simple, common - interface for everything to connect to. This means that you if you have - clients that dump subscribed messages to a database, to Twitter, - Cosm or even a simple text file, then it becomes very simple to add - new sensors or other data input to a database, Twitter or so on. + + The MQTT protocol is based on the principle of publishing + messages and subscribing to topics, or "pub/sub". Multiple clients + connect to a broker and subscribe to topics that they are interested + in. Clients also connect to the broker and publish messages to topics. + Many clients may subscribe to the same topics and do with the + information as they please. The broker and MQTT act as a simple, common + interface for everything to connect to. This means that you if you have + clients that dump subscribed messages to a database, to Twitter, + or even a simple text file, then it becomes very simple to add + new sensors or other data input to a database, Twitter or so on. + Topics/Subscriptions - Messages in MQTT are published on topics. There is no need to - configure a topic, publishing on it is enough. Topics are treated as a - hierarchy, using a slash (/) as a separator. This allows sensible - arrangement of common themes to be created, much in the same way as a - filesystem. For example, multiple computers may all publish their - hard drive temperature information on the following topic, with their - own computer and hard drive name being replaced as appropriate: + + Messages in MQTT are published on topics. There is no need to + configure a topic, publishing on it is enough. Topics are treated as a + hierarchy, using a slash (/) as a separator. This allows sensible + arrangement of common themes to be created, much in the same way as a + filesystem. For example, multiple computers may all publish their + hard drive temperature information on the following topic, with their + own computer and hard drive name being replaced as appropriate: + sensors/COMPUTER_NAME/temperature/HARDDRIVE_NAME - Clients can receive messages by creating subscriptions. A - subscription may be to an explicit topic, in which case only messages - to that topic will be received, or it may include wildcards. Two - wildcards are available, or . - can be used as a wildcard for a single level - of hierarchy. It could be used with the topic above to get information - on all computers and hard drives as follows: + + Clients can receive messages by creating subscriptions. A + subscription may be to an explicit topic, in which case only messages + to that topic will be received, or it may include wildcards. Two + wildcards are available, or . + + + can be used as a wildcard for a single level + of hierarchy. It could be used with the topic above to get information + on all computers and hard drives as follows: + sensors/+/temperature/+ - As another example, for a topic of "a/b/c/d", the following - example subscriptions will match: + + As another example, for a topic of "a/b/c/d", the following + example subscriptions will match: + a/b/c/d +/b/c/d @@ -75,16 +87,20 @@ a/+/+/d +/+/+/+ - The following subscriptions will not match: + + The following subscriptions will not match: + a/b/c b/+/c/d +/+/+ - can be used as a wildcard for all remaining levels of - hierarchy. This means that it must be the final character in a - subscription. With a topic of "a/b/c/d", the following example - subscriptions will match: + + can be used as a wildcard for all remaining levels of + hierarchy. This means that it must be the final character in a + subscription. With a topic of "a/b/c/d", the following example + subscriptions will match: + a/b/c/d # @@ -93,31 +109,37 @@ a/b/c/# +/b/c/# - Zero length topic levels are valid, which can lead to some + + Zero length topic levels are valid, which can lead to some slightly non-obvious behaviour. For example, a topic of "a//topic" would correctly match against a subscription of "a/+/topic". Likewise, zero length topic levels can exist at both the beginning and the end of a topic string, so "/a/topic" would match against a subscription of "+/a/topic", "#" or "/#", and a topic "a/topic/" would match against a subscription of "a/topic/+" or - "a/topic/#". + "a/topic/#". + Quality of Service - MQTT defines three levels of Quality of Service (QoS). The QoS - defines how hard the broker/client will try to ensure that a message is - received. Messages may be sent at any QoS level, and clients may - attempt to subscribe to topics at any QoS level. This means that the - client chooses the maximum QoS it will receive. For example, if a - message is published at QoS 2 and a client is subscribed with QoS 0, - the message will be delivered to that client with QoS 0. If a second - client is also subscribed to the same topic, but with QoS 2, then it - will receive the same message but with QoS 2. For a second example, if - a client is subscribed with QoS 2 and a message is published on QoS 0, - the client will receive it on QoS 0. - Higher levels of QoS are more reliable, but involve higher - latency and have higher bandwidth requirements. + + MQTT defines three levels of Quality of Service (QoS). The QoS + defines how hard the broker/client will try to ensure that a message is + received. Messages may be sent at any QoS level, and clients may + attempt to subscribe to topics at any QoS level. This means that the + client chooses the maximum QoS it will receive. For example, if a + message is published at QoS 2 and a client is subscribed with QoS 0, + the message will be delivered to that client with QoS 0. If a second + client is also subscribed to the same topic, but with QoS 2, then it + will receive the same message but with QoS 2. For a second example, if + a client is subscribed with QoS 2 and a message is published on QoS 0, + the client will receive it on QoS 0. + + + Higher levels of QoS are more reliable, but involve higher + latency and have higher bandwidth requirements. + 0: The broker/client will deliver the message once, with no confirmation. 1: The broker/client will deliver the message at least once, with confirmation required. @@ -127,33 +149,39 @@ Retained Messages - All messages may be set to be retained. This means that the - broker will keep the message even after sending it to all current - subscribers. If a new subscription is made that matches the topic of - the retained message, then the message will be sent to the client. This - is useful as a "last known good" mechanism. If a topic is only updated - infrequently, then without a retained message, a newly subscribed - client may have to wait a long time to receive an update. With a - retained message, the client will receive an instant update. + + All messages may be set to be retained. This means that the + broker will keep the message even after sending it to all current + subscribers. If a new subscription is made that matches the topic of + the retained message, then the message will be sent to the client. This + is useful as a "last known good" mechanism. If a topic is only updated + infrequently, then without a retained message, a newly subscribed + client may have to wait a long time to receive an update. With a + retained message, the client will receive an instant update. + Clean session / Durable connections - On connection, a client sets the "clean session" flag, which is - sometimes also known as the "clean start" flag. If clean session is set - to false, then the connection is treated as durable. This means that - when the client disconnects, any subscriptions it has will remain and - any subsequent QoS 1 or 2 messages will be stored until it connects - again in the future. If clean session is true, then all subscriptions - will be removed for the client when it disconnects. + + On connection, a client sets the "clean session" flag, which is + sometimes also known as the "clean start" flag. If clean session is set + to false, then the connection is treated as durable. This means that + when the client disconnects, any subscriptions it has will remain and + any subsequent QoS 1 or 2 messages will be stored until it connects + again in the future. If clean session is true, then all subscriptions + will be removed for the client when it disconnects. + Wills - When a client connects to a broker, it may inform the broker that - it has a will. This is a message that it wishes the broker to send when - the client disconnects unexpectedly. The will message has a topic, - QoS and retain status just the same as any other message. + + When a client connects to a broker, it may inform the broker that + it has a will. This is a message that it wishes the broker to send when + the client disconnects unexpectedly. The will message has a topic, + QoS and retain status just the same as any other message. +