diff options
| author | Jean-Sébastien Pédron <jean-sebastien@rabbitmq.com> | 2017-04-25 10:50:00 +0200 |
|---|---|---|
| committer | Jean-Sébastien Pédron <jean-sebastien@rabbitmq.com> | 2017-04-26 18:24:27 +0200 |
| commit | c0af14ba3b98d4e028274fa326144223cb508b5c (patch) | |
| tree | 528e2231c4ccd80a10be3da79485e8e385b216e7 /docs | |
| parent | 775a41579c6ed5dd046aaed0eb5eacf8a48460f7 (diff) | |
| download | rabbitmq-server-git-c0af14ba3b98d4e028274fa326144223cb508b5c.tar.gz | |
docs: Convert manpages from DocBook to mdoc(7)
Writing those manpages directly in the target markup language allows to
use its full expressiveness, unlike the generated output from DocBook.
To create their HTML versions, we use mandoc(1), plus a small awk script
to adapt the generated HTML to our needs. I tried groff(1) and
man2html(1) but the former transforms nearly everything to simple <p>
and the later tries to reproduce the rendering of a manpage in a
terminal.
Manpages in section 1 are moved to section 8 because they are commands
to manage a system service, not general purpose commands.
This commits requires a change in the website to integrate the new
generated HTML manpages.
[#143563295]
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/examples-to-end.xsl | 93 | ||||
| -rw-r--r-- | docs/html-to-website-xml.xsl | 90 | ||||
| -rw-r--r-- | docs/rabbitmq-echopid.8 | 82 | ||||
| -rw-r--r-- | docs/rabbitmq-echopid.xml | 71 | ||||
| -rw-r--r-- | docs/rabbitmq-env.conf.5 | 86 | ||||
| -rw-r--r-- | docs/rabbitmq-env.conf.5.xml | 83 | ||||
| -rw-r--r-- | docs/rabbitmq-plugins.1.xml | 245 | ||||
| -rw-r--r-- | docs/rabbitmq-plugins.8 | 196 | ||||
| -rw-r--r-- | docs/rabbitmq-server.1.xml | 132 | ||||
| -rw-r--r-- | docs/rabbitmq-server.8 | 96 | ||||
| -rw-r--r-- | docs/rabbitmq-service.8 | 157 | ||||
| -rw-r--r-- | docs/rabbitmq-service.xml | 217 | ||||
| -rw-r--r-- | docs/rabbitmqctl.1.xml | 2338 | ||||
| -rw-r--r-- | docs/rabbitmqctl.8 | 1692 | ||||
| -rw-r--r-- | docs/remove-namespaces.xsl | 18 | ||||
| -rw-r--r-- | docs/usage.xsl | 82 |
16 files changed, 2309 insertions, 3369 deletions
diff --git a/docs/examples-to-end.xsl b/docs/examples-to-end.xsl deleted file mode 100644 index 4db1d5c479..0000000000 --- a/docs/examples-to-end.xsl +++ /dev/null @@ -1,93 +0,0 @@ -<?xml version='1.0'?> -<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" - version='1.0'> - -<xsl:output doctype-public="-//OASIS//DTD DocBook XML V4.5//EN" - doctype-system="http://www.docbook.org/xml/4.5/docbookx.dtd" - indent="yes" -/> - -<!-- Don't copy examples through in place --> -<xsl:template match="*[@role='example-prefix']"/> -<xsl:template match="*[@role='example']"/> - -<!-- Copy everything through (with lower priority) --> -<xsl:template match="@*|node()"> - <xsl:copy><xsl:apply-templates select="@*|node()"/></xsl:copy> -</xsl:template> - -<!-- Copy the root node, and add examples at the end--> -<xsl:template match="/refentry"> -<refentry lang="en"> -<xsl:for-each select="*"> - <xsl:copy><xsl:apply-templates select="@*|node()"/></xsl:copy> -</xsl:for-each> - <refsect1> - <title>Examples</title> -<xsl:if test="//screen[@role='example']"> - <variablelist> -<xsl:for-each select="//screen[@role='example']"> - <varlistentry> - <term><command><xsl:copy-of select="text()"/></command></term> - <listitem> - <xsl:copy-of select="following-sibling::para[@role='example' and preceding-sibling::screen[1] = current()]"/> - </listitem> - </varlistentry> -</xsl:for-each> - </variablelist> -</xsl:if> -<!-- -We need to handle multiline examples separately, since not using a -variablelist leads to slightly less nice formatting (the explanation doesn't get -indented) ---> -<xsl:for-each select="//screen[@role='example-multiline']"> -<screen><emphasis role="bold"><xsl:copy-of select="text()"/></emphasis></screen> -<xsl:copy-of select="following-sibling::para[@role='example']"/> -</xsl:for-each> - </refsect1> -</refentry> -</xsl:template> - -<!-- - We show all the subcommands using XML that looks like this: - - <term> - <cmdsynopsis> - <command>list_connections</command> - <arg choice="opt"> - <replaceable>connectioninfoitem</replaceable> - ... - </arg> - </cmdsynopsis> - </term> - - However, while DocBook renders this sensibly for HTML, for some reason it - doen't show anything inside <cmdsynopsis> at all for man pages. I think what - we're doing is semantically correct so this is a bug in DocBook. The following - rules essentially do what DocBook does when <cmdsynopsis> is not inside a - <term>. ---> - -<xsl:template match="term/cmdsynopsis"> - <xsl:apply-templates mode="docbook-bug"/> -</xsl:template> - -<xsl:template match="command" mode="docbook-bug"> - <emphasis role="bold"><xsl:apply-templates mode="docbook-bug"/></emphasis> -</xsl:template> - -<xsl:template match="arg[@choice='opt']" mode="docbook-bug"> - [<xsl:apply-templates mode="docbook-bug"/>] -</xsl:template> - -<xsl:template match="arg[@choice='req']" mode="docbook-bug"> - {<xsl:apply-templates mode="docbook-bug"/>} -</xsl:template> - -<xsl:template match="replaceable" mode="docbook-bug"> - <emphasis><xsl:apply-templates mode="docbook-bug"/></emphasis> -</xsl:template> - -</xsl:stylesheet> - diff --git a/docs/html-to-website-xml.xsl b/docs/html-to-website-xml.xsl deleted file mode 100644 index d83d507369..0000000000 --- a/docs/html-to-website-xml.xsl +++ /dev/null @@ -1,90 +0,0 @@ -<?xml version='1.0'?> -<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" - xmlns:doc="http://www.rabbitmq.com/namespaces/ad-hoc/doc" - xmlns="http://www.w3.org/1999/xhtml" - version='1.0'> - -<xsl:param name="original"/> - -<xsl:output method="xml" /> - -<!-- Copy every element through --> -<xsl:template match="*"> - <xsl:element name="{name()}" namespace="http://www.w3.org/1999/xhtml"> - <xsl:apply-templates select="@*|node()"/> - </xsl:element> -</xsl:template> - -<xsl:template match="@*"> - <xsl:copy/> -</xsl:template> - -<!-- Copy the root node, and munge the outer part of the page --> -<xsl:template match="/html"> -<xsl:processing-instruction name="xml-stylesheet">type="text/xml" href="page.xsl"</xsl:processing-instruction> -<html xmlns:doc="http://www.rabbitmq.com/namespaces/ad-hoc/doc" xmlns="http://www.w3.org/1999/xhtml"> - <head> - <title><xsl:value-of select="document($original)/refentry/refnamediv/refname"/><xsl:if test="document($original)/refentry/refmeta/manvolnum">(<xsl:value-of select="document($original)/refentry/refmeta/manvolnum"/>)</xsl:if> manual page</title> - </head> - <body show-in-this-page="true"> - <xsl:choose> - <xsl:when test="document($original)/refentry/refmeta/manvolnum"> - <p> - This is the manual page for - <code><xsl:value-of select="document($original)/refentry/refnamediv/refname"/>(<xsl:value-of select="document($original)/refentry/refmeta/manvolnum"/>)</code>. - </p> - <p> - <a href="../manpages.html">See a list of all manual pages</a>. - </p> - </xsl:when> - <xsl:otherwise> - <p> - This is the documentation for - <code><xsl:value-of select="document($original)/refentry/refnamediv/refname"/></code>. - </p> - </xsl:otherwise> - </xsl:choose> - <p> - For more general documentation, please see the - <a href="../admin-guide.html">administrator's guide</a>. - </p> - - <xsl:apply-templates select="body/div[@class='refentry']"/> - </body> -</html> -</xsl:template> - -<!-- Specific instructions to revert the DocBook HTML to be more like our ad-hoc XML schema --> - -<xsl:template match="div[@class='refsect1'] | div[@class='refnamediv'] | div[@class='refsynopsisdiv']"> - <doc:section name="{h2}"> - <xsl:apply-templates select="node()"/> - </doc:section> -</xsl:template> - -<xsl:template match="div[@class='refsect2']"> - <doc:subsection name="{h3}"> - <xsl:apply-templates select="node()"/> - </doc:subsection> -</xsl:template> - -<xsl:template match="h2 | h3"> - <doc:heading> - <xsl:apply-templates select="node()"/> - </doc:heading> -</xsl:template> - -<xsl:template match="pre[@class='screen']"> - <pre class="sourcecode"> - <xsl:apply-templates select="node()"/> - </pre> -</xsl:template> - -<xsl:template match="div[@class='cmdsynopsis']"> - <div class="cmdsynopsis" id="{p/code[@class='command']}"> - <xsl:apply-templates select="node()"/> - </div> -</xsl:template> - -</xsl:stylesheet> - diff --git a/docs/rabbitmq-echopid.8 b/docs/rabbitmq-echopid.8 new file mode 100644 index 0000000000..04081f9581 --- /dev/null +++ b/docs/rabbitmq-echopid.8 @@ -0,0 +1,82 @@ +.\" vim:ft=nroff: +.\" The contents of this file are subject to the Mozilla Public License +.\" Version 1.1 (the "License"); you may not use this file except in +.\" compliance with the License. You may obtain a copy of the License +.\" at http://www.mozilla.org/MPL/ +.\" +.\" Software distributed under the License is distributed on an "AS IS" +.\" basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See +.\" the License for the specific language governing rights and +.\" limitations under the License. +.\" +.\" The Original Code is RabbitMQ. +.\" +.\" The Initial Developer of the Original Code is Pivotal Software, Inc. +.\" Copyright (c) 2007-2017 Pivotal Software, Inc. All rights reserved. +.\" +.Dd April 25, 2017 +.Dt RABBITMQ-ECHOPID.BAT 8 +.Os "RabbitMQ Server" +.Sh NAME +.Nm rabbitmq-echopid.bat +.Nd return the Windows process id of the Erlang runtime hosting RabbitMQ +.\" ------------------------------------------------------------------ +.Sh SYNOPSIS +.\" ------------------------------------------------------------------ +.Nm +.Ar sname +.\" ------------------------------------------------------------------ +.Sh DESCRIPTION +.\" ------------------------------------------------------------------ +RabbitMQ is an implementation of AMQP, the emerging standard for high +performance enterprise messaging. +The RabbitMQ server is a robust and scalable implementation of an AMQP +broker. +.Pp +Running +.Nm +will attempt to discover and echo the process id (PID) of the Erlang +runtime process +.Pq Pa erl.exe +that is hosting RabbitMQ. +To allow +.Pa erl.exe +time to start up and load RabbitMQ, the script will wait for ten seconds +before timing out if a suitable PID cannot be found. +.Pp +If a PID is discovered, the script will echo it to stdout +before exiting with a +.Ev ERRORLEVEL +of 0. +If no PID is discovered before the timeout, nothing is written to stdout +and the script exits setting +.Ev ERRORLEVEL +to 1. +.Pp +Note that this script only exists on Windows due to the need to wait for +.Pa erl.exe +and possibly time-out. +To obtain the PID on Unix set +.Ev RABBITMQ_PID_FILE +before starting +.Xr rabbitmq-server 8 +and do not use +.Fl detached . +.\" ------------------------------------------------------------------ +.Sh OPTIONS +.\" ------------------------------------------------------------------ +.Bl -tag -width Ds +.It Ar sname +The short-name form of the RabbitMQ node name. +.El +.\" ------------------------------------------------------------------ +.Sh SEE ALSO +.\" ------------------------------------------------------------------ +.Xr rabbitmq-plugins 8 , +.Xr rabbitmq-server 8 , +.Xr rabbitmq-service 8 , +.Xr rabbitmqctl 8 +.\" ------------------------------------------------------------------ +.Sh AUTHOR +.\" ------------------------------------------------------------------ +.An The RabbitMQ Team Aq Mt info@rabbitmq.com diff --git a/docs/rabbitmq-echopid.xml b/docs/rabbitmq-echopid.xml deleted file mode 100644 index d3dcea521b..0000000000 --- a/docs/rabbitmq-echopid.xml +++ /dev/null @@ -1,71 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.docbook.org/xml/4.5/docbookx.dtd"> -<refentry lang="en"> - <refentryinfo> - <productname>RabbitMQ Server</productname> - <authorgroup> - <corpauthor>The RabbitMQ Team <<ulink url="mailto:info@rabbitmq.com"><email>info@rabbitmq.com</email></ulink>></corpauthor> - </authorgroup> - </refentryinfo> - - <refmeta> - <refentrytitle>rabbitmq-echopid.bat</refentrytitle> - <refmiscinfo class="manual">RabbitMQ Server</refmiscinfo> - </refmeta> - - <refnamediv> - <refname>rabbitmq-echopid.bat</refname> - <refpurpose>return the process id of the Erlang runtime hosting RabbitMQ</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <cmdsynopsis> - <command>rabbitmq-echopid.bat</command> - <arg choice="req">sname</arg> - </cmdsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - <para> - RabbitMQ is an implementation of AMQP, the emerging - standard for high performance enterprise messaging. The - RabbitMQ server is a robust and scalable implementation of - an AMQP broker. - </para> - <para> - Running <command>rabbitmq-echopid</command> will attempt to - discover and echo the process id (PID) of the Erlang runtime - process (erl.exe) that is hosting RabbitMQ. To allow erl.exe - time to start up and load RabbitMQ, the script will wait for - ten seconds before timing out if a suitable PID cannot be - found. - </para> - <para> - If a PID is discovered, the script will echo it to stdout - before exiting with a ERRORLEVEL of 0. If no PID is - discovered before the timeout, nothing is written to stdout - and the script exits setting ERRORLEVEL to 1. - </para> - <para> - Note that this script only exists on Windows due to the need - to wait for erl.exe and possibly time-out. To obtain the PID - on Unix set RABBITMQ_PID_FILE before starting - rabbitmq-server and do not use "-detached". - </para> - </refsect1> - - <refsect1> - <title>Options</title> - <variablelist> - <varlistentry> - <term><cmdsynopsis><arg choice="req">sname</arg></cmdsynopsis></term> - <listitem> - <para role="usage"> -The short-name form of the RabbitMQ node name. - </para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> -</refentry> diff --git a/docs/rabbitmq-env.conf.5 b/docs/rabbitmq-env.conf.5 new file mode 100644 index 0000000000..4d86d672e4 --- /dev/null +++ b/docs/rabbitmq-env.conf.5 @@ -0,0 +1,86 @@ +.\" vim:ft=nroff: +.\" The contents of this file are subject to the Mozilla Public License +.\" Version 1.1 (the "License"); you may not use this file except in +.\" compliance with the License. You may obtain a copy of the License +.\" at http://www.mozilla.org/MPL/ +.\" +.\" Software distributed under the License is distributed on an "AS IS" +.\" basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See +.\" the License for the specific language governing rights and +.\" limitations under the License. +.\" +.\" The Original Code is RabbitMQ. +.\" +.\" The Initial Developer of the Original Code is Pivotal Software, Inc. +.\" Copyright (c) 2007-2017 Pivotal Software, Inc. All rights reserved. +.\" +.Dd April 25, 2017 +.Dt RABBITMQ-ENV.CONF 5 +.Os "RabbitMQ Server" +.Sh NAME +.Nm rabbitmq-env.conf +.Nd default settings for RabbitMQ AMQP server +.\" ------------------------------------------------------------------ +.Sh DESCRIPTION +.\" ------------------------------------------------------------------ +.Nm +contains variable settings that override the defaults built in to the +RabbitMQ startup scripts. +.Pp +The file is interpreted by the system shell, and so should consist of a +sequence of shell environment variable definitions. +Normal shell syntax is permitted (since the file is sourced using the +shell "." operator), including line comments starting with "#". +.Pp +In order of preference, the startup scripts get their values from the +environment, from +.Nm +and finally from the built-in default values. +For example, for the +.Ev RABBITMQ_NODENAME +setting, +.Ev RABBITMQ_NODENAME +from the environment is checked first. +If it is absent or equal to the empty string, then +.Ev NODENAME +from +.Nm +is checked. +If it is also absent or set equal to the empty string then the default +value from the startup script is used. +.Pp +The variable names in +.Nm +are always equal to the environment variable names, with the +.Qq RABBITMQ_ +prefix removed: +.Ev RABBITMQ_NODE_PORT +from the environment becomes +.Ev NODE_PORT +in +.Nm , +etc. +.\" ------------------------------------------------------------------ +.Sh EXAMPLES +.\" ------------------------------------------------------------------ +Here is an example of a complete +.Nm +file that overrides the default Erlang node name from "rabbit" to +"hare". +.sp +.Dl # I am a complete rabbitmq-env.conf file. +.Dl # Comment lines start with a hash character. +.Dl # This is a /bin/sh script file - use ordinary envt var syntax +.Dl NODENAME=hare +.\" ------------------------------------------------------------------ +.Sh SEE ALSO +.\" ------------------------------------------------------------------ +.Xr rabbitmq-echopid 8 , +.Xr rabbitmq-plugins 8 , +.Xr rabbitmq-server 8 , +.Xr rabbitmq-service 8 , +.Xr rabbitmqctl 8 +.\" ------------------------------------------------------------------ +.Sh AUTHOR +.\" ------------------------------------------------------------------ +.An The RabbitMQ Team Aq Mt info@rabbitmq.com diff --git a/docs/rabbitmq-env.conf.5.xml b/docs/rabbitmq-env.conf.5.xml deleted file mode 100644 index c887596c59..0000000000 --- a/docs/rabbitmq-env.conf.5.xml +++ /dev/null @@ -1,83 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.docbook.org/xml/4.5/docbookx.dtd"> -<refentry lang="en"> - <refentryinfo> - <productname>RabbitMQ Server</productname> - <authorgroup> - <corpauthor>The RabbitMQ Team <<ulink url="mailto:info@rabbitmq.com"><email>info@rabbitmq.com</email></ulink>></corpauthor> - </authorgroup> - </refentryinfo> - - <refmeta> - <refentrytitle>rabbitmq-env.conf</refentrytitle> - <manvolnum>5</manvolnum> - <refmiscinfo class="manual">RabbitMQ Server</refmiscinfo> - </refmeta> - - <refnamediv> - <refname>rabbitmq-env.conf</refname> - <refpurpose>default settings for RabbitMQ AMQP server</refpurpose> - </refnamediv> - - <refsect1> - <title>Description</title> - <para> -<filename>/etc/rabbitmq/rabbitmq-env.conf</filename> contains variable settings that override the -defaults built in to the RabbitMQ startup scripts. - </para> - <para> -The file is interpreted by the system shell, and so should consist of -a sequence of shell environment variable definitions. Normal shell -syntax is permitted (since the file is sourced using the shell "." -operator), including line comments starting with "#". - </para> - <para> -In order of preference, the startup scripts get their values from the -environment, from <filename>/etc/rabbitmq/rabbitmq-env.conf</filename> and finally from the -built-in default values. For example, for the <envar>RABBITMQ_NODENAME</envar> -setting, - </para> - <para> - <envar>RABBITMQ_NODENAME</envar> - </para> - <para> -from the environment is checked first. If it is absent or equal to the -empty string, then - </para> - <para> - <envar>NODENAME</envar> - </para> - <para> -from <filename>/etc/rabbitmq/rabbitmq-env.conf</filename> is checked. If it is also absent -or set equal to the empty string then the default value from the -startup script is used. - </para> - <para> -The variable names in /etc/rabbitmq/rabbitmq-env.conf are always equal to the -environment variable names, with the <envar>RABBITMQ_</envar> prefix removed: -<envar>RABBITMQ_NODE_PORT</envar> from the environment becomes <envar>NODE_PORT</envar> in the -<filename>/etc/rabbitmq/rabbitmq-env.conf</filename> file, etc. - </para> - <para role="example-prefix">For example:</para> - <screen role="example-multiline"> -# I am a complete /etc/rabbitmq/rabbitmq-env.conf file. -# Comment lines start with a hash character. -# This is a /bin/sh script file - use ordinary envt var syntax -NODENAME=hare - </screen> - <para role="example"> - This is an example of a complete - <filename>/etc/rabbitmq/rabbitmq-env.conf</filename> file that overrides the default Erlang - node name from "rabbit" to "hare". - </para> - - </refsect1> - - <refsect1> - <title>See also</title> - <para> - <citerefentry><refentrytitle>rabbitmq-server</refentrytitle><manvolnum>1</manvolnum></citerefentry> - <citerefentry><refentrytitle>rabbitmqctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> - </para> - </refsect1> -</refentry> diff --git a/docs/rabbitmq-plugins.1.xml b/docs/rabbitmq-plugins.1.xml deleted file mode 100644 index f7be2d2995..0000000000 --- a/docs/rabbitmq-plugins.1.xml +++ /dev/null @@ -1,245 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.docbook.org/xml/4.5/docbookx.dtd"> -<!-- - There is some extra magic in this document besides the usual DocBook semantics - to allow us to derive manpages, HTML and usage messages from the same source - document. - - Examples need to be moved to the end for man pages. To this end, <para>s and - <screen>s with role="example" will be moved, and with role="example-prefix" - will be removed. - - The usage messages are more involved. We have some magic in usage.xsl to pull - out the command synopsis, global option and subcommand synopses. We also pull - out <para>s with role="usage". - - Finally we construct lists of possible values for subcommand options, if the - subcommand's <varlistentry> has role="usage-has-option-list". The option which - takes the values should be marked with role="usage-option-list". ---> - -<refentry lang="en"> - <refentryinfo> - <productname>RabbitMQ Server</productname> - <authorgroup> - <corpauthor>The RabbitMQ Team <<ulink url="mailto:info@rabbitmq.com"><email>info@rabbitmq.com</email></ulink>></corpauthor> - </authorgroup> - </refentryinfo> - - <refmeta> - <refentrytitle>rabbitmq-plugins</refentrytitle> - <manvolnum>1</manvolnum> - <refmiscinfo class="manual">RabbitMQ Service</refmiscinfo> - </refmeta> - - <refnamediv> - <refname>rabbitmq-plugins</refname> - <refpurpose>command line tool for managing RabbitMQ broker plugins</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <cmdsynopsis> - <command>rabbitmq-plugins</command> - <arg choice="opt">-n <replaceable>node</replaceable></arg> - <arg choice="req"><replaceable>command</replaceable></arg> - <arg choice="opt" rep="repeat"><replaceable>command options</replaceable></arg> - </cmdsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - <para> - <command>rabbitmq-plugins</command> is a command line tool for managing - RabbitMQ broker plugins. It allows one to enable, disable and browse - plugins. It must be run by a user with write permissions to the RabbitMQ - configuration directory. - </para> - <para> - Some plugins depend on others to work - correctly. <command>rabbitmq-plugins</command> traverses these - dependencies and enables all required plugins. Plugins listed on - the <command>rabbitmq-plugins</command> command line are marked as - explicitly enabled; dependent plugins are marked as implicitly - enabled. Implicitly enabled plugins are automatically disabled again - when they are no longer required. - </para> - - <para> - The <command>enable</command>, <command>disable</command> and - <command>set</command> commands will update the plugins file and - then attempt to connect to the broker and ensure it is running - all enabled plugins. By default if it is not possible to connect - to the running broker (for example if it is stopped) then a - warning is displayed. Specify <command>--online</command> or - <command>--offline</command> to change this behaviour. - </para> - </refsect1> - - <refsect1> - <title>Commands</title> - - <variablelist> - <varlistentry> - <term><cmdsynopsis><command>list</command> <arg choice="opt">-v</arg> <arg choice="opt">-m</arg> <arg choice="opt">-E</arg> <arg choice="opt">-e</arg> <arg choice="opt"><replaceable>pattern</replaceable></arg></cmdsynopsis></term> - <listitem> - <variablelist> - <varlistentry> - <term>-v</term> - <listitem><para>Show all plugin details (verbose).</para></listitem> - </varlistentry> - <varlistentry> - <term>-m</term> - <listitem><para>Show only plugin names (minimal).</para></listitem> - </varlistentry> - <varlistentry> - <term>-E</term> - <listitem><para>Show only explicitly enabled - plugins.</para></listitem> - </varlistentry> - <varlistentry> - <term>-e</term> - <listitem><para>Show only explicitly or implicitly - enabled plugins.</para></listitem> - </varlistentry> - <varlistentry> - <term>pattern</term> - <listitem><para>Pattern to filter the plugin names by.</para></listitem> - </varlistentry> - </variablelist> - <para> - Lists all plugins, their versions, dependencies and - descriptions. Each plugin is prefixed with two status - indicator characters inside [ ]. The first indicator can - be " " to indicate that the plugin is not enabled, "E" to - indicate that it is explicitly enabled, "e" to indicate - that it is implicitly enabled, or "!" to indicate that it - is enabled but missing and thus not operational. The - second indicator can be " " to show that the plugin is not - running, or "*" to show that it is. - </para> - <para> - If the optional pattern is given, only plugins whose - name matches <command>pattern</command> are shown. - </para> - <para role="example-prefix">For example:</para> - <screen role="example">rabbitmq-plugins list</screen> - <para role="example"> - This command lists all plugins, on one line each. - </para> - <screen role="example">rabbitmq-plugins list -v </screen> - <para role="example"> - This command lists all plugins. - </para> - <screen role="example">rabbitmq-plugins list -v management</screen> - <para role="example"> - This command lists all plugins whose name contains "management". - </para> - <screen role="example">rabbitmq-plugins list -e rabbit</screen> - <para role="example"> - This command lists all implicitly or explicitly enabled - RabbitMQ plugins. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><cmdsynopsis><command>enable</command> <arg choice="opt">--offline</arg> <arg choice="opt">--online</arg> <arg choice="req"><replaceable>plugin</replaceable> ...</arg></cmdsynopsis></term> - <listitem> - <variablelist> - <varlistentry> - <term>--offline</term> - <listitem><para>Just modify the enabled plugins file.</para></listitem> - </varlistentry> - <varlistentry> - <term>--online</term> - <listitem><para>Treat failure to connect to the running broker as fatal.</para></listitem> - </varlistentry> - <varlistentry> - <term>plugin</term> - <listitem><para>One or more plugins to enable.</para></listitem> - </varlistentry> - </variablelist> - <para> - Enables the specified plugins and all their dependencies. - </para> - - <para role="example-prefix">For example:</para> - <screen role="example">rabbitmq-plugins enable rabbitmq_shovel rabbitmq_management</screen> - <para role="example"> - This command enables the <command>shovel</command> and - <command>management</command> plugins and all their - dependencies. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><cmdsynopsis><command>disable</command> <arg choice="opt">--offline</arg> <arg choice="opt">--online</arg> <arg choice="req"><replaceable>plugin</replaceable> ...</arg></cmdsynopsis></term> - <listitem> - <variablelist> - <varlistentry> - <term>--offline</term> - <listitem><para>Just modify the enabled plugins file.</para></listitem> - </varlistentry> - <varlistentry> - <term>--online</term> - <listitem><para>Treat failure to connect to the running broker as fatal.</para></listitem> - </varlistentry> - <varlistentry> - <term>plugin</term> - <listitem><para>One or more plugins to disable.</para></listitem> - </varlistentry> - </variablelist> - <para> - Disables the specified plugins and all their dependencies. - </para> - - <para role="example-prefix">For example:</para> - <screen role="example">rabbitmq-plugins disable amqp_client</screen> - <para role="example"> - This command disables <command>amqp_client</command> and - all plugins that depend on it. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><cmdsynopsis><command>set</command> <arg choice="opt">--offline</arg> <arg choice="opt">--online</arg> <arg choice="req"><replaceable>plugin</replaceable> ...</arg></cmdsynopsis></term> - <listitem> - <variablelist> - <varlistentry> - <term>--offline</term> - <listitem><para>Just modify the enabled plugins file.</para></listitem> - </varlistentry> - <varlistentry> - <term>--online</term> - <listitem><para>Treat failure to connect to the running broker as fatal.</para></listitem> - </varlistentry> - <varlistentry> - <term>plugin</term> - <listitem><para>Zero or more plugins to enable.</para></listitem> - </varlistentry> - </variablelist> - <para> - Enables the specified plugins and all their - dependencies. Unlike <command>rabbitmq-plugins - enable</command> this command ignores and overwrites any - existing enabled plugins. <command>rabbitmq-plugins - set</command> with no plugin arguments is a legal command - meaning "disable all plugins". - </para> - - <para role="example-prefix">For example:</para> - <screen role="example">rabbitmq-plugins set rabbitmq_management</screen> - <para role="example"> - This command enables the <command>management</command> - plugin and its dependencies and disables everything else. - </para> - </listitem> - </varlistentry> - - </variablelist> - - </refsect1> - -</refentry> diff --git a/docs/rabbitmq-plugins.8 b/docs/rabbitmq-plugins.8 new file mode 100644 index 0000000000..12383ca686 --- /dev/null +++ b/docs/rabbitmq-plugins.8 @@ -0,0 +1,196 @@ +.\" vim:ft=nroff: +.\" The contents of this file are subject to the Mozilla Public License +.\" Version 1.1 (the "License"); you may not use this file except in +.\" compliance with the License. You may obtain a copy of the License +.\" at http://www.mozilla.org/MPL/ +.\" +.\" Software distributed under the License is distributed on an "AS IS" +.\" basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See +.\" the License for the specific language governing rights and +.\" limitations under the License. +.\" +.\" The Original Code is RabbitMQ. +.\" +.\" The Initial Developer of the Original Code is Pivotal Software, Inc. +.\" Copyright (c) 2007-2017 Pivotal Software, Inc. All rights reserved. +.\" +.Dd April 25, 2017 +.Dt RABBITMQ-PLUGINS 8 +.Os "RabbitMQ Server" +.Sh NAME +.Nm rabbitmq-plugins +.Nd command line for managing RabbitMQ broker plugins +.\" ------------------------------------------------------------------ +.Sh SYNOPSIS +.\" ------------------------------------------------------------------ +.Nm +.Op Fl n Ar node +.Ar command +.Op Ar command_options +.\" ------------------------------------------------------------------ +.Sh DESCRIPTION +.\" ------------------------------------------------------------------ +.Nm +is a command line tool for managing RabbitMQ broker plugins. +It allows one to enable, disable and browse plugins. +It must be run by a user with write permissions to the RabbitMQ +configuration directory. +.Pp +Some plugins depend on others to work correctly. +.Nm +traverses these dependencies and enables all required plugins. +Plugins listed on the +.Nm +command line are marked as explicitly enabled; dependent plugins are +marked as implicitly enabled. +Implicitly enabled plugins are automatically disabled again when they +are no longer required. +.Pp +The +.Cm enable , +.Cm disable , +and +.Cm set +commands will update the plugins file and then attempt to connect to the +broker and ensure it is running all enabled plugins. +By default if it is not possible to connect to the running broker (for +example if it is stopped) then a warning is displayed. +Specify +.Fl -online +or +.Fl -offline +to change this behaviour. +.\" ------------------------------------------------------------------ +.Sh COMMANDS +.\" ------------------------------------------------------------------ +.Bl -tag -width Ds +.\" ------------------------------------ +.It Cm list Oo Fl Eemv Oc Op Ar pattern +.Bl -tag -width Ds +.It Fl E +Show only explicitly enabled plugins. +.It Fl e +Show only explicitly or implicitly enabled plugins. +.It Fl m +Show only plugin names (minimal). +.It Fl v +Show all plugin details (verbose). +.It Ar pattern +Pattern to filter the plugin names by. +.El +.Pp +Lists all plugins, their versions, dependencies and descriptions. +Each plugin is prefixed with two status indicator characters inside [ ]. +The first indicator can be: +.Bl -tag -width <space> -compact +.It Sy <space> +to indicate that the plugin is not enabled +.It Sy E +to indicate that it is explicitly enabled +.It Sy e +to indicate that it is implicitly enabled +.It Sy \! +to indicate that it is enabled but missing and thus not operational +.El +.Pp +The second indicator can be: +.Bl -tag -width <space> -compact +.It Sy <space> +to show that the plugin is not running +.It Sy * +to show that it is +.El +.Pp +If the optional pattern is given, only plugins whose name matches +.Ar pattern +are shown. +.Pp +For example, this command lists all plugins, on one line each +.sp +.Dl rabbitmq-plugins list +.Pp +This command lists all plugins: +.sp +.Dl rabbitmq-plugins list -v +.Pp +This command lists all plugins whose name contains "management". +.sp +.Dl rabbitmq-plugins list -v management +.Pp +This command lists all implicitly or explicitly enabled RabbitMQ plugins. +.sp +.Dl rabbitmq-plugins list -e rabbit +.\" ------------------------------------ +.It Cm enable Oo Fl -offline Oc Oo Fl -online Oc Ar plugin ... +.Bl -tag -width Ds +.It Fl -offline +Just modify the enabled plugins file. +.It Fl -online +Treat failure to connect to the running broker as fatal. +.It Ar plugin +One or more plugins to enable. +.El +.Pp +Enables the specified plugins and all their dependencies. +.Pp +For example, this command enables the +.Qq shovel +and +.Qq management +plugins and all their dependencies: +.sp +.Dl rabbitmq\-plugins enable rabbitmq_shovel rabbitmq_management +.\" ------------------------------------ +.It Cm disable Oo Fl -offline Oc Oo Fl -online Oc Ar plugin ... +.Bl -tag -width Ds +.It Fl -offline +Just modify the enabled plugins file. +.It Fl -online +Treat failure to connect to the running broker as fatal. +.It Ar plugin +One or more plugins to disable. +.El +.Pp +Disables the specified plugins and all their dependencies. +.Pp +For example, this command disables +.Qq amqp_client +and all plugins that depend on it: +.sp +.Dl rabbitmq-plugins disable amqp_client +.\" ------------------------------------ +.It Cm set Oo Fl -offline Oc Oo Fl -online Oc Op Ar plugin ... +.Bl -tag -width Ds +.It Fl -offline +Just modify the enabled plugins file. +.It Fl -online +Treat failure to connect to the running broker as fatal. +.It Ar plugin +Zero or more plugins to enable. +.El +.Pp +Enables the specified plugins and all their dependencies. +Unlike +.Cm enable , +this command ignores and overwrites any existing enabled plugins. +.Cm set +with no plugin arguments is a legal command meaning "disable all plugins". +.Pp +For example, this command enables the +.Qq management +plugin and its dependencies and disables everything else: +.sp +.Dl rabbitmq-plugins set rabbitmq_management +.El +.\" ------------------------------------------------------------------ +.Sh SEE ALSO +.\" ------------------------------------------------------------------ +.Xr rabbitmq-env.conf 5 , +.Xr rabbitmq-echopid 8 , +.Xr rabbitmq-server 8 , +.Xr rabbitmq-service 8 , +.Xr rabbitmqctl 8 +.\" ------------------------------------------------------------------ +.Sh AUTHOR +.\" ------------------------------------------------------------------ +.An The RabbitMQ Team Aq Mt info@rabbitmq.com diff --git a/docs/rabbitmq-server.1.xml b/docs/rabbitmq-server.1.xml deleted file mode 100644 index 32ae842c76..0000000000 --- a/docs/rabbitmq-server.1.xml +++ /dev/null @@ -1,132 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.docbook.org/xml/4.5/docbookx.dtd"> -<refentry lang="en"> - <refentryinfo> - <productname>RabbitMQ Server</productname> - <authorgroup> - <corpauthor>The RabbitMQ Team <<ulink url="mailto:info@rabbitmq.com"><email>info@rabbitmq.com</email></ulink>></corpauthor> - </authorgroup> - </refentryinfo> - - <refmeta> - <refentrytitle>rabbitmq-server</refentrytitle> - <manvolnum>1</manvolnum> - <refmiscinfo class="manual">RabbitMQ Server</refmiscinfo> - </refmeta> - - <refnamediv> - <refname>rabbitmq-server</refname> - <refpurpose>start RabbitMQ AMQP server</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <cmdsynopsis> - <command>rabbitmq-server</command> - <arg choice="opt">-detached</arg> - </cmdsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - <para> - RabbitMQ is an implementation of AMQP, the emerging standard for high -performance enterprise messaging. The RabbitMQ server is a robust and -scalable implementation of an AMQP broker. - </para> - <para> -Running rabbitmq-server in the foreground displays a banner message, -and reports on progress in the startup sequence, concluding with the -message "broker running", indicating that the RabbitMQ broker has been -started successfully. To shut down the server, just terminate the -process or use rabbitmqctl(1). - </para> - </refsect1> - - <refsect1> - <title>Environment</title> - <variablelist> - - <varlistentry> - <term>RABBITMQ_MNESIA_BASE</term> - <listitem> - <para> -Defaults to <filename>/var/lib/rabbitmq/mnesia</filename>. Set this to the directory where -Mnesia database files should be placed. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term>RABBITMQ_LOG_BASE</term> - <listitem> - <para> -Defaults to <filename>/var/log/rabbitmq</filename>. Log files generated by the server will -be placed in this directory. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term>RABBITMQ_NODENAME</term> - <listitem> - <para> -Defaults to rabbit. This can be useful if you want to run more than -one node per machine - <envar>RABBITMQ_NODENAME</envar> should be unique per -erlang-node-and-machine combination. See the -<ulink url="http://www.rabbitmq.com/clustering.html#single-machine">clustering on a single -machine guide</ulink> for details. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term>RABBITMQ_NODE_IP_ADDRESS</term> - <listitem> - <para> -By default RabbitMQ will bind to all interfaces, on IPv4 and IPv6 if -available. Set this if you only want to bind to one network interface -or address family. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term>RABBITMQ_NODE_PORT</term> - <listitem> - <para> -Defaults to 5672. - </para> - </listitem> - </varlistentry> - - </variablelist> - </refsect1> - - <refsect1> - <title>Options</title> - <variablelist> - <varlistentry> - <term>-detached</term> - <listitem> - <para> - Start the server process in the background. Note that this will - cause the pid not to be written to the pid file. - </para> - <para role="example-prefix">For example:</para> - <screen role="example">rabbitmq-server -detached</screen> - <para role="example"> - Runs RabbitMQ AMQP server in the background. - </para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> - <title>See also</title> - <para> - <citerefentry><refentrytitle>rabbitmq-env.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry> - <citerefentry><refentrytitle>rabbitmqctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> - </para> - </refsect1> -</refentry> diff --git a/docs/rabbitmq-server.8 b/docs/rabbitmq-server.8 new file mode 100644 index 0000000000..84772aa042 --- /dev/null +++ b/docs/rabbitmq-server.8 @@ -0,0 +1,96 @@ +.\" vim:ft=nroff: +.\" The contents of this file are subject to the Mozilla Public License +.\" Version 1.1 (the "License"); you may not use this file except in +.\" compliance with the License. You may obtain a copy of the License +.\" at http://www.mozilla.org/MPL/ +.\" +.\" Software distributed under the License is distributed on an "AS IS" +.\" basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See +.\" the License for the specific language governing rights and +.\" limitations under the License. +.\" +.\" The Original Code is RabbitMQ. +.\" +.\" The Initial Developer of the Original Code is Pivotal Software, Inc. +.\" Copyright (c) 2007-2017 Pivotal Software, Inc. All rights reserved. +.\" +.Dd April 25, 2017 +.Dt RABBITMQ-SERVER 8 +.Os "RabbitMQ Server" +.Sh NAME +.Nm rabbitmq-server +.Nd start RabbitMQ AMQP server +.\" ------------------------------------------------------------------ +.Sh SYNOPSIS +.\" ------------------------------------------------------------------ +.Nm +.Op Fl detached +.\" ------------------------------------------------------------------ +.Sh DESCRIPTION +.\" ------------------------------------------------------------------ +RabbitMQ is an implementation of AMQP, the emerging standard for high +performance enterprise messaging. +The RabbitMQ server is a robust and scalable implementation of an AMQP +broker. +.Pp +Running +.Nm +in the foreground displays a banner message, and reports on progress in +the startup sequence, concluding with the message +.Qq broker running , +indicating that the RabbitMQ broker has been started successfully. +To shut down the server, just terminate the process or use +.Xr rabbitmqctl 8 . +.\" ------------------------------------------------------------------ +.Sh ENVIRONMENT +.\" ------------------------------------------------------------------ +.Bl -tag -width Ds +.It Ev RABBITMQ_MNESIA_BASE +Defaults to +.Pa /var/lib/rabbitmq/mnesia . +Set this to the directory where Mnesia database files should be placed. +.It Ev RABBITMQ_LOG_BASE +Defaults to +.Pa /var/log/rabbitmq . +Log files generated by the server will be placed in this directory. +.It Ev RABBITMQ_NODENAME +Defaults to +.Qq rabbit . +This can be useful if you want to run more than one node per machine - +.Ev RABBITMQ_NODENAME +should be unique per erlang-node-and-machine combination. +See the +.Lk http://www.rabbitmq.com/clustering.html#single-machine "clustering on a single machine guide" +for details. +.It Ev RABBITMQ_NODE_IP_ADDRESS +By default RabbitMQ will bind to all interfaces, on IPv4 and IPv6 if +available. +Set this if you only want to bind to one network interface or address +family. +.It Ev RABBITMQ_NODE_PORT +Defaults to 5672. +.El +.\" ------------------------------------------------------------------ +.Sh OPTIONS +.\" ------------------------------------------------------------------ +.Bl -tag -width Ds +.It Fl -detached +Start the server process in the background. +Note that this will cause the pid not to be written to the pid file. +.Pp +For example, runs RabbitMQ AMQP server in the background: +.sp +.Dl rabbitmq-server -detached +.El +.\" ------------------------------------------------------------------ +.Sh SEE ALSO +.\" ------------------------------------------------------------------ +.Xr rabbitmq-env.conf 5 , +.Xr rabbitmq-echopid 8 , +.Xr rabbitmq-plugins 8 , +.Xr rabbitmq-service 8 , +.Xr rabbitmqctl 8 +.\" ------------------------------------------------------------------ +.Sh AUTHOR +.\" ------------------------------------------------------------------ +.An The RabbitMQ Team Aq Mt info@rabbitmq.com diff --git a/docs/rabbitmq-service.8 b/docs/rabbitmq-service.8 new file mode 100644 index 0000000000..1e0f3760bb --- /dev/null +++ b/docs/rabbitmq-service.8 @@ -0,0 +1,157 @@ +.\" vim:ft=nroff: +.\" The contents of this file are subject to the Mozilla Public License +.\" Version 1.1 (the "License"); you may not use this file except in +.\" compliance with the License. You may obtain a copy of the License +.\" at http://www.mozilla.org/MPL/ +.\" +.\" Software distributed under the License is distributed on an "AS IS" +.\" basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See +.\" the License for the specific language governing rights and +.\" limitations under the License. +.\" +.\" The Original Code is RabbitMQ. +.\" +.\" The Initial Developer of the Original Code is Pivotal Software, Inc. +.\" Copyright (c) 2007-2017 Pivotal Software, Inc. All rights reserved. +.\" +.Dd April 25, 2017 +.Dt RABBITMQ-SERVICE.BAT 8 +.Os "RabbitMQ Server" +.Sh NAME +.Nm rabbitmq-service.bat +.Nd manage RabbitMQ AMQP Windows service +.\" ------------------------------------------------------------------ +.Sh SYNOPSIS +.\" ------------------------------------------------------------------ +.Nm +.Op Ar command +.\" ------------------------------------------------------------------ +.Sh DESCRIPTION +.\" ------------------------------------------------------------------ +RabbitMQ is an implementation of AMQP, the emerging standard for high +performance enterprise messaging. +The RabbitMQ server is a robust and scalable implementation of an AMQP +broker. +.Pp +Running +.Nm +allows the RabbitMQ broker to be run as a service on +NT/2000/2003/XP/Vista® environments. +The RabbitMQ broker service can be started and stopped using the +Windows® services applet. +.Pp +By default the service will run in the authentication context of the +local system account. +It is therefore necessary to synchronise Erlang cookies between the +local system account (typically +.Pa C:\(rsWindows\(rs.erlang.cookie +and the account that will be used to run +.Xr rabbitmqctl 8 . +.\" ------------------------------------------------------------------ +.Sh COMMANDS +.\" ------------------------------------------------------------------ +.Bl -tag -width Ds +.It Cm help +Display usage information. +.It Cm install +Install the service. +The service will not be started. +Subsequent invocations will update the service parameters if relevant +environment variables were modified. +.It Cm remove +Remove the service. +If the service is running then it will automatically be stopped before +being removed. +No files will be deleted as a consequence and +.Xr rabbitmq-server 8 +will remain operable. +.It Cm start +Start the service. +The service must have been correctly installed beforehand. +.It Cm stop +Stop the service. +The service must be running for this command to have any effect. +.It Cm disable +Disable the service. +This is the equivalent of setting the startup type to +.Sy Disabled +using the service control panel. +.It Cm enable +Enable the service. +This is the equivalent of setting the startup type to +.Sy Automatic +using the service control panel. +.El +.\" ------------------------------------------------------------------ +.Sh ENVIRONMENT +.\" ------------------------------------------------------------------ +.Bl -tag -width Ds +.It Ev RABBITMQ_SERVICENAME +Defaults to RabbitMQ. +.It Ev RABBITMQ_BASE +Defaults to the application data directory of the current user. +This is the location of log and database directories. +.It Ev RABBITMQ_NODENAME +Defaults to +.Qq rabbit . +This can be useful if you want to run more than one node per machine - +.Ev RABBITMQ_NODENAME +should be unique per erlang-node-and-machine combination. +See the +.Lk http://www.rabbitmq.com/clustering.html#single-machine clustering on a single machine guide +for details. +.It Ev RABBITMQ_NODE_IP_ADDRESS +By default RabbitMQ will bind to all interfaces, on IPv4 and IPv6 if +available. +Set this if you only want to bind to one network interface or address +family. +.It Ev RABBITMQ_NODE_PORT +Defaults to 5672. +.It Ev ERLANG_SERVICE_MANAGER_PATH +Defaults to +.Pa C:\(rsProgram\ Files\(rserl5.5.5\(rserts-5.5.5\(rsbin +(or +.Pa C:\(rsProgram\ Files\ (x86)\(rserl5.5.5\(rserts-5.5.5\(rsbin +for 64-bit environments). +This is the installation location of the Erlang service manager. +.It Ev RABBITMQ_CONSOLE_LOG +Set this varable to +.Sy new or +.Sy reuse +to have the console output from the server redirected to a file named +.Pa SERVICENAME.debug +in the application data directory of the user that installed the +service. +Under Vista this will be +.Pa C:\(rsUsers\(rsAppData\(rsusername\(rsSERVICENAME . +Under previous versions of Windows this will be +.Pa C:\(rsDocuments and Settings\(rsusername\(rsApplication Data\(rsSERVICENAME . +If +.Ev RABBITMQ_CONSOLE_LOG +is set to +.Sy new +then a new file will be created each time the service starts. +If +.Ev RABBITMQ_CONSOLE_LOG +is set to +.Sy reuse +then the file will be overwritten each time the service starts. +The default behaviour when +.Ev RABBITMQ_CONSOLE_LOG +is not set or set to a value other than +.Sy new +or +.Sy reuse +is to discard the server output. +.El +.\" ------------------------------------------------------------------ +.Sh SEE ALSO +.\" ------------------------------------------------------------------ +.Xr rabbitmq-echopid 8 , +.Xr rabbitmq-plugins 8 , +.Xr rabbitmq-server 8 , +.Xr rabbitmqctl 8 +.\" ------------------------------------------------------------------ +.Sh AUTHOR +.\" ------------------------------------------------------------------ +.An The RabbitMQ Team Aq Mt info@rabbitmq.com diff --git a/docs/rabbitmq-service.xml b/docs/rabbitmq-service.xml deleted file mode 100644 index 3368960b80..0000000000 --- a/docs/rabbitmq-service.xml +++ /dev/null @@ -1,217 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.docbook.org/xml/4.5/docbookx.dtd"> -<refentry lang="en"> - <refentryinfo> - <productname>RabbitMQ Server</productname> - <authorgroup> - <corpauthor>The RabbitMQ Team <<ulink url="mailto:info@rabbitmq.com"><email>info@rabbitmq.com</email></ulink>></corpauthor> - </authorgroup> - </refentryinfo> - - <refmeta> - <refentrytitle>rabbitmq-service.bat</refentrytitle> - <refmiscinfo class="manual">RabbitMQ Server</refmiscinfo> - </refmeta> - - <refnamediv> - <refname>rabbitmq-service.bat</refname> - <refpurpose>manage RabbitMQ AMQP service</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <cmdsynopsis> - <command>rabbitmq-service.bat</command> - <arg choice="opt">command</arg> - </cmdsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - <para> - RabbitMQ is an implementation of AMQP, the emerging standard for high -performance enterprise messaging. The RabbitMQ server is a robust and -scalable implementation of an AMQP broker. - </para> - <para> -Running <command>rabbitmq-service</command> allows the RabbitMQ broker to be run as a -service on NT/2000/2003/XP/Vista® environments. The RabbitMQ broker -service can be started and stopped using the Windows® services -applet. - </para> - <para> -By default the service will run in the authentication context of the -local system account. It is therefore necessary to synchronise Erlang -cookies between the local system account (typically -<filename>C:\WINDOWS\.erlang.cookie</filename> and the account that will be used to -run <command>rabbitmqctl</command>. - </para> - </refsect1> - - <refsect1> - <title>Commands</title> - <variablelist> - - <varlistentry> - <term>help</term> - <listitem> - <para> -Display usage information. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term>install</term> - <listitem> - <para> -Install the service. The service will not be started. -Subsequent invocations will update the service parameters if -relevant environment variables were modified. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term>remove</term> - <listitem> - <para> -Remove the service. If the service is running then it will -automatically be stopped before being removed. No files will be -deleted as a consequence and <command>rabbitmq-server</command> will remain operable. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term>start</term> - <listitem> - <para> -Start the service. The service must have been correctly installed -beforehand. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term>stop</term> - <listitem> - <para> -Stop the service. The service must be running for this command to -have any effect. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term>disable</term> - <listitem> - <para> -Disable the service. This is the equivalent of setting the startup -type to <code>Disabled</code> using the service control panel. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term>enable</term> - <listitem> - <para> -Enable the service. This is the equivalent of setting the startup -type to <code>Automatic</code> using the service control panel. - </para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> - <title>Environment</title> - <variablelist> - - <varlistentry> - <term>RABBITMQ_SERVICENAME</term> - <listitem> - <para> -Defaults to RabbitMQ. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term>RABBITMQ_BASE</term> - <listitem> - <para> -Defaults to the application data directory of the current user. -This is the location of log and database directories. - - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term>RABBITMQ_NODENAME</term> - <listitem> - <para> -Defaults to rabbit. This can be useful if you want to run more than -one node per machine - <envar>RABBITMQ_NODENAME</envar> should be unique per -erlang-node-and-machine combination. See the -<ulink url="http://www.rabbitmq.com/clustering.html#single-machine">clustering on a single -machine guide</ulink> for details. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term>RABBITMQ_NODE_IP_ADDRESS</term> - <listitem> - <para> -By default RabbitMQ will bind to all interfaces, on IPv4 and IPv6 if -available. Set this if you only want to bind to one network interface -or address family. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term>RABBITMQ_NODE_PORT</term> - <listitem> - <para> -Defaults to 5672. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term>ERLANG_SERVICE_MANAGER_PATH</term> - <listitem> - <para> -Defaults to <filename>C:\Program Files\erl5.5.5\erts-5.5.5\bin</filename> -(or <filename>C:\Program Files (x86)\erl5.5.5\erts-5.5.5\bin</filename> for 64-bit -environments). This is the installation location of the Erlang service -manager. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term>RABBITMQ_CONSOLE_LOG</term> - <listitem> - <para> -Set this varable to <code>new</code> or <code>reuse</code> to have the console -output from the server redirected to a file named <code>SERVICENAME</code>.debug -in the application data directory of the user that installed the service. -Under Vista this will be <filename>C:\Users\AppData\username\SERVICENAME</filename>. -Under previous versions of Windows this will be -<filename>C:\Documents and Settings\username\Application Data\SERVICENAME</filename>. -If <code>RABBITMQ_CONSOLE_LOG</code> is set to <code>new</code> then a new file will be -created each time the service starts. If <code>RABBITMQ_CONSOLE_LOG</code> is -set to <code>reuse</code> then the file will be overwritten each time the -service starts. The default behaviour when <code>RABBITMQ_CONSOLE_LOG</code> is -not set or set to a value other than <code>new</code> or <code>reuse</code> is to discard -the server output. - </para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> -</refentry> diff --git a/docs/rabbitmqctl.1.xml b/docs/rabbitmqctl.1.xml deleted file mode 100644 index b92e1f0229..0000000000 --- a/docs/rabbitmqctl.1.xml +++ /dev/null @@ -1,2338 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.docbook.org/xml/4.5/docbookx.dtd"> -<!-- - There is some extra magic in this document besides the usual DocBook semantics - to allow us to derive manpages, HTML and usage messages from the same source - document. - - Examples need to be moved to the end for man pages. To this end, <para>s and - <screen>s with role="example" will be moved, and with role="example-prefix" - will be removed. - - The usage messages are more involved. We have some magic in usage.xsl to pull - out the command synopsis, global option and subcommand synopses. We also pull - out <para>s with role="usage". - - Finally we construct lists of possible values for subcommand options, if the - subcommand's <varlistentry> has role="usage-has-option-list". The option which - takes the values should be marked with role="usage-option-list". ---> - -<refentry lang="en"> - <refentryinfo> - <productname>RabbitMQ Server</productname> - <authorgroup> - <corpauthor>The RabbitMQ Team <<ulink url="mailto:info@rabbitmq.com"><email>info@rabbitmq.com</email></ulink>></corpauthor> - </authorgroup> - </refentryinfo> - - <refmeta> - <refentrytitle>rabbitmqctl</refentrytitle> - <manvolnum>1</manvolnum> - <refmiscinfo class="manual">RabbitMQ Service</refmiscinfo> - </refmeta> - - <refnamediv> - <refname>rabbitmqctl</refname> - <refpurpose>command line tool for managing a RabbitMQ broker</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <cmdsynopsis> - <command>rabbitmqctl</command> - <arg choice="opt">-n <replaceable>node</replaceable></arg> - <arg choice="opt">-t <replaceable>timeout</replaceable></arg> - <arg choice="opt">-q</arg> - <arg choice="req"><replaceable>command</replaceable></arg> - <arg choice="opt" rep="repeat"><replaceable>command options</replaceable></arg> - </cmdsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - <para> - RabbitMQ is an implementation of AMQP, the emerging standard for high - performance enterprise messaging. The RabbitMQ server is a robust and - scalable implementation of an AMQP broker. - </para> - <para> - <command>rabbitmqctl</command> is a command line tool for managing a - RabbitMQ broker. It performs all actions by connecting to one of the - broker's nodes. - </para> - <para> - Diagnostic information is displayed if the broker was not - running, could not be reached, or rejected the connection due to - mismatching Erlang cookies. - </para> - </refsect1> - - <refsect1> - <title>Options</title> - <variablelist> - <varlistentry> - <term><cmdsynopsis><arg choice="opt">-n <replaceable>node</replaceable></arg></cmdsynopsis></term> - <listitem> - <para role="usage"> - Default node is "rabbit@server", where server is the local host. On - a host named "server.example.com", the node name of the RabbitMQ - Erlang node will usually be rabbit@server (unless RABBITMQ_NODENAME - has been set to some non-default value at broker startup time). The - output of <command>hostname -s</command> is usually the correct suffix to use after the - "@" sign. See rabbitmq-server(1) for details of configuring the - RabbitMQ broker. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term><cmdsynopsis><arg choice="opt">-q</arg></cmdsynopsis></term> - <listitem> - <para role="usage"> - Quiet output mode is selected with the "-q" flag. Informational - messages are suppressed when quiet mode is in effect. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term><cmdsynopsis><arg choice="opt">-t <replaceable>timeout</replaceable></arg></cmdsynopsis></term> - <listitem> - <para role="usage"> - Operation timeout in seconds. Only applicable to "list" commands. - Default is "infinity". - </para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> - <title>Commands</title> - - <refsect2> - <title>Application and Cluster Management</title> - - <variablelist> - <varlistentry> - <term><cmdsynopsis><command>stop</command> <arg choice="opt"><replaceable>pid_file</replaceable></arg></cmdsynopsis></term> - <listitem> - <para> - Stops the Erlang node on which RabbitMQ is running. To - restart the node follow the instructions for <citetitle>Running - the Server</citetitle> in the <ulink url="http://www.rabbitmq.com/install.html">installation - guide</ulink>. - </para> - <para> - If a <option>pid_file</option> is specified, also waits - for the process specified there to terminate. See the - description of the <option>wait</option> command below - for details on this file. - </para> - <para role="example-prefix">For example:</para> - <screen role="example">rabbitmqctl stop</screen> - <para role="example"> - This command instructs the RabbitMQ node to terminate. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><cmdsynopsis><command>shutdown</command></cmdsynopsis></term> - <listitem> - <para> - Shuts down the Erlang process on which RabbitMQ is running. The - command is blocking and will return after the Erlang process - exits. If RabbitMQ fails to stop, it will return a non-zero exit - code. - </para> - <para> - Unlike the stop command, the shutdown command: - * does not require a pid_file to wait for the Erlang process to exit - * if RabbitMQ node is not running, it will return a non-zero exit code - </para> - <para role="example-prefix">For example:</para> - <screen role="example">rabbitmqctl shutdown</screen> - <para role="example"> - This command shuts down the Erlang process on which RabbitMQ is running. - </para> - </listitem> - </varlistentry> - - <varlistentry id="stop_app"> - <term><cmdsynopsis><command>stop_app</command></cmdsynopsis></term> - <listitem> - <para> - Stops the RabbitMQ application, leaving the Erlang node - running. - </para> - <para> - This command is typically run prior to performing other - management actions that require the RabbitMQ application - to be stopped, e.g. <link - linkend="reset"><command>reset</command></link>. - </para> - <para role="example-prefix">For example:</para> - <screen role="example">rabbitmqctl stop_app</screen> - <para role="example"> - This command instructs the RabbitMQ node to stop the - RabbitMQ application. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><cmdsynopsis><command>start_app</command></cmdsynopsis></term> - <listitem> - <para> - Starts the RabbitMQ application. - </para> - <para> - This command is typically run after performing other - management actions that required the RabbitMQ application - to be stopped, e.g. <link - linkend="reset"><command>reset</command></link>. - </para> - <para role="example-prefix">For example:</para> - <screen role="example">rabbitmqctl start_app</screen> - <para role="example"> - This command instructs the RabbitMQ node to start the - RabbitMQ application. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><cmdsynopsis><command>wait</command> <arg choice="req"><replaceable>pid_file</replaceable></arg></cmdsynopsis></term> - <listitem> - <para> - Wait for the RabbitMQ application to start. - </para> - <para> - This command will wait for the RabbitMQ application to - start at the node. It will wait for the pid file to - be created, then for a process with a pid specified in the - pid file to start, and then for the RabbitMQ application - to start in that process. It will fail if the process - terminates without starting the RabbitMQ application. - </para> - <para> - A suitable pid file is created by - the <command>rabbitmq-server</command> script. By - default this is located in the Mnesia directory. Modify - the <command>RABBITMQ_PID_FILE</command> environment - variable to change the location. - </para> - <para role="example-prefix">For example:</para> - <screen role="example">rabbitmqctl wait /var/run/rabbitmq/pid</screen> - <para role="example"> - This command will return when the RabbitMQ node has - started up. - </para> - </listitem> - </varlistentry> - - <varlistentry id="reset"> - <term><cmdsynopsis><command>reset</command></cmdsynopsis></term> - <listitem> - <para> - Return a RabbitMQ node to its virgin state. - </para> - <para> - Removes the node from any cluster it belongs to, removes - all data from the management database, such as configured - users and vhosts, and deletes all persistent - messages. - </para> - <para> - For <command>reset</command> and <command>force_reset</command> to - succeed the RabbitMQ application must have been stopped, - e.g. with <link linkend="stop_app"><command>stop_app</command></link>. - </para> - <para role="example-prefix">For example:</para> - <screen role="example">rabbitmqctl reset</screen> - <para role="example"> - This command resets the RabbitMQ node. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><cmdsynopsis><command>force_reset</command></cmdsynopsis></term> - <listitem> - <para> - Forcefully return a RabbitMQ node to its virgin state. - </para> - <para> - The <command>force_reset</command> command differs from - <command>reset</command> in that it resets the node - unconditionally, regardless of the current management - database state and cluster configuration. It should only - be used as a last resort if the database or cluster - configuration has been corrupted. - </para> - <para> - For <command>reset</command> and <command>force_reset</command> to - succeed the RabbitMQ application must have been stopped, - e.g. with <link linkend="stop_app"><command>stop_app</command></link>. - </para> - <para role="example-prefix">For example:</para> - <screen role="example">rabbitmqctl force_reset</screen> - <para role="example"> - This command resets the RabbitMQ node. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><cmdsynopsis><command>rotate_logs</command></cmdsynopsis></term> - <listitem> - <para> - Instruct the RabbitMQ node to perform internal log rotation. - </para> - <para> - Log rotation is performed according to lager settings - specified in configuration file. - </para> - <para> - Note that there is no need to call this command in case of - external log rotation (e.g. from logrotate), because lager - detects renames and automatically reopens log files. - </para> - <para role="example-prefix">For example:</para> - <screen role="example">rabbitmqctl rotate_logs</screen> - <para role="example"> - This command starts internal log rotation - process. Rotation is performed asynchronously, so there is - no guarantee that it will be completed when this command - returns. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><cmdsynopsis><command>hipe_compile</command> <arg choice="req"><replaceable>directory</replaceable></arg></cmdsynopsis></term> - <listitem> - <para> - Performs HiPE-compilation and caches resulting - .beam-files in the given directory. - </para> - <para> - Parent directories are created if necessary. Any - existing <command>.beam</command> files from the - directory are automatically deleted prior to - compilation. - </para> - <para> - To use this precompiled files, you should set - <command>RABBITMQ_SERVER_CODE_PATH</command> environment - variable to directory specified in - <command>hipe_compile</command> invokation. - </para> - <para role="example-prefix">For example:</para> - <screen role="example">rabbitmqctl hipe_compile /tmp/rabbit-hipe/ebin</screen> - <para role="example"> - HiPE-compiles modules and stores them to /tmp/rabbit-hipe/ebin directory. - </para> - </listitem> - </varlistentry> - </variablelist> - </refsect2> - - <refsect2> - <title>Cluster management</title> - - <variablelist> - <varlistentry id="join_cluster"> - <term><cmdsynopsis><command>join_cluster</command> <arg choice="req"><replaceable>clusternode</replaceable></arg> <arg choice="opt">--ram</arg></cmdsynopsis></term> - <listitem> - <variablelist> - <varlistentry> - <term>clusternode</term> - <listitem><para>Node to cluster with.</para></listitem> - </varlistentry> - <varlistentry> - <term><cmdsynopsis><arg choice="opt">--ram</arg></cmdsynopsis></term> - <listitem> - <para> - If provided, the node will join the cluster as a RAM node. - </para> - </listitem> - </varlistentry> - </variablelist> - <para> - Instruct the node to become a member of the cluster that the - specified node is in. Before clustering, the node is reset, so be - careful when using this command. For this command to succeed the - RabbitMQ application must have been stopped, e.g. with <link - linkend="stop_app"><command>stop_app</command></link>. - </para> - <para> - Cluster nodes can be of two types: disc or RAM. Disc nodes - replicate data in RAM and on disc, thus providing redundancy in - the event of node failure and recovery from global events such - as power failure across all nodes. RAM nodes replicate data in - RAM only (with the exception of queue contents, which can reside - on disc if the queue is persistent or too big to fit in memory) - and are mainly used for scalability. RAM nodes are more - performant only when managing resources (e.g. adding/removing - queues, exchanges, or bindings). A cluster must always have at - least one disc node, and usually should have more than one. - </para> - <para> - The node will be a disc node by default. If you wish to - create a RAM node, provide the <command>--ram</command> flag. - </para> - <para> - After executing the <command>cluster</command> command, whenever - the RabbitMQ application is started on the current node it will - attempt to connect to the nodes that were in the cluster when the - node went down. - </para> - <para> - To leave a cluster, <command>reset</command> the node. You can - also remove nodes remotely with the - <command>forget_cluster_node</command> command. - </para> - <para> - For more details see the <ulink - url="http://www.rabbitmq.com/clustering.html">clustering - guide</ulink>. - </para> - <para role="example-prefix">For example:</para> - <screen role="example">rabbitmqctl join_cluster hare@elena --ram</screen> - <para role="example"> - This command instructs the RabbitMQ node to join the cluster that - <command>hare@elena</command> is part of, as a ram node. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term><cmdsynopsis><command>cluster_status</command></cmdsynopsis></term> - <listitem> - <para> - Displays all the nodes in the cluster grouped by node type, - together with the currently running nodes. - </para> - <para role="example-prefix">For example:</para> - <screen role="example">rabbitmqctl cluster_status</screen> - <para role="example"> - This command displays the nodes in the cluster. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term><cmdsynopsis><command>change_cluster_node_type</command> <arg choice="req">disc | ram</arg></cmdsynopsis> - </term> - <listitem> - <para> - Changes the type of the cluster node. The node must be stopped for - this operation to succeed, and when turning a node into a RAM node - the node must not be the only disc node in the cluster. - </para> - <para role="example-prefix">For example:</para> - <screen role="example">rabbitmqctl change_cluster_node_type disc</screen> - <para role="example"> - This command will turn a RAM node into a disc node. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term><cmdsynopsis><command>forget_cluster_node</command> <arg choice="opt">--offline</arg></cmdsynopsis></term> - <listitem> - <variablelist> - <varlistentry> - <term><cmdsynopsis><arg choice="opt">--offline</arg></cmdsynopsis></term> - <listitem> - <para> - Enables node removal from an offline node. This is only - useful in the situation where all the nodes are offline and - the last node to go down cannot be brought online, thus - preventing the whole cluster from starting. It should not be - used in any other circumstances since it can lead to - inconsistencies. - </para> - </listitem> - </varlistentry> - </variablelist> - <para> - Removes a cluster node remotely. The node that is being removed - must be offline, while the node we are removing from must be - online, except when using the <command>--offline</command> flag. - </para> - <para> - When using the <command>--offline</command> flag - rabbitmqctl will not attempt to connect to a node as - normal; instead it will temporarily become the node in - order to make the change. This is useful if the node - cannot be started normally. In this case the node will - become the canonical source for cluster metadata - (e.g. which queues exist), even if it was not - before. Therefore you should use this command on the - latest node to shut down if at all possible. - </para> - <para role="example-prefix">For example:</para> - <screen role="example">rabbitmqctl -n hare@mcnulty forget_cluster_node rabbit@stringer</screen> - <para role="example"> - This command will remove the node - <command>rabbit@stringer</command> from the node - <command>hare@mcnulty</command>. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term><cmdsynopsis><command>rename_cluster_node</command> <arg choice="req">oldnode1</arg> <arg choice="req">newnode1</arg> <arg choice="opt">oldnode2</arg> <arg choice="opt">newnode2 ...</arg></cmdsynopsis></term> - <listitem> - <para> - Supports renaming of cluster nodes in the local database. - </para> - <para> - This subcommand causes rabbitmqctl to temporarily become - the node in order to make the change. The local cluster - node must therefore be completely stopped; other nodes - can be online or offline. - </para> - <para> - This subcommand takes an even number of arguments, in - pairs representing the old and new names for nodes. You - must specify the old and new names for this node and for - any other nodes that are stopped and being renamed at - the same time. - </para> - <para> - It is possible to stop all nodes and rename them all - simultaneously (in which case old and new names for all - nodes must be given to every node) or stop and rename - nodes one at a time (in which case each node only needs - to be told how its own name is changing). - </para> - <para role="example-prefix">For example:</para> - <screen role="example">rabbitmqctl rename_cluster_node rabbit@misshelpful rabbit@cordelia</screen> - <para role="example"> - This command will rename the node - <command>rabbit@misshelpful</command> to the node - <command>rabbit@cordelia</command>. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term><cmdsynopsis><command>update_cluster_nodes</command> <arg choice="req">clusternode</arg></cmdsynopsis> - </term> - <listitem> - <variablelist> - <varlistentry> - <term>clusternode</term> - <listitem> - <para> - The node to consult for up to date information. - </para> - </listitem> - </varlistentry> - </variablelist> - <para> - Instructs an already clustered node to contact - <command>clusternode</command> to cluster when waking up. This is - different from <command>join_cluster</command> since it does not - join any cluster - it checks that the node is already in a cluster - with <command>clusternode</command>. - </para> - <para> - The need for this command is motivated by the fact that clusters - can change while a node is offline. Consider the situation in - which node A and B are clustered. A goes down, C clusters with B, - and then B leaves the cluster. When A wakes up, it'll try to - contact B, but this will fail since B is not in the cluster - anymore. <command>update_cluster_nodes -n A C</command> will solve - this situation. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term><cmdsynopsis><command>force_boot</command></cmdsynopsis></term> - <listitem> - <para> - Ensure that the node will start next time, even if it - was not the last to shut down. - </para> - <para> - Normally when you shut down a RabbitMQ cluster - altogether, the first node you restart should be the - last one to go down, since it may have seen things - happen that other nodes did not. But sometimes - that's not possible: for instance if the entire cluster - loses power then all nodes may think they were not the - last to shut down. - </para> - <para> - In such a case you can invoke <command>rabbitmqctl - force_boot</command> while the node is down. This will - tell the node to unconditionally start next time you ask - it to. If any changes happened to the cluster after this - node shut down, they will be lost. - </para> - <para> - If the last node to go down is permanently lost then you - should use <command>rabbitmqctl forget_cluster_node - --offline</command> in preference to this command, as it - will ensure that mirrored queues which were mastered on - the lost node get promoted. - </para> - <para role="example-prefix">For example:</para> - <screen role="example">rabbitmqctl force_boot</screen> - <para role="example"> - This will force the node not to wait for other nodes - next time it is started. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term><cmdsynopsis><command>sync_queue</command> <arg choice="opt">-p <replaceable>vhost</replaceable></arg> <arg choice="req">queue</arg></cmdsynopsis> - </term> - <listitem> - <variablelist> - <varlistentry> - <term>queue</term> - <listitem> - <para> - The name of the queue to synchronise. - </para> - </listitem> - </varlistentry> - </variablelist> - <para> - Instructs a mirrored queue with unsynchronised slaves to - synchronise itself. The queue will block while - synchronisation takes place (all publishers to and - consumers from the queue will block). The queue must be - mirrored for this command to succeed. - </para> - <para> - Note that unsynchronised queues from which messages are - being drained will become synchronised eventually. This - command is primarily useful for queues which are not - being drained. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term><cmdsynopsis><command>cancel_sync_queue</command> <arg choice="opt">-p <replaceable>vhost</replaceable></arg> <arg choice="req">queue</arg></cmdsynopsis> - </term> - <listitem> - <variablelist> - <varlistentry> - <term>queue</term> - <listitem> - <para> - The name of the queue to cancel synchronisation for. - </para> - </listitem> - </varlistentry> - </variablelist> - <para> - Instructs a synchronising mirrored queue to stop - synchronising itself. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term><cmdsynopsis><command>purge_queue</command> <arg choice="opt">-p <replaceable>vhost</replaceable></arg> <arg choice="req">queue</arg></cmdsynopsis> - </term> - <listitem> - <variablelist> - <varlistentry> - <term>queue</term> - <listitem> - <para> - The name of the queue to purge. - </para> - </listitem> - </varlistentry> - </variablelist> - <para> - Purges a queue (removes all messages in it). - </para> - </listitem> - </varlistentry> - <varlistentry> - <term><cmdsynopsis><command>set_cluster_name</command> <arg choice="req">name</arg></cmdsynopsis></term> - <listitem> - <para> - Sets the cluster name. The cluster name is announced to - clients on connection, and used by the federation and - shovel plugins to record where a message has been. The - cluster name is by default derived from the hostname of - the first node in the cluster, but can be changed. - </para> - <para role="example-prefix">For example:</para> - <screen role="example">rabbitmqctl set_cluster_name london</screen> - <para role="example"> - This sets the cluster name to "london". - </para> - </listitem> - </varlistentry> - </variablelist> - </refsect2> - - <refsect2> - <title>User management</title> - <para> - Note that <command>rabbitmqctl</command> manages the RabbitMQ - internal user database. Users from any alternative - authentication backend will not be visible - to <command>rabbitmqctl</command>. - </para> - <variablelist> - <varlistentry> - <term><cmdsynopsis><command>add_user</command> <arg choice="req"><replaceable>username</replaceable></arg> <arg choice="req"><replaceable>password</replaceable></arg></cmdsynopsis></term> - <listitem> - <variablelist> - <varlistentry> - <term>username</term> - <listitem><para>The name of the user to create.</para></listitem> - </varlistentry> - <varlistentry> - <term>password</term> - <listitem><para>The password the created user will use to log in to the broker.</para></listitem> - </varlistentry> - </variablelist> - <para role="example-prefix">For example:</para> - <screen role="example">rabbitmqctl add_user tonyg changeit</screen> - <para role="example"> - This command instructs the RabbitMQ broker to create a - (non-administrative) user named <command>tonyg</command> with - (initial) password - <command>changeit</command>. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><cmdsynopsis><command>delete_user</command> <arg choice="req"><replaceable>username</replaceable></arg></cmdsynopsis></term> - <listitem> - <variablelist> - <varlistentry> - <term>username</term> - <listitem><para>The name of the user to delete.</para></listitem> - </varlistentry> - </variablelist> - <para role="example-prefix">For example:</para> - <screen role="example">rabbitmqctl delete_user tonyg</screen> - <para role="example"> - This command instructs the RabbitMQ broker to delete the - user named <command>tonyg</command>. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><cmdsynopsis><command>change_password</command> <arg choice="req"><replaceable>username</replaceable></arg> <arg choice="req"><replaceable>newpassword</replaceable></arg></cmdsynopsis></term> - <listitem> - <variablelist> - <varlistentry> - <term>username</term> - <listitem><para>The name of the user whose password is to be changed.</para></listitem> - </varlistentry> - <varlistentry> - <term>newpassword</term> - <listitem><para>The new password for the user.</para></listitem> - </varlistentry> - </variablelist> - <para role="example-prefix">For example:</para> - <screen role="example">rabbitmqctl change_password tonyg newpass</screen> - <para role="example"> - This command instructs the RabbitMQ broker to change the - password for the user named <command>tonyg</command> to - <command>newpass</command>. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><cmdsynopsis><command>clear_password</command> <arg choice="req"><replaceable>username</replaceable></arg></cmdsynopsis></term> - <listitem> - <variablelist> - <varlistentry> - <term>username</term> - <listitem><para>The name of the user whose password is to be cleared.</para></listitem> - </varlistentry> - </variablelist> - <para role="example-prefix">For example:</para> - <screen role="example">rabbitmqctl clear_password tonyg</screen> - <para role="example"> - This command instructs the RabbitMQ broker to clear the - password for the user named - <command>tonyg</command>. This user now cannot log in with a password (but may be able to through e.g. SASL EXTERNAL if configured). - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <cmdsynopsis><command>authenticate_user</command> <arg choice="req"><replaceable>username</replaceable></arg> <arg choice="req"><replaceable>password</replaceable></arg></cmdsynopsis> - </term> - <listitem> - <variablelist> - <varlistentry> - <term>username</term> - <listitem><para>The name of the user.</para></listitem> - </varlistentry> - <varlistentry> - <term>password</term> - <listitem><para>The password of the user.</para></listitem> - </varlistentry> - </variablelist> - <para role="example-prefix">For example:</para> - <screen role="example">rabbitmqctl authenticate_user tonyg verifyit</screen> - <para role="example"> - This command instructs the RabbitMQ broker to authenticate the - user named <command>tonyg</command> with password - <command>verifyit</command>. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><cmdsynopsis><command>set_user_tags</command> <arg choice="req"><replaceable>username</replaceable></arg> <arg choice="req"><replaceable>tag</replaceable> ...</arg></cmdsynopsis></term> - <listitem> - <variablelist> - <varlistentry> - <term>username</term> - <listitem><para>The name of the user whose tags are to - be set.</para></listitem> - </varlistentry> - <varlistentry> - <term>tag</term> - <listitem><para>Zero, one or more tags to set. Any - existing tags will be removed.</para></listitem> - </varlistentry> - </variablelist> - <para role="example-prefix">For example:</para> - <screen role="example">rabbitmqctl set_user_tags tonyg administrator</screen> - <para role="example"> - This command instructs the RabbitMQ broker to ensure the user - named <command>tonyg</command> is an administrator. This has no - effect when the user logs in via AMQP, but can be used to permit - the user to manage users, virtual hosts and permissions when the - user logs in via some other means (for example with the - management plugin). - </para> - <screen role="example">rabbitmqctl set_user_tags tonyg</screen> - <para role="example"> - This command instructs the RabbitMQ broker to remove any - tags from the user named <command>tonyg</command>. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><cmdsynopsis><command>list_users</command></cmdsynopsis></term> - <listitem> - <para> - Lists users. Each result row will contain the user name - followed by a list of the tags set for that user. - </para> - <para role="example-prefix">For example:</para> - <screen role="example">rabbitmqctl list_users</screen> - <para role="example"> - This command instructs the RabbitMQ broker to list all - users. - </para> - </listitem> - </varlistentry> - </variablelist> - </refsect2> - - <refsect2> - <title>Access control</title> - <para> - Note that <command>rabbitmqctl</command> manages the RabbitMQ - internal user database. Permissions for users from any - alternative authorisation backend will not be visible - to <command>rabbitmqctl</command>. - </para> - <variablelist> - <varlistentry> - <term><cmdsynopsis><command>add_vhost</command> <arg choice="req"><replaceable>vhost</replaceable></arg></cmdsynopsis></term> - <listitem> - <variablelist> - <varlistentry> - <term>vhost</term> - <listitem><para>The name of the virtual host entry to create.</para></listitem> - </varlistentry> - </variablelist> - <para> - Creates a virtual host. - </para> - <para role="example-prefix">For example:</para> - <screen role="example">rabbitmqctl add_vhost test</screen> - <para role="example"> - This command instructs the RabbitMQ broker to create a new - virtual host called <command>test</command>. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><cmdsynopsis><command>delete_vhost</command> <arg choice="req"><replaceable>vhost</replaceable></arg></cmdsynopsis></term> - <listitem> - <variablelist> - <varlistentry> - <term>vhost</term> - <listitem><para>The name of the virtual host entry to delete.</para></listitem> - </varlistentry> - </variablelist> - <para> - Deletes a virtual host. - </para> - <para> - Deleting a virtual host deletes all its exchanges, - queues, bindings, user permissions, parameters and policies. - </para> - <para role="example-prefix">For example:</para> - <screen role="example">rabbitmqctl delete_vhost test</screen> - <para role="example"> - This command instructs the RabbitMQ broker to delete the - virtual host called <command>test</command>. - </para> - </listitem> - </varlistentry> - - <varlistentry role="usage-has-option-list"> - <term><cmdsynopsis><command>list_vhosts</command> <arg choice="opt" role="usage-option-list"><replaceable>vhostinfoitem</replaceable> ...</arg></cmdsynopsis></term> - <listitem> - <para> - Lists virtual hosts. - </para> - <para> - The <command>vhostinfoitem</command> parameter is used to indicate which - virtual host information items to include in the results. The column order in the - results will match the order of the parameters. - <command>vhostinfoitem</command> can take any value from - the list that follows: - </para> - <variablelist> - <varlistentry> - <term>name</term> - <listitem><para>The name of the virtual host with non-ASCII characters escaped as in C.</para></listitem> - </varlistentry> - <varlistentry> - <term>tracing</term> - <listitem><para>Whether tracing is enabled for this virtual host.</para></listitem> - </varlistentry> - </variablelist> - <para> - If no <command>vhostinfoitem</command>s are specified - then the vhost name is displayed. - </para> - <para role="example-prefix">For example:</para> - <screen role="example">rabbitmqctl list_vhosts name tracing</screen> - <para role="example"> - This command instructs the RabbitMQ broker to list all - virtual hosts. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><cmdsynopsis><command>set_permissions</command> <arg choice="opt">-p <replaceable>vhost</replaceable></arg> <arg choice="req"><replaceable>user</replaceable></arg> <arg choice="req"><replaceable>conf</replaceable></arg> <arg choice="req"><replaceable>write</replaceable></arg> <arg choice="req"><replaceable>read</replaceable></arg></cmdsynopsis></term> - <listitem> - <variablelist> - <varlistentry> - <term>vhost</term> - <listitem><para>The name of the virtual host to which to grant the user access, defaulting to <command>/</command>.</para></listitem> - </varlistentry> - <varlistentry> - <term>user</term> - <listitem><para>The name of the user to grant access to the specified virtual host.</para></listitem> - </varlistentry> - <varlistentry> - <term>conf</term> - <listitem><para>A regular expression matching resource names for which the user is granted configure permissions.</para></listitem> - </varlistentry> - <varlistentry> - <term>write</term> - <listitem><para>A regular expression matching resource names for which the user is granted write permissions.</para></listitem> - </varlistentry> - <varlistentry> - <term>read</term> - <listitem><para>A regular expression matching resource names for which the user is granted read permissions.</para></listitem> - </varlistentry> - </variablelist> - <para> - Sets user permissions. - </para> - <para role="example-prefix">For example:</para> - <screen role="example">rabbitmqctl set_permissions -p /myvhost tonyg "^tonyg-.*" ".*" ".*"</screen> - <para role="example"> - This command instructs the RabbitMQ broker to grant the - user named <command>tonyg</command> access to the virtual host - called <command>/myvhost</command>, with configure permissions - on all resources whose names starts with "tonyg-", and - write and read permissions on all resources. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><cmdsynopsis><command>clear_permissions</command> <arg choice="opt">-p <replaceable>vhost</replaceable></arg> <arg choice="req"><replaceable>username</replaceable></arg></cmdsynopsis></term> - <listitem> - <variablelist> - <varlistentry> - <term>vhost</term> - <listitem><para>The name of the virtual host to which to deny the user access, defaulting to <command>/</command>.</para></listitem> - </varlistentry> - <varlistentry> - <term>username</term> - <listitem><para>The name of the user to deny access to the specified virtual host.</para></listitem> - </varlistentry> - </variablelist> - <para> - Sets user permissions. - </para> - <para role="example-prefix">For example:</para> - <screen role="example">rabbitmqctl clear_permissions -p /myvhost tonyg</screen> - <para role="example"> - This command instructs the RabbitMQ broker to deny the - user named <command>tonyg</command> access to the virtual host - called <command>/myvhost</command>. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><cmdsynopsis><command>list_permissions</command> <arg choice="opt">-p <replaceable>vhost</replaceable></arg></cmdsynopsis></term> - <listitem> - <variablelist> - <varlistentry> - <term>vhost</term> - <listitem><para>The name of the virtual host for which to list the users that have been granted access to it, and their permissions. Defaults to <command>/</command>.</para></listitem> - </varlistentry> - </variablelist> - <para> - Lists permissions in a virtual host. - </para> - <para role="example-prefix">For example:</para> - <screen role="example">rabbitmqctl list_permissions -p /myvhost</screen> - <para role="example"> - This command instructs the RabbitMQ broker to list all - the users which have been granted access to the virtual - host called <command>/myvhost</command>, and the - permissions they have for operations on resources in - that virtual host. Note that an empty string means no - permissions granted. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><cmdsynopsis><command>list_user_permissions</command> <arg choice="req"><replaceable>username</replaceable></arg></cmdsynopsis></term> - <listitem> - <variablelist> - <varlistentry> - <term>username</term> - <listitem><para>The name of the user for which to list the permissions.</para></listitem> - </varlistentry> - </variablelist> - <para> - Lists user permissions. - </para> - <para role="example-prefix">For example:</para> - <screen role="example">rabbitmqctl list_user_permissions tonyg</screen> - <para role="example"> - This command instructs the RabbitMQ broker to list all the - virtual hosts to which the user named <command>tonyg</command> - has been granted access, and the permissions the user has - for operations on resources in these virtual hosts. - </para> - </listitem> - </varlistentry> - </variablelist> - </refsect2> - - <refsect2> - <title>Parameter Management</title> - <para> - Certain features of RabbitMQ (such as the federation plugin) - are controlled by dynamic, - cluster-wide <emphasis>parameters</emphasis>. - There are 2 kinds of parameters: parameters scoped to - a virtual host and global parameters. - Each vhost-scoped parameter - consists of a component name, a name and a value. - The component name and name are - strings, and the value is an Erlang term. - A global parameter consists of a name and value. The name - is a string and the value is an Erlang term. - Parameters can be set, cleared and listed. In general you should refer to the - documentation for the feature in question to see how to set - parameters. - </para> - <variablelist> - <varlistentry> - <term><cmdsynopsis><command>set_parameter</command> <arg choice="opt">-p <replaceable>vhost</replaceable></arg> <arg choice="req"><replaceable>component_name</replaceable></arg> <arg choice="req"><replaceable>name</replaceable></arg> <arg choice="req"><replaceable>value</replaceable></arg></cmdsynopsis></term> - <listitem> - <para> - Sets a parameter. - </para> - <variablelist> - <varlistentry> - <term>component_name</term> - <listitem><para> - The name of the component for which the - parameter is being set. - </para></listitem> - </varlistentry> - <varlistentry> - <term>name</term> - <listitem><para> - The name of the parameter being set. - </para></listitem> - </varlistentry> - <varlistentry> - <term>value</term> - <listitem><para> - The value for the parameter, as a - JSON term. In most shells you are very likely to - need to quote this. - </para></listitem> - </varlistentry> - </variablelist> - <para role="example-prefix">For example:</para> - <screen role="example">rabbitmqctl set_parameter federation local_username '"guest"'</screen> - <para role="example"> - This command sets the parameter <command>local_username</command> for the <command>federation</command> component in the default virtual host to the JSON term <command>"guest"</command>. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term><cmdsynopsis><command>clear_parameter</command> <arg choice="opt">-p <replaceable>vhost</replaceable></arg> <arg choice="req"><replaceable>component_name</replaceable></arg> <arg choice="req"><replaceable>key</replaceable></arg></cmdsynopsis></term> - <listitem> - <para> - Clears a parameter. - </para> - <variablelist> - <varlistentry> - <term>component_name</term> - <listitem><para> - The name of the component for which the - parameter is being cleared. - </para></listitem> - </varlistentry> - <varlistentry> - <term>name</term> - <listitem><para> - The name of the parameter being cleared. - </para></listitem> - </varlistentry> - </variablelist> - <para role="example-prefix">For example:</para> - <screen role="example">rabbitmqctl clear_parameter federation local_username</screen> - <para role="example"> - This command clears the parameter <command>local_username</command> for the <command>federation</command> component in the default virtual host. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term><cmdsynopsis><command>list_parameters</command> <arg choice="opt">-p <replaceable>vhost</replaceable></arg></cmdsynopsis></term> - <listitem> - <para> - Lists all parameters for a virtual host. - </para> - <para role="example-prefix">For example:</para> - <screen role="example">rabbitmqctl list_parameters</screen> - <para role="example"> - This command lists all parameters in the default virtual host. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term><cmdsynopsis><command>set_global_parameter</command> <arg choice="req"><replaceable>name</replaceable></arg> <arg choice="req"><replaceable>value</replaceable></arg></cmdsynopsis></term> - <listitem> - <para> - Sets a global runtime parameter. This is similar to <command>set_parameter</command> - but the key-value pair isn't tied to a virtual host. - </para> - <variablelist> - <varlistentry> - <term>name</term> - <listitem><para> - The name of the global runtime parameter being set. - </para></listitem> - </varlistentry> - <varlistentry> - <term>value</term> - <listitem><para> - The value for the global runtime parameter, as a - JSON term. In most shells you are very likely to - need to quote this. - </para></listitem> - </varlistentry> - </variablelist> - <para role="example-prefix">For example:</para> - <screen role="example">rabbitmqctl set_global_parameter mqtt_default_vhosts '{"O=client,CN=guest":"/"}'</screen> - <para role="example"> - This command sets the global runtime parameter <command>mqtt_default_vhosts</command> to the JSON term <command>{"O=client,CN=guest":"/"}</command>. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term><cmdsynopsis><command>clear_global_parameter</command> <arg choice="req"><replaceable>name</replaceable></arg></cmdsynopsis></term> - <listitem> - <para> - Clears a global runtime parameter. This is similar to <command>clear_global_parameter</command> - but the key-value pair isn't tied to a virtual host. - </para> - <variablelist> - <varlistentry> - <term>name</term> - <listitem><para> - The name of the global runtime parameter being cleared. - </para></listitem> - </varlistentry> - </variablelist> - <para role="example-prefix">For example:</para> - <screen role="example">rabbitmqctl clear_global_parameter mqtt_default_vhosts</screen> - <para role="example"> - This command clears the global runtime parameter <command>mqtt_default_vhosts</command>. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term><cmdsynopsis><command>list_global_parameters</command></cmdsynopsis></term> - <listitem> - <para> - Lists all global runtime parameters. This is similar to <command>list_parameters</command> - but the global runtime parameters are not tied to any virtual host. - </para> - <para role="example-prefix">For example:</para> - <screen role="example">rabbitmqctl list_global_parameters</screen> - <para role="example"> - This command lists all global parameters. - </para> - </listitem> - </varlistentry> - </variablelist> - </refsect2> - - <refsect2> - <title>Policy Management</title> - <para> - Policies are used to control and modify the behaviour of queues - and exchanges on a cluster-wide basis. Policies apply within a - given vhost, and consist of a name, pattern, definition and an - optional priority. Policies can be set, cleared and listed. - </para> - <variablelist> - <varlistentry> - <term><cmdsynopsis><command>set_policy</command> <arg choice="opt">-p <replaceable>vhost</replaceable></arg> <arg choice="opt">--priority <replaceable>priority</replaceable></arg> <arg choice="opt">--apply-to <replaceable>apply-to</replaceable></arg> <arg choice="req"><replaceable>name</replaceable></arg> <arg choice="req"><replaceable>pattern</replaceable></arg> <arg choice="req"><replaceable>definition</replaceable></arg></cmdsynopsis></term> - <listitem> - <para> - Sets a policy. - </para> - <variablelist> - <varlistentry> - <term>name</term> - <listitem><para> - The name of the policy. - </para></listitem> - </varlistentry> - <varlistentry> - <term>pattern</term> - <listitem><para> - The regular expression, which when matches on a given resources causes the policy to apply. - </para></listitem> - </varlistentry> - <varlistentry> - <term>definition</term> - <listitem><para> - The definition of the policy, as a - JSON term. In most shells you are very likely to - need to quote this. - </para></listitem> - </varlistentry> - <varlistentry> - <term>priority</term> - <listitem><para> - The priority of the policy as an integer. Higher numbers indicate greater precedence. The default is 0. - </para></listitem> - </varlistentry> - <varlistentry> - <term>apply-to</term> - <listitem><para> - Which types of object this policy should apply to - "queues", "exchanges" or "all". The default is "all". - </para></listitem> - </varlistentry> - </variablelist> - <para role="example-prefix">For example:</para> - <screen role="example">rabbitmqctl set_policy federate-me "^amq." '{"federation-upstream-set":"all"}'</screen> - <para role="example"> - This command sets the policy <command>federate-me</command> in the default virtual host so that built-in exchanges are federated. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term><cmdsynopsis><command>clear_policy</command> <arg choice="opt">-p <replaceable>vhost</replaceable></arg> <arg choice="req"><replaceable>name</replaceable></arg></cmdsynopsis></term> - <listitem> - <para> - Clears a policy. - </para> - <variablelist> - <varlistentry> - <term>name</term> - <listitem><para> - The name of the policy being cleared. - </para></listitem> - </varlistentry> - </variablelist> - <para role="example-prefix">For example:</para> - <screen role="example">rabbitmqctl clear_policy federate-me</screen> - <para role="example"> - This command clears the <command>federate-me</command> policy in the default virtual host. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term><cmdsynopsis><command>list_policies</command> <arg choice="opt">-p <replaceable>vhost</replaceable></arg></cmdsynopsis></term> - <listitem> - <para> - Lists all policies for a virtual host. - </para> - <para role="example-prefix">For example:</para> - <screen role="example">rabbitmqctl list_policies</screen> - <para role="example"> - This command lists all policies in the default virtual host. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term><cmdsynopsis><command>set_operator_policy</command> <arg choice="opt">-p <replaceable>vhost</replaceable></arg> <arg choice="opt">--priority <replaceable>priority</replaceable></arg> <arg choice="opt">--apply-to <replaceable>apply-to</replaceable></arg> <arg choice="req"><replaceable>name</replaceable></arg> <arg choice="req"><replaceable>pattern</replaceable></arg> <arg choice="req"><replaceable>definition</replaceable></arg></cmdsynopsis></term> - <listitem> - <para> - Sets an operator policy that overrides a subset of arguments in user policies. Arguments are identical to those of <command>set_policy</command>. - Supported arguments: <command>expires</command>, <command>message-ttl</command>, <command>max-length</command>, and <command>max-length-bytes</command>. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term><cmdsynopsis><command>clear_operator_policy</command> <arg choice="opt">-p <replaceable>vhost</replaceable></arg> <arg choice="req"><replaceable>name</replaceable></arg></cmdsynopsis></term> - <listitem> - <para> - Clears an operator policy. Arguments are identical to those of <command>clear_policy</command>. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term><cmdsynopsis><command>list_operator_policies</command> <arg choice="opt">-p <replaceable>vhost</replaceable></arg></cmdsynopsis></term> - <listitem> - <para> - Lists operator policy overrides for a virtual host. Arguments are identical to those of <command>list_policies</command>. - </para> - </listitem> - </varlistentry> - </variablelist> - </refsect2> - - <refsect2> - <title>Virtual Host Limits</title> - <para> - It is possible to enforce certain limits on virtual hosts. - </para> - <variablelist> - <varlistentry> - <term><cmdsynopsis><command>set_vhost_limits</command> <arg choice="opt">-p <replaceable>vhostpath</replaceable></arg> <arg choice="req"><replaceable>definition</replaceable></arg></cmdsynopsis></term> - <listitem> - <para> - Sets virtual host limits - </para> - <variablelist> - <varlistentry> - <term>definition</term> - <listitem><para> - The definition of the limits, as a - JSON term. In most shells you are very likely to - need to quote this. - - Recognised limits: max-connections, max-queues. Use a negative value to specify "no limit". - </para></listitem> - </varlistentry> - </variablelist> - <para role="example-prefix">For example:</para> - <screen role="example">rabbitmqctl set_vhost_limits -p qa_env '{"max-connections": 64}'</screen> - <para role="example"> - This command limits the max number of concurrent connections in vhost <command>qa_env</command> - to 64. - </para> - <screen role="example">rabbitmqctl set_vhost_limits -p qa_env '{"max-queues": 256}'</screen> - <para role="example"> - This command limits the max number of queues in vhost <command>qa_env</command> - to 256. - </para> - <screen role="example">rabbitmqctl set_vhost_limits -p qa_env '{"max-connections": -1}'</screen> - <para role="example"> - This command clears the max number of connections limit in vhost <command>qa_env</command>. - </para> - <screen role="example">rabbitmqctl set_vhost_limits -p qa_env '{"max-connections": 0}'</screen> - <para role="example"> - This command disables client connections in vhost <command>qa_env</command>. - </para> - </listitem> - </varlistentry> - -<varlistentry> - <term><cmdsynopsis><command>clear_vhost_limits</command> <arg choice="opt">-p <replaceable>vhostpath</replaceable></arg></cmdsynopsis></term> - <listitem> - <para> - Clears virtual host limits - </para> - <para role="example-prefix">For example:</para> - <screen role="example">rabbitmqctl clear_vhost_limits -p qa_env</screen> - <para role="example"> - This command clears vhost limits in vhost <command>qa_env</command>. - </para> - </listitem> - </varlistentry> - </variablelist> - </refsect2> - - <refsect2> - <title>Server Status</title> - <para> - The server status queries interrogate the server and return a list of - results with tab-delimited columns. Some queries (<command>list_queues</command>, - <command>list_exchanges</command>, <command>list_bindings</command>, and - <command>list_consumers</command>) accept an - optional <command>vhost</command> parameter. This parameter, if present, must be - specified immediately after the query. - </para> - <para role="usage"> - The list_queues, list_exchanges and list_bindings commands accept an - optional virtual host parameter for which to display results. The - default value is "/". - </para> - - <variablelist> - <varlistentry role="usage-has-option-list"> - <term> - <cmdsynopsis><command>list_queues</command> <arg choice="opt">-p <replaceable>vhost</replaceable></arg> <group choice="opt"><arg>--offline</arg><arg>--online</arg><arg>--local</arg></group> <arg choice="opt" role="usage-option-list"><replaceable>queueinfoitem</replaceable> ...</arg></cmdsynopsis> - </term> - <listitem> - <para> - Returns queue details. Queue details of the <command>/</command> virtual host - are returned if the "-p" flag is absent. The "-p" flag can be used to - override this default. - </para> - <para> - Displayed queues can be filtered by their status or - location using one of the following mutually exclusive - options: - <variablelist> - <varlistentry> - <term><cmdsynopsis><arg choice="opt">--offline</arg></cmdsynopsis></term> - <listitem> - <para> - List only those durable queues that are not - currently available (more specifically, their master node isn't). - </para> - </listitem> - </varlistentry> - <varlistentry> - <term><cmdsynopsis><arg choice="opt">--online</arg></cmdsynopsis></term> - <listitem> - <para> - List queues that are currently available (their master node is). - </para> - </listitem> - </varlistentry> - <varlistentry> - <term><cmdsynopsis><arg choice="opt">--local</arg></cmdsynopsis></term> - <listitem> - <para> - List only those queues whose master process is - located on the current node. - </para> - </listitem> - </varlistentry> - </variablelist> - </para> - <para> - The <command>queueinfoitem</command> parameter is used to indicate which queue - information items to include in the results. The column order in the - results will match the order of the parameters. - <command>queueinfoitem</command> can take any value from the list - that follows: - </para> - <variablelist> - <varlistentry> - <term>name</term> - <listitem><para>The name of the queue with non-ASCII characters escaped as in C.</para></listitem> - </varlistentry> - <varlistentry> - <term>durable</term> - <listitem><para>Whether or not the queue survives server restarts.</para></listitem> - </varlistentry> - <varlistentry> - <term>auto_delete</term> - <listitem><para>Whether the queue will be deleted automatically when no longer used.</para></listitem> - </varlistentry> - <varlistentry> - <term>arguments</term> - <listitem><para>Queue arguments.</para></listitem> - </varlistentry> - <varlistentry> - <term>policy</term> - <listitem><para>Policy name applying to the queue.</para></listitem> - </varlistentry> - <varlistentry> - <term>pid</term> - <listitem><para>Id of the Erlang process associated with the queue.</para></listitem> - </varlistentry> - <varlistentry> - <term>owner_pid</term> - <listitem><para>Id of the Erlang process representing the connection - which is the exclusive owner of the queue. Empty if the - queue is non-exclusive.</para></listitem> - </varlistentry> - <varlistentry> - <term>exclusive</term> - <listitem><para>True if queue is exclusive (i.e. has - owner_pid), false otherwise</para></listitem> - </varlistentry> - <varlistentry> - <term>exclusive_consumer_pid</term> - <listitem><para>Id of the Erlang process representing the channel of the - exclusive consumer subscribed to this queue. Empty if - there is no exclusive consumer.</para></listitem> - </varlistentry> - <varlistentry> - <term>exclusive_consumer_tag</term> - <listitem><para>Consumer tag of the exclusive consumer subscribed to - this queue. Empty if there is no exclusive consumer.</para></listitem> - </varlistentry> - <varlistentry> - <term>messages_ready</term> - <listitem><para>Number of messages ready to be delivered to clients.</para></listitem> - </varlistentry> - <varlistentry> - <term>messages_unacknowledged</term> - <listitem><para>Number of messages delivered to clients but not yet acknowledged.</para></listitem> - </varlistentry> - <varlistentry> - <term>messages</term> - <listitem><para>Sum of ready and unacknowledged messages - (queue depth).</para></listitem> - </varlistentry> - <varlistentry> - <term>messages_ready_ram</term> - <listitem><para>Number of messages from messages_ready which are resident in ram.</para></listitem> - </varlistentry> - <varlistentry> - <term>messages_unacknowledged_ram</term> - <listitem><para>Number of messages from messages_unacknowledged which are resident in ram.</para></listitem> - </varlistentry> - <varlistentry> - <term>messages_ram</term> - <listitem><para>Total number of messages which are resident in ram.</para></listitem> - </varlistentry> - <varlistentry> - <term>messages_persistent</term> - <listitem><para>Total number of persistent messages in the queue (will always be 0 for transient queues).</para></listitem> - </varlistentry> - <varlistentry> - <term>message_bytes</term> - <listitem><para>Sum of the size of all message bodies in the queue. This does not include the message properties (including headers) or any overhead.</para></listitem> - </varlistentry> - <varlistentry> - <term>message_bytes_ready</term> - <listitem><para>Like <command>message_bytes</command> but counting only those messages ready to be delivered to clients.</para></listitem> - </varlistentry> - <varlistentry> - <term>message_bytes_unacknowledged</term> - <listitem><para>Like <command>message_bytes</command> but counting only those messages delivered to clients but not yet acknowledged.</para></listitem> - </varlistentry> - <varlistentry> - <term>message_bytes_ram</term> - <listitem><para>Like <command>message_bytes</command> but counting only those messages which are in RAM.</para></listitem> - </varlistentry> - <varlistentry> - <term>message_bytes_persistent</term> - <listitem><para>Like <command>message_bytes</command> but counting only those messages which are persistent.</para></listitem> - </varlistentry> - <varlistentry> - <term>head_message_timestamp</term> - <listitem><para>The timestamp property of the first message in the queue, if present. Timestamps of messages only appear when they are in the paged-in state.</para></listitem> - </varlistentry> - <varlistentry> - <term>disk_reads</term> - <listitem><para>Total number of times messages have been read from disk by this queue since it started.</para></listitem> - </varlistentry> - <varlistentry> - <term>disk_writes</term> - <listitem><para>Total number of times messages have been written to disk by this queue since it started.</para></listitem> - </varlistentry> - <varlistentry> - <term>consumers</term> - <listitem><para>Number of consumers.</para></listitem> - </varlistentry> - <varlistentry> - <term>consumer_utilisation</term> - <listitem><para>Fraction of the time (between 0.0 and 1.0) - that the queue is able to immediately deliver messages to - consumers. This can be less than 1.0 if consumers are limited - by network congestion or prefetch count.</para></listitem> - </varlistentry> - <varlistentry> - <term>memory</term> - <listitem><para>Bytes of memory consumed by the Erlang process associated with the - queue, including stack, heap and internal structures.</para></listitem> - </varlistentry> - <varlistentry> - <term>slave_pids</term> - <listitem><para>If the queue is mirrored, this gives the IDs of the current slaves.</para></listitem> - </varlistentry> - <varlistentry> - <term>synchronised_slave_pids</term> - <listitem><para>If the queue is mirrored, this gives the IDs of - the current slaves which are synchronised with the master - - i.e. those which could take over from the master without - message loss.</para></listitem> - </varlistentry> - <varlistentry> - <term>state</term> - <listitem><para>The state of the queue. Normally - 'running', but may be "{syncing, MsgCount}" if the - queue is synchronising. Queues which are located on - cluster nodes that are currently down will be shown - with a status of 'down' (and most other - <command>queueinfoitem</command>s will be - unavailable).</para></listitem> - </varlistentry> - </variablelist> - <para> - If no <command>queueinfoitem</command>s are specified then queue name and depth are - displayed. - </para> - <para role="example-prefix"> - For example: - </para> - <screen role="example">rabbitmqctl list_queues -p /myvhost messages consumers</screen> - <para role="example"> - This command displays the depth and number of consumers for each - queue of the virtual host named <command>/myvhost</command>. - </para> - </listitem> - </varlistentry> - - <varlistentry role="usage-has-option-list"> - <term><cmdsynopsis><command>list_exchanges</command> <arg choice="opt">-p <replaceable>vhost</replaceable></arg> <arg choice="opt" role="usage-option-list"><replaceable>exchangeinfoitem</replaceable> ...</arg></cmdsynopsis></term> - <listitem> - <para> - Returns exchange details. Exchange details of the <command>/</command> virtual host - are returned if the "-p" flag is absent. The "-p" flag can be used to - override this default. - </para> - <para> - The <command>exchangeinfoitem</command> parameter is used to indicate which - exchange information items to include in the results. The column order in the - results will match the order of the parameters. - <command>exchangeinfoitem</command> can take any value from the list - that follows: - </para> - <variablelist> - <varlistentry> - <term>name</term> - <listitem><para>The name of the exchange with non-ASCII characters escaped as in C.</para></listitem> - </varlistentry> - <varlistentry> - <term>type</term> - <listitem><para>The exchange type (such as - [<command>direct</command>, - <command>topic</command>, <command>headers</command>, - <command>fanout</command>]).</para></listitem> - </varlistentry> - <varlistentry> - <term>durable</term> - <listitem><para>Whether or not the exchange survives server restarts.</para></listitem> - </varlistentry> - <varlistentry> - <term>auto_delete</term> - <listitem><para>Whether the exchange will be deleted automatically when no longer used.</para></listitem> - </varlistentry> - <varlistentry> - <term>internal</term> - <listitem><para>Whether the exchange is internal, i.e. cannot be directly published to by a client.</para></listitem> - </varlistentry> - <varlistentry> - <term>arguments</term> - <listitem><para>Exchange arguments.</para></listitem> - </varlistentry> - <varlistentry> - <term>policy</term> - <listitem><para>Policy name for applying to the exchange.</para></listitem> - </varlistentry> - </variablelist> - <para> - If no <command>exchangeinfoitem</command>s are specified then - exchange name and type are displayed. - </para> - <para role="example-prefix"> - For example: - </para> - <screen role="example">rabbitmqctl list_exchanges -p /myvhost name type</screen> - <para role="example"> - This command displays the name and type for each - exchange of the virtual host named <command>/myvhost</command>. - </para> - </listitem> - </varlistentry> - - <varlistentry role="usage-has-option-list"> - <term><cmdsynopsis><command>list_bindings</command> <arg choice="opt">-p <replaceable>vhost</replaceable></arg> <arg choice="opt" role="usage-option-list"><replaceable>bindinginfoitem</replaceable> ...</arg></cmdsynopsis></term> - <listitem> - <para> - Returns binding details. By default the bindings for - the <command>/</command> virtual host are returned. The - "-p" flag can be used to override this default. - </para> - <para> - The <command>bindinginfoitem</command> parameter is used - to indicate which binding information items to include - in the results. The column order in the results will - match the order of the parameters. - <command>bindinginfoitem</command> can take any value - from the list that follows: - </para> - <variablelist> - <varlistentry> - <term>source_name</term> - <listitem><para>The name of the source of messages to - which the binding is attached. With non-ASCII - characters escaped as in C.</para></listitem> - </varlistentry> - <varlistentry> - <term>source_kind</term> - <listitem><para>The kind of the source of messages to - which the binding is attached. Currently always - exchange. With non-ASCII characters escaped as in - C.</para></listitem> - </varlistentry> - <varlistentry> - <term>destination_name</term> - <listitem><para>The name of the destination of - messages to which the binding is attached. With - non-ASCII characters escaped as in - C.</para></listitem> - </varlistentry> - <varlistentry> - <term>destination_kind</term> - <listitem><para>The kind of the destination of - messages to which the binding is attached. With - non-ASCII characters escaped as in - C.</para></listitem> - </varlistentry> - <varlistentry> - <term>routing_key</term> - <listitem><para>The binding's routing key, with - non-ASCII characters escaped as in C.</para></listitem> - </varlistentry> - <varlistentry> - <term>arguments</term> - <listitem><para>The binding's arguments.</para></listitem> - </varlistentry> - </variablelist> - <para> - If no <command>bindinginfoitem</command>s are specified then - all above items are displayed. - </para> - <para role="example-prefix"> - For example: - </para> - <screen role="example">rabbitmqctl list_bindings -p /myvhost exchange_name queue_name</screen> - <para role="example"> - This command displays the exchange name and queue name - of the bindings in the virtual host - named <command>/myvhost</command>. - </para> - </listitem> - </varlistentry> - - <varlistentry id="list_connections" role="usage-has-option-list"> - <term><cmdsynopsis><command>list_connections</command> <arg choice="opt" role="usage-option-list"><replaceable>connectioninfoitem</replaceable> ...</arg></cmdsynopsis></term> - <listitem> - <para> - Returns TCP/IP connection statistics. - </para> - <para> - The <command>connectioninfoitem</command> parameter is used to indicate - which connection information items to include in the results. The - column order in the results will match the order of the parameters. - <command>connectioninfoitem</command> can take any value from the list - that follows: - </para> - - <variablelist> - <varlistentry> - <term>pid</term> - <listitem><para>Id of the Erlang process associated with the connection.</para></listitem> - </varlistentry> - <varlistentry> - <term>name</term> - <listitem><para>Readable name for the connection.</para></listitem> - </varlistentry> - <varlistentry> - <term>port</term> - <listitem><para>Server port.</para></listitem> - </varlistentry> - <varlistentry> - <term>host</term> - <listitem><para>Server hostname obtained via reverse - DNS, or its IP address if reverse DNS failed or was - not enabled.</para></listitem> - </varlistentry> - <varlistentry> - <term>peer_port</term> - <listitem><para>Peer port.</para></listitem> - </varlistentry> - <varlistentry> - <term>peer_host</term> - <listitem><para>Peer hostname obtained via reverse - DNS, or its IP address if reverse DNS failed or was - not enabled.</para></listitem> - </varlistentry> - <varlistentry> - <term>ssl</term> - <listitem><para>Boolean indicating whether the - connection is secured with SSL.</para></listitem> - </varlistentry> - <varlistentry> - <term>ssl_protocol</term> - <listitem><para>SSL protocol - (e.g. tlsv1)</para></listitem> - </varlistentry> - <varlistentry> - <term>ssl_key_exchange</term> - <listitem><para>SSL key exchange algorithm - (e.g. rsa)</para></listitem> - </varlistentry> - <varlistentry> - <term>ssl_cipher</term> - <listitem><para>SSL cipher algorithm - (e.g. aes_256_cbc)</para></listitem> - </varlistentry> - <varlistentry> - <term>ssl_hash</term> - <listitem><para>SSL hash function - (e.g. sha)</para></listitem> - </varlistentry> - <varlistentry> - <term>peer_cert_subject</term> - <listitem><para>The subject of the peer's SSL - certificate, in RFC4514 form.</para></listitem> - </varlistentry> - <varlistentry> - <term>peer_cert_issuer</term> - <listitem><para>The issuer of the peer's SSL - certificate, in RFC4514 form.</para></listitem> - </varlistentry> - <varlistentry> - <term>peer_cert_validity</term> - <listitem><para>The period for which the peer's SSL - certificate is valid.</para></listitem> - </varlistentry> - - <varlistentry> - <term>state</term> - <listitem><para>Connection state (one of [<command>starting</command>, <command>tuning</command>, - <command>opening</command>, <command>running</command>, <command>flow</command>, <command>blocking</command>, <command>blocked</command>, <command>closing</command>, <command>closed</command>]).</para></listitem> - </varlistentry> - <varlistentry> - <term>channels</term> - <listitem><para>Number of channels using the connection.</para></listitem> - </varlistentry> - <varlistentry> - <term>protocol</term> - <listitem><para>Version of the AMQP protocol in use (currently one of <command>{0,9,1}</command> or <command>{0,8,0}</command>). Note that if a client requests an AMQP 0-9 connection, we treat it as AMQP 0-9-1.</para></listitem> - </varlistentry> - <varlistentry> - <term>auth_mechanism</term> - <listitem><para>SASL authentication mechanism used, such as <command>PLAIN</command>.</para></listitem> - </varlistentry> - <varlistentry> - <term>user</term> - <listitem><para>Username associated with the connection.</para></listitem> - </varlistentry> - <varlistentry> - <term>vhost</term> - <listitem><para>Virtual host name with non-ASCII characters escaped as in C.</para></listitem> - </varlistentry> - <varlistentry> - <term>timeout</term> - <listitem><para>Connection timeout / negotiated heartbeat interval, in seconds.</para></listitem> - </varlistentry> - <varlistentry> - <term>frame_max</term> - <listitem><para>Maximum frame size (bytes).</para></listitem> - </varlistentry> - <varlistentry> - <term>channel_max</term> - <listitem><para>Maximum number of channels on this connection.</para></listitem> - </varlistentry> - <varlistentry> - <term>client_properties</term> - <listitem><para>Informational properties transmitted by the client - during connection establishment.</para></listitem> - </varlistentry> - <varlistentry> - <term>recv_oct</term> - <listitem><para>Octets received.</para></listitem> - </varlistentry> - <varlistentry> - <term>recv_cnt</term> - <listitem><para>Packets received.</para></listitem> - </varlistentry> - <varlistentry> - <term>send_oct</term> - <listitem><para>Octets send.</para></listitem> - </varlistentry> - <varlistentry> - <term>send_cnt</term> - <listitem><para>Packets sent.</para></listitem> - </varlistentry> - <varlistentry> - <term>send_pend</term> - <listitem><para>Send queue size.</para></listitem> - </varlistentry> - <varlistentry> - <term>connected_at</term> - <listitem><para>Date and time this connection was established, as timestamp.</para></listitem> - </varlistentry> - </variablelist> - <para> - If no <command>connectioninfoitem</command>s are - specified then user, peer host, peer port, time since - flow control and memory block state are displayed. - </para> - - <para role="example-prefix"> - For example: - </para> - <screen role="example">rabbitmqctl list_connections send_pend port</screen> - <para role="example"> - This command displays the send queue size and server port for each - connection. - </para> - </listitem> - </varlistentry> - - <varlistentry role="usage-has-option-list"> - <term><cmdsynopsis><command>list_channels</command> <arg choice="opt" role="usage-option-list"><replaceable>channelinfoitem</replaceable> ...</arg></cmdsynopsis></term> - <listitem> - <para> - Returns information on all current channels, the logical - containers executing most AMQP commands. This includes - channels that are part of ordinary AMQP connections, and - channels created by various plug-ins and other extensions. - </para> - <para> - The <command>channelinfoitem</command> parameter is used to - indicate which channel information items to include in the - results. The column order in the results will match the - order of the parameters. - <command>channelinfoitem</command> can take any value from the list - that follows: - </para> - - <variablelist> - <varlistentry> - <term>pid</term> - <listitem><para>Id of the Erlang process associated with the connection.</para></listitem> - </varlistentry> - <varlistentry> - <term>connection</term> - <listitem><para>Id of the Erlang process associated with the connection - to which the channel belongs.</para></listitem> - </varlistentry> - <varlistentry> - <term>name</term> - <listitem><para>Readable name for the channel.</para></listitem> - </varlistentry> - <varlistentry> - <term>number</term> - <listitem><para>The number of the channel, which uniquely identifies it within - a connection.</para></listitem> - </varlistentry> - <varlistentry> - <term>user</term> - <listitem><para>Username associated with the channel.</para></listitem> - </varlistentry> - <varlistentry> - <term>vhost</term> - <listitem><para>Virtual host in which the channel operates.</para></listitem> - </varlistentry> - <varlistentry> - <term>transactional</term> - <listitem><para>True if the channel is in transactional mode, false otherwise.</para></listitem> - </varlistentry> - <varlistentry> - <term>confirm</term> - <listitem><para>True if the channel is in confirm mode, false otherwise.</para></listitem> - </varlistentry> - <varlistentry> - <term>consumer_count</term> - <listitem><para>Number of logical AMQP consumers retrieving messages via - the channel.</para></listitem> - </varlistentry> - <varlistentry> - <term>messages_unacknowledged</term> - <listitem><para>Number of messages delivered via this channel but not - yet acknowledged.</para></listitem> - </varlistentry> - <varlistentry> - <term>messages_uncommitted</term> - <listitem><para>Number of messages received in an as yet - uncommitted transaction.</para></listitem> - </varlistentry> - <varlistentry> - <term>acks_uncommitted</term> - <listitem><para>Number of acknowledgements received in an as yet - uncommitted transaction.</para></listitem> - </varlistentry> - <varlistentry> - <term>messages_unconfirmed</term> - <listitem><para>Number of published messages not yet - confirmed. On channels not in confirm mode, this - remains 0.</para></listitem> - </varlistentry> - <varlistentry> - <term>prefetch_count</term> - <listitem><para>QoS prefetch limit for new consumers, 0 if unlimited.</para></listitem> - </varlistentry> - <varlistentry> - <term>global_prefetch_count</term> - <listitem><para>QoS prefetch limit for the entire channel, 0 if unlimited.</para></listitem> - </varlistentry> - </variablelist> - <para> - If no <command>channelinfoitem</command>s are specified then pid, - user, consumer_count, and messages_unacknowledged are assumed. - </para> - - <para role="example-prefix"> - For example: - </para> - <screen role="example">rabbitmqctl list_channels connection messages_unacknowledged</screen> - <para role="example"> - This command displays the connection process and count - of unacknowledged messages for each channel. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><cmdsynopsis><command>list_consumers</command> <arg choice="opt">-p <replaceable>vhost</replaceable></arg></cmdsynopsis></term> - <listitem> - <para> - List consumers, i.e. subscriptions to a queue's message - stream. Each line printed shows, separated by tab - characters, the name of the queue subscribed to, the id of - the channel process via which the subscription was created - and is managed, the consumer tag which uniquely identifies - the subscription within a channel, a boolean - indicating whether acknowledgements are expected for - messages delivered to this consumer, an integer indicating - the prefetch limit (with 0 meaning 'none'), and any arguments - for this consumer. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><cmdsynopsis><command>status</command></cmdsynopsis></term> - <listitem> - <para> - Displays broker status information such as the running - applications on the current Erlang node, RabbitMQ and - Erlang versions, OS name, memory and file descriptor - statistics. (See the <command>cluster_status</command> - command to find out which nodes are clustered and - running.) - </para> - <para role="example-prefix">For example:</para> - <screen role="example">rabbitmqctl status</screen> - <para role="example"> - This command displays information about the RabbitMQ - broker. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><cmdsynopsis><command>node_health_check</command></cmdsynopsis></term> - <listitem> - <para> - Health check of the RabbitMQ node. Verifies the rabbit application is - running, list_queues and list_channels return, and alarms are not set. - </para> - <para role="example-prefix">For example:</para> - <screen role="example">rabbitmqctl node_health_check -n rabbit@stringer</screen> - <para role="example"> - This command performs a health check on the RabbitMQ node. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><cmdsynopsis><command>environment</command></cmdsynopsis></term> - <listitem> - <para> - Display the name and value of each variable in the - application environment for each running application. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><cmdsynopsis><command>report</command></cmdsynopsis></term> - <listitem> - <para> - Generate a server status report containing a - concatenation of all server status information for - support purposes. The output should be redirected to a - file when accompanying a support request. - </para> - <para role="example-prefix"> - For example: - </para> - <screen role="example">rabbitmqctl report > server_report.txt</screen> - <para role="example"> - This command creates a server report which may be - attached to a support request email. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><cmdsynopsis><command>eval</command> <arg choice="req"><replaceable>expr</replaceable></arg></cmdsynopsis></term> - <listitem> - <para> - Evaluate an arbitrary Erlang expression. - </para> - <para role="example-prefix"> - For example: - </para> - <screen role="example">rabbitmqctl eval 'node().'</screen> - <para role="example"> - This command returns the name of the node to which rabbitmqctl has connected. - </para> - </listitem> - </varlistentry> - </variablelist> - </refsect2> - - <refsect2> - <title>Miscellaneous</title> - <variablelist> - <varlistentry> - <term><cmdsynopsis><command>close_connection</command> <arg choice="req"><replaceable>connectionpid</replaceable></arg> <arg choice="req"><replaceable>explanation</replaceable></arg></cmdsynopsis></term> - <listitem> - <variablelist> - <varlistentry> - <term>connectionpid</term> - <listitem><para>Id of the Erlang process associated with the connection to close.</para></listitem> - </varlistentry> - <varlistentry> - <term>explanation</term> - <listitem><para>Explanation string.</para></listitem> - </varlistentry> - </variablelist> - <para> - Instruct the broker to close the connection associated - with the Erlang process id <option>connectionpid</option> (see also the - <link linkend="list_connections"><command>list_connections</command></link> - command), passing the <option>explanation</option> string to the - connected client as part of the AMQP connection shutdown - protocol. - </para> - <para role="example-prefix">For example:</para> - <screen role="example">rabbitmqctl close_connection "<rabbit@tanto.4262.0>" "go away"</screen> - <para role="example"> - This command instructs the RabbitMQ broker to close the - connection associated with the Erlang process - id <command><rabbit@tanto.4262.0></command>, passing the - explanation <command>go away</command> to the connected client. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term><cmdsynopsis><command>trace_on</command> <arg choice="opt">-p <replaceable>vhost</replaceable></arg></cmdsynopsis></term> - <listitem> - <variablelist> - <varlistentry> - <term>vhost</term> - <listitem><para>The name of the virtual host for which to start tracing.</para></listitem> - </varlistentry> - </variablelist> - <para> - Starts tracing. Note that the trace state is not - persistent; it will revert to being off if the server is - restarted. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><cmdsynopsis><command>trace_off</command> <arg choice="opt">-p <replaceable>vhost</replaceable></arg></cmdsynopsis></term> - <listitem> - <variablelist> - <varlistentry> - <term>vhost</term> - <listitem><para>The name of the virtual host for which to stop tracing.</para></listitem> - </varlistentry> - </variablelist> - <para> - Stops tracing. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term><cmdsynopsis><command>set_vm_memory_high_watermark</command> <arg choice="req"><replaceable>fraction</replaceable></arg></cmdsynopsis></term> - <listitem> - <variablelist> - <varlistentry> - <term>fraction</term> - <listitem><para> - The new memory threshold fraction at which flow - control is triggered, as a floating point number - greater than or equal to 0. - </para></listitem> - </varlistentry> - </variablelist> - </listitem> - </varlistentry> - <varlistentry> - <term><cmdsynopsis><command>set_vm_memory_high_watermark absolute</command> <arg choice="req"><replaceable>memory_limit</replaceable></arg></cmdsynopsis></term> - <listitem> - <variablelist> - <varlistentry> - <term>memory_limit</term> - <listitem><para> - The new memory limit at which flow control is - triggered, expressed in bytes as an integer number - greater than or equal to 0 or as a string with memory units - (e.g. 512M or 1G). Available units are: - k, kiB: kibibytes (2^10 bytes) - M, MiB: mebibytes (2^20) - G, GiB: gibibytes (2^30) - kB: kilobytes (10^3) - MB: megabytes (10^6) - GB: gigabytes (10^9) - </para></listitem> - </varlistentry> - </variablelist> - </listitem> - </varlistentry> - <varlistentry> - <term><cmdsynopsis><command>set_disk_free_limit</command> <arg choice="req"><replaceable>disk_limit</replaceable></arg></cmdsynopsis></term> - <listitem> - <variablelist> - <varlistentry> - <term>disk_limit</term> - <listitem><para> - Lower bound limit as an integer in bytes or a string with memory units (see vm_memory_high_watermark), - e.g. 512M or 1G. Once free disk space reaches the limit, a disk alarm will be set. - </para></listitem> - </varlistentry> - </variablelist> - </listitem> - </varlistentry> - <varlistentry> - <term><cmdsynopsis><command>set_disk_free_limit mem_relative</command> <arg choice="req"><replaceable>fraction</replaceable></arg></cmdsynopsis></term> - <listitem> - <variablelist> - <varlistentry> - <term>fraction</term> - <listitem><para> - Limit relative to the total amount available RAM - as a non-negative floating point number. - Values lower than 1.0 can be dangerous and - should be used carefully. - </para></listitem> - </varlistentry> - </variablelist> - </listitem> - </varlistentry> - <varlistentry> - <!-- one-line formatting matters for rabbit_ctl_usage.erl code generation --> - <term><cmdsynopsis><command>encode</command> <arg choice="opt">--decode</arg> <arg choice="opt"><replaceable>value</replaceable></arg> <arg choice="opt"><replaceable>passphrase</replaceable></arg> <arg choice="opt">--list-ciphers</arg> <arg choice="opt">--list-hashes</arg> <arg choice="opt">--cipher <replaceable>cipher</replaceable></arg> <arg choice="opt">--hash <replaceable>hash</replaceable></arg> <arg choice="opt">--iterations <replaceable>iterations</replaceable></arg></cmdsynopsis> - </term> - <listitem> - <variablelist> - <varlistentry> - <term><cmdsynopsis><arg choice="opt">--decode</arg></cmdsynopsis></term> - <listitem> - <para> - Flag to decrypt the input value. - </para> - <para role="example-prefix">For example:</para> - <screen role="example">rabbitmqctl encode --decode '{encrypted,'<<"...">>}' mypassphrase</screen> - </listitem> - </varlistentry> - <varlistentry> - <term> - <cmdsynopsis> - <arg choice="opt"><replaceable>value</replaceable></arg> - <arg choice="opt"><replaceable>passphrase</replaceable></arg> - </cmdsynopsis> - </term> - <listitem> - <para> - Value to encrypt/decrypt and passphrase. - </para> - <para role="example-prefix">For example:</para> - <screen role="example">rabbitmqctl encode '<<"guest">>' mypassphrase</screen> - <screen role="example">rabbitmqctl encode --decode '{encrypted,'<<"...">>}' mypassphrase</screen> - </listitem> - </varlistentry> - <varlistentry> - <term><cmdsynopsis><arg choice="opt">--list-ciphers</arg></cmdsynopsis></term> - <listitem> - <para> - Flag to list the supported ciphers. - </para> - <para role="example-prefix">For example:</para> - <screen role="example">rabbitmqctl encode --list-ciphers</screen> - </listitem> - </varlistentry> - <varlistentry> - <term><cmdsynopsis><arg choice="opt">--list-hashes</arg></cmdsynopsis></term> - <listitem> - <para> - Flag to list the supported hash algorithms. - </para> - <para role="example-prefix">For example:</para> - <screen role="example">rabbitmqctl encode --list-hashes</screen> - </listitem> - </varlistentry> - <varlistentry> - <term> - <cmdsynopsis> - <arg choice="opt">--cipher <replaceable>cipher</replaceable></arg> - <arg choice="opt">--hash <replaceable>hash</replaceable></arg> - <arg choice="opt">--iterations <replaceable>iterations</replaceable></arg> - </cmdsynopsis> - </term> - <listitem> - <para> - Options to specify the encryption settings. They can be used independently. - </para> - <para role="example-prefix">For example:</para> - <screen role="example"> -rabbitmqctl encode --cipher blowfish_cfb64 --hash sha256 --iterations 10000 \ - '<<"guest">>' mypassphrase</screen> - </listitem> - </varlistentry> - </variablelist> - </listitem> - </varlistentry> - </variablelist> - </refsect2> - </refsect1> - -</refentry> diff --git a/docs/rabbitmqctl.8 b/docs/rabbitmqctl.8 new file mode 100644 index 0000000000..e12f6f496f --- /dev/null +++ b/docs/rabbitmqctl.8 @@ -0,0 +1,1692 @@ +.\" vim:ft=nroff: +.\" The contents of this file are subject to the Mozilla Public License +.\" Version 1.1 (the "License"); you may not use this file except in +.\" compliance with the License. You may obtain a copy of the License +.\" at http://www.mozilla.org/MPL/ +.\" +.\" Software distributed under the License is distributed on an "AS IS" +.\" basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See +.\" the License for the specific language governing rights and +.\" limitations under the License. +.\" +.\" The Original Code is RabbitMQ. +.\" +.\" The Initial Developer of the Original Code is Pivotal Software, Inc. +.\" Copyright (c) 2007-2017 Pivotal Software, Inc. All rights reserved. +.\" +.Dd April 25, 2017 +.Dt RABBITMQCTL 8 +.Os "RabbitMQ Server" +.Sh NAME +.Nm rabbitmqctl +.Nd command line for managing a RabbitMQ broker +.\" ------------------------------------------------------------------ +.Sh SYNOPSIS +.\" ------------------------------------------------------------------ +.Nm +.Op Fl q +.Op Fl n Ar node +.Op Fl t Ar timeout +.Ar command +.Op Ar command_options +.\" ------------------------------------------------------------------ +.Sh DESCRIPTION +.\" ------------------------------------------------------------------ +RabbitMQ is an implementation of AMQP, the emerging standard for high +performance enterprise messaging. +The RabbitMQ Server is a robust and scalable implementation of an AMQP +broker. +.Pp +.Nm +is a command line tool for managing a RabbitMQ broker. +It performs all actions by connecting to one of the broker's nodes. +.Pp +Diagnostic information is displayed if the broker was not running, could +not be reached, or rejected the connection due to mismatching Erlang +cookies. +.\" ------------------------------------------------------------------ +.Sh OPTIONS +.\" ------------------------------------------------------------------ +.Bl -tag -width Ds +.It Fl n Ar node +Default node is +.Qq Pf rabbit@ Ar server , +where +.Ar server +is the local host. +On a host named +.Qq myserver.example.com , +the node name of the RabbitMQ Erlang node will usually be +.Qq rabbit@myserver +(unless +.Ev RABBITMQ_NODENAME +has been set to some non-default value at broker startup time). +The output of +.Qq hostname -s +is usually the correct suffix to use after the +.Qq @ +sign. +See +.Xr rabbitmq-server 8 +for details of configuring the RabbitMQ broker. +.It Fl q +Quiet output mode is selected. +Informational messages are suppressed when quiet mode is in effect. +.It Fl t Ar timeout +Operation timeout in seconds. +Only applicable to +.Qq list +commands. +Default is +.Qq infinity . +.El +.\" ------------------------------------------------------------------ +.Sh COMMANDS +.\" ------------------------------------------------------------------ +.Ss Application Management +.Bl -tag -width Ds +.\" ------------------------------------ +.It Cm force_reset +Forcefully returns a RabbitMQ node to its virgin state. +.Pp +The +.Cm force_reset +command differs from +.Cm reset +in that it resets the node unconditionally, regardless of the current +management database state and cluster configuration. +It should only be used as a last resort if the database or cluster +configuration has been corrupted. +.Pp +For +.Cm reset +and +.Cm force_reset +to succeed the RabbitMQ application must have been stopped, e.g. with +.Cm stop_app . +.Pp +For example, to reset the RabbitMQ node: +.sp +.Dl rabbitmqctl force_reset +.\" ------------------------------------ +.It Cm hipe_compile Ar directory +Performs HiPE-compilation and caches resulting +.Pa .beam Ns -files in the given directory. +.Pp +Parent directories are created if necessary. +Any existing +.Pa .beam +files from the directory are automatically deleted prior to compilation. +.Pp +To use this precompiled files, you should set +.Ev RABBITMQ_SERVER_CODE_PATH +environment variable to directory specified in +.Cm hipe_compile +invokation. +.Pp +For example, to HiPE-compile modules and store them to +.Pa /tmp/rabbit-hipe/ebin +directory: +.sp +.Dl rabbitmqctl hipe_compile /tmp/rabbit-hipe/ebin +.\" ------------------------------------ +.It Cm reset +Returns a RabbitMQ node to its virgin state. +.Pp +Removes the node from any cluster it belongs to, removes all data from +the management database, such as configured users and vhosts, and +deletes all persistent messages. +.Pp +For +.Cm reset +and +.Cm force_reset +to succeed the RabbitMQ application must have been stopped, e.g. with +.Cm stop_app . +.Pp +For example, to resets the RabbitMQ node: +.sp +.Dl rabbitmqctl reset +.\" ------------------------------------ +.It Cm rotate_logs +Instructs the RabbitMQ node to perform internal log rotation. +.Pp +Log rotation is performed according to lager settings specified in +configuration file. +.Pp +Note that there is no need to call this command in case of external log +rotation (e.g. from logrotate(8)), because lager detects renames and +automatically reopens log files. +.Pp +For example, this command starts internal log rotation +process: +.sp +.Dl rabbitmqctl rotate_logs +.Pp +Rotation is performed asynchronously, so there is no guarantee that it +will be completed when this command returns. +.\" ------------------------------------ +.It Cm shutdown +Shuts down the Erlang process on which RabbitMQ is running. +The command is blocking and will return after the Erlang process exits. +If RabbitMQ fails to stop, it will return a non-zero exit code. +.Pp +Unlike the stop command, the shutdown command: +.Bl -bullet +.It +does not require a +.Ar pid_file +to wait for the Erlang process to exit +.It +returns a non-zero exit code if RabbitMQ node is not running +.El +.Pp +For example, to shut down the Erlang process on which RabbitMQ is +running: +.sp +.Dl rabbitmqctl shutdown +.\" ------------------------------------ +.It Cm start_app +Starts the RabbitMQ application. +.Pp +This command is typically run after performing other management actions +that required the RabbitMQ application to be stopped, e.g.\& +.Cm reset . +.Pp +For example, to instruct the RabbitMQ node to start the RabbitMQ +application: +.sp +.Dl rabbitmqctl start_app +.\" ------------------------------------ +.It Cm stop Op Ar pid_file +Stops the Erlang node on which RabbitMQ is running. +To restart the node follow the instructions for +.Qq Running the Server +in the +.Lk http://www.rabbitmq.com/download.html installation guide . +.Pp +If a +.Ar pid_file +is specified, also waits for the process specified there to terminate. +See the description of the +.Cm wait +command for details on this file. +.Pp +For example, to instruct the RabbitMQ node to terminate: +.sp +.Dl rabbitmqctl stop +.\" ------------------------------------ +.It Cm stop_app +Stops the RabbitMQ application, leaving the Erlang node running. +.Pp +This command is typically run prior to performing other management +actions that require the RabbitMQ application to be stopped, e.g.\& +.Cm reset . +.Pp +For example, to instruct the RabbitMQ node to stop the RabbitMQ +application: +.sp +.Dl rabbitmqctl stop_app +.\" ------------------------------------ +.It Cm wait Ar pid_file +Waits for the RabbitMQ application to start. +.Pp +This command will wait for the RabbitMQ application to start at the +node. +It will wait for the pid file to be created, then for a process with +a pid specified in the pid file to start, and then for the RabbitMQ +application to start in that process. +It will fail if the process terminates without starting the RabbitMQ +application. +.Pp +A suitable pid file is created by the +.Xr rabbitmq-server 8 +script. +By default this is located in the Mnesia directory. +Modify the +.Ev RABBITMQ_PID_FILE +environment variable to change the location. +.Pp +For example, this command will return when the RabbitMQ node has started +up: +.sp +.Dl rabbitmqctl wait /var/run/rabbitmq/pid +.\" ------------------------------------ +.El +.Ss Cluster Management +.Bl -tag -width Ds +.\" ------------------------------------ +.It Cm join_cluster Ar clusternode Op Fl -ram +.Bl -tag -width Ds +.It Ar clusternode +Node to cluster with. +.It Fl -ram +If provided, the node will join the cluster as a RAM node. +.El +.Pp +Instructs the node to become a member of the cluster that the specified +node is in. +Before clustering, the node is reset, so be careful when using this +command. +For this command to succeed the RabbitMQ application must have been +stopped, e.g. with +.Cm stop_app . +.Pp +Cluster nodes can be of two types: disc or RAM. +Disc nodes replicate data in RAM and on disc, thus providing redundancy +in the event of node failure and recovery from global events such as +power failure across all nodes. +RAM nodes replicate data in RAM only (with the exception of queue +contents, which can reside on disc if the queue is persistent or too big +to fit in memory) and are mainly used for scalability. +RAM nodes are more performant only when managing resources (e.g.\& +adding/removing queues, exchanges, or bindings). +A cluster must always have at least one disc node, and usually should +have more than one. +.Pp +The node will be a disc node by default. +If you wish to create a RAM node, provide the +.Fl -ram +flag. +.Pp +After executing the +.Cm join_cluster +command, whenever the RabbitMQ application is started on the current +node it will attempt to connect to the nodes that were in the cluster +when the node went down. +.Pp +To leave a cluster, +.Cm reset +the node. +You can also remove nodes remotely with the +.Cm forget_cluster_node +command. +.Pp +For more details see the +.Lk http://www.rabbitmq.com/clustering.html Clustering guide . +.Pp +For example, this command instructs the RabbitMQ node to join the cluster that +.Qq hare@elena +is part of, as a ram node: +.sp +.Dl rabbitmqctl join_cluster hare@elena --ram +.\" ------------------------------------ +.It Cm cluster_status +Displays all the nodes in the cluster grouped by node type, together +with the currently running nodes. +.Pp +For example, this command displays the nodes in the cluster: +.sp +.Dl rabbitmqctl cluster_status +.\" ------------------------------------ +.It Cm change_cluster_node_type Ar type +Changes the type of the cluster node. +.Pp +The +.Ar type +must be one of the following: +.Bl -bullet -compact +.It +.Cm disc +.It +.Cm ram +.El +.Pp +The node must be stopped for this operation to succeed, and when turning +a node into a RAM node the node must not be the only disc node in the +cluster. +.Pp +For example, this command will turn a RAM node into a disc node: +.sp +.Dl rabbitmqctl change_cluster_node_type disc +.\" ------------------------------------ +.It Cm forget_cluster_node Op Fl -offline +.Bl -tag -width Ds +.It Fl -offline +Enables node removal from an offline node. +This is only useful in the situation where all the nodes are offline and +the last node to go down cannot be brought online, thus preventing the +whole cluster from starting. +It should not be used in any other circumstances since it can lead to +inconsistencies. +.El +.Pp +Removes a cluster node remotely. +The node that is being removed must be offline, while the node we are +removing from must be online, except when using the +.Fl -offline +flag. +.Pp +When using the +.Fl -offline +flag , +.Nm +will not attempt to connect to a node as normal; instead it will +temporarily become the node in order to make the change. +This is useful if the node cannot be started normally. +In this case the node will become the canonical source for cluster +metadata (e.g. which queues exist), even if it was not before. +Therefore you should use this command on the latest node to shut down if +at all possible. +.Pp +For example, this command will remove the node +.Qq rabbit@stringer +from the node +.Qq hare@mcnulty : +.sp +.Dl rabbitmqctl -n hare@mcnulty forget_cluster_node rabbit@stringer +.\" ------------------------------------ +.It Cm rename_cluster_node Ar oldnode1 Ar newnode1 Op Ar oldnode2 Ar newnode2 ... +Supports renaming of cluster nodes in the local database. +.Pp +This subcommand causes +.Nm +to temporarily become the node in order to make the change. +The local cluster node must therefore be completely stopped; other nodes +can be online or offline. +.Pp +This subcommand takes an even number of arguments, in pairs representing +the old and new names for nodes. +You must specify the old and new names for this node and for any other +nodes that are stopped and being renamed at the same time. +.Pp +It is possible to stop all nodes and rename them all simultaneously (in +which case old and new names for all nodes must be given to every node) +or stop and rename nodes one at a time (in which case each node only +needs to be told how its own name is changing). +.Pp +For example, this command will rename the node +.Qq rabbit@misshelpful +to the node +.Qq rabbit@cordelia +.sp +.Dl rabbitmqctl rename_cluster_node rabbit@misshelpful rabbit@cordelia +.\" ------------------------------------ +.It Cm update_cluster_nodes Ar clusternode +.Bl -tag -width Ds +.It Ar clusternode +The node to consult for up-to-date information. +.El +.Pp +Instructs an already clustered node to contact +.Ar clusternode +to cluster when waking up. +This is different from +.Cm join_cluster +since it does not join any cluster - it checks that the node is already +in a cluster with +.Ar clusternode . +.Pp +The need for this command is motivated by the fact that clusters can +change while a node is offline. +Consider the situation in which node +.Va A +and +.Va B +are clustered. +.Va A +goes down, +.Va C +clusters with +.Va B , +and then +.Va B +leaves the cluster. +When +.Va A +wakes up, it'll try to contact +.Va B , +but this will fail since +.Va B +is not in the cluster anymore. +The following command will solve this situation: +.sp +.Dl update_cluster_nodes -n Va A Va C +.\" ------------------------------------ +.It Cm force_boot +Ensures that the node will start next time, even if it was not the last +to shut down. +.Pp +Normally when you shut down a RabbitMQ cluster altogether, the first +node you restart should be the last one to go down, since it may have +seen things happen that other nodes did not. +But sometimes that's not possible: for instance if the entire cluster +loses power then all nodes may think they were not the last to shut +down. +.Pp +In such a case you can invoke +.Cm force_boot +while the node is down. +This will tell the node to unconditionally start next time you ask it +to. +If any changes happened to the cluster after this node shut down, they +will be lost. +.Pp +If the last node to go down is permanently lost then you should use +.Cm forget_cluster_node Fl -offline +in preference to this command, as it will ensure that mirrored queues +which were mastered on the lost node get promoted. +.Pp +For example, this will force the node not to wait for other nodes next +time it is started: +.sp +.Dl rabbitmqctl force_boot +.\" ------------------------------------ +.It Cm sync_queue Oo Fl p Ar vhost Oc Ar queue +.Bl -tag -width Ds +.It Ar queue +The name of the queue to synchronise. +.El +.Pp +Instructs a mirrored queue with unsynchronised slaves to synchronise +itself. +The queue will block while synchronisation takes place (all publishers +to and consumers from the queue will block). +The queue must be mirrored for this command to succeed. +.Pp +Note that unsynchronised queues from which messages are being drained +will become synchronised eventually. +This command is primarily useful for queues which are not being drained. +.\" ------------------------------------ +.It Cm cancel_sync_queue Oo Fl p Ar vhost Oc Ar queue +.Bl -tag -width Ds +.It Ar queue +The name of the queue to cancel synchronisation for. +.El +.Pp +Instructs a synchronising mirrored queue to stop synchronising itself. +.\" ------------------------------------ +.It Cm purge_queue Oo Fl p Ar vhost Oc Ar queue +.Bl -tag -width Ds +.It Ar queue +The name of the queue to purge. +.El +.Pp +Purges a queue (removes all messages in it). +.\" ------------------------------------ +.It Cm set_cluster_name Ar name +Sets the cluster name to +.Ar name . +The cluster name is announced to clients on connection, and used by the +federation and shovel plugins to record where a message has been. +The cluster name is by default derived from the hostname of the first +node in the cluster, but can be changed. +.Pp +For example, this sets the cluster name to +.Qq london : +.sp +.Dl rabbitmqctl set_cluster_name london +.El +.Ss User Management +Note that +.Nm +manages the RabbitMQ internal user database. +Users from any alternative authentication backend will not be visible to +.Nm . +.Bl -tag -width Ds +.\" ------------------------------------ +.It Cm add_user Ar username Ar password +.Bl -tag -width Ds +.It Ar username +The name of the user to create. +.It Ar password +The password the created user will use to log in to the broker. +.El +.Pp +For example, this command instructs the RabbitMQ broker to create a (non-administrative) user named +.Qq tonyg +with (initial) password +.Qq changeit : +.sp +.Dl rabbitmqctl add_user tonyg changeit +.\" ------------------------------------ +.It Cm delete_user Ar username +.Bl -tag -width Ds +.It Ar username +The name of the user to delete. +.El +.Pp +For example, this command instructs the RabbitMQ broker to delete the user named +.Qq tonyg : +.sp +.Dl rabbitmqctl delete_user tonyg +.\" ------------------------------------ +.It Cm change_password Ar username Ar newpassword +.Bl -tag -width Ds +.It Ar username +The name of the user whose password is to be changed. +.It Ar newpassword +The new password for the user. +.El +.Pp +For example, this command instructs the RabbitMQ broker to change the +password for the user named +.Qq tonyg +to +.Qq newpass : +.sp +.Dl rabbitmqctl change_password tonyg newpass +.\" ------------------------------------ +.It Cm clear_password Ar username +.Bl -tag -width Ds +.It Ar username +The name of the user whose password is to be cleared. +.El +.Pp +For example, this command instructs the RabbitMQ broker to clear the +password for the user named +.Qq tonyg : +.sp +.Dl rabbitmqctl clear_password tonyg +.Pp +This user now cannot log in with a password (but may be able to through +e.g. SASL EXTERNAL if configured). +.\" ------------------------------------ +.It Cm authenticate_user Ar username Ar password +.Bl -tag -width Ds +.It Ar username +The name of the user. +.It Ar password +The password of the user. +.El +.Pp +For example, this command instructs the RabbitMQ broker to authenticate the user named +.Qq tonyg +with password +.Qq verifyit : +.sp +.Dl rabbitmqctl authenticate_user tonyg verifyit +.\" ------------------------------------ +.It Cm set_user_tags Ar username Op Ar tag ... +.Bl -tag -width Ds +.It Ar username +The name of the user whose tags are to be set. +.It Ar tag +Zero, one or more tags to set. +Any existing tags will be removed. +.El +.Pp +For example, this command instructs the RabbitMQ broker to ensure the user named +.Qq tonyg +is an administrator: +.sp +.Dl rabbitmqctl set_user_tags tonyg administrator +.Pp +This has no effect when the user logs in via AMQP, but can be used to +permit the user to manage users, virtual hosts and permissions when +the user logs in via some other means (for example with the management +plugin). +.Pp +This command instructs the RabbitMQ broker to remove any tags from the user named +.Qq tonyg : +.sp +.Dl rabbitmqctl set_user_tags tonyg +.\" ------------------------------------ +.It Cm list_users +Lists users. +Each result row will contain the user name followed by a list of the +tags set for that user. +.Pp +For example, this command instructs the RabbitMQ broker to list all users: +.sp +.Dl rabbitmqctl list_users +.El +.Ss Access Control +Note that +.Nm +manages the RabbitMQ internal user database. +Permissions for users from any alternative authorisation backend will +not be visible to +.Nm . +.Bl -tag -width Ds +.\" ------------------------------------ +.It Cm add_vhost Ar vhost +.Bl -tag -width Ds +.It Ar vhost +The name of the virtual host entry to create. +.El +.Pp +Creates a virtual host. +.Pp +For example, this command instructs the RabbitMQ broker to create a new +virtual host called +.Qq test : +.Pp +.Dl rabbitmqctl add_vhost test +.\" ------------------------------------ +.It Cm delete_vhost Ar vhost +.Bl -tag -width Ds +.It Ar vhost +The name of the virtual host entry to delete. +.El +.Pp +Deletes a virtual host. +.Pp +Deleting a virtual host deletes all its exchanges, queues, bindings, +user permissions, parameters and policies. +.Pp +For example, this command instructs the RabbitMQ broker to delete the +virtual host called +.Qq test : +.sp +.Dl rabbitmqctl delete_vhost test +.\" ------------------------------------ +.It Cm list_vhosts Op Ar vhostinfoitem ... +Lists virtual hosts. +.Pp +The +.Ar vhostinfoitem +parameter is used to indicate which virtual host information items to +include in the results. +The column order in the results will match the order of the parameters. +.Ar vhostinfoitem +can take any value from the list that follows: +.Bl -tag -width Ds +.It Cm name +The name of the virtual host with non-ASCII characters escaped as in C. +.It Cm tracing +Whether tracing is enabled for this virtual host. +.El +.Pp +If no +.Ar vhostinfoitem +are specified then the vhost name is displayed. +.Pp +For example, this command instructs the RabbitMQ broker to list all +virtual hosts: +.sp +.Dl rabbitmqctl list_vhosts name tracing +.\" ------------------------------------ +.It Cm set_permissions Oo Fl p Ar vhost Oc Ar user Ar conf Ar write Ar read +.Bl -tag -width Ds +.It Ar vhost +The name of the virtual host to which to grant the user access, +defaulting to +.Qq / . +.It Ar user +The name of the user to grant access to the specified virtual host. +.It Ar conf +A regular expression matching resource names for which the user is +granted configure permissions. +.It Ar write +A regular expression matching resource names for which the user is +granted write permissions. +.It Ar read +A regular expression matching resource names for which the user is +granted read permissions. +.El +.Pp +Sets user permissions. +.Pp +For example, this command instructs the RabbitMQ broker to grant the +user named +.Qq tonyg +access to the virtual host called +.Qq /myvhost , +with configure permissions on all resources whose names starts with +.Qq tonyg- , +and write and read permissions on all resources: +.sp +.Dl rabbitmqctl set_permissions -p /myvhost tonyg Qo ^tonyg-.* Qc Qo .* Qc Qq .* +.\" ------------------------------------ +.It Cm clear_permissions Oo Fl p Ar vhost Oc Ar username +.Bl -tag -width Ds +.It Ar vhost +The name of the virtual host to which to deny the user access, +defaulting to +.Qq / . +.It Ar username +The name of the user to deny access to the specified virtual host. +.El +.Pp +Sets user permissions. +.Pp +For example, this command instructs the RabbitMQ broker to deny the user +named +.Qq tonyg +access to the virtual host called +.Qq /myvhost : +.sp +.Dl rabbitmqctl clear_permissions -p /myvhost tonyg +.\" ------------------------------------ +.It Cm list_permissions Op Fl p Ar vhost +.Bl -tag -width Ds +.It Ar vhost +The name of the virtual host for which to list the users that have been +granted access to it, and their permissions. +Defaults to +.Qq / . +.El +.Pp +Lists permissions in a virtual host. +.Pp +For example, this command instructs the RabbitMQ broker to list all the +users which have been granted access to the virtual host called +.Qq /myvhost , +and the permissions they have for operations on resources in that +virtual host. +Note that an empty string means no permissions granted: +.sp +.Dl rabbitmqctl list_permissions -p /myvhost +.\" ------------------------------------ +.It Cm list_user_permissions Ar username +.Bl -tag -width Ds +.It Ar username +The name of the user for which to list the permissions. +.El +.Pp +Lists user permissions. +.Pp +For example, this command instructs the RabbitMQ broker to list all the +virtual hosts to which the user named +.Qq tonyg +has been granted access, and the permissions the user has for operations +on resources in these virtual hosts: +.sp +.Dl rabbitmqctl list_user_permissions tonyg +.El +.Ss Parameter Management +Certain features of RabbitMQ (such as the federation plugin) are +controlled by dynamic, cluster-wide +.Em parameters. +There are 2 kinds of parameters: parameters scoped to a virtual host and +global parameters. +Each vhost-scoped parameter consists of a component name, a name and a +value. +The component name and name are strings, and the value is an Erlang term. +A global parameter consists of a name and value. +The name is a string and the value is an Erlang term. +Parameters can be set, cleared and listed. +In general you should refer to the documentation for the feature in +question to see how to set parameters. +.Bl -tag -width Ds +.\" ------------------------------------ +.It Cm set_parameter Oo Fl p Ar vhost Oc Ar component_name Ar name Ar value +Sets a parameter. +.Bl -tag -width Ds +.It Ar component_name +The name of the component for which the parameter is being set. +.It Ar name +The name of the parameter being set. +.It Ar value +The value for the parameter, as a JSON term. +In most shells you are very likely to need to quote this. +.El +.Pp +For example, this command sets the parameter +.Qq local_username +for the +.Qq federation +component in the default virtual host to the JSON term +.Qq guest : +.sp +.Dl rabbitmqctl set_parameter federation local_username Qq guest +.\" ------------------------------------ +.It Cm clear_parameter Oo Fl p Ar vhost Oc Ar component_name Ar key +Clears a parameter. +.Bl -tag -width Ds +.It Ar component_name +The name of the component for which the parameter is being cleared. +.It Ar name +The name of the parameter being cleared. +.El +.Pp +For example, this command clears the parameter +.Qq local_username +for the +.Qq federation +component in the default virtual host: +.sp +.Dl rabbitmqctl clear_parameter federation local_username +.\" ------------------------------------ +.It Cm list_parameters Op Fl p Ar vhost +Lists all parameters for a virtual host. +.Pp +For example, this command lists all parameters in the default virtual +host: +.sp +.Dl rabbitmqctl list_parameters +.\" ------------------------------------ +.It Cm set_global_parameter Ar name Ar value +Sets a global runtime parameter. +This is similar to +.Cm set_parameter +but the key-value pair isn't tied to a virtual host. +.Bl -tag -width Ds +.It Ar name +The name of the global runtime parameter being set. +.It Ar value +The value for the global runtime parameter, as a JSON term. +In most shells you are very likely to need to quote this. +.El +.Pp +For example, this command sets the global runtime parameter +.Qq mqtt_default_vhosts +to the JSON term {"O=client,CN=guest":"/"}: +.sp +.Dl rabbitmqctl set_global_parameter mqtt_default_vhosts '{"O=client,CN=guest":"/"}' +.\" ------------------------------------ +.It Cm clear_global_parameter Ar name +Clears a global runtime parameter. +This is similar to +.Cm clear_parameter +but the key-value pair isn't tied to a virtual host. +.Bl -tag -width Ds +.It Ar name +The name of the global runtime parameter being cleared. +.El +.Pp +For example, this command clears the global runtime parameter +.Qq mqtt_default_vhosts : +.sp +.Dl rabbitmqctl clear_global_parameter mqtt_default_vhosts +.\" ------------------------------------ +.It Cm list_global_parameters +Lists all global runtime parameters. +This is similar to +.Cm list_parameters +but the global runtime parameters are not tied to any virtual host. +.Pp +For example, this command lists all global parameters: +.sp +.Dl rabbitmqctl list_global_parameters +.El +.Ss Policy Management +Policies are used to control and modify the behaviour of queues and +exchanges on a cluster-wide basis. +Policies apply within a given vhost, and consist of a name, pattern, +definition and an optional priority. +Policies can be set, cleared and listed. +.Bl -tag -width Ds +.\" ------------------------------------ +.It Cm set_policy Oo Fl p Ar vhost Oc Oo Fl -priority Ar priority Oc Oo Fl -apply-to Ar apply-to Oc Ar name Ar pattern Ar definition +Sets a policy. +.Bl -tag -width Ds +.It Ar name +The name of the policy. +.It Ar pattern +The regular expression, which when matches on a given resources causes +the policy to apply. +.It Ar definition +The definition of the policy, as a JSON term. +In most shells you are very likely to need to quote this. +.It Ar priority +The priority of the policy as an integer. +Higher numbers indicate greater precedence. +The default is 0. +.It Ar apply-to +Which types of object this policy should apply to. +Possible values are: +.Bl -bullet -compact +.It +.Cm queues +.It +.Cm exchanges +.It +.Cm all +.El +The default is +.Cm all .. +.El +.Pp +For example, this command sets the policy +.Qq federate-me +in the default virtual host so that built-in exchanges are federated: +.sp +.Dl rabbitmqctl set_policy federate-me "^amq." '{"federation-upstream-set":"all"}' +.\" ------------------------------------ +.It Cm clear_policy Oo Fl p Ar vhost Oc Ar name +Clears a policy. +.Bl -tag -width Ds +.It Ar name +The name of the policy being cleared. +.El +.Pp +For example, this command clears the +.Qq federate-me +policy in the default virtual host: +.sp +.Dl rabbitmqctl clear_policy federate-me +.\" ------------------------------------ +.It Cm list_policies Op Fl p Ar vhost +Lists all policies for a virtual host. +.Pp +For example, this command lists all policies in the default virtual +host: +.sp +.Dl rabbitmqctl list_policies +.\" ------------------------------------ +.It Cm set_operator_policy Oo Fl p Ar vhost Oc Oo Fl -priority Ar priority Oc Oo Fl -apply-to Ar apply-to Oc Ar name Ar pattern Ar definition +Sets an operator policy that overrides a subset of arguments in user +policies. +Arguments are identical to those of +.Cm set_policy . +.Pp +Supported arguments are: +.Bl -bullet -compact +.It +expires +.It +message-ttl +.It +max-length +.It +max-length-bytes +.El +.\" ------------------------------------ +.It Cm clear_operator_policy Oo Fl p Ar vhost Oc Ar name +Clears an operator policy. +Arguments are identical to those of +.Cm clear_policy . +.\" ------------------------------------ +.It Cm list_operator_policies Op Fl p Ar vhost +Lists operator policy overrides for a virtual host. +Arguments are identical to those of +.Cm list_policies . +.El +.Ss Virtual Host Limits +It is possible to enforce certain limits on virtual hosts. +.Bl -tag -width Ds +.\" ------------------------------------ +.It Cm set_vhost_limits Oo Fl p Ar vhostpath Oc Ar definition +Sets virtual host limits. +.Bl -tag -width Ds +.It Ar definition +The definition of the limits, as a JSON term. +In most shells you are very likely to need to quote this. +.Pp +Recognised limits are: +.Bl -bullet -compact +.It +max-connections +.It +max-queues +.El +.Pp +Use a negative value to specify "no limit". +.El +.Pp +For example, this command limits the max number of concurrent +connections in vhost +.Qq qa_env +to 64: +.sp +.Dl rabbitmqctl set_vhost_limits -p qa_env '{"max-connections": 64}' +.Pp +This command limits the max number of queues in vhost +.Qq qa_env +to 256: +.sp +.Dl rabbitmqctl set_vhost_limits -p qa_env '{"max-queues": 256}' +.Pp +This command clears the max number of connections limit in vhost +.Qq qa_env : +.sp +.Dl rabbitmqctl set_vhost_limits -p qa_env '{"max\-connections": \-1}' +.Pp +This command disables client connections in vhost +.Qq qa_env : +.sp +.Dl rabbitmqctl set_vhost_limits -p qa_env '{"max-connections": 0}' +.\" ------------------------------------ +.It Cm clear_vhost_limits Op Fl p Ar vhostpath +Clears virtual host limits. +.Pp +For example, this command clears vhost limits in vhost +.Qq qa_env : +.sp +.Dl rabbitmqctl clear_vhost_limits -p qa_env +.El +.Ss Server Status +The server status queries interrogate the server and return a list of +results with tab-delimited columns. +Some queries ( +.Cm list_queues , +.Cm list_exchanges , +.Cm list_bindings +and +.Cm list_consumers ) +accept an optional +.Ar vhost +parameter. +This parameter, if present, must be specified immediately after the +query. +.Pp +The +.Cm list_queues , +.Cm list_exchanges +and +.Cm list_bindings +commands accept an optional virtual host parameter for which to display +results. +The default value is +.Qq / . +.Bl -tag -width Ds +.\" ------------------------------------ +.It Cm list_queues Oo Fl p Ar vhost Oc Oo Fl -offline | Fl -online | Fl -local Oc Op Ar queueinfoitem ... +Returns queue details. +Queue details of the +.Qq / +virtual host are returned if the +.Fl p +flag is absent. +The +.Fl p +flag can be used to override this default. +.Pp +Displayed queues can be filtered by their status or location using one +of the following mutually exclusive options: +.Bl -tag -width Ds +.It Fl -offline +List only those durable queues that are not currently available (more +specifically, their master node isn't). +.It Fl -online +List queues that are currently available (their master node is). +.It Fl -local +List only those queues whose master process is located on the current +node. +.El +.Pp +The +.Ar queueinfoitem +parameter is used to indicate which queue information items to include +in the results. +The column order in the results will match the order of the parameters. +.Ar queueinfoitem +can take any value from the list that follows: +.Bl -tag -width Ds +.It Cm name +The name of the queue with non\-ASCII characters escaped as in C. +.It Cm durable +Whether or not the queue survives server restarts. +.It Cm auto_delete +Whether the queue will be deleted automatically when no longer used. +.It Cm arguments +Queue arguments. +.It Cm policy +Policy name applying to the queue. +.It Cm pid +Id of the Erlang process associated with the queue. +.It Cm owner_pid +Id of the Erlang process representing the connection which is the +exclusive owner of the queue. +Empty if the queue is non-exclusive. +.It Cm exclusive +True if queue is exclusive (i.e. has owner_pid), false otherwise. +.It Cm exclusive_consumer_pid +Id of the Erlang process representing the channel of the exclusive +consumer subscribed to this queue. +Empty if there is no exclusive consumer. +.It Cm exclusive_consumer_tag +Consumer tag of the exclusive consumer subscribed to this queue. +Empty if there is no exclusive consumer. +.It Cm messages_ready +Number of messages ready to be delivered to clients. +.It Cm messages_unacknowledged +Number of messages delivered to clients but not yet acknowledged. +.It Cm messages +Sum of ready and unacknowledged messages (queue depth). +.It Cm messages_ready_ram +Number of messages from messages_ready which are resident in ram. +.It Cm messages_unacknowledged_ram +Number of messages from messages_unacknowledged which are resident in +ram. +.It Cm messages_ram +Total number of messages which are resident in ram. +.It Cm messages_persistent +Total number of persistent messages in the queue (will always be 0 for +transient queues). +.It Cm message_bytes +Sum of the size of all message bodies in the queue. +This does not include the message properties (including headers) or any +overhead. +.It Cm message_bytes_ready +Like +.Cm message_bytes +but counting only those messages ready to be delivered to clients. +.It Cm message_bytes_unacknowledged +Like +.Cm message_bytes +but counting only those messages delivered to clients but not yet +acknowledged. +.It Cm message_bytes_ram +Like +.Cm message_bytes +but counting only those messages which are in RAM. +.It Cm message_bytes_persistent +Like +.Cm message_bytes +but counting only those messages which are persistent. +.It Cm head_message_timestamp +The timestamp property of the first message in the queue, if present. +Timestamps of messages only appear when they are in the paged-in state. +.It Cm disk_reads +Total number of times messages have been read from disk by this queue +since it started. +.It Cm disk_writes +Total number of times messages have been written to disk by this queue +since it started. +.It Cm consumers +Number of consumers. +.It Cm consumer_utilisation +Fraction of the time (between 0.0 and 1.0) that the queue is able to +immediately deliver messages to consumers. +This can be less than 1.0 if consumers are limited by network congestion +or prefetch count. +.It Cm memory +Bytes of memory consumed by the Erlang process associated with the +queue, including stack, heap and internal structures. +.It Cm slave_pids +If the queue is mirrored, this gives the IDs of the current slaves. +.It Cm synchronised_slave_pids +If the queue is mirrored, this gives the IDs of the current slaves which +are synchronised with the master - i.e. those which could take over from +the master without message loss. +.It Cm state +The state of the queue. +Normally +.Qq running , +but may be +.Qq Bro syncing, Ar message_count Brc +if the queue is synchronising. +.Pp +Queues which are located on cluster nodes that are currently down will +be shown with a status of +.Qq down +(and most other +.Ar queueinfoitem +will be unavailable). +.El +.Pp +If no +.Ar queueinfoitem +are specified then queue name and depth are displayed. +.Pp +For example, this command displays the depth and number of consumers for +each queue of the virtual host named +.Qq /myvhost +.sp +.Dl rabbitmqctl list_queues -p /myvhost messages consumers +.\" ------------------------------------ +.It Cm list_exchanges Oo Fl p Ar vhost Oc Op Ar exchangeinfoitem ... +Returns exchange details. +Exchange details of the +.Qq / +virtual host are returned if the +.Fl p +flag is absent. +The +.Fl p +flag can be used to override this default. +.Pp +The +.Ar exchangeinfoitem +parameter is used to indicate which exchange information items to +include in the results. +The column order in the results will match the order of the parameters. +.Ar exchangeinfoitem +can take any value from the list that follows: +.Bl -tag -width Ds +.It Cm name +The name of the exchange with non-ASCII characters escaped as in C. +.It Cm type +The exchange type, such as: +.Bl -bullet -compact +.It +direct +.It +topic +.It +headers +.It +fanout +.El +.It Cm durable +Whether or not the exchange survives server restarts. +.It Cm auto_delete +Whether the exchange will be deleted automatically when no longer used. +.It Cm internal +Whether the exchange is internal, i.e. cannot be directly published to +by a client. +.It Cm arguments +Exchange arguments. +.It Cm policy +Policy name for applying to the exchange. +.El +.Pp +If no +.Ar exchangeinfoitem +are specified then exchange name and type are displayed. +.Pp +For example, this command displays the name and type for each exchange +of the virtual host named +.Qq /myvhost : +.sp +.Dl rabbitmqctl list_exchanges -p /myvhost name type +.\" ------------------------------------ +.It Cm list_bindings Oo Fl p Ar vhost Oc Op Ar bindinginfoitem ... +Returns binding details. +By default the bindings for the +.Qq / +virtual host are returned. +The +.Fl p +flag can be used to override this default. +.Pp +The +.Ar bindinginfoitem +parameter is used to indicate which binding information items to include +in the results. +The column order in the results will match the order of the parameters. +.Ar bindinginfoitem +can take any value from the list that follows: +.Bl -tag -width Ds +.It Cm source_name +The name of the source of messages to which the binding is attached. +With non-ASCII characters escaped as in C. +.It Cm source_kind +The kind of the source of messages to which the binding is attached. +Currently always exchange. +With non-ASCII characters escaped as in C. +.It Cm destination_name +The name of the destination of messages to which the binding is +attached. +With non-ASCII characters escaped as in C. +.It Cm destination_kind +The kind of the destination of messages to which the binding is +attached. +With non-ASCII characters escaped as in C. +.It Cm routing_key +The binding's routing key, with non-ASCII characters escaped as in C. +.It Cm arguments +The binding's arguments. +.El +.Pp +If no +.Ar bindinginfoitem +are specified then all above items are displayed. +.Pp +For example, this command displays the exchange name and queue name of +the bindings in the virtual host named +.Qq /myvhost +.sp +.Dl rabbitmqctl list_bindings -p /myvhost exchange_name queue_name +.\" ------------------------------------ +.It Cm list_connections Op Ar connectioninfoitem ... +Returns TCP/IP connection statistics. +.Pp +The +.Ar connectioninfoitem +parameter is used to indicate which connection information items to +include in the results. +The column order in the results will match the order of the parameters. +.Ar connectioninfoitem +can take any value from the list that follows: +.Bl -tag -width Ds +.It Cm pid +Id of the Erlang process associated with the connection. +.It Cm name +Readable name for the connection. +.It Cm port +Server port. +.It Cm host +Server hostname obtained via reverse DNS, or its IP address if reverse +DNS failed or was not enabled. +.It Cm peer_port +Peer port. +.It Cm peer_host +Peer hostname obtained via reverse DNS, or its IP address if reverse DNS +failed or was not enabled. +.It Cm ssl +Boolean indicating whether the connection is secured with SSL. +.It Cm ssl_protocol +SSL protocol (e.g.\& +.Qq tlsv1 ) . +.It Cm ssl_key_exchange +SSL key exchange algorithm (e.g.\& +.Qq rsa ) . +.It Cm ssl_cipher +SSL cipher algorithm (e.g.\& +.Qq aes_256_cbc ) . +.It Cm ssl_hash +SSL hash function (e.g.\& +.Qq sha ) . +.It Cm peer_cert_subject +The subject of the peer's SSL certificate, in RFC4514 form. +.It Cm peer_cert_issuer +The issuer of the peer's SSL certificate, in RFC4514 form. +.It Cm peer_cert_validity +The period for which the peer's SSL certificate is valid. +.It Cm state +Connection state; one of: +.Bl -bullet -compact +.It +starting +.It +tuning +.It +opening +.It +running +.It +flow +.It +blocking +.It +blocked +.It +closing +.It +closed +.El +.It Cm channels +Number of channels using the connection. +.It Cm protocol +Version of the AMQP protocol in use; currently one of: +.Bl -bullet -compact +.It +{0,9,1} +.It +{0,8,0} +.El +.Pp +Note that if a client requests an AMQP 0-9 connection, we treat it as +AMQP 0-9-1. +.It Cm auth_mechanism +SASL authentication mechanism used, such as +.Qq PLAIN . +.It Cm user +Username associated with the connection. +.It Cm vhost +Virtual host name with non-ASCII characters escaped as in C. +.It Cm timeout +Connection timeout / negotiated heartbeat interval, in seconds. +.It Cm frame_max +Maximum frame size (bytes). +.It Cm channel_max +Maximum number of channels on this connection. +.It Cm client_properties +Informational properties transmitted by the client during connection +establishment. +.It Cm recv_oct +Octets received. +.It Cm recv_cnt +Packets received. +.It Cm send_oct +Octets send. +.It Cm send_cnt +Packets sent. +.It Cm send_pend +Send queue size. +.It Cm connected_at +Date and time this connection was established, as timestamp. +.El +.Pp +If no +.Ar connectioninfoitem +are specified then user, peer host, peer port, time since flow control +and memory block state are displayed. +.Pp +For example, this command displays the send queue size and server port +for each connection: +.sp +.Dl rabbitmqctl list_connections send_pend port +.\" ------------------------------------ +.It Cm list_channels Op Ar channelinfoitem ... +Returns information on all current channels, the logical containers +executing most AMQP commands. +This includes channels that are part of ordinary AMQP connections, and +channels created by various plug-ins and other extensions. +.Pp +The +.Ar channelinfoitem +parameter is used to indicate which channel information items to include +in the results. +The column order in the results will match the order of the parameters. +.Ar channelinfoitem +can take any value from the list that follows: +.Bl -tag -width Ds +.It Cm pid +Id of the Erlang process associated with the connection. +.It Cm connection +Id of the Erlang process associated with the connection to which the +channel belongs. +.It Cm name +Readable name for the channel. +.It Cm number +The number of the channel, which uniquely identifies it within a +connection. +.It Cm user +Username associated with the channel. +.It Cm vhost +Virtual host in which the channel operates. +.It Cm transactional +True if the channel is in transactional mode, false otherwise. +.It Cm confirm +True if the channel is in confirm mode, false otherwise. +.It Cm consumer_count +Number of logical AMQP consumers retrieving messages via the channel. +.It Cm messages_unacknowledged +Number of messages delivered via this channel but not yet acknowledged. +.It Cm messages_uncommitted +Number of messages received in an as yet uncommitted transaction. +.It Cm acks_uncommitted +Number of acknowledgements received in an as yet uncommitted transaction. +.It Cm messages_unconfirmed +Number of published messages not yet confirmed. +On channels not in confirm mode, this remains 0. +.It Cm prefetch_count +QoS prefetch limit for new consumers, 0 if unlimited. +.It Cm global_prefetch_count +QoS prefetch limit for the entire channel, 0 if unlimited. +.El +.Pp +If no +.Ar channelinfoitem +are specified then pid, user, consumer_count, and +messages_unacknowledged are assumed. +.Pp +For example, this command displays the connection process and count of +unacknowledged messages for each channel: +.sp +.Dl rabbitmqctl list_channels connection messages_unacknowledged +.\" ------------------------------------ +.It Cm list_consumers Op Fl p Ar vhost +Lists consumers, i.e. subscriptions to a queue\'s message stream. +Each line printed shows, separated by tab characters, the name of +the queue subscribed to, the id of the channel process via which the +subscription was created and is managed, the consumer tag which uniquely +identifies the subscription within a channel, a boolean indicating +whether acknowledgements are expected for messages delivered to this +consumer, an integer indicating the prefetch limit (with 0 meaning +.Qq none ) , +and any arguments for this consumer. +.\" ------------------------------------ +.It Cm status +Displays broker status information such as the running applications on +the current Erlang node, RabbitMQ and Erlang versions, OS name, memory +and file descriptor statistics. +(See the +.Cm cluster_status +command to find out which nodes are clustered and running.) +.Pp +For example, this command displays information about the RabbitMQ +broker: +.sp +.Dl rabbitmqctl status +.\" ------------------------------------ +.It Cm node_health_check +Health check of the RabbitMQ node. +Verifies the rabbit application is running, list_queues and +list_channels return, and alarms are not set. +.Pp +For example, this command performs a health check on the RabbitMQ node: +.sp +.Dl rabbitmqctl node_health_check -n rabbit@stringer +.\" ------------------------------------ +.It Cm environment +Displays the name and value of each variable in the application +environment for each running application. +.\" ------------------------------------ +.It Cm report +Generate a server status report containing a concatenation of all server +status information for support purposes. +The output should be redirected to a file when accompanying a support +request. +.Pp +For example, this command creates a server report which may be attached +to a support request email: +.sp +.Dl rabbitmqctl report > server_report.txt +.\" ------------------------------------ +.It Cm eval Ar expr +Evaluate an arbitrary Erlang expression. +.Pp +For example, this command returns the name of the node to which +.Nm +has connected: +.sp +.Dl rabbitmqctl eval Qq node(). +.El +.Ss Miscellaneous +.Bl -tag -width Ds +.\" ------------------------------------ +.It Cm close_connection Ar connectionpid Ar explanation +.Bl -tag -width Ds +.It Ar connectionpid +Id of the Erlang process associated with the connection to close. +.It Ar explanation +Explanation string. +.El +.Pp +Instructs the broker to close the connection associated with the Erlang +process id +.Ar connectionpid +(see also the +.Cm list_connections +command), passing the +.Ar explanation +string to the connected client as part of the AMQP connection shutdown +protocol. +.Pp +For example, this command instructs the RabbitMQ broker to close the connection associated with the Erlang process id +.Qq <rabbit@tanto.4262.0> , +passing the explanation +.Qq go away +to the connected client: +.sp +.Dl rabbitmqctl close_connection Qo <rabbit@tanto.4262.0> Qc Qq go away +.\" ------------------------------------ +.It Cm trace_on Op Fl p Ar vhost +.Bl -tag -width Ds +.It Ar vhost +The name of the virtual host for which to start tracing. +.El +.Pp +Starts tracing. +Note that the trace state is not persistent; it will revert to being off +if the server is restarted. +.\" ------------------------------------ +.It Cm trace_off Op Fl p Ar vhost +.Bl -tag -width Ds +.It Ar vhost +The name of the virtual host for which to stop tracing. +.El +.Pp +Stops tracing. +.\" ------------------------------------ +.It Cm set_vm_memory_high_watermark Ar fraction +.Bl -tag -width Ds +.It Ar fraction +The new memory threshold fraction at which flow control is triggered, as +a floating point number greater than or equal to 0. +.El +.\" ------------------------------------ +.It Cm set_vm_memory_high_watermark absolute Ar memory_limit +.Bl -tag -width Ds +.It Ar memory_limit +The new memory limit at which flow control is triggered, expressed in +bytes as an integer number greater than or equal to 0 or as a string +with memory units (e.g. 512M or 1G). +Available units are: +.Bl -tag -width Ds +.It Cm k , Cm kiB +kibibytes (2^10 bytes) +.It Cm M , Cm MiB +mebibytes (2^20 bytes) +.It Cm G , Cm GiB +gibibytes (2^30 bytes) +.It Cm kB +kilobytes (10^3 bytes) +.It Cm MB +megabytes (10^6 bytes) +.It Cm GB +gigabytes (10^9 bytes) +.El +.El +.\" ------------------------------------ +.It Cm set_disk_free_limit Ar disk_limit +.Bl -tag -width Ds +.It Ar disk_limit +Lower bound limit as an integer in bytes or a string with memory units +(see vm_memory_high_watermark), e.g. 512M or 1G. +Once free disk space reaches the limit, a disk alarm will be set. +.El +.\" ------------------------------------ +.It Cm set_disk_free_limit mem_relative Ar fraction +.Bl -tag -width Ds +.It Ar fraction +Limit relative to the total amount available RAM as a non-negative +floating point number. +Values lower than 1.0 can be dangerous and should be used carefully. +.El +.\" ------------------------------------ +.It Cm encode Oo Fl -decode Oc Oo Ar value Oc Oo Ar passphrase Oc Oo Fl -list-ciphers Oc Oo Fl -list-hashes Oc Oo Fl -cipher Ar cipher Oc Oo Fl -hash Ar hash Oc Op Fl -iterations Ar iterations +.Bl -tag -width Ds +.It Fl -decode +Flag to decrypt the input value. +.Pp +For example: +.sp +.Dl rabbitmqctl encode --decode '{encrypted,<<"...">>}' mypassphrase +.It Ar value Ar passphrase +Value to encrypt/decrypt and passphrase. +.Pp +For example: +.sp +.Dl rabbitmqctl encode '<<"guest">>' mypassphrase +.sp +.Dl rabbitmqctl encode --decode '{encrypted,<<"...">>}' mypassphrase +.It Fl -list-ciphers +Flag to list the supported ciphers. +.Pp +For example: +.sp +.Dl rabbitmqctl encode --list-ciphers +.It Fl -list-hashes +Flag to list the supported hash algorithms. +.Pp +For example: +.sp +.Dl rabbitmqctl encode --list-hashes +.It Fl -cipher Ar cipher Fl -hash Ar hash Fl -iterations Ar iterations +Options to specify the encryption settings. +They can be used independently. +.Pp +For example: +.sp +.Dl rabbitmqctl encode --cipher blowfish_cfb64 --hash sha256 --iterations 10000 '<<"guest">>' mypassphrase +.El +.El +.\" ------------------------------------------------------------------ +.Sh SEE ALSO +.\" ------------------------------------------------------------------ +.Xr rabbitmq-env.conf 5 , +.Xr rabbitmq-echopid 8 , +.Xr rabbitmq-plugins 8 , +.Xr rabbitmq-server 8 , +.Xr rabbitmq-service 8 +.\" ------------------------------------------------------------------ +.Sh AUTHOR +.\" ------------------------------------------------------------------ +.An The RabbitMQ Team Aq Mt info@rabbitmq.com diff --git a/docs/remove-namespaces.xsl b/docs/remove-namespaces.xsl deleted file mode 100644 index 7f7f3c12b2..0000000000 --- a/docs/remove-namespaces.xsl +++ /dev/null @@ -1,18 +0,0 @@ -<?xml version='1.0'?> -<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" - xmlns:doc="http://www.rabbitmq.com/namespaces/ad-hoc/doc" - xmlns="http://www.w3.org/1999/xhtml" - version='1.0'> - -<xsl:output method="xml" /> - - <!-- Copy every element through with local name only --> - <xsl:template match="*"> - <xsl:element name="{local-name()}" namespace=""> - <xsl:apply-templates select="@*|node()"/> - </xsl:element> - </xsl:template> - - <!-- Copy every attribute through --> - <xsl:template match="@*"><xsl:copy/></xsl:template> -</xsl:stylesheet> diff --git a/docs/usage.xsl b/docs/usage.xsl deleted file mode 100644 index 0d3cb6f235..0000000000 --- a/docs/usage.xsl +++ /dev/null @@ -1,82 +0,0 @@ -<?xml version='1.0'?> -<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" - version='1.0'> - -<xsl:param name="modulename"/> - -<xsl:output method="text" - encoding="UTF-8" - indent="no"/> -<xsl:strip-space elements="*"/> -<xsl:preserve-space elements="cmdsynopsis arg group" /> - -<xsl:template match="/"> -<!-- Pull out cmdsynopsis to show the command usage line. -->%% Generated, do not edit! --module(<xsl:value-of select="$modulename" />). --export([usage/0]). -usage() -> %QUOTE%Usage: -<xsl:value-of select="refentry/refsynopsisdiv/cmdsynopsis/command"/> -<xsl:text> </xsl:text> -<xsl:for-each select="refentry/refsynopsisdiv/cmdsynopsis/arg"> - <xsl:apply-templates select="." /> - <xsl:text> </xsl:text> -</xsl:for-each> - -<xsl:text> </xsl:text> - -<!-- List options (any variable list in a section called "Options"). --> -<xsl:for-each select=".//*[title='Options']/variablelist"> - <xsl:if test="position() = 1"> Options: </xsl:if> - <xsl:for-each select="varlistentry"> - <xsl:text> </xsl:text> - <xsl:for-each select=".//term"> - <xsl:value-of select="."/> - <xsl:if test="not(position() = last())">, </xsl:if> - </xsl:for-each><xsl:text> </xsl:text> - </xsl:for-each> -</xsl:for-each> - -<!-- Any paragraphs which have been marked as role="usage" (principally for global flags). --> -<xsl:text> </xsl:text> -<xsl:for-each select=".//*[title='Options']//para[@role='usage']"> -<xsl:value-of select="normalize-space(.)"/><xsl:text> </xsl:text> -</xsl:for-each> - -<!-- List commands (any first-level variable list in a section called "Commands"). --> -<xsl:for-each select=".//*[title='Commands']/variablelist | .//*[title='Commands']/refsect2/variablelist"> - <xsl:if test="position() = 1">Commands: </xsl:if> - <xsl:for-each select="varlistentry"> - <xsl:text> </xsl:text> - <xsl:apply-templates select="term"/> - <xsl:text> </xsl:text> - </xsl:for-each> - <xsl:text> </xsl:text> -</xsl:for-each> - -<xsl:apply-templates select=".//*[title='Commands']/refsect2" mode="command-usage" /> -%QUOTE%. -</xsl:template> - -<!-- Option lists in command usage --> -<xsl:template match="varlistentry[@role='usage-has-option-list']" mode="command-usage"><<xsl:value-of select="term/cmdsynopsis/arg[@role='usage-option-list']/replaceable"/>> must be a member of the list [<xsl:for-each select="listitem/variablelist/varlistentry"><xsl:apply-templates select="term"/><xsl:if test="not(position() = last())">, </xsl:if></xsl:for-each>].<xsl:text> </xsl:text></xsl:template> - -<!-- Usage paras in command usage --> -<xsl:template match="para[@role='usage']" mode="command-usage"> -<xsl:value-of select="normalize-space(.)"/><xsl:text> </xsl:text> -</xsl:template> - -<!-- Don't show anything else in command usage --> -<xsl:template match="text()" mode="command-usage"/> - -<xsl:template match="group[@choice='opt']"> - <xsl:text>[</xsl:text> - <xsl:for-each select="arg"> - <xsl:apply-templates/> - <xsl:if test="not(position() = last())"><xsl:text>|</xsl:text></xsl:if> - </xsl:for-each> - <xsl:text>]</xsl:text> -</xsl:template> -<xsl:template match="arg[@choice='opt']">[<xsl:apply-templates/>]</xsl:template> -<xsl:template match="replaceable"><<xsl:value-of select="."/>></xsl:template> - -</xsl:stylesheet> |