diff --git a/man/common/option-config-file.xml b/man/common/option-config-file.xml new file mode 100644 index 00000000..2a684b89 --- /dev/null +++ b/man/common/option-config-file.xml @@ -0,0 +1,13 @@ + +]> + + config-file + + &from-version21; + + Load options from a config file. See the Default Config File and + Config File sections at the start of the Options section. + + + diff --git a/man/common/option-no-tls.xml b/man/common/option-no-tls.xml index ba652c63..c0d15729 100644 --- a/man/common/option-no-tls.xml +++ b/man/common/option-no-tls.xml @@ -1,6 +1,10 @@ + +]> + &from-version21; Disable all use of TLS encryption. This is useful if you specify TLS options in a configuration file but want to disable those options. diff --git a/man/common/option-retain-handling.xml b/man/common/option-retain-handling.xml index aecebd9b..6cb32631 100644 --- a/man/common/option-retain-handling.xml +++ b/man/common/option-retain-handling.xml @@ -1,6 +1,10 @@ + +]> always | new | never + &from-version21; Use this option to control the retain handling option when making a subscription. This controls under what circumstances an existing diff --git a/man/common/option-tls-keylog.xml b/man/common/option-tls-keylog.xml index 493ddd0d..44d73122 100644 --- a/man/common/option-tls-keylog.xml +++ b/man/common/option-tls-keylog.xml @@ -1,6 +1,10 @@ + +]> file + &from-version21; Log TLS connection information to file. This option allows tools such as tcpdump, @@ -11,7 +15,8 @@ protocol. - This option should be used for debugging only. + This option should be used for debugging only, it must not be used + in production. diff --git a/man/common/options-intro.xml b/man/common/options-intro.xml new file mode 100644 index 00000000..8dddefee --- /dev/null +++ b/man/common/options-intro.xml @@ -0,0 +1,51 @@ + + There are three ways to provide options to &commandname;: the + default config file, a specified config file, or options on + the command line. + + + + Default Config File + + The default config file is located at + or + on POSIX systems, or + on Windows. + + + + The contents of the config file should consist of + options, one per line in the format: + . If + options are also specified on the command line, those + options will override the same options set in the config + file. The exceptions to this are the message type options, of which + only one can be specified. Note also that currently some options + cannot be negated, e.g. . TLS encryption options + can be negated with the option. + + + Config file lines that have a as the first + character are treated as comments and not processed any further. + + + It is suggested that config files are primarily used for + authentication purposes. Use of a config file allows you to + authenticate without the need to show the username and password + on the command line. + + + + + Config File + &from-version21; + + A config file can be specified on the command line using + . + If the option is used, the default config + file will not be loaded. + + + The format is the same as for the default config file. + + diff --git a/man/common/version-2.1.xml b/man/common/version-2.1.xml new file mode 100644 index 00000000..179071c4 --- /dev/null +++ b/man/common/version-2.1.xml @@ -0,0 +1 @@ +Available from version 2.1. diff --git a/man/mosquitto.7.xml b/man/mosquitto.7.xml index 13f55775..e1a1b3d2 100644 --- a/man/mosquitto.7.xml +++ b/man/mosquitto.7.xml @@ -1,4 +1,7 @@ + +]> @@ -45,7 +48,6 @@ - Mosquitto Broker @@ -67,8 +69,8 @@ This can be used to interact with the broker MQTT APIs when the broker is running. It can run in batch mode, where all arguments - are provided on the command line, or in an interactive shell - mode. + are provided on the command line, or from version 2.1 onwards, + in an interactive shell mode. @@ -97,7 +99,7 @@ mosquitto_signal - + &from-version21; This tool is used to send signals to the broker. On POSIX systems it performs the same task as the kill command, but diff --git a/man/mosquitto.8.xml b/man/mosquitto.8.xml index 239b6612..bd9e6c73 100644 --- a/man/mosquitto.8.xml +++ b/man/mosquitto.8.xml @@ -1,4 +1,7 @@ + +]> + &from-version21; Disable all logging. This is equivalent to setting to in the configuration file. This overrides any logging @@ -93,22 +97,21 @@ - file + + &from-version21; - Log TLS connection information to file. - This option allows tools such as tcpdump and - wireshark 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, it must - not be used on production servers. + Load the config file specified with , + and verify that it is valid but do not start the broker. + The broker exit code will be 0 if the config was valid, + or non-zero if no config file was specified or the + config file was invalid. + + + diff --git a/man/mosquitto_pub.1.xml b/man/mosquitto_pub.1.xml index decbe265..0b7e375b 100644 --- a/man/mosquitto_pub.1.xml +++ b/man/mosquitto_pub.1.xml @@ -1,6 +1,8 @@ + + ]> @@ -32,6 +34,7 @@ auth-options connection-options + misc-options mqtt-options output-options publish-options @@ -65,6 +68,11 @@ socks-url + + misc-options: + + config-file + mqtt-options: @@ -126,171 +134,139 @@ Options - - There are three ways to provide options to mosquitto_pub: the - default config file, a specified config file, or options on - the command line. - - - The default config file is located at - or - on POSIX systems, or - on Windows. - - - A config file can be specified on the command line using - . - If the option is used, the default config - file will not be loaded. - - - In both cases, the contents of the config file should consist of - options, one per line in the format: - . If - options are also specified on the command line, those - options will override the same options set in the config - file. The exceptions to this are the message type options, of which - only one can be specified. Note also that currently some options - cannot be negated, e.g. . TLS encryption options - can be negated with the option. - - - Config file lines that have a as the first - character are treated as comments and not processed any further. - - - It is suggested that config files are primarily used for - authentication purposes. Use of a config file allows you to - authenticate without the need to show the username and password - on the command line. - - - - - - - - - - - - - - - - - - - - - - - - - - Send messages read from stdin, splitting separate lines into separate messages. - - - - - - - - - - - - - - - - - - Specify the quality of service to use for the message, - from 0, 1 and 2. Defaults to 0. - - - - - - - - - - If retain is given, the message will be retained as a - "last known good" value on the broker. See - mqtt7 - for more information. 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. - - - - - - - - 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 . - - - - - - - - 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 - between messages, this option simply defines the minimum - time from delivery of one message to the start of the - publish of the next. - - - - - - - - - - - The MQTT topic on which to publish the message. See - mqtt7 - for more information on MQTT topics. - - - - - - - - - - - - - - - - - - - + &options-intro; + + + The options + + + + + + + + + + + + + + + + + + + + + + + + + Send messages read from stdin, splitting separate lines into separate messages. + + + + + + + + + + + + + + + + + + + Specify the quality of service to use for the message, + from 0, 1 and 2. Defaults to 0. + + + + + + + + + + If retain is given, the message will be retained as a + "last known good" value on the broker. See + mqtt7 + for more information. 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. + + + + + + + + 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 . + + + + + + + + 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 + between messages, this option simply defines the minimum + time from delivery of one message to the start of the + publish of the next. + + + + + + + + + + + The MQTT topic on which to publish the message. See + mqtt7 + for more information on MQTT topics. + + + + + + + + + + + + + + + + + + + + diff --git a/man/mosquitto_rr.1.xml b/man/mosquitto_rr.1.xml index 7aa0b093..71b831c6 100644 --- a/man/mosquitto_rr.1.xml +++ b/man/mosquitto_rr.1.xml @@ -1,4 +1,9 @@ + + + +]> misc-options: + config-file message-processing-timeout @@ -138,138 +144,107 @@ Options - - There are three ways to provide options to mosquitto_rr: the - default config file, a specified config file, or options on - the command line. - - - The default config file is located at - or - on POSIX systems, or - on Windows. - - - A config file can be specified on the command line using - . - If the option is used, the default config - file will not be loaded. - - - In both cases, the contents of the config file should consist of - options, one per line in the format: - . If - options are also specified on the command line, those - options will override the same options set in the config - file. The exceptions to this are the message type options, of which - only one can be specified. Note also that currently some options - cannot be negated, e.g. . TLS encryption options - can be negated with the option. - - - Config file lines that have a as the first - character are treated as comments and not processed any further. - - - It is suggested that config files are primarily used for - authentication purposes. Use of a config file allows you to - authenticate without the need to show the username and password - on the command line. - - - - - - - - - - - - - - - Response topic. The client will subscribe to this topic to wait for a response. - - - - - - - - - - - - - - - - - - - If this option is specified, mosquitto_rr will print out - the latency between it starting to publish a request and - the response arriving. This number includes both the - broker and client processing times, as well as any - inherent network latency. - + &options-intro; - - This can be used to measure message delivery latency - very simply by specifying an identical request and - response topic. - - - The option will be automatically - used when is in use. - - - - - - - - - - - - - - - - - - - - - - - - - - The MQTT topic where the request message will be sent. - - - - - - - - - - - - - - - - - - - - - + + The options + + + + + + + + + + + + + + Response topic. The client will subscribe to this topic to wait for a response. + + + + + + + + + + + + + + + + + + &from-version21; + + If this option is specified, mosquitto_rr will print out + the latency between it starting to publish a request and + the response arriving. This number includes both the + broker and client processing times, as well as any + inherent network latency. + + + + This can be used to measure message delivery latency + very simply by specifying an identical request and + response topic. + + + The option will be automatically + used when is in use. + + + + + + + + + + + + + + + + + + + + + + + + + + + The MQTT topic where the request message will be sent. + + + + + + + + + + + + + + + + + + + + + + diff --git a/man/mosquitto_sub.1.xml b/man/mosquitto_sub.1.xml index 0e915f79..082c1d9f 100644 --- a/man/mosquitto_sub.1.xml +++ b/man/mosquitto_sub.1.xml @@ -1,4 +1,9 @@ + + + +]> misc-options: + config-file message-processing-timeout @@ -141,312 +147,282 @@ Options - - There are three ways to provide options to mosquitto_sub: the - default config file, a specified config file, or options on - the command line. - - - The default config file is located at - or - on POSIX systems, or - on Windows. - - - A config file can be specified on the command line using - . - If the option is used, the default config - file will not be loaded. - - - In both cases, the contents of the config file should consist of - options, one per line in the format: - . If - options are also specified on the command line, those - options will override the same options set in the config - file. The exceptions to this are the message type options, of which - only one can be specified. Note also that currently some options - cannot be negated, e.g. . TLS encryption options - can be negated with the option. - - - Config file lines that have a as the first - character are treated as comments and not processed any further. - - - It is suggested that config files are primarily used for - authentication purposes. Use of a config file allows you to - authenticate without the need to show the username and password - on the command line. - - - - - - - - - - - - - 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. - - - - - - - - - - - - - - - - - - Instead of printing the messages received, print a count - of the messages received at one second intervals. Other - options related to output formatting are not valid when - this option is active. - - - - - - - - - - - - - - - - - - - - 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. - - - - - - - - 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 - and - options. - + &options-intro; - + + The options + + + + + + + + + + - Remove all retained messages on the server, - assuming we have access to do so, and then exit: + 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. + + + + + + + + + + + + + + + + + &from-version21; + + Instead of printing the messages received, print a count + of the messages received at one second intervals. Other + options related to output formatting are not valid when + this option is active. + + + + + + + + + + + + + + + + + + + + + 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. + + + + + + + + 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 + and + options. - -mosquitto_sub -t '#' --remove-retained --retained-only + + + 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: + + + + mosquitto_sub -t 'bbc/#' -T bbc/bbc1 --remove-retained - - + + + + + - Remove a whole tree, with the exception of a - single topic: + 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. + + + + + + + + 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. + + + + + + + + + + + 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: + + + mosquitto_sub -t + bbc/# -T + bbc/radio3 + + + This option may be repeated to filter out multiple + topics or topic trees. + + + + + + + + + + + + + + + + + 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 + then unsubscribing from + as shown below + will still result in messages matching the + being delivered + 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. - -mosquitto_sub -t 'bbc/#' -T bbc/bbc1 --remove-retained - - - - - - - - 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. - - - - - - - - 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. - - - - - - - - - - - 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: - - - mosquitto_sub -t - bbc/# -T - bbc/radio3 - - - This option may be repeated to filter out multiple - topics or topic trees. - - - - - - - - - - - - - - - - - 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 - then unsubscribing from - as shown below - will still result in messages matching the - being delivered - 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. - - - - This option may be repeated to unsubscribe from multiple topics. - - - - - - - - - - - - Messages will be printed on a fixed line number based on - the topic and order in which topics are received. Useful - for monitoring multiple topics that have single line - payloads. Unexpected behaviour will occur if there are - more topics than lines in the terminal, or if the - payload occupies more than a single line. - This can be used in conjuction with other output options - e.g. . - - - Requires ANSI escape code support in the terminal. - - - - - - - - - - + + This option may be repeated to unsubscribe from multiple topics. + + + + + + + + + + + &from-version21; + + Messages will be printed on a fixed line number based on + the topic and order in which topics are received. Useful + for monitoring multiple topics that have single line + payloads. Unexpected behaviour will occur if there are + more topics than lines in the terminal, or if the + payload occupies more than a single line. + This can be used in conjuction with other output options + e.g. . + + + Requires ANSI escape code support in the terminal. + + + + + + + + + + +