openstack/openstack-manuals
Code Issues Proposed changes

Improved messaging server section

Browse Source 
I improved the messaging server section including structure and
content to meet conventions. I also added links to each message
broker for those who may consider using a different message broker
than the one supported by their particular distribution.

Change-Id: Ic046ae7ceee315a9da91f8530542c2e0cb3a66f9
Closes-Bug: #1309304
Closes-Bug: #1298153
This commit is contained in:
Matt Kassawara 2014-04-17 21:45:07 -06:00
parent 0ae77db0fe
commit 09e1b316f8
1 changed files with 101 additions and 56 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

157
doc/install-guide/section_basics-queue.xml
View File

@ -4,63 +4,108 @@
xml:id="basics-queue"> xml:id="basics-queue">
<?dbhtml-stop-chunking?> <?dbhtml-stop-chunking?>
<title>Messaging server</title> <title>Messaging server</title>
<para>On the controller node, install the messaging queue server. <para>OpenStack uses a <glossterm>message broker</glossterm> to coordinate
Typically this is <phrase os="ubuntu;debian;opensuse;sles" operations and status information among services. The message broker
><glossterm>RabbitMQ</glossterm></phrase> service typically runs on the controller node. OpenStack supports several
<phrase os="centos;rhel;fedora"> message brokers including <application>RabbitMQ</application>,
<glossterm>Qpid</glossterm></phrase> but <application>Qpid</application>, and <application>ZeroMQ</application>.
<phrase os="ubuntu;debian;opensuse;sles"><glossterm>Qpid</glossterm></phrase> However, most distributions that package OpenStack support a particular
<phrase os="centos;rhel;fedora"><glossterm>RabbitMQ</glossterm></phrase> message broker. This guide covers the message broker supported by each
and <glossterm>ZeroMQ</glossterm> (0MQ) are also available:</para> distribution. If you prefer to implement a different message broker,
<screen os="ubuntu;debian"><prompt>#</prompt> <userinput>apt-get install rabbitmq-server</userinput></screen> consult the documentation associated with it.</para>
<screen os="opensuse;sles"><prompt>#</prompt> <userinput>zypper install rabbitmq-server</userinput></screen> <itemizedlist>
<screen os="fedora;centos;rhel"><prompt>#</prompt> <userinput>yum install qpid-cpp-server</userinput></screen> <listitem>
<para os="fedora;centos;rhel">Disable Qpid authentication by <para><link xlink:href="http://www.rabbitmq.com">RabbitMQ</link></para>
editing <filename>/etc/qpidd.conf</filename> file and changing </listitem>
the <literal>auth</literal> option to <listitem>
<literal>no</literal>:</para> <para><link xlink:href="http://qpid.apache.org">Qpid</link></para>
<screen os="fedora;centos;rhel"> <userinput>auth=no</userinput></screen> </listitem>
<note os="fedora;centos;rhel"> <listitem>
<para> <para><link xlink:href="http://zeromq.org">ZeroMQ</link></para>
To simplify configuration, the Qpid examples in this guide do not use </listitem>
authentication. However, we strongly advise enabling authentication </itemizedlist>
for production deployments. For more information on securing Qpid <procedure>
refer to the <title>To install the message broker service</title>
<link xlink:href= <step os="ubuntu;debian">
"http://qpid.apache.org/books/trunk/AMQP-Messaging-Broker-CPP-Book/html/chap-Messaging_User_Guide-Security.html" <para>Ubuntu and Debian use <application>RabbitMQ</application>.</para>
>Qpid Documentation</link>. <screen><prompt>#</prompt> <userinput>apt-get install rabbitmq-server</userinput></screen>
</para> </step>
<para> <step os="rhel;centos;fedora">
After you enable Qpid authentication, you must update the configuration <para>Red Hat Enterprise Linux (RHEL), CentOS, Scientific Linux, and
file of each OpenStack service to ensure that the Fedora use <application>Qpid</application>.
<literal>qpid_username</literal> and <literal>qpid_password</literal> </para>
configuration keys refer to a valid Qpid username and password, <screen><prompt>#</prompt> <userinput>yum install qpid-cpp-server</userinput></screen>
respectively. </step>
</para> <step os="sles;opensuse">
</note> <para>SUSE Linux Enterprise Server (SLES) and openSUSE use
<para os="fedora;centos;rhel">Start Qpid and set it to start <application>RabbitMQ</application>.</para>
automatically when the system boots:</para> <screen><prompt>#</prompt> <userinput>zypper install rabbitmq-server</userinput></screen>
<screen os="fedora;centos;rhel"><prompt>#</prompt> <userinput>service qpidd start</userinput> </step>
</procedure>
<procedure>
<title>To configure the message broker service</title>
<step os="rhel;centos;fedora">
<para>To simplify installation of your test environment, we recommend
that you disable authentication.</para>
<para>Edit the <filename>/etc/qpidd.conf</filename> file and change
the following key:</para>
<programlisting>auth=no</programlisting>
<note>
<para>For production environments, you should enable authentication.
For more information on securing the message broker, see the
<link xlink:href=
"http://qpid.apache.org/books/trunk/AMQP-Messaging-Broker-CPP-Book/html/chap-Messaging_User_Guide-Security.html"
>documentation</link>.</para>
<para>If you decide to enable authentication for your test
environment, you must configure the <literal>qpid_username</literal>
and <literal>qpid_password</literal> keys in the configuration file
of each OpenStack service that uses the message broker.</para>
</note>
</step>
<step os="sles;opensuse">
<para>Start the message broker service:</para>
<screen><prompt>#</prompt> <userinput>service rabbitmq-server start</userinput></screen>
</step>
<step os="ubuntu;debian;sles;opensuse">
<para>The message broker creates a default account that uses
<literal>guest</literal> for the username and password. To simplify
installation of your test environment, we recommend that you use this
account, but change the password for it.</para>
<para>Run the following command:</para>
<para>Replace <replaceable>RABBIT_PASS</replaceable> with a suitable
password.</para>
<screen><prompt>#</prompt> <userinput>rabbitmqctl change_password guest <replaceable>RABBIT_PASS</replaceable></userinput></screen>
<para>You must configure the <literal>rabbit_password</literal> key
in the configuration file for each OpenStack service that uses the
message broker.</para>
<note>
<para>For production environments, you should create a unique account
with suitable password. For more information on securing the
message broker, see the
<link xlink:href="https://www.rabbitmq.com/man/rabbitmqctl.1.man.html"
>documentation</link>.</para>
<para>If you decide to create a unique account with suitable password
for your test environment, you must configure the
<literal>rabbit_userid</literal> and
<literal>rabbit_password</literal> keys in the configuration file
of each OpenStack service that uses the message broker.</para>
</note>
</step>
</procedure>
<procedure os="rhel;centos;fedora;sles;opensuse">
<title>To finalize installation</title>
<step os="rhel;centos;fedora">
<para>Start the message broker service and configure it to start when
the system boots:</para>
<screen><prompt>#</prompt> <userinput>service qpidd start</userinput>
<prompt>#</prompt> <userinput>chkconfig qpidd on</userinput></screen> <prompt>#</prompt> <userinput>chkconfig qpidd on</userinput></screen>
<para os="opensuse;sles">Start the messaging service and set it to </step>
start automatically when the system boots:</para> <step os="sles;opensuse">
<screen os="opensuse;sles"><prompt>#</prompt> <userinput>service rabbitmq-server start</userinput> <para>Configure the message broker service to start when the system
<prompt>#</prompt> <userinput>chkconfig rabbitmq-server on</userinput></screen> boots:</para>
<note os="ubuntu;debian;opensuse;sles"> <screen><prompt>#</prompt> <userinput>chkconfig rabbitmq-server on</userinput></screen>
<title>Important security consideration</title> </step>
<para>The <package>rabbitmq-server</package> package configures </procedure>
the RabbitMQ service to start automatically and creates a
<literal>guest</literal> user with a default
<literal>guest</literal> password. The RabbitMQ examples in
this guide use the <literal>guest</literal> account, though it
is strongly advised to change its default password, especially
if you have IPv6 available: by default the RabbitMQ server
enables anyone to connect to it by using guest as login and
password, and with IPv6, it is reachable from the
outside.</para>
<para>To change the default guest password of RabbitMQ:</para>
<screen><prompt>#</prompt> <userinput>rabbitmqctl change_password guest <replaceable>RABBIT_PASS</replaceable></userinput></screen>
</note>
<para>Congratulations, now you are ready to install OpenStack <para>Congratulations, now you are ready to install OpenStack
services!</para> services!</para>
</section> </section>