mirror of
https://github.com/eclipse-mosquitto/mosquitto.git
synced 2026-02-06 02:52:07 +08:00
349 lines
12 KiB
XML
349 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_shell</refname>
|
|
<refpurpose>a interactive shell for configuring a Mosquitto broker instance</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<cmdsynopsis>
|
|
<command>mosquitto_ctrl</command>
|
|
<arg><option>-h</option> <replaceable>hostname</replaceable></arg>
|
|
<arg><option>-p</option> <replaceable>port-number</replaceable></arg>
|
|
<arg><option>-u</option> <replaceable>username</replaceable></arg>
|
|
<arg><option>-P</option> <replaceable>password</replaceable></arg>
|
|
<arg><option>-i</option> <replaceable>client-id</replaceable></arg>
|
|
<arg><option>--cafile</option> <replaceable>file</replaceable></arg>
|
|
<arg><option>--capath</option> <replaceable>dir</replaceable></arg>
|
|
<arg choice='opt'>
|
|
<option>--cert</option> <replaceable>file</replaceable>
|
|
<option>--key</option> <replaceable>file</replaceable>
|
|
</arg>
|
|
</cmdsynopsis>
|
|
</refsynopsisdiv>
|
|
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<para>
|
|
<command>mosquitto_ctrl</command> is a tool for helping configure
|
|
a Mosquitto broker instance.
|
|
</para>
|
|
<para>
|
|
This man page describes how to use the interactive shell. For
|
|
information on the pure command line mode, see
|
|
<citerefentry>
|
|
<refentrytitle><link xlink:href="mosquitto_ctrl-1.html">mosquitto_ctrl</link></refentrytitle>
|
|
<manvolnum>1</manvolnum>
|
|
</citerefentry>.
|
|
The interactive shell makes most operations very straightforward
|
|
and is recommended for ease of use.
|
|
</para>
|
|
<para>
|
|
To run in interactive mode, run <command>mosquitto_ctrl</command>
|
|
with no module or command, i.e. with at most the set of options
|
|
described in the synopsis above. The shell will start and you
|
|
will be presented with a prompt.
|
|
</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, connect using the <option>mqtts://</option>
|
|
or <option>wss://</option> scheme inside the shell, or use either
|
|
<option>--cafile</option> or <option>--capath</option> when starting
|
|
mosquitto_ctrl on the command line - this also allows custom CA
|
|
certificates to be used.
|
|
</para>
|
|
<para>
|
|
Client certificates may be used for additional security. To
|
|
enable this, use the <option>--cert</option> and
|
|
<option>--key</option> options.
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Example shell workflow</title>
|
|
<example title="shell-create-group">
|
|
<para>
|
|
The typical workflow for using the interactive shell is to configure
|
|
authentication and connect to a broker, then switch to the mode you are
|
|
interested in and run its commands. For example, to create a new group
|
|
in the dynamic-security plugin:
|
|
</para>
|
|
|
|
<programlisting language="shell">
|
|
$ mosquitto_ctrl
|
|
mosquitto_ctrl shell v2.1.0
|
|
> auth
|
|
username: admin
|
|
password:
|
|
> connect mqtt://localhost
|
|
mqtt://localhost:1883> dynsec
|
|
mqtt://localhost:1883|dynsec> createGroup newgroup
|
|
OK</programlisting>
|
|
</example>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Shell Behaviour</title>
|
|
<para>
|
|
The interactive shell operates in a set of different modes which
|
|
have different commands available. The shell has tab completion for
|
|
the commands and their arguments, where possible. It should usually
|
|
be possible to press the tab key twice to be able to be shown a list
|
|
of the currently available commmands or arguments.
|
|
</para>
|
|
<para>
|
|
The shell has a history of commands that can be accessed by pressing
|
|
the up and down arrow keys. The history is not saved to disk.
|
|
</para>
|
|
<para>
|
|
Help can be obtained for any command by typing <command>help</command>
|
|
followed by the command name. For example: <command>help createGroup</command>.
|
|
</para>
|
|
|
|
<para>The different modes are:</para>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><command>Pre-connection</command></term>
|
|
<listitem>
|
|
<para>
|
|
In this mode it is possible to set the authentication
|
|
details, connect to a broker, read help and exit.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><command>Post-connection</command></term>
|
|
<listitem>
|
|
<para>
|
|
In this mode, mosquitto_ctrl is connected to a broker
|
|
and you can switch between different control modules,
|
|
view help or exit.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><command>dynsec</command></term>
|
|
<listitem><para>
|
|
Allows you to create, delete, and modify users, groups, roles, and ACLs.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><command>broker</command></term>
|
|
<listitem><para>
|
|
Allows you to view listener and plugin information.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Authentication</title>
|
|
<para>
|
|
<command>mosquitto_ctrl</command> supports authentication via
|
|
username and password, or via x509 client certificates. If you are
|
|
using username and password authentication, then you must set the
|
|
username and password before connecting. This can be done in one of
|
|
two ways. The first is by using the <option>-u</option> and
|
|
<option>-P</option> options on the command line. The second is by
|
|
using the <command>auth</command> command in the shell.
|
|
</para>
|
|
<para>
|
|
Authentication in the shell can done in one of two ways. The first
|
|
is by using the <command>auth</command> command, which will then
|
|
prompt for a username and password. The second is by using the
|
|
<command>auth</command> <replaceable>username</replaceable> command,
|
|
which will then prompt for a password.
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Connection</title>
|
|
<para>
|
|
To connect to a broker, use the <command>connect</command> command.
|
|
</para>
|
|
|
|
<itemizedlist mark="circle">
|
|
<listitem>
|
|
<para>Connect to the broker at localhost on port 1883.</para>
|
|
<programlisting language="shell">> connect</programlisting>
|
|
</listitem>
|
|
<listitem>
|
|
<para>Connect to a specific broker using the default port 1883.</para>
|
|
<programlisting language="shell">> connect mqtt://test.mosquitto.org</programlisting>
|
|
</listitem>
|
|
<listitem>
|
|
<para>Connect to a specific broker using the specific port 1884.</para>
|
|
<programlisting language="shell">> connect mqtt://test.mosquitto.org:1884</programlisting>
|
|
</listitem>
|
|
<listitem>
|
|
<para>Connect to a specific broker using TLS.</para>
|
|
<programlisting language="shell">> connect mqtts://test.mosquitto.org</programlisting>
|
|
</listitem>
|
|
<listitem>
|
|
<para>Connect to a specific broker using websockets.</para>
|
|
<programlisting language="shell">> connect ws://test.mosquitto.org</programlisting>
|
|
</listitem>
|
|
<listitem>
|
|
<para>Connect to a specific broker using websockets over TLS.</para>
|
|
<programlisting language="shell">> connect wss://test.mosquitto.org</programlisting>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
<para>
|
|
If the <option>-h</option> option is used on the command line, the
|
|
shell will immediately attempt to connect to the host specified.
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Dynamic-security mode</title>
|
|
<para>
|
|
Once connected, you can use the command <command>dynsec</command> to switch
|
|
to the dynamic-security mode. This will only work if the broker has the
|
|
dynamic-security plugin loaded, and you have permission to use it.
|
|
</para>
|
|
<para>
|
|
The dynamic-security mode has commands to create, delete,
|
|
and modify users, groups, roles, and ACLs. The commands can be discovered by
|
|
pressing the tab key twice. Usernames, group names, and role names can be
|
|
auto-completed for the appropriate commands by pressing the tab key. Help
|
|
is available for each command by using <command>help</command> followed by
|
|
the command name.
|
|
</para>
|
|
<para>
|
|
To leave the dynamic-security mode, use the <command>return</command> command,
|
|
or use the <command>exit</command> command to exit the shell.
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Broker mode</title>
|
|
<para>
|
|
Use the command <command>broker</command> to switch
|
|
to the broker mode. This will only work if the broker has the
|
|
<option>enable_control_api</option> option set to true.
|
|
</para>
|
|
<para>
|
|
The broker mode has the commands <command>listListeners</command>, to show
|
|
currently configured listener configuration, and <command>listPlugins</command>,
|
|
to show currently loaded plugins.
|
|
</para>
|
|
<para>
|
|
To leave the broker mode, use the <command>return</command> command,
|
|
or use the <command>exit</command> command to exit the shell.
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Connection Options</title>
|
|
<para>The options below may be given on the command line</para>
|
|
<variablelist>
|
|
<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-help.xml" />
|
|
<xi:include href="common/option-host.xml" />
|
|
<xi:include href="common/option-clientid.xml" />
|
|
<xi:include href="common/option-tls-key.xml" />
|
|
<xi:include href="common/option-port.xml" />
|
|
<xi:include href="common/option-username.xml" />
|
|
</variablelist>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Exit Status</title>
|
|
<para>
|
|
mosquitto_ctrl returns zero on success, or non-zero on error.
|
|
</para>
|
|
</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-1.html">mosquitto_ctrl</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>
|