Improve mosquitto_ctrl documentation.

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)

apps/mosquitto_ctrl/mosquitto_ctrl.c

@@ -43,7 +43,8 @@ static void print_usage(void)
  printf("\nGeneral usage: mosquitto_ctrl <module> <module-command> <command-options>\n");
  printf("For module specific help use: mosquitto_ctrl <module> 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");
 }
 
 

man/mosquitto_ctrl.1.xml

@@ -17,7 +17,7 @@
  <refsynopsisdiv>
  <cmdsynopsis>
  <command>mosquitto_ctrl</command>
- <arg choice='opt'>connection-options</arg>
+ <arg choice='opt'>connection-options | -o config-file</arg>
  <arg choice='plain'>module-name</arg>
  <arg choice='plain'>module-command</arg>
  <arg choice='opt'>command-options</arg>
@@ -132,7 +132,11 @@
  <para>The options below may be given on the command line, but may also
  be placed in a config file located at
  <option>$XDG_CONFIG_HOME/mosquitto_ctrl</option> or
- <option>$HOME/.config/mosquitto_ctrl</option> with one pair of
+ <option>$HOME/.config/mosquitto_ctrl</option>.</para>
+ <para>The config file may be specified manually with the
+ <option>-o <replaceable>config-file</replaceable></option>
+ option.</para>
+ <para>The config file should have one pair of
  <option>-option <replaceable>value</replaceable></option>
  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.</para>
  </listitem>
  </varlistentry>
+ <varlistentry>
+ <term><option>-o</option> <replaceable>config-file</replaceable></term>
+ <listitem>
+ <para>Provide a path to a config file to load options from. The config file should have one pair of
+ <option>-option <replaceable>value</replaceable></option>
+ 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. <option>-S</option>. Config file lines that have a
+ <option>#</option> as the first character are treated as comments
+ and not processed any further.</para>
+ </listitem>
+ </varlistentry>
  <varlistentry>
  <term><option>-p</option></term>
  <term><option>--port</option></term>

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 <command> ...
 ```
 
-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 <path to options file>`.
+
+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