diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/examples-to-end.xsl | 43 | ||||
| -rw-r--r-- | docs/rabbitmqctl.1.pod | 536 | ||||
| -rw-r--r-- | docs/rabbitmqctl.1.xml | 996 | ||||
| -rw-r--r-- | docs/usage.xsl | 65 |
4 files changed, 1104 insertions, 536 deletions
diff --git a/docs/examples-to-end.xsl b/docs/examples-to-end.xsl new file mode 100644 index 0000000000..adcab2539d --- /dev/null +++ b/docs/examples-to-end.xsl @@ -0,0 +1,43 @@ +<?xml version='1.0'?> +<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" + xmlns:exsl="http://exslt.org/common" + xmlns:ng="http://docbook.org/docbook-ng" + xmlns:db="http://docbook.org/ns/docbook" + exclude-result-prefixes="exsl ng db" + 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" /> + +<!-- Don't copy exmaples 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> + <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']"/> + </listitem> + </varlistentry> +</xsl:for-each> + </variablelist> + </refsect1> +</refentry> +</xsl:template> + +</xsl:stylesheet> + diff --git a/docs/rabbitmqctl.1.pod b/docs/rabbitmqctl.1.pod deleted file mode 100644 index e26767ab4f..0000000000 --- a/docs/rabbitmqctl.1.pod +++ /dev/null @@ -1,536 +0,0 @@ -=head1 NAME - -rabbitmqctl - command line tool for managing a RabbitMQ broker - -=head1 SYNOPSIS - -rabbitmqctl [-n I<node>] I<<command>> [command options] - -=head1 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. - -rabbitmqctl is a command line tool for managing a RabbitMQ broker. -It performs all actions by connecting to one of the broker's nodes. - - -=head1 OPTIONS - -=over - -=item B<-n> I<node> - -Default node is C<rabbit@server>, where server is the local host. On -a host named C<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 hostname -s is usually the correct suffix to use after the -"@" sign. See rabbitmq-server(1) for details of configuring the -RabbitMQ broker. - -=item B<-q> - -Quiet output mode is selected with the B<-q> flag. Informational -messages are suppressed when quiet mode is in effect. - -=back - -=head1 COMMANDS - -=head2 APPLICATION AND CLUSTER MANAGEMENT - -=over - -=item stop - -Stop the Erlang node on which RabbitMQ broker is running. - -=item stop_app - -Stop the RabbitMQ application, leaving the Erlang node running. This -command is typically run prior to performing other management actions -that require the RabbitMQ application to be stopped, e.g. I<reset>. - -=item start_app - -Start the RabbitMQ application. This command is typically run prior -to performing other management actions that require the RabbitMQ -application to be stopped, e.g. I<reset>. - -=item status - -Display various information about the RabbitMQ broker, such as whether -the RabbitMQ application on the current node, its version number, what -nodes are part of the broker, which of these are running. - -=item reset - -Return a RabbitMQ node to its virgin state. Removes the node from any -cluster it belongs to, removes all data from the management database, -such as configured users, vhosts and deletes all persistent messages. - -=item force_reset - -The same as I<reset> command, but 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. - -=item rotate_logs [suffix] - -Instruct the RabbitMQ node to rotate the log files. The RabbitMQ -broker will attempt to append the current contents of the log file to -the file with the name composed of the original name and the -suffix. It will create a new file if such a file does not already -exist. When no I<suffix> is specified, the empty log file is simply -created at the original location; no rotation takes place. When an -error occurs while appending the contents of the old log file, the -operation behaves in the same way as if no I<suffix> was specified. -This command might be helpful when you are e.g. writing your own -logrotate script and you do not want to restart the RabbitMQ node. - -=item cluster I<clusternode> ... - -Instruct the node to become member of a cluster with the specified -nodes determined by I<clusternode> option(s). See -L<http://www.rabbitmq.com/clustering.html> for more information about -clustering. - -=item close_connection I<connectionpid> I<explanation> - -Instruct the broker to close the connection associated with the Erlang -process id I<connectionpid> (see also the I<list_connections> -command), passing the I<explanation> string to the connected client as -part of the AMQP connection shutdown protocol. - -=back - -=head2 USER MANAGEMENT - -=over - -=item add_user I<username> I<password> - -Create a user named I<username> with (initial) password I<password>. - -=item delete_user I<username> - -Delete the user named I<username>. - -=item change_password I<username> I<newpassword> - -Change the password for the user named I<username> to I<newpassword>. - -=item list_users - -List all users, one per line. - -=back - -=head2 ACCESS CONTROL - -=over - -=item add_vhost I<vhostpath> - -Create a new virtual host called I<vhostpath>. - -=item delete_vhost I<vhostpath> - -Delete a virtual host I<vhostpath>. This command deletes also all its -exchanges, queues and user mappings. - -=item list_vhosts - -List all virtual hosts, one per line. - -=item set_permissions [-p I<vhostpath>] I<username> I<regexp> I<regexp> I<regexp> - -Set the permissions for the user named I<username> in the virtual host -I<vhostpath>, granting I<configure>, I<write> and I<read> access to -resources with names matching the first, second and third I<regexp>, -respectively. - -=item clear_permissions [-p I<vhostpath>] I<username> - -Remove the permissions for the user named I<username> in the virtual -host I<vhostpath>. - -=item list_permissions [-p I<vhostpath>] - -List all the users and their permissions in the virtual host -I<vhostpath>. Each output line contains the username and their -I<configure>, I<write> and I<read> access regexps, separated by tab -characters. - -=item list_user_permissions I<username> - -List the permissions of the user named I<username> across all virtual -hosts. - -=back - -=head2 SERVER STATUS - -=over - -=item list_queues [-p I<vhostpath>] [I<queueinfoitem> ...] - -List queue information by virtual host. Each line printed -describes a queue, with the requested I<queueinfoitem> values -separated by tab characters. If no I<queueinfoitem>s are -specified then I<name> and I<messages> are assumed. - -=back - -=head3 Queue information items - -=over - -=item name - -name of the queue - -=item durable - -whether the queue survives server restarts - -=item auto_delete - -whether the queue will be deleted when no longer used - -=item arguments - -queue arguments - -=item pid - -id of the Erlang process associated with the queue - -=item owner_pid - -id of the Erlang process representing the connection which is the -exclusive owner of the queue, or empty if the queue is non-exclusive - -=item exclusive_consumer_pid - -id of the Erlang process representing the channel of the exclusive -consumer subscribed to this queue, or empty if there is no exclusive -consumer - -=item exclusive_consumer_tag - -consumer tag of the exclusive consumer subscribed to this queue, or -empty if there is no exclusive consumer - -=item messages_ready - -number of messages ready to be delivered to clients - -=item messages_unacknowledged - -number of messages delivered to clients but not yet acknowledged - -=item messages_uncommitted - -number of messages published in as yet uncommitted transactions - -=item messages - -sum of ready, unacknowledged and uncommitted messages - -=item acks_uncommitted - -number of acknowledgements received in as yet uncommitted transactions - -=item consumers - -number of consumers - -=item transactions - -number of transactions - -=item memory - -bytes of memory consumed by the Erlang process for the queue, -including stack, heap and internal structures - -=back - -=over - -=item list_exchanges [-p I<vhostpath>] [I<exchangeinfoitem> ...] - -List queue information by virtual host. Each line printed describes an -exchange, with the requested I<exchangeinfoitem> values separated by -tab characters. If no I<exchangeinfoitem>s are specified then I<name> -and I<type> are assumed. - -=back - -=head3 Exchange information items - -=over - -=item name - -name of the exchange - -=item type - -exchange type (B<direct>, B<topic>, B<fanout>, or B<headers>) - -=item durable - -whether the exchange survives server restarts - -=item auto_delete - -whether the exchange is deleted when no longer used - -=item arguments - -exchange arguments - -=back - -=over - -=item list_bindings [-p I<vhostpath>] - -List bindings by virtual host. Each line printed describes a binding, -with the exchange name, queue name, routing key and arguments, -separated by tab characters. - -=item list_connections [I<connectioninfoitem> ...] - -List current AMQP connections. Each line printed describes a -connection, with the requested I<connectioninfoitem> values separated -by tab characters. If no I<connectioninfoitem>s are specified then -I<user>, I<peer_address>, I<peer_port> and I<state> are assumed. - -=back - -=head3 Connection information items - -=over - -=item pid - -id of the Erlang process associated with the connection - -=item address - -server IP number - -=item port - -server port - -=item peer_address - -peer address - -=item peer_port - -peer port - -=item state - -connection state (B<pre-init>, B<starting>, B<tuning>, B<opening>, -B<running>, B<closing>, B<closed>) - -=item channels - -number of channels using the connection - -=item user - -username associated with the connection - -=item vhost - -virtual host - -=item timeout - -connection timeout - -=item frame_max - -maximum frame size (bytes) - -=item client_properties - -informational properties transmitted by the client during connection -establishment - -=item recv_oct - -octets received - -=item recv_cnt - -packets received - -=item send_oct - -octets sent - -=item send_cnt - -packets sent - -=item send_pend - -send queue size - -=back - -=over - -=item list_channels [I<channelinfoitem> ...] - -List channel information. Each line printed describes a channel, with -the requested I<channelinfoitem> values separated by tab characters. -If no I<channelinfoitem>s are specified then I<pid>, I<user>, -I<transactional>, I<consumer_count>, and I<messages_unacknowledged> -are assumed. - -The list includes channels which are part of ordinary AMQP connections -(as listed by list_connections) and channels created by various -plug-ins and other extensions. - -=back - -=head3 Channel information items - -=over - -=item pid - -id of the Erlang process associated with the channel - -=item connection - -id of the Erlang process associated with the connection to which the -channel belongs - -=item number - -the number of the channel, which uniquely identifies it within a -connection - -=item user - -username associated with the channel - -=item vhost - -virtual host in which the channel operates - -=item transactional - -true if the channel is in transactional mode, false otherwise - -=item consumer_count - -number of logical AMQP consumers retrieving messages via the channel - -=item messages_unacknowledged - -number of messages delivered via this channel but not yet acknowledged - -=item acks_uncommitted - -number of acknowledgements received in an as yet uncommitted -transaction - -=item prefetch_count - -QoS prefetch count limit in force, 0 if unlimited - -=back - -=item list_consumers - -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, and a boolean -indicating whether acknowledgements are expected for messages -delivered to this consumer. - -=back - -The list_queues, list_exchanges, list_bindings and list_consumers -commands accept an optional virtual host parameter for which to -display results, defaulting to I<"/">. The default can be overridden -with the B<-p> flag. - -=head1 OUTPUT ESCAPING - -Various items that may appear in the output of rabbitmqctl can contain -arbitrary octets. If a octet corresponds to a non-printing ASCII -character (values 0 to 31, and 127), it will be escaped in the output, -using a sequence consisting of a backslash character followed by three -octal digits giving the octet's value (i.e., as used in string -literals in the C programming language). An octet corresponding to -the backslash character (i.e. with value 92) will be escaped using a -sequence of two backslash characters. Octets with a value of 128 or -above are not escaped, in order to preserve strings encoded with -UTF-8. - -The items to which this escaping scheme applies are: - -=over - -=item * -Usernames - -=item * -Virtual host names - -=item * -Queue names - -=item * -Exchange names - -=item * -Regular expressions used for access control - -=back - -=head1 EXAMPLES - -Create a user named foo with (initial) password bar at the Erlang node -rabbit@test: - - rabbitmqctl -n rabbit@test add_user foo bar - -Grant user named foo access to the virtual host called test at the -default Erlang node: - - rabbitmqctl map_user_vhost foo test - -Append the current logs' content to the files with ".1" suffix and reopen -them: - - rabbitmqctl rotate_logs .1 - -=head1 SEE ALSO - -rabbitmq.conf(5), rabbitmq-multi(1), rabbitmq-server(1) - -=head1 AUTHOR - -The RabbitMQ Team <info@rabbitmq.com> - -=head1 REFERENCES - -RabbitMQ Web Site: L<http://www.rabbitmq.com> diff --git a/docs/rabbitmqctl.1.xml b/docs/rabbitmqctl.1.xml new file mode 100644 index 0000000000..f2d49ba83d --- /dev/null +++ b/docs/rabbitmqctl.1.xml @@ -0,0 +1,996 @@ +<?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>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">-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> + </refsect1> + + <refsect1> + <title>Options</title> + <variablelist> + <varlistentry> + <term><option>-n</option> <replaceable>node</replaceable></term> + <listitem> + <para> + 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><option>-q</option></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> + </variablelist> + <para> + Flags must precede all other parameters to <command>rabbitmqctl</command>. + </para> + </refsect1> + + <refsect1> + <title>Commands</title> + + <refsect2> + <title>Application and Cluster Management</title> + + <variablelist> + <varlistentry> + <term>stop</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 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 id="stop_app"> + <term>stop_app</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>start_app</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>status</term> + <listitem> + <para> + Displays various information about the RabbitMQ broker, + such as whether the RabbitMQ application on the current + node, its version number, what nodes are part of the + broker, which of these are 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 id="reset"> + <term>reset</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>force_reset</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>rotate_logs <replaceable>suffix</replaceable></term> + <listitem> + <para> + Instruct the RabbitMQ node to rotate the log files. + </para> + <para> + The RabbitMQ broker will attempt to append the current contents + of the log file to the file with name composed of the original + name and the suffix. + It will create a new file if such a file does not already exist. + When no <option>suffix</option> is specified, the empty log file is + simply created at the original location; no rotation takes place. + </para> + <para> + When an error occurs while appending the contents of the old log + file, the operation behaves in the same way as if no <option>suffix</option> was + specified. + </para> + <para> + This command might be helpful when you are e.g. writing your + own logrotate script and you do not want to restart the RabbitMQ + node. + </para> + <para role="example-prefix">For example:</para> + <screen role="example">rabbitmqctl rotate_logs .1</screen> + <para role="example"> + This command instructs the RabbitMQ node to append the current content + of the log files to the files with names consisting of the original logs' + names and ".1" suffix, e.g. rabbit.log.1. Finally, the old log files are reopened. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2> + <title>Cluster management</title> + + <variablelist> + <varlistentry> + <term>cluster <replaceable>clusternode</replaceable></term> + <listitem> + <variablelist> + <varlistentry> + <term>clusternode</term> + <listitem><para>Subset of the nodes of the cluster to which this node should be connected.</para></listitem> + </varlistentry> + </variablelist> + <para> + Instruct the node to become member of a cluster with the + specified nodes. + </para> + <para> + Cluster nodes can be of two types: disk or ram. Disk nodes + replicate data in ram and on disk, 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 and are mainly used for + scalability. A cluster must always have at least one disk node. + </para> + <para> + If the current node is to become a disk node it needs to + appear in the cluster node list. Otherwise it becomes a + ram node. If the node list is empty or only contains the + current node then the node becomes a standalone, + i.e. non-clustered, (disk) node. + </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 specified nodes, thus + becoming an active node in the cluster comprising those + nodes (and possibly others). + </para> + <para> + The list of nodes does not have to contain all the + cluster's nodes; a subset is sufficient. Also, clustering + generally succeeds as long as at least one of the + specified nodes is active. Hence adjustments to the list + are only necessary if the cluster configuration is to be + altered radically. + </para> + <para> + For this command to succeed the RabbitMQ application must + have been stopped, e.g. with <link linkend="stop_app"><command>stop_app</command></link>. Furthermore, + turning a standalone node into a clustered node requires + the node be <link linkend="reset"><command>reset</command></link> first, + in order to avoid accidental destruction of data with the + <command>cluster</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 cluster rabbit@tanto hare@elena</screen> + <para role="example"> + This command instructs the RabbitMQ node to join the + cluster with nodes <command>rabbit@tanto</command> and + <command>hare@elena</command>. If the node is one of these then + it becomes a disk node, otherwise a ram node. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2> + <title>Closing individual connections</title> + + <variablelist> + <varlistentry> + <term>close_connection <replaceable>connectionpid</replaceable> <replaceable>explanation</replaceable></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> + </variablelist> + </refsect2> + + <refsect2> + <title>User management</title> + + <variablelist> + <varlistentry> + <term>add_user <replaceable>username</replaceable> <replaceable>password</replaceable></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 + user named <command>tonyg</command> with (initial) password + <command>changeit</command>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>delete_user <replaceable>username</replaceable></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>change_password <replaceable>username</replaceable> <replaceable>newpassword</replaceable></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>list_users</term> + <listitem> + <para>Lists users</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> + + <variablelist> + <varlistentry> + <term>add_vhost <replaceable>vhostpath</replaceable></term> + <listitem> + <variablelist> + <varlistentry> + <term>vhostpath</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>delete_vhost <replaceable>vhostpath</replaceable></term> + <listitem> + <variablelist> + <varlistentry> + <term>vhostpath</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, user mappings and associated permissions. + </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> + <term>list_vhosts</term> + <listitem> + <para> + Lists virtual hosts. + </para> + <para role="example-prefix">For example:</para> + <screen role="example">rabbitmqctl list_vhosts</screen> + <para role="example"> + This command instructs the RabbitMQ broker to list all + virtual hosts. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>set_permissions <option>-p <replaceable>vhostpath</replaceable></option> <replaceable>username</replaceable> <replaceable>regexp</replaceable> <replaceable>regexp</replaceable> <replaceable>regexp</replaceable></term> + <listitem> + <variablelist> + <varlistentry> + <term>vhostpath</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>username</term> + <listitem><para>The name of the user to grant access to the specified virtual host.</para></listitem> + </varlistentry> + <varlistentry> + <term>regexp</term> + <listitem><para>The regular expressions for matching resource names for which the user is granted configure, write and read permissions, respectively.</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>clear_permissions <option>-p <replaceable>vhostpath</replaceable></option> <replaceable>username</replaceable></term> + <listitem> + <variablelist> + <varlistentry> + <term>vhostpath</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>list_permissions <option>-p <replaceable>vhostpath</replaceable></option></term> + <listitem> + <variablelist> + <varlistentry> + <term>vhostpath</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. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>list_user_permissions <option>-p <replaceable>vhostpath</replaceable></option></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>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> + <variablelist> + <varlistentry> + <term>list_queues <option>-p <replaceable>vhostpath</replaceable></option> <option><replaceable>queueinfoitem</replaceable> ...</option></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> + 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. If no + <command>queueinfoitem</command>s are specified then queue name and depth are + displayed. <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 URL-escaped.</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>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_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_uncommitted</term> + <listitem><para>Number of messages published in as yet uncommitted transactions</para></listitem> + </varlistentry> + <varlistentry> + <term>messages</term> + <listitem><para>Sum of ready, unacknowledged and uncommitted messages + (queue depth).</para></listitem> + </varlistentry> + <varlistentry> + <term>acks_uncommitted</term> + <listitem><para>Number of acknowledgements received in as yet uncommitted + transactions.</para></listitem> + </varlistentry> + <varlistentry> + <term>consumers</term> + <listitem><para>Number of consumers.</para></listitem> + </varlistentry> + <varlistentry> + <term>transactions</term> + <listitem><para>Number of transactions.</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> + </variablelist> + + <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> + <term>list_exchanges <option>-p <replaceable>vhostpath</replaceable></option> <option><replaceable>queueinfoitem</replaceable> ...</option></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. If no + <command>exchangeinfoitem</command>s are specified then exchange name and type are + displayed. <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 URL-escaped.</para></listitem> + </varlistentry> + <varlistentry> + <term>type</term> + <listitem><para>The exchange type (one of [<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>arguments</term> + <listitem><para>Exchange arguments.</para></listitem> + </varlistentry> + </variablelist> + <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> + </variablelist> + + <variablelist> + <varlistentry> + <term>list_bindings <option>-p <replaceable>vhostpath</replaceable></option></term> + <listitem> + <para> + By default the bindings for the <command>/</command> virtual + host are returned. The "-p" flag can be used to override + this default. Each result row will contain an exchange + name, queue name, routing key and binding arguments, in + that order. Non-ASCII characters will be URL-encoded. + </para> + </listitem> + </varlistentry> + + <varlistentry id="list_connections"> + <term>list_connections <option><replaceable>connectioninfoitem</replaceable> ...</option></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. If + no <command>connectioninfoitem</command>s are specified then user, peer + address, peer port and connection state are displayed. + <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>address</term> + <listitem><para>Server IP address.</para></listitem> + </varlistentry> + <varlistentry> + <term>port</term> + <listitem><para>Server port.</para></listitem> + </varlistentry> + <varlistentry> + <term>peer_address</term> + <listitem><para>Peer address.</para></listitem> + </varlistentry> + <varlistentry> + <term>peer_port</term> + <listitem><para>Peer port.</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>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>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 URL-escaped.</para></listitem> + </varlistentry> + <varlistentry> + <term>timeout</term> + <listitem><para>Connection timeout.</para></listitem> + </varlistentry> + <varlistentry> + <term>frame_max</term> + <listitem><para>Maximum frame size (bytes).</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> + </variablelist> + <para role="example-prefix"> + For example: + </para> + <screen role="example"> + rabbitmqctl list_connections send_pend server_port + </screen> + <para role="example"> + This command displays the send queue size and server port for each + connection. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>list_channels <option><replaceable>channelinfoitem</replaceable> ...</option></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. If + no <command>channelinfoitem</command>s are specified then pid, + user, transactional, consumer_count, and + messages_unacknowledged are assumed. + <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>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>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>acks_uncommitted</term> + <listitem><para>Number of acknowledgements received in an as yet + uncommitted transaction.</para></listitem> + </varlistentry> + <varlistentry> + <term>prefetch_count</term> + <listitem><para>QoS prefetch count limit in force, 0 if unlimited.</para></listitem> + </varlistentry> + </variablelist> + <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>rabbitmqctl list_consumers</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, and a boolean + indicating whether acknowledgements are expected for + messages delivered to this consumer. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + </refsect1> + +</refentry> diff --git a/docs/usage.xsl b/docs/usage.xsl new file mode 100644 index 0000000000..fee452f4e7 --- /dev/null +++ b/docs/usage.xsl @@ -0,0 +1,65 @@ +<?xml version='1.0'?> +<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" + xmlns:exsl="http://exslt.org/common" + xmlns:ng="http://docbook.org/docbook-ng" + xmlns:db="http://docbook.org/ns/docbook" + exclude-result-prefixes="exsl" + version='1.0'> + +<xsl:output method="text" + encoding="UTF-8" + indent="no"/> +<xsl:strip-space elements="arg"/> + +<xsl:template match="/"> +<!-- Pull out cmdsynopsis to show the command usage line. -->Usage: +<xsl:value-of select="refentry/refsynopsisdiv/cmdsynopsis/command"/> +<xsl:text> </xsl:text> +<xsl:for-each select="refentry/refsynopsisdiv/cmdsynopsis/arg"> + <xsl:if test="@choice='opt'">[</xsl:if> + <xsl:apply-templates select="." /> + <xsl:if test="@choice='opt'">]</xsl:if> + <xsl:text> </xsl:text> +</xsl:for-each> + +<!-- List options (any variable list in a section called "Options"). --> +Options: +<xsl:for-each select=".//*[title='Options']/variablelist"> + <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> + +<!-- List commands (any first-level variable list in a section called "Commands"). --> +Commands: +<xsl:for-each select=".//*[title='Commands']/refsect2/variablelist"> + <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> + +<!-- Any paragraphs which have been marked as role="usage" (principally for global flags). --> +<xsl:for-each select="//para[@role='usage']"> +<xsl:value-of select="normalize-space(.)"/><xsl:text> </xsl:text> +</xsl:for-each> + +<!-- Any second-level variable lists (principally for options for subcommands). --> +<xsl:for-each select=".//*[title='Commands']//variablelist//variablelist"> + <xsl:for-each select="varlistentry"><<xsl:apply-templates select="term"/>> - <xsl:apply-templates select="listitem"/> + <xsl:text> </xsl:text> + </xsl:for-each> + <xsl:text> </xsl:text> +</xsl:for-each> + +</xsl:template> + +<xsl:template match="replaceable"><<xsl:value-of select="normalize-space(.)"/>></xsl:template> + +</xsl:stylesheet> |