Merged default into bug17880bug17880

1 files changed, 307 insertions, 188 deletions

diff --git a/docs/rabbitmqctl.1.pod b/docs/rabbitmqctl.1.pod
index 42156896..6d4aadeb 100644
--- a/docs/rabbitmqctl.1.pod
+++ b/docs/rabbitmqctl.1.pod
@@ -18,269 +18,388 @@ It performs all actions by connecting to one of the broker's nodes.
 
 =head1 OPTIONS
 
-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.
-
-B<-q>
-    quiet output mode is selected with the B<-q> flag. Informational 
-    messages are suppressed when quiet mode is in effect.
+=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
 
-stop
-    stop the Erlang node on which RabbitMQ broker is running.
-
-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>.
-
-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>.
-
-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.
-
-force
-    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.
-
-force_reset
-    the same as I<force> 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.
-
-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.
-
-cluster I<clusternode> ...
-    instruct the node to become member of a cluster with the specified
-    nodes determined by I<clusternode> option(s).
-    See http://www.rabbitmq.com/clustering.html for more information
-    about clustering.
+=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.
+
+=back
 
 =head2 USER MANAGEMENT
 
-add_user I<username> I<password>
-    create a user named I<username> with (initial) password I<password>.
+=over
+
+=item add_user I<username> I<password>
 
-delete_user I<username>
-    delete the user named I<username>.
+Create a user named I<username> with (initial) password I<password>.
 
-change_password I<username> I<newpassword>
-    change the password for the user named I<username> to I<newpassword>.
+=item delete_user I<username>
 
-list_users
-    list all users.
+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
 
-add_vhost I<vhostpath>
-    create a new virtual host called I<vhostpath>.
+=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>
 
-delete_vhost I<vhostpath>
-    delete a virtual host I<vhostpath>.
-    That command deletes also all its exchanges, queues and user
-    mappings.
-    
-list_vhosts
-    list all virtual hosts.
+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.
 
-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 'configure', 'write' and 'read' access
-    to resources with names matching the first, second and third
-    I<regexp>, respectively.
+=item clear_permissions [-p I<vhostpath>] I<username>
 
-clear_permissions [-p I<vhostpath>] I<username>
-    remove the permissions for the user named I<username> in the
-    virtual host I<vhostpath>.
+Remove the permissions for the user named I<username> in the virtual
+host I<vhostpath>.
 
-list_permissions [-p I<vhostpath>]
-    list all the users and their permissions in the virtual host
-    I<vhostpath>.
+=item list_permissions [-p I<vhostpath>]
 
-list_user_permissions I<username> 
-    list the permissions of the user named I<username> across all
-    virtual hosts.
+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
 
-list_queues [-p I<vhostpath>] [I<queueinfoitem> ...]
-    list queue information by virtual host. If no I<queueinfoitem>s
-    are specified then then name and number of messages is displayed
-    for each queue.
+=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 4
+=over
+
+=item name
+
+name of the queue
+
+=item durable
+
+whether the queue survives server restarts
 
-name 
-    URL-encoded name of the queue
+=item auto_delete
 
-durable 
-    whether the queue survives server restarts
+whether the queue will be deleted when no longer used
 
-auto_delete
-    whether the queue will be deleted when no longer used
+=item arguments
 
-arguments
-    queue arguments
+queue arguments
 
-node
-    node on which the process associated with the queue resides
+=item node
 
-messages_ready
-    number of messages ready to be delivered to clients
+node on which the process associated with the queue resides
 
-messages_unacknowledged
-    number of messages delivered to clients but not yet
-    acknowledged
+=item messages_ready
 
-messages_uncommitted
-    number of messages published in as yet uncommitted transactions
+number of messages ready to be delivered to clients
 
-messages
-    sum of ready, unacknowledged and uncommitted messages
+=item messages_unacknowledged
 
-acks_uncommitted
-    number of acknowledgements received in as yet uncommitted
-    transactions
+number of messages delivered to clients but not yet acknowledged
 
-consumers
-    number of consumers
+=item messages_uncommitted
 
-transactions
-    number of transactions
+number of messages published in as yet uncommitted transactions
 
-memory
-    bytes of memory consumed by the Erlang process for the queue,
-    including stack, heap and internal structures
+=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
 
-list_exchanges [-p I<vhostpath>] [I<exchangeinfoitem> ...]
-    list exchange information by virtual host. If no
-    I<exchangeinfoitem>s are specified then name and type is displayed
-    for each exchange.
+=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 4
+=over
 
-name 
-    URL-encoded name of the exchange
+=item name 
 
-type
-    exchange type (B<direct>, B<topic>, B<fanout>, or B<headers>)
+name of the exchange
 
-durable
-    whether the exchange survives server restarts
+=item type
 
-auto_delete
-    whether the exchange is deleted when no longer used
+exchange type (B<direct>, B<topic>, B<fanout>, or B<headers>)
 
-arguments
-    exchange arguments
+=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
 
-list_bindings [-p I<vhostpath>]
-    list bindings by virtual host. Each line contains exchange name,
-    routing key and queue name (all URL encoded) and arguments.
+=over
+
+=item list_bindings [-p I<vhostpath>]
 
-list_connections [I<connectioninfoitem> ...]
-    list connection information. If no I<connectioninfoitem>s are
-    specified then the user, peer address and peer port are displayed.
+List bindings by virtual host. Each line printed describes a binding,
+with the exchange name, routing key, queue name and arguments,
+separated by tab characters.
+
+=item list_connections [I<connectioninfoitem> ...]
+
+List queue information by virtual host. Each line printed describes an
+connection, with the requested I<connectioninfoitem> values separated
+by tab characters.  If no I<connectioninfoitem>s are specified then
+I<user>, I<peer_address> and I<peer_port> are assumed.
+
+=back
 
 =head3 Connection information items
 
-=over 4
+=over
+
+=item node
+
+node on which the process associated with the connection resides
 
-node
-    node on which the process associated with the connection resides
+=item address
 
-address
-    server IP number
+server IP number
 
-port
-    server port
+=item port
 
-peer_address
-    peer address
+server port
 
-peer_port
-    peer port
+=item peer_address
 
-state
-    connection state (B<pre-init>, B<starting>, B<tuning>, B<opening>,
-    B<running>, B<closing>, B<closed>)
+peer address
 
-channels
-    number of channels using the connection
+=item peer_port
 
-user
-    username associated with the connection
+peer port
 
-vhost
-    URL-encoded virtual host
+=item state
 
-timeout
-    connection timeout
+connection state (B<pre-init>, B<starting>, B<tuning>, B<opening>,
+B<running>, B<closing>, B<closed>)
 
-frame_max
-    maximum frame size (bytes)
+=item channels
 
-recv_oct
-    octets received
+number of channels using the connection
 
-recv_cnt
-    packets received
+=item user
 
-send_oct
-    octets sent
+username associated with the connection
 
-send_cnt
-    packets sent
+=item vhost
 
-send_pend
-    send queue size
+virtual host
+
+=item timeout
+
+connection timeout
+
+=item frame_max
+
+maximum frame size (bytes)
+
+=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
 
 The list_queues, list_exchanges and list_bindings 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. Result
-columns for these commands and list_connections are tab-separated.
+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
 
@@ -309,4 +428,4 @@ The RabbitMQ Team <info@rabbitmq.com>
 
 =head1 REFERENCES
 
-RabbitMQ Web Site: http://www.rabbitmq.com
+RabbitMQ Web Site: L<http://www.rabbitmq.com>