From 3ac2c3ee0956104687212fbab8fbfcbf6b1addb0 Mon Sep 17 00:00:00 2001 From: "Roger A. Light" Date: Fri, 26 Mar 2021 10:38:57 +0000 Subject: [PATCH] Improve mosquitto_ctrl documentation. --- apps/mosquitto_ctrl/dynsec.c | 2 ++ apps/mosquitto_ctrl/mosquitto_ctrl.c | 3 +- man/mosquitto_ctrl.1.xml | 22 +++++++++++-- www/pages/documentation/dynamic-security.md | 36 +++++++++++++++++++-- 4 files changed, 57 insertions(+), 6 deletions(-) diff --git a/apps/mosquitto_ctrl/dynsec.c b/apps/mosquitto_ctrl/dynsec.c index c906cb2c..8e3d7250 100644 --- a/apps/mosquitto_ctrl/dynsec.c +++ b/apps/mosquitto_ctrl/dynsec.c @@ -79,6 +79,8 @@ void dynsec__print_usage(void) printf("acltype: publishClientSend|publishClientReceive\n"); printf(" |subscribeLiteral|subscribePattern\n"); printf(" |unsubscribeLiteral|unsubscribePattern\n"); + printf("\nFor more information see:\n"); + printf(" https://mosquitto.org/documentation/dynamic-security/\n\n"); } cJSON *cJSON_AddIntToObject(cJSON * const object, const char * const name, int number) diff --git a/apps/mosquitto_ctrl/mosquitto_ctrl.c b/apps/mosquitto_ctrl/mosquitto_ctrl.c index b4433988..aa706a61 100644 --- a/apps/mosquitto_ctrl/mosquitto_ctrl.c +++ b/apps/mosquitto_ctrl/mosquitto_ctrl.c @@ -43,7 +43,8 @@ static void print_usage(void) printf("\nGeneral usage: mosquitto_ctrl \n"); printf("For module specific help use: mosquitto_ctrl help\n"); printf("\nModules available: dynsec\n"); - printf("\nSee https://mosquitto.org/man/mosquitto_ctrl-1.html for more information.\n\n"); + printf("\nFor more information see:\n"); + printf(" https://mosquitto.org/man/mosquitto_ctrl-1.html\n\n"); } diff --git a/man/mosquitto_ctrl.1.xml b/man/mosquitto_ctrl.1.xml index 1f1f29f2..e86180d9 100644 --- a/man/mosquitto_ctrl.1.xml +++ b/man/mosquitto_ctrl.1.xml @@ -17,7 +17,7 @@ mosquitto_ctrl - connection-options + connection-options | -o config-file module-name module-command command-options @@ -132,7 +132,11 @@ The options below may be given on the command line, but may also be placed in a config file located at or - with one pair of + . + The config file may be specified manually with the + + 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 @@ -320,6 +324,20 @@ 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 + + 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 + this are the message type options, of which only one can be + 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. + + diff --git a/www/pages/documentation/dynamic-security.md b/www/pages/documentation/dynamic-security.md index fad933da..331c2dbf 100644 --- a/www/pages/documentation/dynamic-security.md +++ b/www/pages/documentation/dynamic-security.md @@ -343,7 +343,9 @@ application. The initial configuration is the only time that `mosquitto_ctrl` does not connect to a broker to carry out the configuration. All other commands require a connection to a broker, and hence a username, password, and whatever else is -required for that particular connection. +required for that particular connection. It is strongly recommended that your +broker connection uses encryption so that your configuration, including new +passwords, is not transmitted in plain text. The connection options must be given before the `dynsec` part of the command line: @@ -357,8 +359,36 @@ For example: mosquitto_ctrl -u admin -h localhost dynsec ... ``` -It is possible to provide the admin password on the command line, but this is -not recommended. +It is possible to provide the admin password on the command line using `-P +password`, but this is not recommended. If you do not provide a password, +mosquitto_ctrl will ask you to enter the password when it is needed. + +### Using an options file + +For convenience, mosquitto_ctrl can load an options file which contains a list +of options it should use. This means you can set the encryption options, host, +admin username and any other options once and not have to add them to the +command line every time. + +mosquitto_ctrl will try to load a configuration file from a default location. +For Windows this is at `%USER_PROFILE%\mosquitto_ctrl.conf`. For other systems, +it will try `$XDG_CONFIG_HOME/mosquitto_ctrl.conf` or +`$HOME/.config/mosquitto_ctrl.conf`. + +You may override this behaviour by manually specifying an options file with +`-o `. + +The options file should contain a list of options, one per line, exactly as +they would be provided on the command line. For example: + +``` +--cafile /path/to/my/CA.crt +--certfile /path/to/my/client.crt +--keyfile /path/to/my/client.key +-u admin +-h mosquitto.example.com + +``` ### mosquitto_ctrl options