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