<?xml version='1.0' encoding='UTF-8'?>
<?xml-stylesheet type="text/xsl" href="manpage.xsl"?>

<refentry xml:id="mosquitto_ctrl"
		xmlns:xlink="http://www.w3.org/1999/xlink"
		xmlns:xi="http://www.w3.org/2001/XInclude">

	<refmeta>
		<refentrytitle>mosquitto_ctrl</refentrytitle>
		<manvolnum>1</manvolnum>
		<refmiscinfo class="source">Mosquitto Project</refmiscinfo>
		<refmiscinfo class="manual">Commands</refmiscinfo>
	</refmeta>

	<refnamediv>
		<refname>mosquitto_ctrl</refname>
		<refpurpose>a tool for initialising/configuring a Mosquitto broker instance</refpurpose>
	</refnamediv>

	<refsynopsisdiv>
		<cmdsynopsis>
			<command>mosquitto_ctrl</command>
			<arg choice='opt'>options | <option>-o</option> <replaceable>config-file</replaceable></arg>
			<arg choice='plain'>module-name</arg>
			<arg choice='plain'>module-command</arg>
			<arg choice='opt'>command-options</arg>
		</cmdsynopsis>
		<cmdsynopsis>
			<command>options:</command>
			<arg>auth-options</arg>
			<arg>connection-options</arg>
			<arg>mqtt-options</arg>
			<arg>output-options</arg>
			<group>
				<arg choice='plain'>tls-certificate-options</arg>
				<arg choice='plain'>tls-psk-options</arg>
			</group>
		</cmdsynopsis>
		<cmdsynopsis>
			<command>auth-options:</command>
			<sbr/>
			<arg><option>-u</option> <replaceable>username</replaceable></arg>
			<arg><option>-P</option> <replaceable>password</replaceable></arg>
		</cmdsynopsis>
		<cmdsynopsis>
			<command>connection-options:</command>
			<sbr/>
			<group choice='req'>
				<arg choice='plain'>
					<arg><option>-h</option> <replaceable>hostname</replaceable></arg>
					<arg><option>--unix</option> <replaceable>socket path</replaceable></arg>
					<arg><option>-p</option> <replaceable>port-number</replaceable></arg>
				</arg>
				<arg choice='plain'><option>-L</option> <replaceable>URL</replaceable></arg>
			</group>
			<sbr/>
			<arg><option>-A</option> <replaceable>bind-address</replaceable></arg>
			<sbr/>
			<arg><option>--proxy</option> <replaceable>socks-url</replaceable></arg>
		</cmdsynopsis>
		<cmdsynopsis>
			<command>mqtt-options:</command>
			<sbr/>
			<arg><option>-c</option></arg>
			<arg><option>-i</option> <replaceable>client-id</replaceable></arg>
			<arg><option>-q</option> <replaceable>message-QoS</replaceable></arg>
			<arg><option>-V</option> <replaceable>protocol-version</replaceable></arg>
		</cmdsynopsis>
		<cmdsynopsis>
			<command>output-options:</command>
			<sbr/>
			<arg><option>-d</option></arg>
			<arg><option>--quiet</option></arg>
		</cmdsynopsis>
		<xi:include href="common/synopsis-tls-certificate-options.xml" />
		<xi:include href="common/synopsis-tls-psk-options.xml" />

		<cmdsynopsis>
			<command>mosquitto_ctrl</command>
			<arg choice='opt'>connection-options</arg>
			(interactive shell mode)
		</cmdsynopsis>
		<cmdsynopsis>
			<command>mosquitto_ctrl</command>
				<arg><option>--help</option></arg>
		</cmdsynopsis>
	</refsynopsisdiv>

	<refsect1>
		<title>Description</title>
		<para>
			<command>mosquitto_ctrl</command> is a tool for helping configure
			a Mosquitto broker instance.
		</para>
		<para>
			It can be run primarily as a straightforward command line tool, as
			described here, or as an interactive shell as described in
			<citerefentry><refentrytitle><link xlink:href="mosquitto_ctrl_shell-1.html">mosquitto_ctrl_shell</link></refentrytitle> <manvolnum>1</manvolnum> </citerefentry>.
			The interactive shell makes most operations very straightforward
			and is recommended for ease of use.
		</para>
	</refsect1>

	<refsect1>
		<title>Encrypted Connections</title>
		<para>
			<command>mosquitto_ctrl</command> supports TLS encrypted
			connections. It is strongly recommended that you use an encrypted
				connection for all remote use of mosquitto_ctrl.
		</para>
		<para>
			To enable TLS connections when using x509 certificates, one of
			either <option>--cafile</option> or <option>--capath</option> must
			be provided as an option.
		</para>
		<para>
			To enable TLS connections when using TLS-PSK, you must use the
			<option>--psk</option> and the <option>--psk-identity</option>
			options.
		</para>
	</refsect1>

	<refsect1>
		<title>Modules</title>
		<variablelist>
			<varlistentry>
				<term><option>Dynamic security</option></term>
				<listitem>
					<para>
						Authentication, and role based access control with users
						and groups. Uses the <command>dynsec</command> module name. See:
						<citerefentry>
							<refentrytitle><link xlink:href="mosquitto_ctrl_dynsec-1.html">mosquitto_ctrl_dynsec</link></refentrytitle>
							<manvolnum>1</manvolnum>
						</citerefentry>
					</para>
				</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>
		<title>Connection Options</title>
		<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>.
		</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
			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>
		<variablelist>
			<xi:include href="common/option-bind.xml" />
			<xi:include href="common/option-tls-cafile.xml" />
			<xi:include href="common/option-tls-capath.xml" />
			<xi:include href="common/option-tls-cert.xml" />
			<xi:include href="common/option-tls-ciphers.xml" />
			<xi:include href="common/option-debug.xml" />
			<xi:include href="common/option-property.xml" />
			<xi:include href="common/option-help.xml" />
			<xi:include href="common/option-host.xml" />
			<xi:include href="common/option-clientid.xml" />
			<xi:include href="common/option-tls-insecure.xml" />
			<xi:include href="common/option-tls-key.xml" />
			<xi:include href="common/option-tls-keyform.xml" />
			<xi:include href="common/option-url.xml" />
			<xi:include href="common/option-nodelay.xml" />
			<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>
			<xi:include href="common/option-port.xml" />
			<xi:include href="common/option-password.xml" />
			<xi:include href="common/option-proxy.xml" />
			<xi:include href="common/option-tls-psk.xml" />
			<xi:include href="common/option-tls-psk-identity.xml" />
			<varlistentry>
				<term><option>-q</option></term>
				<term><option>--qos</option></term>
				<listitem>
					<para>
						Specify the quality of service to use for messages, from 0, 1 and 2. Defaults to 1.
					</para>
				</listitem>
			</varlistentry>
			<xi:include href="common/option-quiet.xml" />
			<xi:include href="common/option-tls-alpn.xml" />
			<xi:include href="common/option-tls-engine.xml" />
			<xi:include href="common/option-tls-engine-kpass-sha1.xml" />
			<xi:include href="common/option-tls-use-os-certs.xml" />
			<xi:include href="common/option-tls-version.xml" />
			<xi:include href="common/option-username.xml" />
			<varlistentry>
				<term><option>--unix</option></term>
				<listitem>
					<para>
						Connect to a broker through a local unix domain socket
						instead of a TCP socket. This is a replacement for
						<option>-h</option> and <option>-L</option>. For example:
						<option>mosquitto_ctrl --unix /tmp/mosquitto.sock ...</option>
					</para>
					<para>
						See the <option>socket_domain</option> option in
						<refentrytitle>
							<link xlink:href="mosquitto-conf-5.html">mosquitto.conf</link>
						</refentrytitle><manvolnum>5</manvolnum>
						to configure Mosquitto to listen on a unix socket.
					</para>
				</listitem>
			</varlistentry>
			<xi:include href="common/option-protocol-version.xml" />
		</variablelist>
	</refsect1>

	<refsect1 id='properties'>
		<title>Properties</title>
		<para>
			The <option>-D</option> / <option>--property</option> option
			allows adding properties to different stages of the mosquitto_ctrl
			run. The properties supported for each command are as
			follows:
		</para>

		<xi:include href="common/section-properties-connect.xml" />
		<xi:include href="common/section-properties-publish.xml" />
		<xi:include href="common/section-properties-disconnect.xml" />
		<xi:include href="common/section-properties-will.xml" />
	</refsect1>

	<xi:include href="common/section-exit-status.xml" />

	<refsect1>
		<title>Environment Variables</title>
		<variablelist>
			<xi:include href="common/env-var-mosquitto-unsafe-allow-symlinks.xml" />
		</variablelist>
	</refsect1>

	<xi:include href="common/section-bugs.xml" />

	<refsect1>
		<title>See Also</title>
		<simplelist type="inline">
			<member>
				<citerefentry>
					<refentrytitle><link xlink:href="mosquitto-7.html">mosquitto</link></refentrytitle>
					<manvolnum>7</manvolnum>
				</citerefentry>
			</member>
			<member>
				<citerefentry>
					<refentrytitle><link xlink:href="mqtt-7.html">mqtt</link></refentrytitle>
					<manvolnum>7</manvolnum>
				</citerefentry>
			</member>
			<member>
				<citerefentry>
					<refentrytitle><link xlink:href="mosquitto_ctrl_shell-1.html">mosquitto_ctrl_shell</link></refentrytitle>
					<manvolnum>1</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>
