mirror of
https://github.com/eclipse-mosquitto/mosquitto.git
synced 2026-02-06 02:52:07 +08:00
348 lines
12 KiB
XML
348 lines
12 KiB
XML
<?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>
|