~ubuntu-branches/ubuntu/saucy/rabbitmq-server/saucy

        <varlistentry id="join_cluster">

          <term><cmdsynopsis><command>join_cluster</command> <arg choice="req"><replaceable>clusternode</replaceable></arg><arg choice="opt"><replaceable>--ram</replaceable></arg></cmdsynopsis></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>

              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.

              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>.

            <screen role="example">rabbitmqctl join_cluster hare@elena --ram</screen>

              This command instructs the RabbitMQ node to join the cluster that

              <command>hare@elena</command> is part of, as a ram node.

        <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 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>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>

              queues, bindings, user permissions, parameters and policies.

          <term><cmdsynopsis><command>list_user_permissions</command> <arg choice="req"><replaceable>username</replaceable></arg></cmdsynopsis></term>

      <title>Parameter Management</title>

      <para>

        Certain features of RabbitMQ (such as the federation plugin)

        are controlled by dynamic,

        cluster-wide <emphasis>parameters</emphasis>. Each parameter

        consists of a component name, a name and a value, and is

        associated with a virtual host. The component name and name are

        strings, 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>vhostpath</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>vhostpath</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>vhostpath</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>

      </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>vhostpath</replaceable></arg> <arg choice="req"><replaceable>name</replaceable></arg> <arg choice="req"><replaceable>pattern</replaceable></arg>  <arg choice="req"><replaceable>definition</replaceable></arg> <arg choice="opt"><replaceable>priority</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, defaulting to 0. Higher numbers indicate greater precedence.

                </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>vhostpath</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>vhostpath</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>

      </variablelist>

    </refsect2>

 

    <refsect2>

                <term>policy</term>

                <listitem><para>Policy name applying to the queue.</para></listitem>

              </varlistentry>

              <varlistentry>

                <term>active_consumers</term>

                <listitem>

                  <para>

                    Number of active consumers. An active consumer is

                    one which could immediately receive any messages

                    sent to the queue - i.e. it is not limited by its

                    prefetch count, TCP congestion, flow control, or

                    because it has issued channel.flow. At least one

                    of messages_ready and active_consumers must always

                    be zero.

                  </para>

                  <para>

                    Note that this value is an instantaneous snapshot

                    - when consumers are restricted by their prefetch

                    count they may only appear to be active for small

                    fractions of a second until more messages are sent

                    out.

                  </para>

                </listitem>

              </varlistentry>

              <varlistentry>

                <listitem><para>The exchange type (such as

                [<command>direct</command>,

              <varlistentry>

                <term>policy</term>

                <listitem><para>Policy name for applying to the exchange.</para></listitem>

              </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>

                <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>

                <listitem><para>Connection timeout / negotiated heartbeat interval, in seconds.</para></listitem>

              specified then user, peer host, peer port, time since