Split mosquitto_ctrl manpages by module.

.gitignore

@@ -46,6 +46,7 @@ man/mosquitto-tls.7
 man/mosquitto.conf.5
 man/libmosquitto.3
 man/mosquitto_ctrl.1
+man/mosquitto_ctrl_dynsec.1
 man/mosquitto_passwd.1
 man/mosquitto_pub.1
 man/mosquitto_rr.1

man/CMakeLists.txt

@@ -1,4 +1,4 @@
-install(FILES mosquitto_passwd.1 mosquitto_pub.1 mosquitto_sub.1 mosquitto_rr.1 DESTINATION ${CMAKE_INSTALL_MANDIR}/man1)
+install(FILES mosquitto_ctrl.1 mosquitto_ctrl_dynsec.1 mosquitto_passwd.1 mosquitto_pub.1 mosquitto_sub.1 mosquitto_rr.1 DESTINATION ${CMAKE_INSTALL_MANDIR}/man1)
 install(FILES libmosquitto.3 DESTINATION ${CMAKE_INSTALL_MANDIR}/man3)
 install(FILES mosquitto.conf.5 DESTINATION ${CMAKE_INSTALL_MANDIR}/man5)
 install(FILES mosquitto-tls.7 mqtt.7 DESTINATION ${CMAKE_INSTALL_MANDIR}/man7)

man/Makefile

@@ -8,6 +8,7 @@ MANPAGES = \
 	mosquitto.8 \
 	mosquitto.conf.5 \
 	mosquitto_ctrl.1 \
+	mosquitto_ctrl_dynsec.1 \
 	mosquitto_passwd.1 \
 	mosquitto_pub.1 \
 	mosquitto_rr.1 \
@@ -31,6 +32,7 @@ install :
 	$(INSTALL) -m 644 mosquitto.conf.5 "${DESTDIR}${mandir}/man5/mosquitto.conf.5"
 	$(INSTALL) -d "${DESTDIR}$(mandir)/man1"
 	$(INSTALL) -m 644 mosquitto_ctrl.1 "${DESTDIR}${mandir}/man1/mosquitto_ctrl.1"
+	$(INSTALL) -m 644 mosquitto_ctrl_dynsec.1 "${DESTDIR}${mandir}/man1/mosquitto_ctrl_dynsec.1"
 	$(INSTALL) -m 644 mosquitto_passwd.1 "${DESTDIR}${mandir}/man1/mosquitto_passwd.1"
 	$(INSTALL) -m 644 mosquitto_pub.1 "${DESTDIR}${mandir}/man1/mosquitto_pub.1"
 	$(INSTALL) -m 644 mosquitto_sub.1 "${DESTDIR}${mandir}/man1/mosquitto_sub.1"
@@ -45,6 +47,7 @@ uninstall :
 	-rm -f "${DESTDIR}${mandir}/man8/mosquitto.8"
 	-rm -f "${DESTDIR}${mandir}/man5/mosquitto.conf.5"
 	-rm -f "${DESTDIR}${mandir}/man1/mosquitto_ctrl.1"
+	-rm -f "${DESTDIR}${mandir}/man1/mosquitto_ctrl_dynsec.1"
 	-rm -f "${DESTDIR}${mandir}/man1/mosquitto_passwd.1"
 	-rm -f "${DESTDIR}${mandir}/man1/mosquitto_pub.1"
 	-rm -f "${DESTDIR}${mandir}/man1/mosquitto_sub.1"
@@ -62,6 +65,9 @@ mosquitto.conf.5 : mosquitto.conf.5.xml manpage.xsl
 mosquitto_ctrl.1 : mosquitto_ctrl.1.xml manpage.xsl
 	$(XSLTPROC) $<
 
+mosquitto_ctrl_dynsec.1 : mosquitto_ctrl_dynsec.1.xml manpage.xsl
+	$(XSLTPROC) $<
+
 mosquitto_passwd.1 : mosquitto_passwd.1.xml manpage.xsl
 	$(XSLTPROC) $<
 
@@ -94,6 +100,7 @@ potgen :
 	 xml2po -o po/mosquitto/mosquitto.8.pot mosquitto.8.xml
 	 xml2po -o po/mosquitto.conf/mosquitto.conf.5.pot mosquitto.conf.5.xml
 	 xml2po -o po/mosquitto_ctrl/mosquitto_ctrl.1.pot mosquitto_ctrl.1.xml
+	 xml2po -o po/mosquitto_ctrl/mosquitto_ctrl_dynsec.1.pot mosquitto_ctrl_dynsec.1.xml
 	 xml2po -o po/mosquitto_passwd/mosquitto_passwd.1.pot mosquitto_passwd.1.xml
 	 xml2po -o po/mosquitto_pub/mosquitto_pub.1.pot mosquitto_pub.1.xml
 	 xml2po -o po/mosquitto_sub/mosquitto_sub.1.pot mosquitto_sub.1.xml

man/mosquitto_ctrl.1.xml

@@ -18,12 +18,12 @@
 		<cmdsynopsis>
 			<command>mosquitto_ctrl</command>
 			<arg choice='opt'>connection-options</arg>
-			<arg choice='plain'>module</arg>
+			<arg choice='plain'>module-name</arg>
 			<arg choice='plain'>module-command</arg>
 			<arg choice='opt'>command-options</arg>
 		</cmdsynopsis>
 		<cmdsynopsis>
-			<command>mosquitto_ctrl</command>
+			<command>connection-options:</command>
 			<group choice='req'>
 				<arg choice='plain'>
 					<arg><option>-h</option> <replaceable>hostname</replaceable></arg>
@@ -72,9 +72,7 @@
 		</cmdsynopsis>
 		<cmdsynopsis>
 			<command>mosquitto_ctrl</command>
-			<group choice='plain'>
 				<arg><option>--help</option></arg>
-			</group>
 		</cmdsynopsis>
 	</refsynopsisdiv>
 
@@ -99,20 +97,36 @@
 	</refsect1>
 
 	<refsect1>
-		<title>Dynamic Security Module</title>
+		<title>Modules</title>
-        <para>The dynamic security plugin is an optional authentication and
+		<variablelist>
-        access control plugin for Mosquitto that allows on the fly
+			<varlistentry>
-        control of users, groups, and roles. The mosquitto_ctrl
+				<term><option>Dynamic security</option></term>
-		<command>dynsec</command> module allows you to interact with
+				<listitem>
-		a broker using the dynamic security plugin.</para>
+					<para>
-
+						Authentication, and role based access control with users
-		<refsect2>
+						and groups. Uses the <command>dynsec</command> module name. See:
-			<title>Configuration file initialisation</title>
+						<citerefentry>
-			<para></para>
+							<refentrytitle><link xlink:href="mosquitto_ctrl_dynsec-1.html">mosquitto_ctrl_dynsec</link></refentrytitle>
-			<itemizedlist mark="circle">
+							<manvolnum>1</manvolnum>
-				<listitem><para>mosquitto_ctrl dynsec init <literal>filename</literal> <literal>admin-user</literal> admin-password [admin-role]</para></listitem>
+						</citerefentry>
-			</itemizedlist>
+					</para>
-		</refsect2>
+				</listitem>
+			</varlistentry>
+			<varlistentry>
+				<term><option>External modules</option></term>
+				<listitem>
+					<para><command>mosquitto_ctrl</command> has the ability to load
+						external modules in the form of shared libraries. For example
+						using the module name <option>example</option> will try to load
+						the external module <option>mosquitto_ctrl_example.so</option>
+						or <option>mosquitto_ctrl_example.dll</option>, depending on platform.
+						This allows new functionality to be added to Mosquitto by combining
+						a plugin and mosquitto_ctrl module, without having to recompile any
+						Mosquitto source code.
+					</para>
+				</listitem>
+			</varlistentry>
+		</variablelist>
 	</refsect1>
 
 	<refsect1>

man/mosquitto_ctrl_dynsec.1.meta

@@ -0,0 +1,5 @@
+.. title: mosquitto_ctrl man page
+.. slug: mosquitto_ctrl-1
+.. category: man
+.. type: man
+.. pretty_url: False

man/mosquitto_ctrl_dynsec.1.xml

@@ -0,0 +1,108 @@
+<?xml version='1.0' encoding='UTF-8'?>
+<?xml-stylesheet type="text/xsl" href="manpage.xsl"?>
+
+<refentry xml:id="mosquitto_ctrl_dynsec" xmlns:xlink="http://www.w3.org/1999/xlink">
+	<refmeta>
+		<refentrytitle>mosquitto_ctrl_dynsec</refentrytitle>
+		<manvolnum>1</manvolnum>
+		<refmiscinfo class="source">Mosquitto Project</refmiscinfo>
+		<refmiscinfo class="manual">Commands</refmiscinfo>
+	</refmeta>
+
+	<refnamediv>
+		<refname>mosquitto_ctrl_dynsec</refname>
+		<refpurpose>mosquitto_ctrl module for controlling the Mosquitto Dynamic Security plugin.</refpurpose>
+	</refnamediv>
+
+	<refsynopsisdiv>
+		<cmdsynopsis>
+			<command>mosquitto_ctrl</command>
+			<arg choice='opt'>connection-options</arg>
+			<arg choice='plain'>dynsec</arg>
+			<arg choice='plain'>dynsec-command</arg>
+			<arg choice='opt'>command-options</arg>
+		</cmdsynopsis>
+	</refsynopsisdiv>
+
+	<refsect1>
+		<title>Description</title>
+		<para>This page describes the <command>dynsec</command> module for
+		<citerefentry><refentrytitle><link xlink:href="mosquitto_ctrl-1.html">mosquitto_ctrl</link></refentrytitle>
+			<manvolnum>1</manvolnum></citerefentry>. 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
+			control, it is crucial that secure encrypted connections are used.
+        </para>
+	</refsect1>
+
+	<refsect1>
+		<title>Commands</title>
+
+		<refsect2>
+			<title>Configuration file initialisation</title>
+			<para></para>
+			<itemizedlist mark="circle">
+				<listitem><para>mosquitto_ctrl dynsec init <literal>config-filename</literal> <literal>admin-user</literal> [admin-password]</para></listitem>
+			</itemizedlist>
+		</refsect2>
+	</refsect1>
+
+	<refsect1>
+		<title>Bugs</title>
+		<para><command>mosquitto</command> bug information can be found at
+			<ulink url="https://github.com/eclipse/mosquitto/issues"/></para>
+	</refsect1>
+
+	<refsect1>
+		<title>See Also</title>
+		<simplelist type="inline">
+			<member>
+				<citerefentry>
+					<refentrytitle><link xlink:href="mqtt-7.html">mqtt</link></refentrytitle>
+					<manvolnum>7</manvolnum>
+				</citerefentry>
+			</member>
+			<member>
+				<citerefentry>
+					<refentrytitle><link xlink:href="mosquitto_rr-1.html">mosquitto_rr</link></refentrytitle>
+					<manvolnum>1</manvolnum>
+				</citerefentry>
+			</member>
+			<member>
+				<citerefentry>
+					<refentrytitle><link xlink:href="mosquitto_pub-1.html">mosquitto_pub</link></refentrytitle>
+					<manvolnum>1</manvolnum>
+				</citerefentry>
+			</member>
+			<member>
+				<citerefentry>
+					<refentrytitle><link xlink:href="mosquitto_sub-1.html">mosquitto_sub</link></refentrytitle>
+					<manvolnum>1</manvolnum>
+				</citerefentry>
+			</member>
+			<member>
+				<citerefentry>
+					<refentrytitle><link xlink:href="mosquitto-8.html">mosquitto</link></refentrytitle>
+					<manvolnum>8</manvolnum>
+				</citerefentry>
+			</member>
+			<member>
+				<citerefentry>
+					<refentrytitle><link xlink:href="libmosquitto-3.html">libmosquitto</link></refentrytitle>
+					<manvolnum>3</manvolnum>
+				</citerefentry>
+			</member>
+			<member>
+				<citerefentry>
+					<refentrytitle><link xlink:href="mosquitto-tls-7.html">mosquitto-tls</link></refentrytitle>
+					<manvolnum>7</manvolnum>
+				</citerefentry>
+			</member>
+		</simplelist>
+	</refsect1>
+
+	<refsect1>
+		<title>Author</title>
+		<para>Roger Light <email>roger@atchoo.org</email></para>
+	</refsect1>
+</refentry>

www/conf.py

@@ -93,6 +93,8 @@ NAVIGATION_LINKS = {
                 ("/man/libmosquitto-3.html", "libmosquitto"),
                 ("/man/mosquitto-8.html", "mosquitto"),
                 ("/man/mosquitto-conf-5.html", "mosquitto.conf"),
+                ("/man/mosquitto_ctrl-1.html", "mosquitto_ctrl"),
+                ("/man/mosquitto_ctrl_dynsec-1.html", "mosquitto_ctrl_dynsec"),
                 ("/man/mosquitto_passwd-1.html", "mosquitto_passwd"),
                 ("/man/mosquitto_pub-1.html", "mosquitto_pub"),
                 ("/man/mosquitto_rr-1.html", "mosquitto_rr"),