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/"
><glossterm>Horizon</glossterm></link>
</td>
<td>Provides a web-based self-service portal to interact
with underlying OpenStack services, such as launching
an instance, assigning IP addresses and configuring
access controls.</td>
<td>Provides a web-based self-service portal
to interact with underlying OpenStack services,
such as launching an instance, assigning IP
addresses and configuring access controls.</td>
</tr>
<tr>
<td><link

14
doc/common/section_conventions.xml
View File

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

6
doc/common/section_dochistory.xml
View File

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

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

@ -6,19 +6,20 @@
xml:id="basics-security">
<?dbhtml stop-chunking?>
<title>Security</title>
<para>OpenStack services support various security methods including
password, policy, and encryption. Additionally, supporting services
including the database server and message broker support at least
password security.</para>
<para>To ease the installation process, this guide only covers password
security where applicable. You can create secure passwords manually,
generate them using a tool such as
<link xlink:href="http://sourceforge.net/projects/pwgen/">pwgen</link>, or
by running the following command:</para>
<para>OpenStack services support various security methods
including password, policy, and encryption. Additionally,
supporting services including the database server and
message broker support at least password security.</para>
<para>To ease the installation process, this guide only
covers password security where applicable. You can create
secure passwords manually, generate them using a tool such as
<link xlink:href="http://sourceforge.net/projects/pwgen/">pwgen</link>,
or by running the following command:</para>
<screen><prompt>$</prompt> <userinput>openssl rand -hex 10</userinput></screen>
<para>For OpenStack services, this guide uses
<replaceable>SERVICE_PASS</replaceable> to reference service account
passwords and <replaceable>SERVICE_DBPASS</replaceable> to reference
<replaceable>SERVICE_PASS</replaceable> to reference
service account passwords and
<replaceable>SERVICE_DBPASS</replaceable> to reference
database passwords.</para>
<para>The following table provides a list of services that require
passwords and their associated references in the guide:
@ -114,17 +115,19 @@
</tbody>
</table>
</para>
<para>OpenStack and supporting services require administrative privileges
during installation and operation. In some cases, services perform
modifications to the host that can interfere with deployment automation
tools such as Ansible, Chef, and Puppet. For example, some OpenStack
services add a root wrapper to <literal>sudo</literal> that can interfere
with security policies. See the
<para>OpenStack and supporting services require administrative
privileges during installation and operation. In some cases,
services perform modifications to the host that can interfere
with deployment automation tools such as Ansible, Chef, and
Puppet. For example, some OpenStack services add a root
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>
for more information. Also, the Networking service assumes default values
for kernel network parameters and modifies firewall rules. To avoid most
issues during your initial installation, we recommend using a stock
deployment of a supported distribution on your hosts. However, if you
choose to automate deployment of your hosts, review the configuration
for more information. Also, the Networking service assumes
default values for kernel network parameters and modifies
firewall rules. To avoid most issues during your initial
installation, we recommend using a stock deployment of a
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>
</section>

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

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

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

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