openstack/openstack-manuals
Code Issues Proposed changes

Reducing install guide build warnings

Browse Source 
Limiting the number of words per line in the install
guide and common content to reduce install
guide build  warnings concerning overflow from about 22 to 16

Change-Id: Iac4c5d429e2e35148e98885c180990f90cf9ca15
backport: juno
Closes-bug: #1273143
This commit is contained in:
Joseph Robinson 2014-11-12 12:13:31 +10:00
parent 3ba6b2aaf4
commit e9fd400193
6 changed files with 173 additions and 157 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

8
doc/common/ch_getstart.xml
View File

@ -42,10 +42,10 @@
xlink:href="http://docs.openstack.org/developer/horizon/" xlink:href="http://docs.openstack.org/developer/horizon/"
><glossterm>Horizon</glossterm></link> ><glossterm>Horizon</glossterm></link>
</td> </td>
<td>Provides a web-based self-service portal to interact <td>Provides a web-based self-service portal
with underlying OpenStack services, such as launching to interact with underlying OpenStack services,
an instance, assigning IP addresses and configuring such as launching an instance, assigning IP
access controls.</td> addresses and configuring access controls.</td>
</tr> </tr>
<tr> <tr>
<td><link <td><link

16
doc/common/section_conventions.xml
View File

@ -14,7 +14,8 @@
<para>Something you must be aware of before proceeding.</para> <para>Something you must be aware of before proceeding.</para>
</important> </important>
<warning> <warning>
<para>Critical information about the risk of data loss or security issues.</para> <para>Critical information about the risk of data loss or security
issues.</para>
</warning> </warning>
</simplesect> </simplesect>
<simplesect xml:id="conventions-prompts"> <simplesect xml:id="conventions-prompts">
@ -23,16 +24,19 @@
<varlistentry> <varlistentry>
<term><emphasis role="bold"><prompt>$</prompt> prompt</emphasis></term> <term><emphasis role="bold"><prompt>$</prompt> prompt</emphasis></term>
<listitem> <listitem>
<para>Any user, including the <literal>root</literal> user, can run commands that are <para>Any user, including the <literal>root</literal> user,
prefixed with the <prompt>$</prompt> prompt.</para> can run commands that are
prefixed with the <prompt>$</prompt> prompt.</para>
</listitem> </listitem>
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term><emphasis role="bold"><prompt>#</prompt> prompt</emphasis></term> <term><emphasis role="bold"><prompt>#</prompt> prompt</emphasis></term>
<listitem> <listitem>
<para>The <literal>root</literal> user must run commands that are prefixed with the <para>The <literal>root</literal> user must run commands
<prompt>#</prompt> prompt. You can also prefix these commands with the that are prefixed with the <prompt>#</prompt> prompt.
<command>sudo</command> command, if available, to run them.</para> You can also prefix these commands with the
<command>sudo</command> command, if available,
to run them.</para>
</listitem> </listitem>
</varlistentry> </varlistentry>
</variablelist> </variablelist>

6
doc/common/section_dochistory.xml
View File

@ -6,8 +6,10 @@
xml:id="doc_change_history"> xml:id="doc_change_history">
<title>Document change history</title> <title>Document change history</title>
<?dbhtml stop-chunking?> <?dbhtml stop-chunking?>
<para>This version of the guide replaces and obsoletes all earlier versions.</para> <para>This version of the guide replaces and obsoletes all
<para>The following table describes the most recent changes:</para> earlier versions.</para>
<para>The following table describes the most recent
changes:</para>
<?rax revhistory?> <?rax revhistory?>
<!-- Table generated in output from revision element in the book element --> <!-- Table generated in output from revision element in the book element -->
</section> </section>

229
doc/install-guide/section_basics-security.xml
View File

@ -6,125 +6,128 @@
xml:id="basics-security"> xml:id="basics-security">
<?dbhtml stop-chunking?> <?dbhtml stop-chunking?>
<title>Security</title> <title>Security</title>
<para>OpenStack services support various security methods including <para>OpenStack services support various security methods
password, policy, and encryption. Additionally, supporting services including password, policy, and encryption. Additionally,
including the database server and message broker support at least supporting services including the database server and
password security.</para> message broker support at least password security.</para>
<para>To ease the installation process, this guide only covers password <para>To ease the installation process, this guide only
security where applicable. You can create secure passwords manually, covers password security where applicable. You can create
generate them using a tool such as secure passwords manually, generate them using a tool such as
<link xlink:href="http://sourceforge.net/projects/pwgen/">pwgen</link>, or <link xlink:href="http://sourceforge.net/projects/pwgen/">pwgen</link>,
by running the following command:</para> or by running the following command:</para>
<screen><prompt>$</prompt> <userinput>openssl rand -hex 10</userinput></screen> <screen><prompt>$</prompt> <userinput>openssl rand -hex 10</userinput></screen>
<para>For OpenStack services, this guide uses <para>For OpenStack services, this guide uses
<replaceable>SERVICE_PASS</replaceable> to reference service account <replaceable>SERVICE_PASS</replaceable> to reference
passwords and <replaceable>SERVICE_DBPASS</replaceable> to reference service account passwords and
<replaceable>SERVICE_DBPASS</replaceable> to reference
database passwords.</para> database passwords.</para>
<para>The following table provides a list of services that require <para>The following table provides a list of services that require
passwords and their associated references in the guide: passwords and their associated references in the guide:
<table rules="all"> <table rules="all">
<caption>Passwords</caption> <caption>Passwords</caption>
<thead> <thead>
<tr> <tr>
<th>Password name</th> <th>Password name</th>
<th>Description</th> <th>Description</th>
</tr> </tr>
</thead> </thead>
<tbody> <tbody>
<tr> <tr>
<td>Database password (no variable used)</td> <td>Database password (no variable used)</td>
<td>Root password for the database</td> <td>Root password for the database</td>
</tr> </tr>
<tr> <tr>
<td><literal><replaceable>RABBIT_PASS</replaceable></literal></td> <td><literal><replaceable>RABBIT_PASS</replaceable></literal></td>
<td>Password of user guest of RabbitMQ</td> <td>Password of user guest of RabbitMQ</td>
</tr> </tr>
<tr> <tr>
<td><literal><replaceable>KEYSTONE_DBPASS</replaceable></literal></td> <td><literal><replaceable>KEYSTONE_DBPASS</replaceable></literal></td>
<td>Database password of Identity service</td> <td>Database password of Identity service</td>
</tr> </tr>
<tr> <tr>
<td><literal><replaceable>DEMO_PASS</replaceable></literal></td> <td><literal><replaceable>DEMO_PASS</replaceable></literal></td>
<td>Password of user <literal>demo</literal></td> <td>Password of user <literal>demo</literal></td>
</tr> </tr>
<tr> <tr>
<td><literal><replaceable>ADMIN_PASS</replaceable></literal></td> <td><literal><replaceable>ADMIN_PASS</replaceable></literal></td>
<td>Password of user <literal>admin</literal></td> <td>Password of user <literal>admin</literal></td>
</tr> </tr>
<tr> <tr>
<td><literal><replaceable>GLANCE_DBPASS</replaceable></literal></td> <td><literal><replaceable>GLANCE_DBPASS</replaceable></literal></td>
<td>Database password for Image Service</td> <td>Database password for Image Service</td>
</tr> </tr>
<tr> <tr>
<td><literal><replaceable>GLANCE_PASS</replaceable></literal></td> <td><literal><replaceable>GLANCE_PASS</replaceable></literal></td>
<td>Password of Image Service user <literal>glance</literal></td> <td>Password of Image Service user <literal>glance</literal></td>
</tr> </tr>
<tr> <tr>
<td><literal><replaceable>NOVA_DBPASS</replaceable></literal></td> <td><literal><replaceable>NOVA_DBPASS</replaceable></literal></td>
<td>Database password for Compute service</td> <td>Database password for Compute service</td>
</tr> </tr>
<tr> <tr>
<td><literal><replaceable>NOVA_PASS</replaceable></literal></td> <td><literal><replaceable>NOVA_PASS</replaceable></literal></td>
<td>Password of Compute service user <literal>nova</literal></td> <td>Password of Compute service user <literal>nova</literal></td>
</tr> </tr>
<tr> <tr>
<td><literal><replaceable>DASH_DBPASS</replaceable></literal></td> <td><literal><replaceable>DASH_DBPASS</replaceable></literal></td>
<td>Database password for the dashboard</td> <td>Database password for the dashboard</td>
</tr> </tr>
<tr> <tr>
<td><literal><replaceable>CINDER_DBPASS</replaceable></literal></td> <td><literal><replaceable>CINDER_DBPASS</replaceable></literal></td>
<td>Database password for the Block Storage service</td> <td>Database password for the Block Storage service</td>
</tr> </tr>
<tr> <tr>
<td><literal><replaceable>CINDER_PASS</replaceable></literal></td> <td><literal><replaceable>CINDER_PASS</replaceable></literal></td>
<td>Password of Block Storage service user <literal>cinder</literal></td> <td>Password of Block Storage service user <literal>cinder</literal></td>
</tr> </tr>
<tr> <tr>
<td><literal><replaceable>NEUTRON_DBPASS</replaceable></literal></td> <td><literal><replaceable>NEUTRON_DBPASS</replaceable></literal></td>
<td>Database password for the Networking service</td> <td>Database password for the Networking service</td>
</tr> </tr>
<tr> <tr>
<td><literal><replaceable>NEUTRON_PASS</replaceable></literal></td> <td><literal><replaceable>NEUTRON_PASS</replaceable></literal></td>
<td>Password of Networking service user <literal>neutron</literal></td> <td>Password of Networking service user <literal>neutron</literal></td>
</tr> </tr>
<tr> <tr>
<td><literal><replaceable>HEAT_DBPASS</replaceable></literal></td> <td><literal><replaceable>HEAT_DBPASS</replaceable></literal></td>
<td>Database password for the Orchestration service</td> <td>Database password for the Orchestration service</td>
</tr> </tr>
<tr> <tr>
<td><literal><replaceable>HEAT_PASS</replaceable></literal></td> <td><literal><replaceable>HEAT_PASS</replaceable></literal></td>
<td>Password of Orchestration service user <literal>heat</literal></td> <td>Password of Orchestration service user <literal>heat</literal></td>
</tr> </tr>
<tr> <tr>
<td><literal><replaceable>CEILOMETER_DBPASS</replaceable></literal></td> <td><literal><replaceable>CEILOMETER_DBPASS</replaceable></literal></td>
<td>Database password for the Telemetry service</td> <td>Database password for the Telemetry service</td>
</tr> </tr>
<tr> <tr>
<td><literal><replaceable>CEILOMETER_PASS</replaceable></literal></td> <td><literal><replaceable>CEILOMETER_PASS</replaceable></literal></td>
<td>Password of Telemetry service user <literal>ceilometer</literal></td> <td>Password of Telemetry service user <literal>ceilometer</literal></td>
</tr> </tr>
<tr> <tr>
<td><literal><replaceable>TROVE_DBPASS</replaceable></literal></td> <td><literal><replaceable>TROVE_DBPASS</replaceable></literal></td>
<td>Database password of Database service</td> <td>Database password of Database service</td>
</tr> </tr>
<tr> <tr>
<td><literal><replaceable>TROVE_PASS</replaceable></literal></td> <td><literal><replaceable>TROVE_PASS</replaceable></literal></td>
<td>Password of Database Service user <literal>trove</literal></td> <td>Password of Database Service user <literal>trove</literal></td>
</tr> </tr>
</tbody> </tbody>
</table> </table>
</para> </para>
<para>OpenStack and supporting services require administrative privileges <para>OpenStack and supporting services require administrative
during installation and operation. In some cases, services perform privileges during installation and operation. In some cases,
modifications to the host that can interfere with deployment automation services perform modifications to the host that can interfere
tools such as Ansible, Chef, and Puppet. For example, some OpenStack with deployment automation tools such as Ansible, Chef, and
services add a root wrapper to <literal>sudo</literal> that can interfere Puppet. For example, some OpenStack services add a root
with security policies. See the wrapper to <literal>sudo</literal> that can interfere with
security policies. See the
<link xlink:href="http://docs.openstack.org/admin-guide-cloud/content/root-wrap-reference.html">Cloud Administrator Guide</link> <link xlink:href="http://docs.openstack.org/admin-guide-cloud/content/root-wrap-reference.html">Cloud Administrator Guide</link>
for more information. Also, the Networking service assumes default values for more information. Also, the Networking service assumes
for kernel network parameters and modifies firewall rules. To avoid most default values for kernel network parameters and modifies
issues during your initial installation, we recommend using a stock firewall rules. To avoid most issues during your initial
deployment of a supported distribution on your hosts. However, if you installation, we recommend using a stock deployment of a
choose to automate deployment of your hosts, review the configuration supported distribution on your hosts. However, if you choose
to automate deployment of your hosts, review the configuration
and policies applied to them before proceeding further.</para> and policies applied to them before proceeding further.</para>
</section> </section>

36
doc/install-guide/section_neutron-network-node.xml
View File

@ -126,9 +126,9 @@ admin_password = <replaceable>NEUTRON_PASS</replaceable></programlisting>
</note> </note>
</step> </step>
<step> <step>
<para>In the <literal>[DEFAULT]</literal> section, enable the <para>In the <literal>[DEFAULT]</literal> section,
Modular Layer 2 (ML2) plug-in, router service, and overlapping enable the Modular Layer 2 (ML2) plug-in,
IP addresses:</para> router service, and overlapping IP addresses:</para>
<programlisting language="ini">[DEFAULT] <programlisting language="ini">[DEFAULT]
... ...
core_plugin = ml2 core_plugin = ml2
@ -170,24 +170,25 @@ tenant_network_types = gre
mechanism_drivers = openvswitch</programlisting> mechanism_drivers = openvswitch</programlisting>
</step> </step>
<step> <step>
<para>In the <literal>[ml2_type_flat]</literal> section, configure <para>In the <literal>[ml2_type_flat]</literal> section,
the external network:</para> configure the external network:</para>
<programlisting language="ini">[ml2_type_flat] <programlisting language="ini">[ml2_type_flat]
... ...
flat_networks = external</programlisting> flat_networks = external</programlisting>
</step> </step>
<step os="ubuntu;rhel;centos;fedora;sles;opensuse"> <step os="ubuntu;rhel;centos;fedora;sles;opensuse">
<para>In the <literal>[ml2_type_gre]</literal> section, configure <para>In the <literal>[ml2_type_gre]</literal> section,
the tunnel identifier (id) range:</para> configure the tunnel identifier (id) range:</para>
<programlisting language="ini">[ml2_type_gre] <programlisting language="ini">[ml2_type_gre]
... ...
tunnel_id_ranges = 1:1000</programlisting> tunnel_id_ranges = 1:1000</programlisting>
</step> </step>
<step os="ubuntu;rhel;centos;fedora;sles;opensuse"> <step os="ubuntu;rhel;centos;fedora;sles;opensuse">
<para>In the <literal>[securitygroup]</literal> section, enable <para>In the <literal>[securitygroup]</literal>
security groups, enable <glossterm>ipset</glossterm>, and section, enable security groups, enable
configure the OVS <glossterm>iptables</glossterm> firewall <glossterm>ipset</glossterm>, and configure
driver:</para> the OVS <glossterm>iptables</glossterm> firewall
driver:</para>
<programlisting language="ini">[securitygroup] <programlisting language="ini">[securitygroup]
... ...
enable_security_group = True enable_security_group = True
@ -205,8 +206,8 @@ enable_tunneling = True
bridge_mappings = external:br-ex</programlisting> bridge_mappings = external:br-ex</programlisting>
<para>Replace <para>Replace
<replaceable>INSTANCE_TUNNELS_INTERFACE_IP_ADDRESS</replaceable> <replaceable>INSTANCE_TUNNELS_INTERFACE_IP_ADDRESS</replaceable>
with the IP address of the instance tunnels network interface with the IP address of the instance
on your network node.</para> tunnels network interface on your network node.</para>
</step> </step>
</substeps> </substeps>
</step> </step>
@ -216,8 +217,8 @@ bridge_mappings = external:br-ex</programlisting>
<para>The <glossterm>Layer-3 (L3) agent</glossterm> provides <para>The <glossterm>Layer-3 (L3) agent</glossterm> provides
routing services for virtual networks.</para> routing services for virtual networks.</para>
<step> <step>
<para>Edit the <filename>/etc/neutron/l3_agent.ini</filename> file <para>Edit the <filename>/etc/neutron/l3_agent.ini</filename>
and complete the following actions:</para> file and complete the following actions:</para>
<substeps> <substeps>
<step> <step>
<para>In the <literal>[DEFAULT]</literal> section, configure <para>In the <literal>[DEFAULT]</literal> section, configure
@ -247,8 +248,9 @@ verbose = True</programlisting>
<para>The <glossterm>DHCP agent</glossterm> provides DHCP <para>The <glossterm>DHCP agent</glossterm> provides DHCP
services for virtual networks.</para> services for virtual networks.</para>
<step os="ubuntu;rhel;centos;fedora;sles;opensuse"> <step os="ubuntu;rhel;centos;fedora;sles;opensuse">
<para>Edit the <filename>/etc/neutron/dhcp_agent.ini</filename> file <para>Edit the
and complete the following actions:</para> <filename>/etc/neutron/dhcp_agent.ini</filename> file
and complete the following actions:</para>
<substeps> <substeps>
<step> <step>
<para>In the <literal>[DEFAULT]</literal> section, configure <para>In the <literal>[DEFAULT]</literal> section, configure

35
doc/install-guide/section_nova-controller-install.xml
View File

@ -5,18 +5,20 @@
version="5.0" version="5.0"
xml:id="nova-controller-install"> xml:id="nova-controller-install">
<title>Install and configure controller node</title> <title>Install and configure controller node</title>
<para>This section describes how to install and configure the Compute <para>This section describes how to install and configure the
service, code-named nova, on the controller node.</para> Compute service, code-named nova, on the controller node.</para>
<procedure os="ubuntu;rhel;centos;fedora;sles;opensuse"> <procedure os="ubuntu;rhel;centos;fedora;sles;opensuse">
<title>To configure prerequisites</title> <title>To configure prerequisites</title>
<para>Before you install and configure Compute, you must create a database <para>Before you install and configure Compute, you must
and Identity service credentials including endpoints.</para> create a database and Identity service credentials
including endpoints.</para>
<step> <step>
<para>To create the database, complete these steps:</para> <para>To create the database, complete these steps:</para>
<substeps> <substeps>
<step> <step>
<para>Use the database access client to connect to the database <para>Use the database access client to connect to
server as the <literal>root</literal> user:</para> the database server as the
<literal>root</literal> user:</para>
<screen><prompt>$</prompt> <userinput>mysql -u root -p</userinput></screen> <screen><prompt>$</prompt> <userinput>mysql -u root -p</userinput></screen>
</step> </step>
<step> <step>
@ -30,8 +32,9 @@
IDENTIFIED BY '<replaceable>NOVA_DBPASS</replaceable>';</userinput> IDENTIFIED BY '<replaceable>NOVA_DBPASS</replaceable>';</userinput>
<userinput>GRANT ALL PRIVILEGES ON nova.* TO 'nova'@'%' \ <userinput>GRANT ALL PRIVILEGES ON nova.* TO 'nova'@'%' \
IDENTIFIED BY '<replaceable>NOVA_DBPASS</replaceable>';</userinput></screen> IDENTIFIED BY '<replaceable>NOVA_DBPASS</replaceable>';</userinput></screen>
<para>Replace <replaceable>NOVA_DBPASS</replaceable> with a suitable <para>Replace
password.</para> <replaceable>NOVA_DBPASS</replaceable> with a suitable
password.</para>
</step> </step>
<step> <step>
<para>Exit the database access client.</para> <para>Exit the database access client.</para>
@ -49,7 +52,7 @@
<substeps> <substeps>
<step> <step>
<para>Create the <literal>nova</literal> user:</para> <para>Create the <literal>nova</literal> user:</para>
<screen><prompt>$</prompt> <userinput>keystone user-create --name nova --pass <replaceable>NOVA_PASS</replaceable></userinput> <screen><prompt>$</prompt> <userinput>keystone user-create --name nova --pass <replaceable>NOVA_PASS</replaceable></userinput>
<computeroutput>+----------+----------------------------------+ <computeroutput>+----------+----------------------------------+
| Property | Value | | Property | Value |
+----------+----------------------------------+ +----------+----------------------------------+
@ -58,22 +61,23 @@
| id | 387dd4f7e46d4f72965ee99c76ae748c | | id | 387dd4f7e46d4f72965ee99c76ae748c |
| name | nova | | name | nova |
| username | nova | | username | nova |
+----------+----------------------------------+</computeroutput></screen> +----------+----------------------------------+
<para>Replace <replaceable>NOVA_PASS</replaceable> with a suitable </computeroutput></screen>
password.</para> <para>Replace <replaceable>NOVA_PASS</replaceable> with
a suitable password.</para>
</step> </step>
<step> <step>
<para>Link the <literal>nova</literal> user to the <para>Link the <literal>nova</literal> user to the
<literal>service</literal> tenant and <literal>admin</literal> <literal>service</literal> tenant and <literal>admin</literal>
role:</para> role:</para>
<screen><prompt>$</prompt> <userinput>keystone user-role-add --user nova --tenant service --role admin</userinput></screen> <screen><prompt>$</prompt> <userinput>keystone user-role-add --user nova --tenant service --role admin</userinput></screen>
<note> <note>
<para>This command provides no output.</para> <para>This command provides no output.</para>
</note> </note>
</step> </step>
<step> <step>
<para>Create the <literal>nova</literal> service:</para> <para>Create the <literal>nova</literal> service:</para>
<screen><prompt>$</prompt> <userinput>keystone service-create --name nova --type compute \ <screen><prompt>$</prompt> <userinput>keystone service-create --name nova --type compute \
--description "OpenStack Compute"</userinput> --description "OpenStack Compute"</userinput>
<computeroutput>+-------------+----------------------------------+ <computeroutput>+-------------+----------------------------------+
| Property | Value | | Property | Value |
@ -83,7 +87,8 @@
| id | 6c7854f52ce84db795557ebc0373f6b9 | | id | 6c7854f52ce84db795557ebc0373f6b9 |
| name | nova | | name | nova |
| type | compute | | type | compute |
+-------------+----------------------------------+</computeroutput></screen> +-------------+----------------------------------+
</computeroutput></screen>
</step> </step>
</substeps> </substeps>
</step> </step>