openstack/openstack-manuals
Code Issues Proposed changes

Editorial updates to common files, including sentence-style headings and consistency/clarity edits

Browse Source 
Partial-Bug: #1250515

backport: havana

Change-Id: I9675dffd130c8aa6343143d9806adb4e0b74a55d
author: diane fleming
This commit is contained in:
Diane Fleming 2013-11-18 10:26:49 -06:00
parent 80cb0dc762
commit bc7a9f0da7
60 changed files with 2639 additions and 2389 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
doc/common/section_cli_openrc.xml
View File

@ -63,13 +63,12 @@
password.</para>
</step>
</procedure>
<para>Alternatively, you can create the
<filename>openrc.sh</filename> file from scratch.</para>
<procedure>
<step>
<para>Create the <filename>openrc.sh</filename> file
containing the authentication:</para>
and add the authentication information:</para>
<programlisting language="bash">export OS_USERNAME=<replaceable>USERNAME</replaceable>
export OS_PASSWORD=<replaceable>PASSWORD</replaceable>
export OS_TENANT_NAME=<replaceable>PROJECT_NAME</replaceable>

18
doc/common/section_compute-configure-ec2.xml
View File

@ -6,16 +6,12 @@
xmlns:ns4="http://www.w3.org/2000/svg"
xmlns:ns3="http://www.w3.org/1998/Math/MathML"
xmlns:ns="http://docbook.org/ns/docbook">
<title>Configuring the EC2 API</title>
<para>You can use <filename>nova.conf</filename> configuration
options to control which network address and port the EC2 API will
listen on, the formatting of some API responses, and authentication
related options.</para>
<title>Configure the EC2 API</title>
<para>You can set options in the <filename>nova.conf</filename>
configuration file to control which network address and port the
EC2 API listens on, the formatting of some API responses, and
authentication related options.</para>
<para>To customize these options for OpenStack EC2 API, use these
configuration option settings.</para>
<xi:include href="../common/tables/nova-ec2.xml" />
configuration option settings:</para>
<xi:include href="../common/tables/nova-ec2.xml"/>
</section>

13
doc/common/section_compute-configure-quotas.xml
View File

@ -6,13 +6,12 @@
xmlns:ns4="http://www.w3.org/2000/svg"
xmlns:ns3="http://www.w3.org/1998/Math/MathML"
xmlns:ns="http://docbook.org/ns/docbook" version="5.0">
<title>Configuring Quotas</title>
<title>Configure quotas</title>
<para>To prevent system capacities from being exhausted without
notification, you can set up quotas. Quotas are operational limits.
For example, the number of gigabytes allowed per tenant can be
controlled so that cloud resources are optimized.
Quotas are currently enforced at the tenant (or project) level,
rather than by user.
</para>
notification, you can set up quotas. Quotas are operational
limits. For example, the number of gigabytes allowed per tenant
can be controlled so that cloud resources are optimized. Quotas
are currently enforced at the tenant (or project) level, rather
than by user.</para>
<xi:include href="section_nova_cli_quotas.xml"/>
</section>

37
doc/common/section_compute-configure-spice.xml
View File

@ -1,26 +1,25 @@
<?xml version="1.0" encoding="UTF-8"?>
<section
xmlns="http://docbook.org/ns/docbook"
<section xmlns="http://docbook.org/ns/docbook"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink"
version="5.0"
xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
xml:id="spice-console">
<title>Spice Console</title>
<para>OpenStack Compute has long had support for VNC consoles to
guests. The VNC protocol is fairly limited, lacking support for
multiple monitors, bi-directional audio, reliable cut+paste, video
streaming and more. SPICE is a new protocol which aims to address
all the limitations in VNC, to provide good remote desktop
support.</para>
<title>SPICE console</title>
<para>OpenStack Compute supports VNC consoles to guests. The VNC
protocol is fairly limited, lacking support for multiple monitors,
bi-directional audio, reliable cut-and-paste, video streaming and
more. SPICE is a new protocol that aims to address the limitations
in VNC and provide good remote desktop support.</para>
<para>SPICE support in OpenStack Compute shares a similar
architecture to the VNC implementation. The OpenStack Dashboard
uses a SPICE-HTML5 widget in its console tab, that communicates to
the <literal>nova-spicehtml5proxy</literal> service using
SPICE-over-websockets. The <literal>nova-spicehtml5proxy</literal>
service communicates directly with the hypervisor process using SPICE.<note>
<para>If Spice is not configured correctly, Compute will fall
back upon VNC.</para>
architecture to the VNC implementation. The OpenStack dashboard
uses a SPICE-HTML5 widget in its console tab that communicates to
the <systemitem class="service">nova-spicehtml5proxy</systemitem>
service by using SPICE-over-websockets. The <systemitem
class="service">nova-spicehtml5proxy</systemitem> service
communicates directly with the hypervisor process by using SPICE.<note>
<para>If you do not configure SPICE correctly, Compute falls
back on VNC.</para>
</note></para>
<para>Options for configuring SPICE as the console for OpenStack Compute can be found below.</para>
<para>The following table shows the options to configure SPICE as
the console for OpenStack Compute:</para>
<xi:include href="../common/tables/nova-spice.xml"/>
</section>

147
doc/common/section_compute-configure-vnc.xml
View File

@ -3,9 +3,10 @@
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
xml:id="getting-started-with-vnc-proxy">
<title>VNC Console Proxy</title>
<title>VNC console proxy</title>
<para>The VNC proxy is an OpenStack component that enables compute
service users to access their instances through VNC clients.</para>
service users to access their instances through VNC
clients.</para>
<para>The VNC console connection works as follows:</para>
<orderedlist>
<listitem>
@ -15,17 +16,18 @@
</para>
</listitem>
<listitem>
<para>The user pastes the URL in a browser or as a client
parameter.</para>
<para>The user pastes the URL in a browser or uses it as a
client parameter.</para>
</listitem>
<listitem>
<para>The browser or client connects to the proxy.</para>
</listitem>
<listitem>
<para>The proxy talks to <systemitem class="service">nova-consoleauth</systemitem> to
authorize the user's token, and maps the token to the
<emphasis>private</emphasis> host and port of an instance's
VNC server.</para>
<para>The proxy talks to <systemitem class="service"
>nova-consoleauth</systemitem> to authorize the token for
the user, and maps the token to the
<emphasis>private</emphasis> host and port of the VNC server
for an instance.</para>
<para>The compute host specifies the address that the proxy
should use to connect through the
<filename>nova.conf</filename> file option,
@ -34,25 +36,25 @@
private host network.</para>
</listitem>
<listitem>
<para>The proxy initiates the connection to VNC server, and
<para>The proxy initiates the connection to VNC server and
continues to proxy until the session ends.</para>
</listitem>
</orderedlist>
<para>The proxy also tunnels the VNC protocol over WebSockets so
that the noVNC client has a way to talk VNC.</para>
that the noVNC client can talk VNC.</para>
<para>In general, the VNC proxy:</para>
<itemizedlist>
<listitem>
<para>Bridges between the public network, where the clients
live, and the private network, where vncservers live.</para>
<para>Bridges between the public network where the clients live
and the private network where vncservers live.</para>
</listitem>
<listitem>
<para>Mediates token authentication.</para>
</listitem>
<listitem>
<para>Transparently deals with hypervisor-specific connection
details to provide a uniform client experience. <figure
xml:id="novnc-process">
details to provide a uniform client experience.</para>
<figure xml:id="novnc-process">
<title>noVNC process</title>
<mediaobject>
<imageobject>
@ -62,7 +64,6 @@
</imageobject>
</mediaobject>
</figure>
</para>
</listitem>
</itemizedlist>
<section xml:id="about-nova-consoleauth">
@ -70,39 +71,44 @@
<title>About nova-consoleauth</title>
</info>
<para>Both client proxies leverage a shared service to manage
token auth called <systemitem class="service">nova-consoleauth</systemitem>. This
service must be running for either proxy to work. Many proxies
of either type can be run against a single
<systemitem class="service">nova-consoleauth</systemitem> service in a cluster
token authentication called <systemitem class="service"
>nova-consoleauth</systemitem>. This service must be running
for either proxy to work. Many proxies of either type can be run
against a single <systemitem class="service"
>nova-consoleauth</systemitem> service in a cluster
configuration.</para>
<para>Do not confuse the <systemitem class="service">nova-consoleauth</systemitem>
shared service with <literal>nova-console</literal>, which is a
XenAPI-specific service that most recent VNC proxy architectures
do not use.</para>
<para>Do not confuse the <systemitem class="service"
>nova-consoleauth</systemitem> shared service with
<literal>nova-console</literal>, which is a XenAPI-specific
service that most recent VNC proxy architectures do not
use.</para>
</section>
<section xml:id="typical-deployment">
<info>
<title>Typical deployment</title>
</info>
<para>A typical deployment consists of the following components:</para>
<para>A typical deployment has the following components:</para>
<itemizedlist>
<listitem>
<para>A <systemitem class="service">nova-consoleauth</systemitem> process. Typically
runs on the controller host.</para>
<para>A <systemitem class="service"
>nova-consoleauth</systemitem> process. Typically runs on
the controller host.</para>
</listitem>
<listitem>
<para>One or more <systemitem class="service">nova-novncproxy</systemitem> services.
Supports browser-based noVNC clients. For simple
deployments, this service typically runs on the same machine
as <systemitem class="service">nova-api</systemitem> because it proxies between the public network
and the private compute host network.</para>
<para>One or more <systemitem class="service"
>nova-novncproxy</systemitem> services. Supports
browser-based noVNC clients. For simple deployments, this
service typically runs on the same machine as <systemitem
class="service">nova-api</systemitem> because it operates
as a proxy between the public network and the private
compute host network.</para>
</listitem>
<listitem>
<para>One or more <literal>nova-xvpvncproxy</literal>
services. Supports the special Java client discussed here.
For simple deployments, this service typically runs on the
same machine as <systemitem class="service">nova-api</systemitem> because it proxies between the
public network and the private compute host network.</para>
same machine as <systemitem class="service"
>nova-api</systemitem> because it acts as a proxy between
the public network and the private compute host
network.</para>
</listitem>
<listitem>
<para>One or more compute hosts. These compute hosts must have
@ -117,15 +123,14 @@
<para>To support <link
xlink:href="http://docs.openstack.org/trunk/config-reference/content/configuring-openstack-compute-basics.html#section_configuring-compute-migrations"
>live migration</link>, you cannot specify a specific IP
address for <literal>vncserver_listen</literal>, because
that IP address does not exist on the destination
host.</para>
address for <literal>vncserver_listen</literal>, because that
IP address does not exist on the destination host.</para>
</note>
<note>
<para>The <literal>vncserver_proxyclient_address</literal>
defaults to <literal>127.0.0.1</literal>, which is the
address of the compute host that nova instructs proxies to
use when connecting to instance servers.</para>
defaults to <literal>127.0.0.1</literal>, which is the address
of the compute host that nova instructs proxies to use when
connecting to instance servers.</para>
<para>For all-in-one XenServer domU deployments, set this to
169.254.0.1.</para>
<para>For multi-host XenServer domU deployments, set to a dom0
@ -139,7 +144,8 @@
<title>nova-novncproxy (noVNC)</title>
</info>
<para>You must install the noVNC package, which contains the
<systemitem class="service">nova-novncproxy</systemitem> service.</para>
<systemitem class="service">nova-novncproxy</systemitem>
service.</para>
<para>As root, run the following command:</para>
<programlisting language="bash" role="gutter: false"><prompt>#</prompt> <userinput>apt-get install novnc</userinput></programlisting>
<para>The service starts automatically on installation.</para>
@ -148,7 +154,8 @@
<para>The configuration option parameter should point to your
<filename>nova.conf</filename> file, which includes the
message queue server address and credentials.</para>
<para>By default, <systemitem class="service">nova-novncproxy</systemitem> binds on
<para>By default, <systemitem class="service"
>nova-novncproxy</systemitem> binds on
<literal>0.0.0.0:6080</literal>.</para>
<para>To connect the service to your nova deployment, add the
following configuration options to your
@ -163,10 +170,9 @@
interfaces. This address is the one used by your domain
file.</para>
<programlisting language="bash" role="gutter: false"> &lt;graphics type="vnc" autoport="yes" keymap="en-us" listen="0.0.0.0"/></programlisting>
<note>
<para>To use live migration, make sure to use the
<replaceable>0.0.0.0</replaceable>address.</para>
<para>To use live migration, use the
<replaceable>0.0.0.0</replaceable> address.</para>
</note>
</listitem>
<listitem>
@ -182,36 +188,39 @@
</section>
<section xml:id="faq-about-vnc">
<info>
<title>Frequently asked questions about VNC access to
virtual machines</title>
<title>Frequently asked questions about VNC access to virtual
machines</title>
</info>
<itemizedlist>
<listitem>
<para><emphasis role="bold">Q: What is the difference between
<literal>nova-xvpvncproxy</literal> and
<systemitem class="service">nova-novncproxy</systemitem>?</emphasis>
<literal>nova-xvpvncproxy</literal> and <systemitem
class="service">nova-novncproxy</systemitem>?</emphasis>
</para>
<para>A: <literal>nova-xvpvncproxy</literal>, which ships with
nova, is a proxy that supports a simple Java client.
<systemitem class="service">nova-novncproxy</systemitem> uses noVNC to provide
VNC support through a web browser.</para>
<systemitem class="service">nova-novncproxy</systemitem>
uses noVNC to provide VNC support through a web
browser.</para>
</listitem>
<listitem>
<para><emphasis role="bold">Q: I want VNC support in the
Dashboard. What services do I need? </emphasis></para>
<para>A: You need <systemitem class="service">nova-novncproxy</systemitem>,
<systemitem class="service">nova-consoleauth</systemitem>, and correctly
configured compute hosts.</para>
<para>A: You need <systemitem class="service"
>nova-novncproxy</systemitem>, <systemitem class="service"
>nova-consoleauth</systemitem>, and correctly configured
compute hosts.</para>
</listitem>
<listitem>
<para><emphasis role="bold">Q: When I use <command>nova
get-vnc-console</command> or click on the VNC tab of the
Dashboard, it hangs. Why? </emphasis></para>
<para>A: Make sure you are running
<systemitem class="service">nova-consoleauth</systemitem> (in addition to
<systemitem class="service">nova-novncproxy</systemitem>). The proxies rely on
<systemitem class="service">nova-consoleauth</systemitem> to validate tokens,
and waits for a reply from them until a timeout is reached.
<para>A: Make sure you are running <systemitem class="service"
>nova-consoleauth</systemitem> (in addition to <systemitem
class="service">nova-novncproxy</systemitem>). The proxies
rely on <systemitem class="service"
>nova-consoleauth</systemitem> to validate tokens, and
waits for a reply from them until a timeout is reached.
</para>
</listitem>
<listitem>
@ -224,7 +233,8 @@
two servers:</para>
<programlisting language="bash" role="gutter: false">PROXYSERVER (public_ip=172.24.1.1, management_ip=192.168.1.1)
COMPUTESERVER (management_ip=192.168.1.2)</programlisting>
<para>Your <systemitem class="service">nova-compute</systemitem> configuration file must set the
<para>Your <systemitem class="service"
>nova-compute</systemitem> configuration file must set the
following values:</para>
<programlisting language="bash" role="gutter: false"># These flags help construct a connection data structure
vncserver_proxyclient_address=192.168.1.2
@ -248,11 +258,12 @@ vncserver_listen=192.168.1.2</programlisting>
<listitem>
<para>
<emphasis role="bold">Q: My noVNC does not work with recent
versions of web browsers. Why? </emphasis>
versions of web browsers. Why?</emphasis>
</para>
<para>A: Make sure you have <literal>python-numpy</literal>
installed, which is required to support a newer version of
the WebSocket protocol (HyBi-07+).</para>
<para>A: Make sure you have installed
<literal>python-numpy</literal>, which is required to
support a newer version of the WebSocket protocol
(HyBi-07+).</para>
</listitem>
<listitem>
<para>
@ -265,9 +276,9 @@ vncserver_listen=192.168.1.2</programlisting>
location of this file varies based on Linux distribution. On
Ubuntu 12.04, the file is at
<filename>/usr/share/pyshared/horizon/dashboards/nova/instances/templates/instances/_detail_vnc.html</filename>.</para>
<para>Modify the <literal>width</literal> and
<literal>height</literal> parameters, as follows:</para>
<programlisting>&lt;iframe src="{{ vnc_url }}" width="720" height="430"&gt;&lt;/iframe&gt;</programlisting>
<para>Modify the <option>width</option> and
<option>height</option> options, as follows:</para>
<programlisting language="bash" role="gutter: false">&lt;iframe src="{{ vnc_url }}" width="720" height="430"&gt;&lt;/iframe&gt;</programlisting>
</listitem>
</itemizedlist>
</section>

164
doc/common/section_compute-options.xml
View File

@ -1,34 +1,40 @@
<?xml version= "1.0" encoding= "UTF-8"?>
<section xml:id="compute-options"
xmlns= "http://docbook.org/ns/docbook"
xmlns:xi= "http://www.w3.org/2001/XInclude"
xmlns:xlink= "http://www.w3.org/1999/xlink" version= "5.0">
xmlns="http://docbook.org/ns/docbook"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0">
<title>File format for nova.conf</title>
<simplesect>
<title>Overview</title>
<para>The Compute service supports a large number of configuration options. These options
are specified in a configuration file whose default location in
<filename>/etc/nova/nova.conf</filename>.</para>
<para>The configuration file is in <link xlink:href="https://en.wikipedia.org/wiki/INI_file"
>INI file format</link>, with options specified as <literal>key=value</literal>
pairs, grouped into sections. Almost all of the configuration options are in the
<literal>DEFAULT</literal> section. Here's a brief
example:<programlisting language="ini">[DEFAULT]
<para>The Compute service supports a large number of
configuration options. These options are specified in the
<filename>/etc/nova/nova.conf</filename> configuration
file.</para>
<para>The configuration file is in <link
xlink:href="https://en.wikipedia.org/wiki/INI_file"
>INI file format</link>, with options specified as
<literal>key=value</literal> pairs, grouped into
sections. Almost all configuration options are in the
<literal>DEFAULT</literal> section. For
example:</para>
<programlisting language="ini">[DEFAULT]
debug=true
verbose=true
[trusted_computing]
server=10.3.4.2</programlisting></para>
server=10.3.4.2</programlisting>
</simplesect>
<simplesect>
<title>Types of configuration options</title>
<para>Each configuration option has an associated type that indicates what values can be
set. The supported option types are as follows:<variablelist>
<para>Each configuration option has an associated type that
indicates which values can be set. The supported option
types are:</para>
<variablelist>
<varlistentry>
<term>BoolOpt</term>
<listitem>
<para>Boolean option. Value must be either <literal>true</literal> or
<para>Boolean option. Value must be either
<literal>true</literal> or
<literal>false</literal> .
Example:<programlisting language="ini">debug=false</programlisting></para>
</listitem>
@ -43,84 +49,90 @@ server=10.3.4.2</programlisting></para>
<varlistentry>
<term>IntOption</term>
<listitem>
<para>Integer option. Value must be an integer. Example:
<para>Integer option. Value must be an integer.
Example:
<programlisting language="ini">glance_port=9292</programlisting></para>
</listitem>
</varlistentry>
<varlistentry>
<term>MultiStrOpt</term>
<listitem>
<para>String option. Same as StrOpt, except that it can be declared multiple
times to indicate multiple values.
Example:<programlisting language="ini">ldap_dns_servers=dns1.example.org
ldap_dns_servers=dns2.example.org</programlisting></para>
<para>String option. Same as StrOpt, except that
it can be declared multiple times to indicate
multiple values. Example:</para>
<programlisting language="ini">ldap_dns_servers=dns1.example.org
ldap_dns_servers=dns2.example.org</programlisting>
</listitem>
</varlistentry>
<varlistentry>
<term>ListOpt</term>
<listitem>
<para>List option. Value is a list of arbitrary strings separated by commas.
Example:<programlisting language="ini">enabled_apis=ec2,osapi_compute,metadata</programlisting></para>
<para>List option. Value is a list of arbitrary
strings separated by commas. Example:</para>
<programlisting language="ini">enabled_apis=ec2,osapi_compute,metadata</programlisting>
</listitem>
</varlistentry>
<varlistentry>
<term>FloatOpt</term>
<listitem>
<para>Floating-point option. Value must be a floating-point number.
Example:<programlisting language="ini">ram_allocation_ratio=1.5</programlisting></para>
<para>Floating-point option. Value must be a
floating-point number. Example:</para>
<programlisting language="ini">ram_allocation_ratio=1.5</programlisting>
</listitem>
</varlistentry>
</variablelist>
</para>
<important>
<para>Nova options should <emphasis>not</emphasis>
be quoted.</para>
<para>Do not specify quotes around Nova options.</para>
</important>
</simplesect>
<simplesect>
<title>Sections</title>
<para>Configuration options are grouped by section. The Compute config file supports the
following sections.<variablelist>
<para>Configuration options are grouped by section. The
Compute configuration file supports the following sections.<variablelist>
<varlistentry>
<term><literal>[DEFAULT]</literal></term>
<listitem>
<para>Almost all of the configuration options are organized into this
section. If the documentation for a configuration option does not
specify its section, assume that it should be placed in this one.</para>
<para>Contains most configuration options. If
the documentation for a configuration
option does not specify its section,
assume that it appears in this
section.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>[cells]</literal></term>
<listitem>
<para>The <literal>cells</literal> section is
used for options for configuring cells
functionality. See the <link
xlink:href="../openstack-compute/admin/content/ch_cells.html">Cells</link>
section of the OpenStack Compute Admin
Manual for more details.</para>
<para>Use options in this section to configure
cells functionality. For details, see the
Cells section (<link
xlink:href="../config-reference/content/section_compute-cells.html"
/>) in the <citetitle>OpenStack
Configuration
Reference</citetitle>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>[baremetal]</literal></term>
<listitem>
<para>This section is used for options that relate to the baremetal
hypervisor driver.</para>
<para>Use options in this section to configure
the baremetal hypervisor driver.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>[conductor]</literal></term>
<listitem>
<para>The <literal>conductor</literal> section is used for options for
configuring the <systemitem class="service">nova-conductor</systemitem> service.</para>
<para>Use options in this section to configure
the <systemitem class="service"
>nova-conductor</systemitem>
service.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>[trusted_computing]</literal></term>
<listitem>
<para>The <literal>trusted_computing</literal> section is used for options
that relate to the trusted computing pools functionality. Options in
this section describe how to connect to a remote attestation
<para>Use options in this section to configure
the trusted computing pools functionality
and how to connect to a remote attestation
service.</para>
</listitem>
</varlistentry>
@ -128,35 +140,47 @@ ldap_dns_servers=dns2.example.org</programlisting></para>
</simplesect>
<simplesect>
<title>Variable substitution</title>
<para>The configuration file supports variable substitution. Once a configuration option is
set, it can be referenced in later configuration values when preceded by
<literal>$</literal>. Consider the following example where <literal>my_ip</literal>
is defined and then <literal>$my_ip</literal> is used as a
variable.<programlisting language="ini">my_ip=10.2.3.4
<para>The configuration file supports variable substitution.
After you set a configuration option, it can be referenced
in later configuration values when you precede it with
<literal>$</literal>. This example defines
<literal>my_ip</literal> and then uses
<literal>$my_ip</literal> as a
variable:<programlisting language="ini">my_ip=10.2.3.4
glance_host=$my_ip
metadata_host=$my_ip</programlisting></para>
<para>If you need a value to contain the <literal>$</literal> symbol, escape it by doing
<literal>$$</literal>. For example, if your LDAP DNS password was
<literal>$xkj432</literal>, you would
do:<programlisting language="ini">ldap_dns_password=$$xkj432</programlisting></para>
<para>The Compute code uses Python's <literal>string.Template.safe_substitute()</literal>
method to implement variable substitution. For more details on how variable substitution
is resolved, see <link
xlink:href="http://docs.python.org/2/library/string.html#template-strings">Python
documentation on template strings</link> and <link
xlink:href="http://www.python.org/dev/peps/pep-0292/">PEP 292</link>.</para>
<para>If you need a value to contain the <literal>$</literal>
symbol, escape it with <literal>$$</literal>. For example,
if your LDAP DNS password was <literal>$xkj432</literal>,
specify it, as
follows:<programlisting language="ini">ldap_dns_password=$$xkj432</programlisting></para>
<para>The Compute code uses the Python
<literal>string.Template.safe_substitute()</literal>
method to implement variable substitution. For more
details on how variable substitution is resolved, see
<link
xlink:href="http://docs.python.org/2/library/string.html#template-strings"
>http://docs.python.org/2/library/string.html#template-strings</link>
and <link
xlink:href="http://www.python.org/dev/peps/pep-0292/"
>http://www.python.org/dev/peps/pep-0292/</link>.</para>
</simplesect>
<simplesect>
<title>Whitespace</title>
<para>To include whitespace in a configuration value, use a quoted string. For
example:<programlisting language="ini">ldap_dns_passsword='a password with spaces'</programlisting></para>
<para>To include whitespace in a configuration value, use a
quoted string. For example:</para>
<programlisting language="ini">ldap_dns_passsword='a password with spaces'</programlisting>
</simplesect>
<simplesect>
<title>Specifying an alternate location for nova.conf</title>
<para>The configuration file is loaded by all of the nova-* services, as well as the
<command>nova-manage</command> command-line tool. To specify an alternate location
for the configuration file, pass the <literal>--config-file
<replaceable>/path/to/nova.conf</replaceable></literal> argument when starting a
nova-* service or calling <command>nova-manage</command>.</para>
<title>Define an alternate location for nova.conf</title>
<para>All <systemitem class="service">nova-*</systemitem>
services and the <command>nova-manage</command>
command-line client load the configuration file. To define
an alternate location for the configuration file, pass the
<parameter>--config-file
<replaceable>/path/to/nova.conf</replaceable></parameter>
parameter when you start a <systemitem class="service"
>nova-*</systemitem> service or call a
<command>nova-manage</command> command.</para>
</simplesect>
</section>

181
doc/common/section_compute_config-api.xml
View File

@ -3,87 +3,92 @@
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
xml:id="configuring-compute-API">
<title>Configuring the Compute API</title>
<para>The Compute API, run by the
<systemitem class="service">nova-api</systemitem>
daemon, is the component of OpenStack Compute that
receives and responds to user requests, whether they
be direct API calls, or via the CLI tools or dashboard.</para>
<title>Configure the Compute API</title>
<para>The Compute API, run by the <systemitem class="service"
>nova-api</systemitem> daemon, is the component of
OpenStack Compute that receives and responds to user requests,
whether they be direct API calls, or via the CLI tools or
dashboard.</para>
<simplesect>
<title>Configuring Compute API password handling</title>
<para>The OpenStack Compute API allows the user to specify an
admin password when creating (or rebuilding) a server
instance. If no password is specified, a randomly generated
password is used. The password is returned in the API
<title>Configure Compute API password handling</title>
<para>The OpenStack Compute API enables users to specify an
administrative password when they create or rebuild a
server instance. If the user does not specify a password,
a random password is generated and returned in the API
response.</para>
<para>In practice, the handling of the admin password depends on
the hypervisor in use, and may require additional
configuration of the instance, such as installing an agent to
handle the password setting. If the hypervisor and instance
configuration do not support the setting of a password at
server create time, then the password returned by the create
API call will be misleading, since it was ignored.</para>
<para>To prevent this confusion, the configuration option
<literal>enable_instance_password</literal> can be used to
disable the return of the admin password for installations
that don't support setting instance passwords.</para>
<para>In practice, how the admin password is handled depends
on the hypervisor in use and might require additional
configuration of the instance. For example, you might have
to install an agent to handle the password setting. If the
hypervisor and instance configuration do not support
setting a password at server create time, the password
that is returned by the create API call is misleading
because it was ignored.</para>
<para>To prevent this confusion, use the
<option>enable_instance_password</option>
configuration option to disable the return of the admin
password for installations that do not support setting
instance passwords.</para>
</simplesect>
<simplesect>
<title>Configuring Compute API Rate Limiting</title>
<title>Configure Compute API rate limiting</title>
<para>OpenStack Compute supports API rate limiting for the
OpenStack API. The rate limiting allows an administrator to
configure limits on the type and number of API calls that can
be made in a specific time interval.</para>
<para>When API rate limits are exceeded, HTTP requests will
return a error with a status code of 413 "Request entity too
large", and will also include a 'Retry-After' HTTP header. The
response body will include the error details, and the delay
before the request should be retried.</para>
OpenStack API. The rate limiting allows an administrator
to configure limits on the type and number of API calls
that can be made in a specific time interval.</para>
<para>When API rate limits are exceeded, HTTP requests return
an error with a status code of <errorcode>413</errorcode>
<errortext>Request entity too large</errortext>, and
includes an HTTP <literal>Retry-After</literal> header.
The response body includes the error details and the delay
before you should retry the request.</para>
<para>Rate limiting is not available for the EC2 API.</para>
</simplesect>
<simplesect>
<title>Specifying Limits</title>
<para>Limits are specified using five values:</para>
<title>Define limits</title>
<para>To define limits, set these values:</para>
<itemizedlist>
<listitem>
<para>The <emphasis role="bold">HTTP method</emphasis> used
in the API call, typically one of GET, PUT, POST, or
DELETE.</para>
<para>The <emphasis role="bold">HTTP method</emphasis>
used in the API call, typically one of GET, PUT,
POST, or DELETE.</para>
</listitem>
<listitem>
<para>A <emphasis role="bold">human readable URI</emphasis>
that is used as a friendly description of where the limit
is applied.</para>
<para>A <emphasis role="bold">human readable
URI</emphasis> that is used as a friendly
description of where the limit is applied.</para>
</listitem>
<listitem>
<para>A <emphasis role="bold">regular expression</emphasis>.
The limit will be applied to all URI's that match the
regular expression and HTTP Method.</para>
<para>A <emphasis role="bold">regular
expression</emphasis>. The limit is applied to
all URIs that match the regular expression and
HTTP method.</para>
</listitem>
<listitem>
<para>A <emphasis role="bold">limit value </emphasis> that
specifies the maximum count of units before the limit
takes effect.</para>
<para>A <emphasis role="bold">limit value </emphasis>
that specifies the maximum count of units before
the limit takes effect.</para>
</listitem>
<listitem>
<para>An <emphasis role="bold">interval</emphasis> that
specifies time frame the limit is applied to. The interval
can be SECOND, MINUTE, HOUR, or DAY.</para>
<para>An <emphasis role="bold">interval</emphasis>
that specifies time frame to which the limit is
applied. The interval can be SECOND, MINUTE, HOUR,
or DAY.</para>
</listitem>
</itemizedlist>
<para>Rate limits are applied in order, relative to the HTTP
<para>Rate limits are applied in relative order to the HTTP
method, going from least to most specific. For example,
although the default threshold for POST to */servers is 50 per
day, one cannot POST to */servers more than 10 times within a
single minute because the rate limits for any POST is
10/min.</para>
although the default threshold for POST to */servers is 50
each day, you cannot POST to */servers more than 10 times
in a single minute because the rate limits for any POST is
10 each minute.</para>
</simplesect>
<simplesect>
<title>Default Limits</title>
<para>OpenStack compute is normally installed with the following
limits enabled:</para>
<title>Default limits</title>
<para>Normally, you install OpenStack Compute with the
following limits enabled:</para>
<table rules="all">
<caption>Default API Rate Limits</caption>
<caption>Default API rate limits</caption>
<thead>
<tr>
<td>HTTP method</td>
@ -127,40 +132,54 @@
</table>
</simplesect>
<simplesect>
<title>Configuring and Changing Limits</title>
<para>The actual limits are specified in the file
<filename>etc/nova/api-paste.ini</filename>, as part of the
WSGI pipeline.</para>
<para>To enable limits, ensure the
'<literal>ratelimit</literal>' filter is included in the API
pipeline specification. If the '<literal>ratelimit</literal>'
filter is removed from the pipeline, limiting will be
disabled. There should also be a definition for the rate limit
filter. The lines will appear as follows:</para>
<programlisting language="ini">
[pipeline:openstack_compute_api_v2]
<title>Configure and change limits</title>
<para>As part of the WSGI pipeline, the
<filename>etc/nova/api-paste.ini</filename> file
defines the actual limits.</para>
<para>To enable limits, include the
<option>ratelimit</option>' filter in the API pipeline
specification. If the <option>ratelimit</option> filter is
removed from the pipeline, limiting is disabled. You must
also define the rate limit filter. The lines appear as
follows:</para>
<programlisting language="ini">[pipeline:openstack_compute_api_v2]
pipeline = faultwrap authtoken keystonecontext ratelimit osapi_compute_app_v2
[pipeline:openstack_volume_api_v1]
pipeline = faultwrap authtoken keystonecontext ratelimit osapi_volume_app_v1
[filter:ratelimit]
paste.filter_factory = nova.api.openstack.compute.limits:RateLimitingMiddleware.factory
</programlisting>
<para>To modify the limits, add a '<literal>limits</literal>'
paste.filter_factory = nova.api.openstack.compute.limits:RateLimitingMiddleware.factory</programlisting>
<para>To modify the limits, add a <literal>limits</literal>
specification to the <literal>[filter:ratelimit]</literal>
section of the file. The limits are specified in the order
HTTP method, friendly URI, regex, limit, and interval. The
following example specifies the default rate limiting
section of the file. Specify the limits in this
order:</para>
<orderedlist>
<listitem>
<para>HTTP method</para>
</listitem>
<listitem>
<para>friendly URI</para>
</listitem>
<listitem>
<para>regex</para>
</listitem>
<listitem>
<para>limit</para>
</listitem>
<listitem>
<para>interval</para>
</listitem>
</orderedlist>
<para>The following example shows the default rate-limiting
values:</para>
<programlisting language="ini">
[filter:ratelimit]
<programlisting language="ini">[filter:ratelimit]
paste.filter_factory = nova.api.openstack.compute.limits:RateLimitingMiddleware.factory
limits =(POST, "*", .*, 10, MINUTE);(POST, "*/servers", ^/servers, 50, DAY);(PUT, "*", .*, 10, MINUTE);(GET, "*changes-since*", .*changes-since.*, 3, MINUTE);(DELETE, "*", .*, 100, MINUTE)
</programlisting>
limits =(POST, "*", .*, 10, MINUTE);(POST, "*/servers", ^/servers, 50, DAY);(PUT, "*", .*, 10, MINUTE);(GET, "*changes-since*", .*changes-since.*, 3, MINUTE);(DELETE, "*", .*, 100, MINUTE)</programlisting>
</simplesect>
<simplesect>
<title>List of configuration options for Compute API</title>
<simplesect xml:id="compute_config_options">
<title>Configuration reference</title>
<para>The following table lists the Compute API configuration options:</para>
<xi:include href="tables/nova-api.xml"/>
</simplesect>
</section>

146
doc/common/section_config_keystone_ldap.xml
View File

@ -1,15 +1,14 @@
<?xml version="1.0" encoding="UTF-8"?>
<section
xmlns="http://docbook.org/ns/docbook"
<section xmlns="http://docbook.org/ns/docbook"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
xml:id="configuring-keystone-for-ldap-backend">
<title>Configuring OpenStack Identity for an LDAP backend</title>
<para>As an alternative to the SQL Database backing store, Identity can use
a directory server to provide the Identity service. An example schema
for AcmeExample would look like this:</para>
<screen>
dn: dc=AcmeExample,dc=org
<title>Configure the Identity Service with an LDAP
back-end</title>
<para>As an alternative to the SQL database backing store, the
Identity Service can use a directory server to provide the
Identity Service, for example:</para>
<programlisting language="ini">dn: dc=AcmeExample,dc=org
dc: AcmeExample
objectClass: dcObject
objectClass: organizationalUnit
@ -28,12 +27,11 @@ ou: users
dn: ou=Roles,dc=AcmeExample,dc=org
objectClass: top
objectClass: organizationalUnit
ou: roles
</screen>
<para>The corresponding entries in the <filename>keystone.conf</filename>
configuration file are:</para>
<programlisting language="ini">
[ldap]
ou: roles</programlisting>
<para>The corresponding entries in the
<filename>keystone.conf</filename> configuration file
are:</para>
<programlisting language="ini">[ldap]
url = ldap://localhost
user = dc=Manager,dc=AcmeExample,dc=org
password = badpassword
@ -48,30 +46,26 @@ tenant_tree_dn = ou=Groups,dc=AcmeExample,dc=com
tenant_objectclass = groupOfNames
role_tree_dn = ou=Roles,dc=AcmeExample,dc=com
role_objectclass = organizationalRole
</programlisting>
role_objectclass = organizationalRole</programlisting>
<para>The default object classes and attributes are intentionally
simplistic. They reflect the common standard objects according to the
LDAP RFCs. However, in a live deployment, the correct attributes can be
overridden to support a preexisting, more complex schema. For example,
in the user object, the objectClass posixAccount from RFC2307 is very
common. If this is the underlying objectclass, then the
<emphasis>uid</emphasis> field should probably be
<emphasis>uidNumber</emphasis> and <emphasis>username</emphasis>
field either <emphasis>uid</emphasis> or <emphasis>cn</emphasis>. To
change these two fields, the corresponding entries in the Keystone
configuration file are:</para>
<programlisting language="ini">
[ldap]
simple. They reflect the common standard objects according to
the LDAP RFCs. However, in a live deployment, you can override
the correct attributes to support a preexisting, complex
schema. For example, in the user object, the objectClass
posixAccount from RFC2307 is very common. If this is the
underlying objectclass, then the <emphasis>uid</emphasis>
field should probably be <emphasis>uidNumber</emphasis> and
<emphasis>username</emphasis> field either
<emphasis>uid</emphasis> or <emphasis>cn</emphasis>. To
change these two fields, the corresponding entries in the
Keystone configuration file are:</para>
<programlisting language="ini">[ldap]
user_id_attribute = uidNumber
user_name_attribute = cn
</programlisting>
<para>There is a set of allowed actions per object type that you can modify
depending on your specific deployment. For example, the users are
managed by another tool and you have only read access, in such case the
configuration is:</para>
<programlisting language="ini">
[ldap]
user_name_attribute = cn</programlisting>
<para>Depending on your deployment, you can modify a set of
allowed actions for each object type. For example, you might
set the following options:</para>
<programlisting language="ini">[ldap]
user_allow_create = False
user_allow_update = False
user_allow_delete = False
@ -82,55 +76,42 @@ tenant_allow_delete = True
role_allow_create = True
role_allow_update = True
role_allow_delete = True
</programlisting>
<para>There are some configuration options for filtering users, tenants and
roles, if the backend is providing too much output, in such case the
configuration will look like:</para>
<programlisting language="ini">
[ldap]
role_allow_delete = True</programlisting>
<para>If the back-end provides too much output, you can filter
users, tenants, and roles. For example:</para>
<programlisting language="ini">[ldap]
user_filter = (memberof=CN=acme-users,OU=workgroups,DC=AcmeExample,DC=com)
tenant_filter =
role_filter =
</programlisting>
<para>
In case that the directory server does not have an attribute enabled
of type boolean for the user, there are several configuration
parameters that can be used to extract the value from an integer
attribute like in Active Directory:
</para>
<programlisting language="ini">
[ldap]
role_filter =</programlisting>
<para>If the directory server has not enabled the
<literal>boolean</literal> type for the user, you can use
configuration options to extract the value from an integer
attribute. For example, in an Active Directory, as
follows:</para>
<programlisting language="ini">[ldap]
user_enabled_attribute = userAccountControl
user_enabled_mask = 2
user_enabled_default = 512
</programlisting>
<para>
In this case the attribute is an integer and the enabled attribute
is listed in bit 1, so the if the mask configured
<emphasis>user_enabled_mask</emphasis> is different from 0, it gets
the value from the field <emphasis>user_enabled_attribute</emphasis>
and it makes an ADD operation with the value indicated on
<emphasis>user_enabled_mask</emphasis> and if the value matches the
mask then the account is disabled.
</para>
<para>
It also saves the value without mask to the user identity in the
attribute <emphasis>enabled_nomask</emphasis>. This is needed in
order to set it back in case that we need to change it to
enable/disable a user because it contains more information than the
status like password expiration. Last setting
<emphasis>user_enabled_mask</emphasis> is needed in order to create
a default value on the integer attribute (512 = NORMAL ACCOUNT on
AD)
</para>
<para>
In case of Active Directory the classes and attributes could not
match the specified classes in the LDAP module so you can configure
them like so:
</para>
<programlisting language="ini">
[ldap]
user_enabled_default = 512</programlisting>
<para>The attribute is an integer. Bit 1 contains the enabled
attribute. If the <emphasis>user_enabled_mask</emphasis> mask
is not 0, it gets its value from the
<option>user_enabled_attribute</option> field and it
performs an ADD operation by using the
<emphasis>user_enabled_mask</emphasis> value. If the value
matches the mask, the account is disabled.</para>
<para>It also saves the value without mask to the
<literal>identity</literal> user in the
<option>enabled_nomask</option> attribute. In case you
must change it to enable or disable a user, you can use this
value because it contains more information than the status
such as, password expiration. The
<emphasis>user_enabled_mask</emphasis> value is required
to create a default value on the integer attribute (512 =
NORMAL ACCOUNT on AD).</para>
<para>If Active Directory classes and attributes do not match the
specified classes in the LDAP module, so you can modify them,
as follows:</para>
<programlisting language="ini">[ldap]
user_objectclass = person
user_id_attribute = cn
user_name_attribute = cn
@ -150,6 +131,5 @@ role_objectclass = organizationalRole
role_id_attribute = cn
role_name_attribute = ou
role_member_attribute = roleOccupant
role_attribute_ignore =
</programlisting>
role_attribute_ignore =</programlisting>
</section>

2
doc/common/section_dashboard_access.xml
View File

@ -41,7 +41,7 @@
for the dashboard:</para>
<screen><prompt>$</prompt> <userinput>https://<replaceable>IP_ADDRESS_OR_HOSTNAME</replaceable>/</userinput></screen>
<note>
<title>Certificate Warning</title>
<title>Certificate warning</title>
<para>If a certificate warning appears when you try to
access the URL for the first time, a self-signed
certificate is in use, which is not considered

3
doc/common/section_dashboard_sessions.xml
View File

@ -96,7 +96,7 @@ CACHES = {
</section>
</section>
<section xml:id="dashboard-session-database">
<title>Database</title>
<title>Initialize and configure the database</title>
<para>Database-backed sessions are scalable, persistent, and
can be made high-concurrency and highly-available.</para>
<para>However, database-backed sessions are one of the slower
@ -105,7 +105,6 @@ CACHES = {
can also be a substantial undertaking and is far beyond
the scope of this documentation.</para>
<procedure>
<title>To initialize and configure the database:</title>
<step>
<para>Start the mysql command line client:</para>
<screen><prompt>$</prompt> <userinput>mysql -u root -p</userinput></screen>

61
doc/common/section_fibrechannel.xml
View File

@ -1,62 +1,49 @@
<?xml version="1.0" encoding="UTF-8"?>
<section xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="fibrechannel">
<title>Nova Compute Fibre Channel Support</title>
<section xml:id="fibre-channel-overview"><title>Overview of Fibre Channel Support</title>
<para>
<itemizedlist>
<listitem>
<para>Fibre Channel support in OpenStack Compute is remote block storage attached
to Compute nodes for VMs.</para>
</listitem>
<listitem>
<para>In the Grizzly release, Fibre Channel only supports the KVM hypervisor.</para>
</listitem>
<listitem>
<para>There is no automatic zoning support in Nova or Cinder for Fibre Channel. 
Fibre Channel arrays must be pre-zoned or directly attached to the KVM
hosts.</para>
</listitem>
</itemizedlist>
</para>
</section>
<section xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
xml:id="fibrechannel">
<title>Fibre Channel support in Compute</title>
<para>Fibre Channel support in OpenStack Compute is remote block
storage attached to Compute nodes for VMs.</para>
<para>In the Grizzly release, Fibre Channel supports only the KVM
hypervisor.</para>
<para>Nova and Cinder for Fibre Channel do not support automatic
zoning. Fibre Channel arrays must be pre-zoned or directly
attached to the KVM hosts.</para>
<section xml:id="fibre-channel-reqs">
<title>Requirements for KVM Hosts</title>
<para>The KVM host must have the following system packages installed:</para>
<para>
<title>KVM host requirements</title>
<para>You must install these packages on the KVM host:</para>
<itemizedlist>
<listitem>
<para>
<filename>sysfstools</filename> - Nova uses the <filename>systool</filename>
application in this package.</para>
<package>sysfstools</package> - Nova uses the
<package>systool</package> application in this
package.</para>
</listitem>
<listitem>
<para>
<filename>sg3-utils</filename> - Nova uses the <filename>sg_scan</filename>
and <filename>sginfo</filename> applications.</para>
<package>sg3-utils</package> - Nova uses the
<package>sg_scan</package> and
<package>sginfo</package> applications.</para>
</listitem>
</itemizedlist>
</para>
<para>Installing the <filename>multipath-tools</filename> package is optional.</para>
<para>Installing the <package>multipath-tools</package>
package is optional.</para>
</section>
<section xml:id="fibre-channel-packages">
<title>Installing the Required Packages</title>
<para>Use the following commands to install the system packages.</para>
<para>
<title>Install required packages</title>
<para>Use these commands to install the system
packages:</para>
<itemizedlist>
<listitem>
<para>For systems running Ubuntu:</para>
<para>
<screen><prompt>$</prompt> <userinput>sudo apt-get install sysfstools sg3-utils multipath-tools</userinput></screen>
</para>
</listitem>
</itemizedlist>
</para>
<itemizedlist>
<listitem>
<para>For systems running Red Hat:</para>
<para>
<screen><prompt>$</prompt> <userinput>sudo yum install sysfstools sg3_utils multipath-tools</userinput></screen>
</para>
</listitem>
</itemizedlist>
</section>

214
doc/common/section_getstart_compute.xml
View File

@ -3,10 +3,10 @@
xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
xml:id="compute-service">
<title>Compute service</title>
<para>The Compute service is a cloud computing fabric
controller, which is the main part of an IaaS system. Use it to
host and manage cloud computing systems. The main modules are
implemented in Python.</para>
<para>The Compute service is a cloud computing fabric controller,
which is the main part of an IaaS system. Use it to host and
manage cloud computing systems. The main modules are implemented
in Python.</para>
<para>Compute interacts with the Identity Service for
authentication, Image Service for images, and the Dashboard for
the user and administrative interface. Access to images is limited
@ -19,60 +19,58 @@
<itemizedlist>
<title>API</title>
<listitem>
<para><systemitem class="service">nova-api</systemitem>
service. Accepts and responds to end user compute API
calls. Supports the OpenStack Compute API, the Amazon EC2
API, and a special Admin API for privileged users to
perform administrative actions. Also, initiates most
orchestration activities, such as running an instance, and
enforces some policies.</para>
<para><systemitem class="service">nova-api</systemitem> service.
Accepts and responds to end user compute API calls. Supports
the OpenStack Compute API, the Amazon EC2 API, and a special
Admin API for privileged users to perform administrative
actions. Also, initiates most orchestration activities, such
as running an instance, and enforces some policies.</para>
</listitem>
<listitem>
<para><systemitem class="service">nova-api-metadata</systemitem> service. Accepts
metadata requests from instances. The <systemitem class="service">nova-api-metadata</systemitem> service
is generally only used when you run in multi-host mode
<para><systemitem class="service">nova-api-metadata</systemitem>
service. Accepts metadata requests from instances. The
<systemitem class="service">nova-api-metadata</systemitem>
service is generally only used when you run in multi-host mode
with <systemitem class="service">nova-network</systemitem>
installations. For details, see
<link xlink:href="http://docs.openstack.org/admin-guide-cloud/content/section_metadata-service.html">Metadata service</link>
in the <citetitle>Cloud Administrator Guide</citetitle>.</para>
<para>Note for Debian users: on Debian system, it is included in the
<systemitem class="service">nova-api</systemitem>
package, and can be selected through <systemitem class="library">debconf</systemitem>.</para>
installations. For details, see <link
xlink:href="http://docs.openstack.org/admin-guide-cloud/content/section_metadata-service.html"
>Metadata service</link> in the <citetitle>Cloud
Administrator Guide</citetitle>.</para>
<para>On Debian systems, it is included in the <systemitem
class="service">nova-api</systemitem> package, and can be
selected through <package>debconf</package>.</para>
</listitem>
</itemizedlist>
<itemizedlist>
<title>Compute core</title>
<listitem>
<para><systemitem class="service">nova-compute</systemitem>
process. A worker daemon that creates and terminates
virtual machine instances through hypervisor APIs. For
example, XenAPI for XenServer/XCP, libvirt for KVM or
QEMU, VMwareAPI for VMware, and so on. The process by
which it does so is fairly complex but the basics are
simple: Accept actions from the queue and perform a series
of system commands, like launching a KVM instance, to
carry them out while updating state in the
process. A worker daemon that creates and terminates virtual
machine instances through hypervisor APIs. For example, XenAPI
for XenServer/XCP, libvirt for KVM or QEMU, VMwareAPI for
VMware, and so on. The process by which it does so is fairly
complex but the basics are simple: Accept actions from the
queue and perform a series of system commands, like launching
a KVM instance, to carry them out while updating state in the
database.</para>
</listitem>
<listitem>
<para><systemitem class="service"
>nova-scheduler</systemitem> process. Conceptually the
simplest piece of code in Compute. Takes a virtual machine
instance request from the queue and determines on which
compute server host it should run.</para>
<para><systemitem class="service">nova-scheduler</systemitem>
process. Conceptually the simplest piece of code in Compute.
Takes a virtual machine instance request from the queue and
determines on which compute server host it should run.</para>
</listitem>
<listitem>
<para><systemitem class="service"
>nova-conductor</systemitem> module. Mediates
interactions between <systemitem class="service"
>nova-compute</systemitem> and the database. Aims to
eliminate direct accesses to the cloud database made by
<systemitem class="service">nova-compute</systemitem>.
The <systemitem class="service"
>nova-conductor</systemitem> module scales horizontally.
However, do not deploy it on any nodes where <systemitem
class="service">nova-compute</systemitem> runs. For more
information, see <link
<para><systemitem class="service">nova-conductor</systemitem>
module. Mediates interactions between <systemitem
class="service">nova-compute</systemitem> and the database.
Aims to eliminate direct accesses to the cloud database made
by <systemitem class="service">nova-compute</systemitem>. The
<systemitem class="service">nova-conductor</systemitem>
module scales horizontally. However, do not deploy it on any
nodes where <systemitem class="service"
>nova-compute</systemitem> runs. For more information, see
<link
xlink:href="http://russellbryantnet.wordpress.com/2012/11/19/a-new-nova-service-nova-conductor/"
>A new Nova service: nova-conductor</link>.</para>
</listitem>
@ -82,61 +80,58 @@
<listitem>
<para><systemitem class="service">nova-network</systemitem>
worker daemon. Similar to <systemitem class="service"
>nova-compute</systemitem>, it accepts networking tasks
from the queue and performs tasks to manipulate the
network, such as setting up bridging interfaces or
changing iptables rules. This functionality is being
migrated to OpenStack Networking, which is a separate
OpenStack service.</para>
>nova-compute</systemitem>, it accepts networking tasks from
the queue and performs tasks to manipulate the network, such
as setting up bridging interfaces or changing iptables rules.
This functionality is being migrated to OpenStack Networking,
which is a separate OpenStack service.</para>
</listitem>
<listitem>
<para><systemitem class="service"
>nova-dhcpbridge</systemitem> script. Tracks IP address
leases and records them in the database by using the
dnsmasq <literal>dhcp-script</literal> facility. This
functionality is being migrated to OpenStack Networking.
OpenStack Networking provides a different script.</para>
<para><systemitem class="service">nova-dhcpbridge</systemitem>
script. Tracks IP address leases and records them in the
database by using the dnsmasq <literal>dhcp-script</literal>
facility. This functionality is being migrated to OpenStack
Networking. OpenStack Networking provides a different
script.</para>
</listitem>
</itemizedlist>
<?hard-pagebreak?>
<itemizedlist>
<title>Console interface</title>
<listitem>
<para><systemitem class="service"
>nova-consoleauth</systemitem> daemon. Authorizes tokens
for users that console proxies provide. See <systemitem
class="service">nova-novncproxy</systemitem> and
<systemitem class="service"
>nova-xvpnvcproxy</systemitem>. This service must be
running for console proxies to work. Many proxies of
<para><systemitem class="service">nova-consoleauth</systemitem>
daemon. Authorizes tokens for users that console proxies
provide. See <systemitem class="service"
>nova-novncproxy</systemitem> and <systemitem
class="service">nova-xvpnvcproxy</systemitem>. This service
must be running for console proxies to work. Many proxies of
either type can be run against a single <systemitem
class="service">nova-consoleauth</systemitem> service in
a cluster configuration. For information, see <link
class="service">nova-consoleauth</systemitem> service in a
cluster configuration. For information, see <link
xlink:href="http://docs.openstack.org/trunk/config-reference/content/about-nova-consoleauth.html"
>About nova-consoleauth</link>.</para>
</listitem>
<listitem>
<para><systemitem class="service"
>nova-novncproxy</systemitem> daemon. Provides a proxy
for accessing running instances through a VNC connection.
Supports browser-based novnc clients.</para>
<para><systemitem class="service">nova-novncproxy</systemitem>
daemon. Provides a proxy for accessing running instances
through a VNC connection. Supports browser-based novnc
clients.</para>
</listitem>
<listitem>
<para><systemitem class="service">nova-console</systemitem>
daemon. Deprecated for use with Grizzly. Instead, the
<systemitem class="service"
>nova-xvpnvncproxy</systemitem> is used.</para>
<systemitem class="service">nova-xvpnvncproxy</systemitem>
is used.</para>
</listitem>
<listitem>
<para><systemitem class="service"
>nova-xvpnvncproxy</systemitem> daemon. A proxy for
accessing running instances through a VNC connection.
Supports a Java client specifically designed for
<para><systemitem class="service">nova-xvpnvncproxy</systemitem>
daemon. A proxy for accessing running instances through a VNC
connection. Supports a Java client specifically designed for
OpenStack.</para>
</listitem>
<listitem>
<para><systemitem class="service">nova-cert</systemitem>
daemon. Manages x509 certificates.</para>
<para><systemitem class="service">nova-cert</systemitem> daemon.
Manages x509 certificates.</para>
</listitem>
</itemizedlist>
<para os="debian">In Debian, a unique
@ -150,37 +145,36 @@
edit the <filename>/etc/default/nova-consoleproxy</filename> file
and stop and start the console daemons.</para>
<itemizedlist>
<title>Image Management (EC2 scenario)</title>
<title>Image management (EC2 scenario)</title>
<listitem>
<para><systemitem class="service"
>nova-objectstore</systemitem> daemon. Provides an S3
interface for registering images with the Image Service.
Mainly used for installations that must support euca2ools.
The euca2ools tools talk to <systemitem class="service"
>nova-objectstore</systemitem> in <emphasis
<para><systemitem class="service">nova-objectstore</systemitem>
daemon. Provides an S3 interface for registering images with
the Image Service. Mainly used for installations that must
support euca2ools. The euca2ools tools talk to <systemitem
class="service">nova-objectstore</systemitem> in <emphasis
role="italic">S3 language</emphasis>, and <systemitem
class="service">nova-objectstore</systemitem> translates
S3 requests into Image Service requests.</para>
class="service">nova-objectstore</systemitem> translates S3
requests into Image Service requests.</para>
</listitem>
<listitem>
<para>euca2ools client. A set of command-line interpreter
commands for managing cloud resources. Though not an
OpenStack module, you can configure <systemitem
class="service">nova-api</systemitem> to support this
EC2 interface. For more information, see the <link
commands for managing cloud resources. Though not an OpenStack
module, you can configure <systemitem class="service"
>nova-api</systemitem> to support this EC2 interface. For
more information, see the <link
xlink:href="http://www.eucalyptus.com/eucalyptus-cloud/documentation/2.0"
>Eucalyptus 2.0 Documentation</link>.</para>
</listitem>
</itemizedlist>
<itemizedlist>
<title>Command Line Interpreter/Interfaces</title>
<title>Command-line clients and other interfaces</title>
<listitem>
<para>nova client. Enables users to submit commands as a
tenant administrator or end user.</para>
<para>nova client. Enables users to submit commands as a tenant
administrator or end user.</para>
</listitem>
<listitem>
<para>nova-manage client. Enables cloud administrators to
submit commands.</para>
<para>nova-manage client. Enables cloud administrators to submit
commands.</para>
</listitem>
</itemizedlist>
<itemizedlist>
@ -188,25 +182,23 @@
<listitem>
<para>The queue. A central hub for passing messages between
daemons. Usually implemented with <link
xlink:href="http://www.rabbitmq.com/">RabbitMQ</link>,
but could be any AMPQ message queue, such as <link
xlink:href="http://qpid.apache.org/">Apache Qpid</link>
or <link xlink:href="http://www.zeromq.org/">Zero
xlink:href="http://www.rabbitmq.com/">RabbitMQ</link>, but
could be any AMPQ message queue, such as <link
xlink:href="http://qpid.apache.org/">Apache Qpid</link> or
<link xlink:href="http://www.zeromq.org/">Zero
MQ</link>.</para>
</listitem>
<listitem>
<para>SQL database. Stores most build-time and runtime
states for a cloud infrastructure. Includes instance types
that are available for use, instances in use, available
networks, and projects. Theoretically, OpenStack Compute
can support any database that SQL-Alchemy supports, but
the only databases widely used are sqlite3 databases
(only appropriate for test and development work), MySQL,
and PostgreSQL.</para>
<para>SQL database. Stores most build-time and runtime states
for a cloud infrastructure. Includes instance types that are
available for use, instances in use, available networks, and
projects. Theoretically, OpenStack Compute can support any
database that SQL-Alchemy supports, but the only databases
widely used are sqlite3 databases (only appropriate for test
and development work), MySQL, and PostgreSQL.</para>
</listitem>
</itemizedlist>
<para>The Compute Service interacts with other OpenStack
services: Identity Service for authentication, Image Service
for images, and the OpenStack dashboard for a web
interface.</para>
<para>The Compute Service interacts with other OpenStack services:
Identity Service for authentication, Image Service for images, and
the OpenStack dashboard for a web interface.</para>
</section>

2
doc/common/section_getstart_logical_arch.xml
View File

@ -26,7 +26,7 @@
architecture for an OpenStack cloud:</para>
<!-- Source files in this repository in doc/src/docbkx/common/figures/openstack-arch-havana-v1.zip -->
<figure xml:id="os-logical-arch">
<title>OpenStack logical architecture</title>
<title>Logical architecture</title>
<mediaobject>
<imageobject>
<imagedata

60
doc/common/section_getstart_networking.xml
View File

@ -1,45 +1,43 @@
<section xmlns="http://docbook.org/ns/docbook"
<section xmlns="http://docbook.org/ns/docbook"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
xml:id="networking-service-overview">
<title>Networking Service Overview</title>
<para>Provides network-connectivity-as-a-service between
interface devices that are managed by other OpenStack
services, usually Compute. Enables users to create and attach
interfaces to networks. Like many OpenStack services,
OpenStack Networking is highly configurable due to its plug-in
architecture. These plug-ins accommodate different networking
equipment and software. Consequently, the architecture and
deployment vary dramatically.</para>
<title>Networking service overview</title>
<para>Provides network-connectivity-as-a-service between interface
devices that are managed by other OpenStack services, usually
Compute. Enables users to create and attach interfaces to
networks. Like many OpenStack services, OpenStack Networking is
highly configurable due to its plug-in architecture. These
plug-ins accommodate different networking equipment and software.
Consequently, the architecture and deployment vary
dramatically.</para>
<para>Includes the following components:</para>
<itemizedlist>
<listitem>
<para><systemitem class="service"
>neutron-server</systemitem>. Accepts and routes API
requests to the appropriate OpenStack Networking plug-in
for action.</para>
<para><systemitem class="service">neutron-server</systemitem>.
Accepts and routes API requests to the appropriate OpenStack
Networking plug-in for action.</para>
</listitem>
<listitem>
<para>OpenStack Networking plug-ins and agents. Plugs and
unplugs ports, creates networks or subnets, and provides
IP addressing. These plug-ins and agents differ depending
on the vendor and technologies used in the particular
cloud. OpenStack Networking ships with plug-ins and agents
for Cisco virtual and physical switches, Nicira NVP
product, NEC OpenFlow products, Open vSwitch, Linux
bridging, and the Ryu Network Operating System.</para>
<para>The common agents are L3 (layer 3), DHCP (dynamic host
IP addressing), and a plug-in agent.</para>
unplugs ports, creates networks or subnets, and provides IP
addressing. These plug-ins and agents differ depending on the
vendor and technologies used in the particular cloud.
OpenStack Networking ships with plug-ins and agents for Cisco
virtual and physical switches, Nicira NVP product, NEC
OpenFlow products, Open vSwitch, Linux bridging, and the Ryu
Network Operating System.</para>
<para>The common agents are L3 (layer 3), DHCP (dynamic host IP
addressing), and a plug-in agent.</para>
</listitem>
<listitem>
<para>Messaging queue. Most OpenStack Networking
installations make use of a messaging queue to route
information between the neutron-server and various agents
as well as a database to store networking state for
particular plug-ins.</para>
<para>Messaging queue. Most OpenStack Networking installations
make use of a messaging queue to route information between the
neutron-server and various agents as well as a database to
store networking state for particular plug-ins.</para>
</listitem>
</itemizedlist>
<para>OpenStack Networking interacts mainly with OpenStack
Compute, where it provides networks and connectivity for its
<para>OpenStack Networking interacts mainly with OpenStack Compute,
where it provides networks and connectivity for its
instances.</para>
</section>
</section>

55
doc/common/section_getstart_object-storage.xml
View File

@ -1,47 +1,46 @@
<section xmlns="http://docbook.org/ns/docbook"
<section xmlns="http://docbook.org/ns/docbook"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
xml:id="object-storage-service">
<title>Object Storage Service</title>
<para>The Object Storage Service is a highly scalable and
durable multi-tenant object storage system for large amounts
of unstructured data at low cost through a RESTful http
API.</para>
<title>Object Storage service</title>
<para>The Object Storage service is a highly scalable and durable
multi-tenant object storage system for large amounts of
unstructured data at low cost through a RESTful HTTP API.</para>
<para>It includes the following components:</para>
<itemizedlist>
<listitem>
<para>Proxy Servers (<systemitem class="service"
<para>Proxy servers (<systemitem class="service"
>swift-proxy-server</systemitem>). Accepts Object Storage
API and raw HTTP requests to upload files, modify
metadata, and create containers. It also serves file or
container listings to web browsers. To improve
performance, the proxy server can use an optional cache
usually deployed with memcache.</para>
API and raw HTTP requests to upload files, modify metadata,
and create containers. It also serves file or container
listings to web browsers. To improve performance, the proxy
server can use an optional cache usually deployed with
memcache.</para>
</listitem>
<listitem>
<para>Account servers (<systemitem
class="service">swift-account-server</systemitem>). Manage
accounts defined with the Object Storage Service.</para>
<para>Account servers (<systemitem class="service"
>swift-account-server</systemitem>). Manage accounts defined
with the Object Storage service.</para>
</listitem>
<listitem>
<para>Container servers (<systemitem
class="service">swift-container-server</systemitem>). Manage
a mapping of containers, or folders, within the Object
Storage Service.</para>
<para>Container servers (<systemitem class="service"
>swift-container-server</systemitem>). Manage a mapping of
containers, or folders, within the Object Storage
service.</para>
</listitem>
<listitem>
<para>Object servers (<systemitem
class="service">swift-object-server</systemitem>). Manage
actual objects, such as files, on the storage nodes.</para>
<para>Object servers (<systemitem class="service"
>swift-object-server</systemitem>). Manage actual objects,
such as files, on the storage nodes.</para>
</listitem>
<listitem>
<para>A number of periodic processes. Performs housekeeping
tasks on the large data store. The replication services
ensure consistency and availability through the cluster.
Other periodic processes include auditors, updaters, and
tasks on the large data store. The replication services ensure
consistency and availability through the cluster. Other
periodic processes include auditors, updaters, and
reapers.</para>
</listitem>
</itemizedlist>
<para>Configurable WSGI middleware, which is usually the
Identity Service, handles authentication.</para>
</section>
<para>Configurable WSGI middleware that handles authentication.
Usually the Identity Service.</para>
</section>

48
doc/common/section_getstart_orchestration.xml
View File

@ -1,27 +1,28 @@
<section xmlns="http://docbook.org/ns/docbook"
<section xmlns="http://docbook.org/ns/docbook"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
xml:id="orchestration-service">
<title>Orchestration Service overview</title>
<para>The Orchestration service provides a template-based orchestration
for describing a cloud application by running OpenStack API calls to
generate running cloud applications. The software integrates other core
components of OpenStack into a one-file template system. The templates
enable you to create most OpenStack resource types, such as instances,
floating IPs, volumes, security groups, users, and so on. Also, provides
some more advanced functionality, such as instance high availability,
<title>Orchestration service overview</title>
<para>The Orchestration service provides a template-based
orchestration for describing a cloud application by running
OpenStack API calls to generate running cloud applications. The
software integrates other core components of OpenStack into a
one-file template system. The templates enable you to create most
OpenStack resource types, such as instances, floating IPs,
volumes, security groups, users, and so on. Also, provides some
more advanced functionality, such as instance high availability,
instance auto-scaling, and nested stacks. By providing very tight
integration with other OpenStack core projects, all OpenStack core projects
could receive a larger user base.</para>
<para>The service enables deployers to integrate with the Orchestration
service directly or through custom plug-ins.</para>
integration with other OpenStack core projects, all OpenStack core
projects could receive a larger user base.</para>
<para>The service enables deployers to integrate with the
Orchestration service directly or through custom plug-ins.</para>
<para>The Orchestration service consists of the following
components:</para>
<itemizedlist>
<listitem>
<para><code>heat</code> tool. A CLI that communicates with the
heat-api to run AWS CloudFormation APIs. End developers could also use
the Orchestration REST API directly.</para>
<para><code>heat</code> command-line client. A CLI that communicates with the
heat-api to run AWS CloudFormation APIs. End developers could
also use the Orchestration REST API directly.</para>
</listitem>
<listitem>
<para><code>heat-api</code> component. Provides an
@ -29,15 +30,14 @@
sending them to the heat-engine over RPC.</para>
</listitem>
<listitem>
<para><code>heat-api-cfn</code> component. Provides an AWS
Query API that is compatible with AWS CloudFormation and
processes API requests by sending them to the heat-engine
over RPC.</para>
<para><code>heat-api-cfn</code> component. Provides an AWS Query
API that is compatible with AWS CloudFormation and processes
API requests by sending them to the heat-engine over
RPC.</para>
</listitem>
<listitem>
<para><code>heat-engine</code>. Orchestrates the launching
of templates and provides events back to the API
consumer.</para>
<para><code>heat-engine</code>. Orchestrates the launching of
templates and provides events back to the API consumer.</para>
</listitem>
</itemizedlist>
</section>
</section>

230
doc/common/section_host_aggregates.xml
View File

@ -1,55 +1,62 @@
<?xml version="1.0" encoding="utf-8"?>
<section xmlns="http://docbook.org/ns/docbook"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
xml:id="host-aggregates">
<title>Host aggregates</title>
<simplesect>
<title>Overview</title>
<para>Host aggregates are a mechanism to further partition an availability zone; while availability
zones are visible to users, host aggregates are only visible to administrators.
Host Aggregates provide a mechanism to allow administrators to assign key-value pairs to
groups of machines. Each node can have multiple aggregates, each aggregate can have
multiple key-value pairs, and the same key-value pair can be assigned to multiple
aggregate. This information can be used in the scheduler to enable advanced scheduling,
to set up hypervisor resource pools or to define logical groups for migration.</para>
</simplesect>
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
xml:id="host-aggregates">
<title>Host aggregates</title>
<para>Host aggregates are a mechanism to further partition an
availability zone; while availability zones are visible to
users, host aggregates are only visible to administrators.
Host Aggregates provide a mechanism to allow administrators to
assign key-value pairs to groups of machines. Each node can
have multiple aggregates, each aggregate can have multiple
key-value pairs, and the same key-value pair can be assigned
to multiple aggregates. This information can be used in the
scheduler to enable advanced scheduling, to set up hypervisor
resource pools or to define logical groups for
migration.</para>
<simplesect>
<title>Command-line interface</title>
<para>The <command>nova</command> command-line tool supports the following aggregate-related
commands. <variablelist>
<para>The <command>nova</command> command-line tool supports
the following aggregate-related commands. <variablelist>
<varlistentry>
<term><command>nova aggregate-list</command></term>
<term><command>nova
aggregate-list</command></term>
<listitem>
<para>Print a list of all aggregates.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><command>nova aggregate-create <replaceable>&lt;name></replaceable>
<term><command>nova aggregate-create
<replaceable>&lt;name></replaceable>
<replaceable>&lt;availability-zone></replaceable></command></term>
<listitem>
<para>Create a new aggregate named
<replaceable>&lt;name></replaceable> in
availability zone
<replaceable>&lt;name></replaceable>
in availability zone
<replaceable>&lt;availability-zone></replaceable>.
Returns the ID of the newly created aggregate. Hosts
can be made available to multiple availability
zones, but administrators should be careful when
adding the host to a different host aggregate within
the same availability zone and pay attention when
using the aggregate-set-metadata and
aggregate-update commands to avoid user confusion
when they boot instances in different availability
zones. You will see an error message if you cannot
add a particular host in an aggregate zone it is not
intended for.</para>
Returns the ID of the newly created
aggregate. Hosts can be made available to
multiple availability zones, but
administrators should be careful when
adding the host to a different host
aggregate within the same availability
zone and pay attention when using the
<command>aggregate-set-metadata</command>
and <command>aggregate-update</command>
commands to avoid user confusion when they
boot instances in different availability
zones. An error occurs if you cannot add a
particular host to an aggregate zone for
which it is not intended.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><command>nova aggregate-delete
<replaceable>&lt;id></replaceable></command></term>
<listitem>
<para>Delete an aggregate with id <replaceable>&lt;id></replaceable>.</para>
<para>Delete an aggregate with id
<replaceable>&lt;id></replaceable>.</para>
</listitem>
</varlistentry>
<varlistentry>
@ -61,36 +68,47 @@ xml:id="host-aggregates">
</listitem>
</varlistentry>
<varlistentry>
<term><command>nova aggregate-add-host <replaceable>&lt;id></replaceable>
<term><command>nova aggregate-add-host
<replaceable>&lt;id></replaceable>
<replaceable>&lt;host></replaceable></command></term>
<listitem>
<para>Add host with name <replaceable>&lt;host></replaceable> to aggregate
with id <replaceable>&lt;id></replaceable>.</para>
<para>Add host with name
<replaceable>&lt;host></replaceable>
to aggregate with id
<replaceable>&lt;id></replaceable>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><command>nova aggregate-remove-host <replaceable>&lt;id></replaceable>
<term><command>nova aggregate-remove-host
<replaceable>&lt;id></replaceable>
<replaceable>&lt;host></replaceable></command></term>
<listitem>
<para>Remove the host with name <replaceable>&lt;host></replaceable> from
the aggregate with id <replaceable>&lt;id></replaceable>.</para>
<para>Remove the host with name
<replaceable>&lt;host></replaceable>
from the aggregate with id
<replaceable>&lt;id></replaceable>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><command>nova aggregate-set-metadata <replaceable>&lt;id></replaceable>
<term><command>nova aggregate-set-metadata
<replaceable>&lt;id></replaceable>
<replaceable>&lt;key=value></replaceable>
[<replaceable>&lt;key=value></replaceable> ...]</command></term>
[<replaceable>&lt;key=value></replaceable>
...]</command></term>
<listitem>
<para>Add or update metadata (key-value pairs) associated with the aggregate
with id <replaceable>&lt;id></replaceable>.</para>
<para>Add or update metadata (key-value pairs)
associated with the aggregate with id
<replaceable>&lt;id></replaceable>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><command>nova aggregate-update <replaceable>&lt;id></replaceable>
<term><command>nova aggregate-update
<replaceable>&lt;id></replaceable>
<replaceable>&lt;name></replaceable>
[<replaceable>&lt;availability_zone></replaceable>]</command></term>
<listitem>
<para>Update the aggregate's name and optionally availability zone.</para>
<para>Update the name and availability zone
(optional) for the aggregate.</para>
</listitem>
</varlistentry>
<varlistentry>
@ -100,45 +118,59 @@ xml:id="host-aggregates">
</listitem>
</varlistentry>
<varlistentry>
<term><command>nova host-update --maintenance [enable |
disable]</command></term>
<term><command>nova host-update --maintenance
[enable | disable]</command></term>
<listitem>
<para>Put/resume host into/from maintenance.</para>
<para>Put/resume host into/from
maintenance.</para>
</listitem>
</varlistentry>
</variablelist></para>
<note><para>These commands are only accessible to administrators. If the username and tenant
you are using to access the Compute service do not have the <literal>admin</literal>
role, or have not been explicitly granted the appropriate privileges, you will see
one of the following errors when trying to use these
commands:<screen><computeroutput>ERROR: Policy doesn't allow compute_extension:aggregates to be performed. (HTTP 403) (Request-ID: req-299fbff6-6729-4cef-93b2-e7e1f96b4864)
</computeroutput></screen><screen><computeroutput>ERROR: Policy doesn't allow compute_extension:hosts to be performed. (HTTP 403) (Request-ID: req-ef2400f6-6776-4ea3-b6f1-7704085c27d1)
</computeroutput></screen></para></note>
<note>
<para>Only administrators can access these commands. If
you try to use these commands and the user name and
tenant that you use to access the Compute service do
not have the <literal>admin</literal> role or the
appropriate privileges, these errors occur:</para>
<screen><computeroutput>ERROR: Policy doesn't allow compute_extension:aggregates to be performed. (HTTP 403) (Request-ID: req-299fbff6-6729-4cef-93b2-e7e1f96b4864)
</computeroutput></screen>
<screen><computeroutput>ERROR: Policy doesn't allow compute_extension:hosts to be performed. (HTTP 403) (Request-ID: req-ef2400f6-6776-4ea3-b6f1-7704085c27d1)
</computeroutput></screen>
</note>
</simplesect>
<simplesect>
<title>Configure scheduler to support host aggregates</title>
<para>One common use case for host aggregates is when you want to support scheduling
instances to a subset of compute hosts because they have a specific capability. For
example, you may want to allow users to request compute hosts that have SSD drives if
they need access to faster disk I/O, or access to compute hosts that have GPU cards to
take advantage of GPU-accelerated code.</para>
<para>To configure the scheduler to support host aggregates, the
<literal>scheduler_default_filters</literal> configuration option must contain the
<literal>AggregateInstanceExtraSpecsFilter</literal> in addition to the other
filters used by the scheduler. Add the following line to
<filename>/etc/nova/nova.conf</filename> on the host that runs the <systemitem class="service">nova-scheduler</systemitem>
service to enable host aggregates filtering, as well as the other filters that are
typically
<para>One common use case for host aggregates is when you want
to support scheduling instances to a subset of compute
hosts because they have a specific capability. For
example, you may want to allow users to request compute
hosts that have SSD drives if they need access to faster
disk I/O, or access to compute hosts that have GPU cards
to take advantage of GPU-accelerated code.</para>
<para>To configure the scheduler to support host aggregates,
the <literal>scheduler_default_filters</literal>
configuration option must contain the
<literal>AggregateInstanceExtraSpecsFilter</literal>
in addition to the other filters used by the scheduler.
Add the following line to
<filename>/etc/nova/nova.conf</filename> on the host
that runs the <systemitem class="service"
>nova-scheduler</systemitem> service to enable host
aggregates filtering, as well as the other filters that
are typically
enabled:<programlisting language="ini">scheduler_default_filters=AggregateInstanceExtraSpecsFilter,AvailabilityZoneFilter,RamFilter,ComputeFilter</programlisting></para>
</simplesect>
<simplesect>
<title>Example: specify compute hosts with SSDs</title>
<para>In this example, we configure the Compute service to allow users to request nodes that
have solid-state drives (SSDs). We create a new host aggregate called
<literal>fast-io</literal> in the availability zone called <literal>nova</literal>,
we add the key-value pair <literal>ssd=true</literal> to the aggregate, and then we add
compute nodes <literal>node1</literal>, and <literal>node2</literal> to
it.<screen><prompt>$</prompt> <userinput>nova aggregate-create fast-io nova</userinput>
<title>Example: Specify compute hosts with SSDs</title>
<para>This example configures the Compute service to enable
users to request nodes that have solid-state drives
(SSDs). You create a <literal>fast-io</literal> host
aggregate in the <literal>nova</literal> availability zone
and you add the <literal>ssd=true</literal> key-value pair
to the aggregate. Then, you add the
<literal>node1</literal>, and <literal>node2</literal>
compute nodes to it.</para>
<screen><prompt>$</prompt> <userinput>nova aggregate-create fast-io nova</userinput>
<computeroutput>+----+---------+-------------------+-------+----------+
| Id | Name | Availability Zone | Hosts | Metadata |
+----+---------+-------------------+-------+----------+
@ -165,25 +197,30 @@ xml:id="host-aggregates">
+----+---------+-------------------+----------------------+-------------------+
| 1 | fast-io | nova | [u'node1', u'node2'] | {u'ssd': u'true'} |
+----+---------+-------------------+----------------------+-------------------+</computeroutput>
</screen></para>
<para>Next, we use the <command>nova flavor-create</command> command to create a new flavor
called <literal>ssd.large</literal> with an ID of 6, 8GB of RAM, 80GB root disk, and 4
vCPUs.
</screen>
<para>Use the <command>nova flavor-create</command> command to
create the <literal>ssd.large</literal> flavor called with
an ID of 6, 8GB of RAM, 80GB root disk, and 4
vCPUs.</para>
<screen><prompt>$</prompt> <userinput>nova flavor-create ssd.large 6 8192 80 4</userinput>
<computeroutput>+----+-----------+-----------+------+-----------+------+-------+-------------+-----------+-------------+
| ID | Name | Memory_MB | Disk | Ephemeral | Swap | VCPUs | RXTX_Factor | Is_Public | extra_specs |
+----+-----------+-----------+------+-----------+------+-------+-------------+-----------+-------------+
| 6 | ssd.large | 8192 | 80 | 0 | | 4 | 1 | True | {} |
+----+-----------+-----------+------+-----------+------+-------+-------------+-----------+-------------+</computeroutput></screen></para>
<para>Once the flavor has been created, we specify one or more key-value pair that must
match the key-value pairs on the host aggregates. In this case, there's only one
key-value pair, <literal>ssd=true</literal>. Setting a key-value pair on a flavor is
done using the <command>nova flavor-key set_key</command>
command.<screen><prompt>#</prompt> <userinput>nova flavor-key set_key --name=ssd.large --key=ssd --value=true</userinput></screen></para>
<para>Once it is set, you should see the <literal>extra_specs</literal> property of the
<literal>ssd.large</literal> flavor populated with a key of <literal>ssd</literal>
and a corresponding value of
<literal>true</literal>.<screen><prompt>$</prompt> <userinput>nova flavor-show ssd.large</userinput>
+----+-----------+-----------+------+-----------+------+-------+-------------+-----------+-------------+</computeroutput></screen>
<para>Once the flavor is created, specify one or more
key-value pairs that match the key-value pairs on the host
aggregates. In this case, that is the
<literal>ssd=true</literal> key-value pair. Setting a
key-value pair on a flavor is done using the <command>nova
flavor-key set_key</command> command.</para>
<screen><prompt>#</prompt> <userinput>nova flavor-key set_key --name=ssd.large --key=ssd --value=true</userinput></screen>
<para>Once it is set, you should see the
<literal>extra_specs</literal> property of the
<literal>ssd.large</literal> flavor populated with a
key of <literal>ssd</literal> and a corresponding value of
<literal>true</literal>.</para>
<screen><prompt>$</prompt> <userinput>nova flavor-show ssd.large</userinput>
<computeroutput>+----------------------------+-------------------+
| Property | Value |
+----------------------------+-------------------+
@ -198,16 +235,21 @@ xml:id="host-aggregates">
| rxtx_factor | 1.0 |
| swap | |
| vcpus | 4 |
+----------------------------+-------------------+</computeroutput></screen></para>
<para>Now, when a user requests an instance with the <literal>ssd.large</literal> flavor,
the scheduler will only consider hosts with the <literal>ssd=true</literal> key-value
pair. In this example, that would only be <literal>node1</literal> and
+----------------------------+-------------------+</computeroutput></screen>
<para>Now, when a user requests an instance with the
<literal>ssd.large</literal> flavor, the scheduler
only considers hosts with the <literal>ssd=true</literal>
key-value pair. In this example, these are
<literal>node1</literal> and
<literal>node2</literal>.</para>
</simplesect>
<simplesect>
<title>XenServer hypervisor pools to support live migration</title>
<para>When using the XenAPI-based hypervisor, the Compute service uses host aggregates to
manage XenServer Resource pools, which are used in supporting live migration. <!--See <link
<title>XenServer hypervisor pools to support live
migration</title>
<para>When using the XenAPI-based hypervisor, the Compute
service uses host aggregates to manage XenServer Resource
pools, which are used in supporting live migration.
<!--See <link
linkend="configuring-migrations-xenserver-shared-storage">Configuring Migrations</link> for details on how to
create these kinds of host aggregates to support live migration. --></para>
</simplesect>

40
doc/common/section_identity-configure.xml
View File

@ -3,16 +3,19 @@
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
xml:id="keystone-configuration-file">
<title>Identity Configuration Files</title>
<title>Identity Service configuration files</title>
<variablelist>
<varlistentry><term>keystone.conf</term>
<listitem><para>The Identity Service
<filename>/etc/keystone/keystone.conf</filename> configuration
file is an INI-format file with sections.</para>
<para>The <literal>[DEFAULT]</literal> section configures general
configuration values.</para>
<para>Specific sections, such as the <literal>[sql]</literal> and
<literal>[ec2]</literal> sections, configure individual
<varlistentry>
<term>keystone.conf</term>
<listitem>
<para>The Identity Service
<filename>/etc/keystone/keystone.conf</filename>
configuration file is an INI-format file with
sections.</para>
<para>The <literal>[DEFAULT]</literal> section configures
general configuration values.</para>
<para>Specific sections, such as the <literal>[sql]</literal>
and <literal>[ec2]</literal> sections, configure individual
services.</para>
<table rules="all">
<caption>keystone.conf file sections</caption>
@ -31,7 +34,7 @@
</tr>
<tr>
<td><literal>[sql]</literal></td>
<td>Optional storage backend configuration.</td>
<td>Optional storage back-end configuration.</td>
</tr>
<tr>
<td><literal>[ec2]</literal></td>
@ -68,11 +71,11 @@
</tbody>
</table>
<para>When you start the Identity Service, you can use the
<literal>--config-file</literal> parameter to specify a
configuration file.</para>
<parameter>--config-file</parameter> parameter to specify
a configuration file.</para>
<para>If you do not specify a configuration file, the Identity
Service looks for the <filename>keystone.conf</filename>
configuration file in the following directories in the following
configuration file in these directories in this
order:</para>
<orderedlist>
<listitem>
@ -98,9 +101,14 @@
</orderedlist>
</listitem>
</varlistentry>
<varlistentry><term>keystone-paste.ini</term>
<listitem><para>The <filename>/etc/keystone/keystone-paste.ini</filename> file
configures the Identity Service WSGI middleware pipeline.</para></listitem>
<varlistentry>
<term>keystone-paste.ini</term>
<listitem>
<para>The
<filename>/etc/keystone/keystone-paste.ini</filename> file
configures the Identity Service WSGI middleware
pipeline.</para>
</listitem>
</varlistentry>
</variablelist>
</section>

51
doc/common/section_keystone-external-auth.xml
View File

@ -1,31 +1,33 @@
<?xml version="1.0" encoding="UTF-8"?>
<section xml:id="keystone-external-auth" xmlns="http://docbook.org/ns/docbook"
xmlns:xi="http://www.w3.org/2001/XInclude" xmlns:xlink="http://www.w3.org/1999/xlink"
version="1.0">
<title>Using External Authentication with OpenStack Identity</title>
<para>When Keystone is executed in <literal>apache-httpd</literal>
it is possible to use external authentication methods different
from the authentication provided by the identity store backend.
For example, this makes possible to use a SQL identity backend
together with X.509 authentication, Kerberos, etc. instead of using
the username/password combination.</para>
<section xml:id="keystone-external-auth"
xmlns="http://docbook.org/ns/docbook"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink" version="1.0">
<title>External authentication with the Identity
Service</title>
<para>When Keystone runs in <literal>apache-httpd</literal>, you
can use external authentication methods that differ from the
authentication provided by the identity store back-end. For
example, you can use an SQL identity back-end together with
X.509 authentication, Kerberos, and so on instead of using the
user name and password combination.</para>
<section xml:id="keystone-httpd-auth">
<title>Using HTTPD authentication</title>
<para>Webservers like Apache HTTP support many methods of
authentication. Keystone can profit from this feature and let the
authentication be done in the webserver, that will pass down the
authenticated user to Keystone using the <literal>REMOTE_USER</literal>
environment variable. This user must exist in advance in the identity
backend so as to get a token from the controller. To use this method,
OpenStack Identity should be running on <literal>apache-httpd</literal>.
</para>
<title>Use HTTPD authentication</title>
<para>Web servers, like Apache HTTP, support many methods of
authentication. Keystone can allow the web server to
perform the authentication. The web server then passes the
authenticated user to Keystone by using the
<literal>REMOTE_USER</literal> environment variable.
This user must already exist in the Identity Service
back-end so as to get a token from the controller. To use
this method, the Identity Service should run on
<literal>apache-httpd</literal>.</para>
</section>
<section xml:id="keystone-x509-auth">
<title>Using X.509</title>
<para>The following snippet for the Apache conf will authenticate
the user based on a valid X.509 certificate from a known CA:
<title>Use X.509</title>
<para>The following Apache configuration snippet authenticates
the user based on a valid X.509 certificate from a known
CA:</para>
<programlisting> &lt;VirtualHost _default_:5000&gt;
SSLEngine on
SSLCertificateFile /etc/ssl/certs/ssl.cert
@ -39,6 +41,5 @@
(...)
&lt;/VirtualHost&gt;</programlisting>
</para>
</section>
</section>

18
doc/common/section_keystone-sample-conf-files.xml
View File

@ -1,23 +1,23 @@
<?xml version="1.0" encoding="UTF-8"?>
<section
xmlns="http://docbook.org/ns/docbook"
<section xmlns="http://docbook.org/ns/docbook"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink"
version="5.0"
xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
xml:id="sample-configuration-files">
<title>Identity Sample Configuration Files</title>
<title>Identity Service sample configuration files</title>
<itemizedlist>
<listitem>
<para>
<filename>etc/keystone.conf.sample</filename>
</para><para>
<programlisting language="ini"><xi:include parse="text" href="http://git.openstack.org/cgit/openstack/keystone/plain/etc/keystone.conf.sample"></xi:include></programlisting></para>
</para>
<para>
<programlisting language="ini"><xi:include parse="text" href="http://git.openstack.org/cgit/openstack/keystone/plain/etc/keystone.conf.sample"/></programlisting></para>
</listitem>
<listitem>
<para>
<filename>etc/keystone-paste.ini</filename>
</para><para>
<programlisting language="ini"><xi:include parse="text" href="http://git.openstack.org/cgit/openstack/keystone/plain/etc/keystone-paste.ini"></xi:include></programlisting></para>
</para>
<para>
<programlisting language="ini"><xi:include parse="text" href="http://git.openstack.org/cgit/openstack/keystone/plain/etc/keystone-paste.ini"/></programlisting></para>
</listitem>
<listitem>
<para>

64
doc/common/section_keystone-ssl-config.xml
View File

@ -1,12 +1,10 @@
<?xml version="1.0" encoding="UTF-8"?>
<section
xmlns="http://docbook.org/ns/docbook"
<section xmlns="http://docbook.org/ns/docbook"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink"
version="5.0"
xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
xml:id="keystone-ssl-config">
<title>Configure the Identity Service with SSL</title>
<para>You can configure the Identity Service to support 2-way
<para>You can configure the Identity Service to support two-way
SSL.</para>
<para>You must obtain the x509 certificates externally and
configure them.</para>
@ -15,50 +13,49 @@
>examples/pki/certs</filename> and <filename
class="directory">examples/pki/private</filename>
directories:</para>
<variablelist><title>Certificate types</title>
<variablelist>
<title>Certificate types</title>
<varlistentry>
<term>cacert.pem
</term>
<term>cacert.pem </term>
<listitem>
<para>Certificate Authority chain to validate against.</para>
<para>Certificate Authority chain to validate
against.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>ssl_cert.pem
</term>
<term>ssl_cert.pem </term>
<listitem>
<para>Public certificate for Identity Service
server.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>middleware.pem
</term>
<term>middleware.pem </term>
<listitem>
<para>Public and private certificate for
Identity Service middleware/client.</para>
<para>Public and private certificate for Identity
Service middleware/client.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>cakey.pem
</term>
<term>cakey.pem </term>
<listitem>
<para>Private key for the CA.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>ssl_key.pem
</term>
<term>ssl_key.pem </term>
<listitem>
<para>Private key for the Identity Service
server.</para>
</listitem>
</varlistentry>
</variablelist>
<note><para>You can choose names for
these certificates. You can also combine the public/private keys in the
same file, if you wish. These certificates are provided as
an example.</para></note>
<note>
<para>You can choose names for these certificates. You can
also combine the public/private keys in the same file, if
you wish. These certificates are provided as an
example.</para>
</note>
<section xml:id="ssl-configuration">
<title>SSL configuration</title>
<para>To enable SSL with client authentication, modify the
@ -72,24 +69,25 @@ certfile = &lt;path to keystone.pem&gt;
keyfile = &lt;path to keystonekey.pem&gt;
ca_certs = &lt;path to ca.pem&gt;
cert_required = True</programlisting>
<itemizedlist><title>Options</title>
<itemizedlist>
<title>Options</title>
<listitem>
<para><literal>enable</literal>. True enables SSL.
Default is False.</para>
</listitem>
<listitem>
<para><literal>certfile</literal>. Path to the Identity
Service public certificate file.</para>
<para><literal>certfile</literal>. Path to the
Identity Service public certificate file.</para>
</listitem>
<listitem>
<para><literal>keyfile</literal>. Path to the
Identity Service private certificate file. If you
include the private key in the certfile, you can
omit the keyfile.</para>
<para><literal>keyfile</literal>. Path to the Identity
Service private certificate file. If you include
the private key in the certfile, you can omit the
keyfile.</para>
</listitem>
<listitem>
<para><literal>ca_certs</literal>. Path to the CA trust chain.
</para>
<para><literal>ca_certs</literal>. Path to the CA
trust chain.</para>
</listitem>
<listitem>
<para><literal>cert_required</literal>. Requires
@ -97,4 +95,4 @@ cert_required = True</programlisting>
</listitem>
</itemizedlist>
</section>
</section>
</section>

46
doc/common/section_keystone_certificates-for-pki.xml
View File

@ -73,9 +73,11 @@
<literal>None</literal>.</para>
</listitem>
</itemizedlist>
<para>If <literal>token_format=UUID</literal>, a typical token will look like
<para>If <literal>token_format=UUID</literal>, a typical token
looks like
<literal>53f7f6ef0cc344b5be706bcc8b1479e1</literal>. If
<literal>token_format=PKI</literal>, a typical token will be a much longer string, e.g.:
<literal>token_format=PKI</literal>, a typical token is a
much longer string, such as:</para>
<screen>MIIKtgYJKoZIhvcNAQcCoIIKpzCCCqMCAQExCTAHBgUrDgMCGjCCCY8GCSqGSIb3DQEHAaCCCYAEggl8eyJhY2Nlc3MiOiB7InRva2VuIjogeyJpc3N1ZWRfYXQiOiAiMjAxMy0wNS0z
MFQxNTo1MjowNi43MzMxOTgiLCAiZXhwaXJlcyI6ICIyMDEzLTA1LTMxVDE1OjUyOjA2WiIsICJpZCI6ICJwbGFjZWhvbGRlciIsICJ0ZW5hbnQiOiB7ImRlc2NyaXB0aW9uIjogbnVs
bCwgImVuYWJsZWQiOiB0cnVlLCAiaWQiOiAiYzJjNTliNGQzZDI4NGQ4ZmEwOWYxNjljYjE4MDBlMDYiLCAibmFtZSI6ICJkZW1vIn19LCAic2VydmljZUNhdGFsb2ciOiBbeyJlbmRw
@ -102,27 +104,26 @@ OiBbeyJuYW1lIjogImFub3RoZXJyb2xlIn0sIHsibmFtZSI6ICJNZW1iZXIifV0sICJuYW1lIjogImRl
YWRiODM3NDVkYzQzNGJhMzk5ODllNjBjOTIzYWZhMjgiLCAiMzM2ZTFiNjE1N2Y3NGFmZGJhNWUwYTYwMWUwNjM5MmYiXX19fTGB-zCB-AIBATBcMFcxCzAJBgNVBAYTAlVTMQ4wDAYD
VQQIEwVVbnNldDEOMAwGA1UEBxMFVW5zZXQxDjAMBgNVBAoTBVVuc2V0MRgwFgYDVQQDEw93d3cuZXhhbXBsZS5jb20CAQEwBwYFKw4DAhowDQYJKoZIhvcNAQEBBQAEgYCAHLpsEs2R
nouriuiCgFayIqCssK3SVdhOMINiuJtqv0sE-wBDFiEj-Prcudqlz-n+6q7VgV4mwMPszz39-rwp+P5l4AjrJasUm7FrO-4l02tPLaaZXU1gBQ1jUG5e5aL5jPDP08HbCWuX6wr-QQQB
SrWY8lF3HrTcJT23sZIleg==</screen></para>
SrWY8lF3HrTcJT23sZIleg==</screen>
<section xml:id="signing-certificate-issued-by-external-ca">
<title>Sign certificate issued by External CA</title>
<para>You may use a signing certificate issued by an external
<title>Sign certificate issued by external CA</title>
<para>You can use a signing certificate issued by an external
CA instead of generated by
<command>keystone-manage</command>. However,
certificate issued by external CA must satisfy the
following conditions:</para>
<itemizedlist>
<listitem>
<para>all certificate and key files must be in
Privacy Enhanced Mail (PEM) format</para>
<para>all certificate and key files must be in Privacy
Enhanced Mail (PEM) format</para>
</listitem>
<listitem>
<para>private key files must not be protected by a
password</para>
</listitem>
</itemizedlist>
<para>When using signing certificate issued by an external
CA, you do not need to specify
<literal>key_size</literal>,
<para>When using signing certificate issued by an external CA,
you do not need to specify <literal>key_size</literal>,
<literal>valid_days</literal>, and
<literal>ca_password</literal> as they will be
ignored.</para>
@ -143,7 +144,8 @@ SrWY8lF3HrTcJT23sZIleg==</screen></para>
</orderedlist>
</section>
<section xml:id="request-signing-certificate-from-external-ca">
<title>Request a signing certificate from external CA</title>
<title>Request a signing certificate from an external
CA</title>
<para>One way to request a signing certificate from an
external CA is to first generate a PKCS #10 Certificate
Request Syntax (CRS) using OpenSSL CLI.</para>
@ -176,10 +178,10 @@ emailAddress = keystone@openstack.org
<para>If everything is successfully, you should end up with
<filename>signing_cert_req.pem</filename> and
<filename>signing_key.pem</filename>. Send
<filename>signing_cert_req.pem</filename> to your CA to
request a token signing certificate and make sure to ask
the certificate to be in PEM format. Also, make sure your
trusted CA certificate chain is also in PEM format.
<filename>signing_cert_req.pem</filename> to your CA
to request a token signing certificate and make sure to
ask the certificate to be in PEM format. Also, make sure
your trusted CA certificate chain is also in PEM format.
</para>
</section>
<section xml:id="install-external-signing-certificate">
@ -193,8 +195,9 @@ emailAddress = keystone@openstack.org
</listitem>
<listitem>
<para>
<filename>signing_key.pem</filename> - corresponding
(non-encrypted) private key in PEM format</para>
<filename>signing_key.pem</filename> -
corresponding (non-encrypted) private key in PEM
format</para>
</listitem>
<listitem>
<para>
@ -214,10 +217,9 @@ emailAddress = keystone@openstack.org
<para>Make sure the certificate directory is only
accessible by root.</para>
</note>
<para>If your certificate directory path is different from
the default <filename>/etc/keystone/ssl/certs</filename>,
make sure it is reflected in the
<literal>[signing]</literal> section of the
configuration file.</para>
<para>If your certificate directory path is different from the
default <filename>/etc/keystone/ssl/certs</filename>, make
sure it is reflected in the <literal>[signing]</literal>
section of the configuration file.</para>
</section>
</section>

62
doc/common/section_keystone_db_sync.xml
View File

@ -3,37 +3,42 @@
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
xml:id="keystone-db_sync">
<title>Migrate the Identity Service Database</title>
<para>Between revisions of the Identity service project code-named
keystone, SQL migrations may need to happen. The keystone
project uses <link
<title>Migrate the Identity Service database</title>
<para>Between revisions of the Identity Service project, you might
need to complete SQL migrations. The Identity Service project
uses SQLAlchemy-migrate (see <link
xlink:href="http://code.google.com/p/sqlalchemy-migrate/"
>SQLAlchemy-migrate</link> to migrate the SQL database
between revisions. For core components, the source code stores
migrations in a central repository under a
>http://code.google.com/p/sqlalchemy-migrate/</link>) to
migrate the SQL database between revisions. For core
components, the source code stores migrations in a central
repository under a
<filename>keystone/common/sql/migrate_repo</filename>
directory.</para>
<para>Extensions to the Identity service may require SQL
migrations as well. The directory
<para>Extensions to the Identity Service might also require SQL
migrations. The directory
<filename>keystone/contrib/example</filename> in the
keystone repository contains a sample extension
migration.</para>
<procedure>
<title>To set up a migration for an extension</title>
<step>
<para>Create a directory structure where "my_extension" is
the name of the extension:
<filename>keystone/contrib/my_extension/migrate_repo/versions/</filename></para>
<para>Create a directory structure where
<literal>my_extension</literal> is the name of the
extension, as follows:
<filename>keystone/contrib/my_extension/migrate_repo/versions/</filename>.</para>
</step>
<step>
<para>Create empty <filename>__init__.py</filename> files in the <filename>migrate_repo</filename>
and <filename>versions</filename> subdirectories.</para>
<para>Create empty <filename>__init__.py</filename> files
in the <filename>migrate_repo</filename> and
<filename>versions</filename>
subdirectories.</para>
</step>
<step>
<para>Create a configuration file in the migrate_repo
subdirectory named <filename>migrate.cfg</filename> conforming to a
key/value ini file format.</para>
<para>Here is an example config file.</para>
<para>Create a <filename>migrate.cfg</filename>
configuration file in the
<filename>migrate_repo</filename> subdirectory,
which conforms to a key/value <filename>.ini</filename> file format.</para>
<para>An example configuration file:</para>
<programlisting language="ini">[db_settings]
repository_id=my_extension
version_table=migrate_version
@ -41,27 +46,28 @@
</step>
</procedure>
<procedure>
<title>To test and run a migration for a specific
extension</title>
<para>You can use the keystone-manage command with the
parameter --extension both the db_sync and db_version
commands. Ensure the required configuration files exist
before doing these steps.</para>
<title>To test a migration for a specific extension</title>
<para>You can use the <command>keystone-manage</command>
command with the <command>--extension</command> parameter
for both the <command>db_sync</command> and
<command>db_version</command> commands. Ensure that the
required configuration files exist before completing these
steps.</para>
<step>
<para>Test your migrations with "example" as a named
<para>Test your migrations with an <literal>example</literal>
extension:</para>
<screen><prompt>#</prompt> <userinput>bin/keystone-manage db_sync --extension example</userinput></screen>
</step>
<step>
<para>Migrate to version 1 with this command:</para>
<para>Migrate to version 1:</para>
<screen><prompt>#</prompt> <userinput>bin/keystone-manage db_sync --extension example 1</userinput></screen>
</step>
<step>
<para>Migrate back to version 0 with this command:</para>
<para>Migrate back to version 0:</para>
<screen><prompt>#</prompt> <userinput>bin/keystone-manage db_sync --extension example 0</userinput></screen>
</step>
<step>
<para>Use this command to check the version:</para>
<para>Check the version:</para>
<screen><prompt>#</prompt> <userinput>bin/keystone-manage db_version --extension example</userinput></screen>
</step>
</procedure>

118
doc/common/section_kvm_enable.xml
View File

@ -3,98 +3,98 @@
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
xml:id="section_kvm_enable">
<title>Enabling KVM</title>
<para>To perform the following steps, you must be logged in as
the <systemitem>root</systemitem> user.</para>
<title>Enable KVM</title>
<para>To perform these steps, you must be logged in as the
<systemitem>root</systemitem> user.</para>
<procedure>
<step>
<para>To determine whether the <literal>svm</literal>
or <literal>vmx</literal> CPU extensions are
present, run the following command:</para>
<para>To determine whether the <literal>svm</literal> or
<literal>vmx</literal> CPU extensions are present,
run this command:</para>
<screen><prompt>#</prompt> <userinput>grep -E 'svm|vmx' /proc/cpuinfo</userinput></screen>
<para>This command generates output if the CPU is
hardware-virtualization capable. Even if output is
shown, you may still need to enable virtualization
shown, you might still need to enable virtualization
in the system BIOS for full support.</para>
<para>If no output appears, consult your system
documentation to ensure that your CPU and
motherboard support hardware virtualization.
Verify that any relevant hardware virtualization
options are enabled in the system BIOS.</para>
<para>Each manufacturer's BIOS is different. If you need to enable virtualization in
the BIOS, look for an option containing the words "virtualization", "VT", "VMX", or
"SVM." </para>
documentation to ensure that your CPU and motherboard
support hardware virtualization. Verify that any
relevant hardware virtualization options are enabled
in the system BIOS.</para>
<para>The BIOS for each manufacturer is different. If you
must enable virtualization in the BIOS, look for an
option containing the words
<literal>virtualization</literal>,
<literal>VT</literal>, <literal>VMX</literal>, or
<literal>SVM</literal>.</para>
</step>
<step>
<para>To list the loaded kernel modules and verify
that the <literal>kvm</literal> modules are
loaded, run the following command:</para>
<screen><prompt>#</prompt> <userinput>lsmod | grep kvm</userinput></screen>
<para>If the output includes <systemitem>kvm_intel</systemitem> or
<systemitem>kvm_amd</systemitem>, the <systemitem>kvm</systemitem> hardware
virtualization modules are loaded and your kernel meets the module requirements for
OpenStack Compute.</para>
<para>If the output does not show that the kvm module
is loaded, run the following command to load
it:</para>
<screen><prompt>#</prompt> <userinput>modprobe -a kvm</userinput></screen>
<para>Run the command for your CPU. For Intel, run
<para>To list the loaded kernel modules and verify that
the <literal>kvm</literal> modules are loaded, run
this command:</para>
<screen><prompt>#</prompt> <userinput>lsmod | grep kvm</userinput></screen>
<para>If the output includes
<systemitem>kvm_intel</systemitem> or
<systemitem>kvm_amd</systemitem>, the
<systemitem>kvm</systemitem> hardware
virtualization modules are loaded and your kernel
meets the module requirements for OpenStack
Compute.</para>
<para>If the output does not show that the
<literal>kvm</literal> module is loaded, run this
command to load it:</para>
<screen><prompt>#</prompt> <userinput>modprobe -a kvm</userinput></screen>
<para>Run the command for your CPU. For Intel, run this
command:</para>
<screen><prompt>#</prompt> <userinput>modprobe -a kvm-intel</userinput></screen>
<para>For AMD, run this command:</para>
<screen><prompt>#</prompt> <userinput>modprobe -a kvm-amd</userinput></screen>
<para>Because a KVM installation can change user group
membership, you might need to log in again for
changes to take effect.</para>
<para>If the kernel modules do not load automatically, please use the procedures listed
in the subsections below.</para>
membership, you might need to log in again for changes
to take effect.</para>
<para>If the kernel modules do not load automatically, use
the procedures listed in these subsections.</para>
</step>
</procedure>
<para>This completes the required checks to ensure that
hardware virtualization support is available and enabled,
and that the correct kernel modules are loaded.</para>
<para>If the checks indicate that required hardware
virtualization support or kernel modules are disabled or
not available, you must either enable this support on the
system or find a system with this support.</para>
<para>If the checks indicate that required hardware virtualization
support or kernel modules are disabled or unavailable, you
must either enable this support on the system or find a system
with this support.</para>
<note>
<para>Some systems require that you enable VT support in
the system BIOS. If you believe your processor
supports hardware acceleration but the previous
command did not produce output, you might need to
reboot your machine, enter the system BIOS, and enable
the VT option.</para>
<para>Some systems require that you enable VT support in the
system BIOS. If you believe your processor supports
hardware acceleration but the previous command did not
produce output, reboot your machine, enter the system
BIOS, and enable the VT option.</para>
</note>
<para>If KVM acceleration is not supported, configure Compute
to use a different hypervisor, such as <link
<para>If KVM acceleration is not supported, configure Compute to
use a different hypervisor, such as <link
xlink:href="http://docs.openstack.org/trunk/config-reference/content/qemu.html"
>QEMU</link> or <link
xlink:href="http://docs.openstack.org/trunk/config-reference/content/introduction-to-xen.html"
>Xen</link>.</para>
<para>The following procedures will help you load the kernel modules for Intel-based and
AMD-based processors if they did not load automatically during KVM installation.</para>
<para>These procedures help you load the kernel modules for
Intel-based and AMD-based processors if they do not load
automatically during KVM installation.</para>
<section xml:id="kvm-intel">
<title>Intel-based processors</title>
<para>If your compute host is Intel-based, run the
following command as root to load the kernel
modules:</para>
<para>If your compute host is Intel-based, run these commands
as root to load the kernel modules:</para>
<screen><prompt>#</prompt> <userinput>modprobe kvm</userinput>
<prompt>#</prompt> <userinput>modprobe kvm-intel</userinput></screen>
<para>Add the following lines to the
<filename>/etc/modules</filename> file so that
these modules load on reboot:</para>
<para>Add these lines to the <filename>/etc/modules</filename>
file so that these modules load on reboot:</para>
<programlisting>kvm
kvm-intel</programlisting>
</section>
<section xml:id="kvm-amd">
<title>AMD-based processors</title>
<para>If your compute host is AMD-based, run the following
command as root to load the kernel modules:</para>
<para>If your compute host is AMD-based, run these commands as
root to load the kernel modules:</para>
<screen><prompt>#</prompt> <userinput>modprobe kvm</userinput>
<prompt>#</prompt> <userinput>modprobe kvm-amd</userinput></screen>
<para>Add the following lines to
<filename>/etc/modules</filename> file so that
these modules load on reboot:</para>
<para>Add these lines to <filename>/etc/modules</filename>
file so that these modules load on reboot:</para>
<programlisting>kvm
kvm-amd</programlisting>
</section>

101
doc/common/section_multiple-compute-nodes.xml
View File

@ -3,29 +3,32 @@
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
xml:id="configuring-multiple-compute-nodes">
<title>Configuring Multiple Compute Nodes</title>
<para>If your goal is to split your VM load across more than one
server, you can connect an additional <systemitem
class="service">nova-compute</systemitem> node to a cloud
controller node. This configuring can be reproduced on
multiple compute servers to start building a true multi-node
OpenStack Compute cluster.</para>
<para>To build out and scale the Compute platform, you spread
out services amongst many servers. While there are additional
ways to accomplish the build-out, this section describes
adding compute nodes, and the service we are scaling out is
called <systemitem class="service"
>nova-compute</systemitem>.</para>
<para>For a multi-node install you only make changes to
<filename>nova.conf</filename> and copy it to additional
compute nodes. Ensure each <filename>nova.conf</filename> file
points to the correct IP addresses for the respective
services.</para>
<para>By default, <systemitem class="service">nova-network</systemitem>
sets the bridge device based on the
setting in <literal>flat_network_bridge</literal>. Now you can
edit <filename>/etc/network/interfaces</filename> with the
following template, updated with your IP information.</para>
<title>Configure multiple Compute nodes</title>
<para>To distribute your VM load across more than one server, you
can connect an additional <systemitem class="service"
>nova-compute</systemitem> node to a cloud controller
node. You can reproduce this configuration on multiple compute
servers to build a true multi-node OpenStack Compute
cluster.</para>
<para>To build and scale the Compute platform, you distribute
services across many servers. While you can accomplish this in
other ways, this section describes how to add compute nodes
and scale out the <systemitem class="service"
>nova-compute</systemitem> service.</para>
<para>For a multi-node installation, you make changes to only the
<filename>nova.conf</filename> file and copy it to
additional compute nodes. Ensure that each
<filename>nova.conf</filename> file points to the correct
IP addresses for the respective services.</para>
<procedure>
<step>
<para>By default, <systemitem class="service"
>nova-network</systemitem> sets the bridge device
based on the setting in
<literal>flat_network_bridge</literal>. Update
your IP information in the
<filename>/etc/network/interfaces</filename> file
by using this template:</para>
<programlisting language="bash"># The loopback network interface
auto lo
iface lo inet loopback
@ -44,30 +47,40 @@ iface br100 inet static
gateway <replaceable>xxx.xxx.xxx.xxx</replaceable>
# dns-* options are implemented by the resolvconf package, if installed
dns-nameservers <replaceable>xxx.xxx.xxx.xxx</replaceable></programlisting>
</step>
<step>
<para>Restart networking:</para>
<screen><prompt>$</prompt> <userinput>sudo service networking restart</userinput></screen>
<para>With <filename>nova.conf</filename> updated and networking
set, configuration is nearly complete. First, bounce the
relevant services to take the latest updates:</para>
</step>
<step>
<para>Bounce the relevant services to take the latest
updates:</para>
<screen><prompt>$</prompt> <userinput>sudo service libvirtd restart</userinput>
$ <userinput>sudo service nova-compute restart</userinput></screen>
<para>To avoid issues with KVM and permissions with Nova, run
the following commands to ensure we have VM's that are running
<prompt>$</prompt> <userinput>sudo service nova-compute restart</userinput></screen>
</step>
<step>
<para>To avoid issues with KVM and permissions with Nova,
run these commands to ensure that your VMs run
optimally:</para>
<screen><prompt>#</prompt> <userinput>chgrp kvm /dev/kvm</userinput>
<prompt>#</prompt> <userinput>chmod g+rwx /dev/kvm</userinput></screen>
</step>
<step>
<para>Any server that does not have
<command>nova-api</command> running on it needs this
iptables entry so that images can get metadata info. On
compute nodes, configure the iptables with this next
step:</para>
<command>nova-api</command> running on it requires
an iptables entry so that images can get metadata
information.</para>
<para>On compute nodes, configure iptables with this
command:</para>
<screen><prompt>#</prompt> <userinput>iptables -t nat -A PREROUTING -d 169.254.169.254/32 -p tcp -m tcp --dport 80 -j DNAT --to-destination <replaceable>$NOVA_API_IP</replaceable>:8773</userinput></screen>
<para>Lastly, confirm that your compute node is talking to your
cloud controller. From the cloud controller, run this database
</step>
<step>
<para>Confirm that your compute node can talk to your
cloud controller.</para>
<para>From the cloud controller, run this database
query:</para>
<screen><prompt>$</prompt> <userinput>mysql -u<replaceable>$MYSQL_USER</replaceable> -p<replaceable>$MYSQL_PASS</replaceable> nova -e 'select * from services;'</userinput></screen>
<para>In return, you should see something similar to
this:</para> <screen><computeroutput>+---------------------+---------------------+------------+---------+----+----------+----------------+-----------+--------------+----------+-------------------+
<screen><computeroutput>+---------------------+---------------------+------------+---------+----+----------+----------------+-----------+--------------+----------+-------------------+
| created_at | updated_at | deleted_at | deleted | id | host | binary | topic | report_count | disabled | availability_zone |
+---------------------+---------------------+------------+---------+----+----------+----------------+-----------+--------------+----------+-------------------+
| 2011-01-28 22:52:46 | 2011-02-03 06:55:48 | NULL | 0 | 1 | osdemo02 | nova-network | network | 46064 | 0 | nova |
@ -77,10 +90,12 @@ $ <userinput>sudo service nova-compute restart</userinput></screen>
| 2011-01-30 23:42:24 | 2011-02-03 06:55:44 | NULL | 0 | 9 | osdemo04 | nova-compute | compute | 28484 | 0 | nova |
| 2011-01-30 21:27:28 | 2011-02-03 06:54:23 | NULL | 0 | 8 | osdemo05 | nova-compute | compute | 29284 | 0 | nova |
+---------------------+---------------------+------------+---------+----+----------+----------------+-----------+--------------+----------+-------------------+</computeroutput></screen>
<para>You can see that <literal>osdemo0{1,2,4,5}</literal> are
all running <systemitem class="service"
>nova-compute</systemitem>. When you start spinning up
instances, they will allocate on any node that is running
<systemitem class="service">nova-compute</systemitem> from
this list.</para>
<para>In this example, the <literal>osdemo</literal> hosts
all run the <systemitem class="service"
>nova-compute</systemitem> service. When you
launch instances, they allocate on any node that runs
<systemitem class="service"
>nova-compute</systemitem> from this list.</para>
</step>
</procedure>
</section>

244
doc/common/section_networking-quotas.xml
View File

@ -4,22 +4,25 @@
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0">
<title>Manage Networking service quotas</title>
<para>A quota is a function used to limit the number of resources. A default quota may be
enforced for all tenants. Attempting to create resources over the limit triggers an
error.</para>
<screen><prompt>$</prompt> <userinput>neutron net-create test_net</userinput>
<computeroutput>Quota exceeded for resources: ['network']</computeroutput></screen>
<para>Per-tenant quota configuration is also supported by the quota extension API. See <link
linkend="cfg_quotas_per_tenant"> Per-tenant quota configuration</link> for details.</para>
<para>A quota limits the number of available resources. A default
quota might be enforced for all tenants. When you try to create
more resources than the quota allows, an errors:</para>
<screen><prompt>$</prompt> <userinput>neutron net-create test_net</userinput></screen>
<screen><computeroutput>Quota exceeded for resources: ['network']</computeroutput></screen>
<para>Per-tenant quota configuration is also supported by the quota
extension API. See <link linkend="cfg_quotas_per_tenant">
Per-tenant quota configuration</link> for details.</para>
<section xml:id="cfg_quotas_common">
<title>Basic quota configuration</title>
<para>In the Networking default quota mechanism, all tenants have the same quota value, such
as the number of resources that a tenant can create. This is enabled by default.</para>
<para>The quota value is defined in the OpenStack Networking configuration file
(<filename>neutron.conf</filename>). If you want to disable quotas for a specific resource
(e.g., network, subnet, port), remove a corresponding item from
<literal>quota_items</literal>. Each of the quota values in the example below is the default
value.</para>
<para>In the Networking default quota mechanism, all tenants have
the same quota values, such as the number of resources that a
tenant can create.</para>
<para>The quota value is defined in the OpenStack Networking
<filename>neutron.conf</filename> configuration file. To
disable quotas for a specific resource, such as network, subnet,
or port, remove a corresponding item from
<option>quota_items</option>. This example shows the default
quota values:</para>
<programlisting language="ini">[quotas]
# resource name(s) that are supported in quota features
quota_items = network,subnet,port
@ -35,38 +38,79 @@ quota_port = 50
# default driver to use for quota checks
quota_driver = neutron.quota.ConfDriver</programlisting>
<para>OpenStack Networking also supports quotas for L3 resources: router and floating IP. You
can configure them by adding the following lines to <literal>quotas</literal> section in
<filename>neutron.conf</filename>. (Note that <literal>quota_items</literal> does not
affect these quotas.)</para>
<para>OpenStack Networking also supports quotas for L3 resources:
router and floating IP. Add these lines to the
<literal>quotas</literal> section in the
<filename>neutron.conf</filename> file.</para>
<programlisting language="ini">[quotas]
# number of routers allowed per tenant, and minus means unlimited
quota_router = 10
# number of floating IPs allowed per tenant, and minus means unlimited
quota_floatingip = 50</programlisting>
<para>OpenStack Networking also supports quotas for security group resources: number of
security groups and the number of rules per security group. You can configure them by adding
the following lines to <literal>quotas</literal> section in
<filename>neutron.conf</filename>. (Note that <literal>quota_items</literal> does not
affect these quotas.)</para>
<note>
<para>The <option>quota_items</option> option does not affect
these quotas.</para>
</note>
<para>OpenStack Networking also supports quotas for security group
resources: number of security groups and the number of rules for
each security group. Add these lines to the
<literal>quotas</literal> section in the
<filename>neutron.conf</filename> file:</para>
<programlisting language="ini">[quotas]
# number of security groups per tenant, and minus means unlimited
quota_security_group = 10
# number of security rules allowed per tenant, and minus means unlimited
quota_security_group_rule = 100</programlisting>
<note>
<para>The <option>quota_items</option> option does not affect
these quotas.</para>
</note>
</section>
<section xml:id="cfg_quotas_per_tenant">
<title>Per-tenant quota configuration</title>
<para>OpenStack Networking also supports per-tenant quota limit by quota extension API. To
enable per-tenant quota, you need to set <literal>quota_driver</literal> in
<literal>neutron.conf</literal>. For example:</para>
<title>Configure per-tenant quotas</title>
<para>OpenStack Networking also supports per-tenant quota limit by
quota extension API.</para>
<para>Use these commands to manage per-tenant quotas:<itemizedlist>
<listitem>
<para><command>neutron quota-delete</command>. Deletes
defined quotas for a specified tenant.</para>
</listitem>
<listitem>
<para><command>neutron quota-list</command>. Lists defined
quotas for all tenants.</para>
</listitem>
<listitem>
<para><command>neutron quota-show</command>. Shows quotas
for a specified tenant.</para>
</listitem>
<listitem>
<para><command>neutron quota-update</command>. Updates
quotas for a specified tenant.</para>
</listitem>
</itemizedlist>Only users with the <literal>admin</literal> role
can change a quota value. By default, the default set of quotas
are enforced for all tenants, so no
<command>quota-create</command> command exists.</para>
<procedure>
<step>
<title>Configure Networking to show per-tenant quotas</title>
<para>Set the <literal>quota_driver</literal> option in the
<literal>neutron.conf</literal> file:</para>
<programlisting language="ini">quota_driver = neutron.db.quota_db.DbQuotaDriver</programlisting>
<para>When per-tenant quota is enabled, the output of the following commands contain
<literal>quotas</literal>.</para>
<screen><prompt>$</prompt> <userinput>neutron ext-list -c alias -c name</userinput>
<computeroutput>+-----------------+--------------------------+
<para>When you set this option, the output for Networking
commands shows <literal>quotas</literal>.</para>
</step>
<step>
<title>List Networking extensions</title>
<para>To list the Networking extensions, run this
command:</para>
<screen><prompt>$</prompt> <userinput>neutron ext-list -c alias -c name</userinput></screen>
<para>The command shows the <literal>quotas</literal>
extension, which provides per-tenant quota management
support:</para>
<screen><computeroutput>+-----------------+--------------------------+
| alias | name |
+-----------------+--------------------------+
| agent_scheduler | Agent Schedulers |
@ -79,9 +123,13 @@ quota_security_group_rule = 100</programlisting>
| lbaas | LoadBalancing service |
| extraroute | Neutron Extra Route |
+-----------------+--------------------------+</computeroutput></screen>
<screen>
<prompt>$</prompt> <userinput>neutron ext-show quotas</userinput>
<computeroutput>+-------------+------------------------------------------------------------+
</step>
<step>
<title>Show information for the quotas extension</title>
<para>To show information for the <literal>quotas</literal>
extension, run this command:</para>
<screen><prompt>$</prompt> <userinput>neutron ext-show quotas</userinput></screen>
<screen><computeroutput>+-------------+------------------------------------------------------------+
| Field | Value |
+-------------+------------------------------------------------------------+
| alias | quotas |
@ -91,49 +139,38 @@ quota_security_group_rule = 100</programlisting>
| namespace | http://docs.openstack.org/network/ext/quotas-sets/api/v2.0 |
| updated | 2012-07-29T10:00:00-00:00 |
+-------------+------------------------------------------------------------+</computeroutput></screen>
<note><para>
Per-tenant quotas are supported only supported by some plugins. At least Open vSwitch,
Linux Bridge, and Nicira NVP are known to work but new versions of other plugins may
bring additional functionality - consult the documentation for each plugin.
</para></note>
<para>There are four CLI commands to manage per-tenant quotas:<itemizedlist>
<listitem>
<para><command>neutron quota-delete</command> - Delete defined quotas of a given
tenant.</para>
</listitem>
<listitem>
<para><command>neutron quota-list</command> - List defined quotas of all tenants.</para>
</listitem>
<listitem>
<para><command>neutron quota-show</command> - Show quotas of a given tenant.</para>
</listitem>
<listitem>
<para><command>neutron quota-update</command> - Define tenant's quotas not to use
defaults.</para>
</listitem>
</itemizedlist>Only users with 'admin' role can change a quota value. Note that the default
set of quotas are enforced for all tenants by default, so there is no
<literal>quota-create</literal> command.</para>
<para>
<literal>quota-list</literal> displays a list of tenants for which per-tenant quota is enabled.
The tenants who have the default set of quota limits are not listed.
This command is permitted to only 'admin' users.
</para>
<screen><prompt>$</prompt> <userinput>neutron quota-list</userinput>
<computeroutput>+------------+---------+------+--------+--------+----------------------------------+
<note>
<para>Only some plug-ins support per-tenant quotas.
Specifically, Open vSwitch, Linux Bridge, and Nicira NVP
support them, but new versions of other plug-ins might
bring additional functionality. See the documentation for
each plug-in.</para>
</note>
</step>
<step>
<title>List tenants who have per-tenant quota support</title>
<para>The <command>quota-list</command> command lists tenants
for which the per-tenant quota is enabled. The command does
not list tenants with default quota support. You must be an
administrative user to run this command:</para>
<screen><prompt>$</prompt> <userinput>neutron quota-list</userinput></screen>
<screen><computeroutput>+------------+---------+------+--------+--------+----------------------------------+
| floatingip | network | port | router | subnet | tenant_id |
+------------+---------+------+--------+--------+----------------------------------+
| 20 | 5 | 20 | 10 | 5 | 6f88036c45344d9999a1f971e4882723 |
| 25 | 10 | 30 | 10 | 10 | bff5c9455ee24231b5bc713c1b96d422 |
+------------+---------+------+--------+--------+----------------------------------+</computeroutput></screen>
<para>
<literal>quota-show</literal> reports the current set of quota limits for the specified tenant.
Regular (non-admin) users can call this command (without --tenant_id parameter).
If per-tenant quota limits are not defined for the tenant, the default set of
quotas are displayed.
</para>
<screen><prompt>$</prompt> <userinput>neutron quota-show --tenant_id 6f88036c45344d9999a1f971e4882723</userinput>
<computeroutput>+------------+-------+
</step>
<step>
<title>Show per-tenant quota values</title>
<para>The <command>quota-show</command> reports the current
set of quota limits for the specified tenant.
Non-administrative users can run this command without the
<parameter>--tenant_id</parameter> parameter. If
per-tenant quota limits are not enabled for the tenant, the
command shows the default set of quotas:</para>
<screen><prompt>$</prompt> <userinput>neutron quota-show --tenant_id 6f88036c45344d9999a1f971e4882723</userinput></screen>
<screen><computeroutput>+------------+-------+
| Field | Value |
+------------+-------+
| floatingip | 20 |
@ -142,11 +179,10 @@ quota_security_group_rule = 100</programlisting>
| router | 10 |
| subnet | 5 |
+------------+-------+</computeroutput></screen>
<para>
The below is an example called by a non-admin user.
</para>
<screen><prompt>$</prompt> <userinput>neutron quota-show</userinput>
<computeroutput>+------------+-------+
<para>The following command shows the command output for a
non-administrative user:</para>
<screen><prompt>$</prompt> <userinput>neutron quota-show</userinput></screen>
<screen><computeroutput>+------------+-------+
| Field | Value |
+------------+-------+
| floatingip | 20 |
@ -155,8 +191,11 @@ quota_security_group_rule = 100</programlisting>
| router | 10 |
| subnet | 5 |
+------------+-------+</computeroutput></screen>
<para>You can update a quota of the given tenant by <literal>quota-update</literal> command.</para>
<para>Update the limit of network quota.</para>
</step>
<step>
<title>Update quota values for a specified tenant</title>
<para>Use the <command>quota-update</command> command to
update a quota for a specified tenant:</para>
<screen><prompt>$</prompt> <userinput>neutron quota-update --tenant_id 6f88036c45344d9999a1f971e4882723 --network 5</userinput>
<computeroutput>+------------+-------+
| Field | Value |
@ -167,7 +206,8 @@ quota_security_group_rule = 100</programlisting>
| router | 10 |
| subnet | 10 |
+------------+-------+</computeroutput></screen>
<para>You can update quotas of multiple resources in one command.</para>
<para>You can update quotas for multiple resources through one
command:</para>
<screen><prompt>$</prompt> <userinput>neutron quota-update --tenant_id 6f88036c45344d9999a1f971e4882723 --subnet 5 --port 20</userinput>
<computeroutput>+------------+-------+
| Field | Value |
@ -178,13 +218,13 @@ quota_security_group_rule = 100</programlisting>
| router | 10 |
| subnet | 5 |
+------------+-------+</computeroutput></screen>
<para>
To update the limits of L3 resource (router, floating IP), we need to
specify new values of the quotas after '--'. The example below updates
the limit of the number of floating IPs for the given tenant.
</para>
<screen><prompt>$</prompt> <userinput>neutron quota-update --tenant_id 6f88036c45344d9999a1f971e4882723 -- --floatingip 20</userinput>
<computeroutput>+------------+-------+
<para>To update the limits for an L3 resource such as, router
or floating IP, you must define new values for the quotas
after the <parameter>--</parameter> directive.</para>
<para>This example updates the limit of the number of floating
IPs for the specified tenant:</para>
<screen><prompt>$</prompt> <userinput>neutron quota-update --tenant_id 6f88036c45344d9999a1f971e4882723 -- --floatingip 20</userinput></screen>
<screen><computeroutput>+------------+-------+
| Field | Value |
+------------+-------+
| floatingip | 20 |
@ -193,9 +233,9 @@ quota_security_group_rule = 100</programlisting>
| router | 10 |
| subnet | 5 |
+------------+-------+</computeroutput></screen>
<para>
You can update the limits of multiple resources including L2 resources and L3 resource in one command.
</para>
<para>You can update the limits of multiple resources by
including L2 resources and L3 resource through one
command.</para>
<screen><prompt>$</prompt> <userinput>neutron quota-update --tenant_id 6f88036c45344d9999a1f971e4882723 --network 3 --subnet 3 --port 3 -- --floatingip 3 --router 3</userinput>
<computeroutput>+------------+-------+
| Field | Value |
@ -206,16 +246,18 @@ quota_security_group_rule = 100</programlisting>
| router | 3 |
| subnet | 3 |
+------------+-------+</computeroutput></screen>
<para>
To clear per-tenant quota limits, use <literal>quota-delete</literal>.
After <literal>quota-delete</literal>, quota limits enforced to the tenant are reset to
the default set of quotas.
</para>
<screen><prompt>$</prompt> <userinput>neutron quota-delete --tenant_id 6f88036c45344d9999a1f971e4882723</userinput>
<computeroutput>Deleted quota: 6f88036c45344d9999a1f971e4882723</computeroutput></screen>
<screen>
<prompt>$</prompt> <userinput>neutron quota-show --tenant_id 6f88036c45344d9999a1f971e4882723</userinput>
<computeroutput>+------------+-------+
</step>
<step>
<title>Delete per-tenant quota values</title>
<para>To clear per-tenant quota limits, use the
<command>quota-delete</command> command:</para>
<screen><prompt>$</prompt> <userinput>neutron quota-delete --tenant_id 6f88036c45344d9999a1f971e4882723</userinput></screen>
<screen><computeroutput>Deleted quota: 6f88036c45344d9999a1f971e4882723</computeroutput></screen>
<para>After you run this command, you can see that quota
values for the tenant are reset to the default
values:</para>
<screen><prompt>$</prompt> <userinput>neutron quota-show --tenant_id 6f88036c45344d9999a1f971e4882723</userinput></screen>
<screen><computeroutput>+------------+-------+
| Field | Value |
+------------+-------+
| floatingip | 50 |
@ -224,5 +266,7 @@ quota_security_group_rule = 100</programlisting>
| router | 10 |
| subnet | 10 |
+------------+-------+</computeroutput></screen>
</step>
</procedure>
</section>
</section>

4
doc/common/section_neutron_cli_commands.xml
View File

@ -21,9 +21,7 @@
[--os-cacert &lt;ca-certificate>] [--insecure]</computeroutput></screen>
</example>
<example>
<title>Positional Arguments</title>
<title>Positional arguments</title>
<screen><computeroutput>
agent-delete Delete a given agent.
agent-list List agents.

22
doc/common/section_nova_boot_from_volume.xml
View File

@ -11,9 +11,9 @@
><citetitle>OpenStack Configuration
Reference</citetitle></link>.</para>
<procedure xml:id="create_volume_from_image">
<title>To launch an instance from a volume</title>
<step><para>To choose an image to create a bootable volume from, run the
following command to list images:</para>
<step>
<para>For a list of images to choose from to create a bootable
volume, run this command:</para>
<screen><prompt>$</prompt> <userinput>nova image-list</userinput>
<computeroutput>+--------------------------------------+---------------------------------+--------+--------+
| ID | Name | Status | Server |
@ -21,7 +21,8 @@
| e0b7734d-2331-42a3-b19e-067adc0da17d | cirros-0.3.1-x86_64-uec | ACTIVE | |
| 75bf193b-237b-435e-8712-896c51484de9 | cirros-0.3.1-x86_64-uec-kernel | ACTIVE | |
| 19eee81c-f972-44e1-a952-1dceee148c47 | cirros-0.3.1-x86_64-uec-ramdisk | ACTIVE | |
+--------------------------------------+---------------------------------+--------+--------+</computeroutput></screen></step>
+--------------------------------------+---------------------------------+--------+--------+</computeroutput></screen>
</step>
<step>
<para>To create a bootable volume from an image, include the
image ID in the command:</para>
@ -66,7 +67,12 @@
<screen><prompt>$</prompt> <userinput>nova boot --flavor <replaceable>FLAVOR</replaceable> --block_device_mapping <replaceable>DEVNAME</replaceable>=<replaceable>ID</replaceable>:<replaceable>TYPE</replaceable>:<replaceable>SIZE</replaceable>:<replaceable>DELETE_ON_TERMINATE</replaceable> <replaceable>NAME</replaceable></userinput></screen>
<para>The command arguments are:</para>
<informaltable>
<thead><tr><th>Parameter</th><th>Description</th></tr></thead>
<thead>
<tr>
<th>Parameter</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>
@ -145,8 +151,10 @@
<literal>Attempt to boot from volume - no image
supplied</literal> error is returned.</para>
</note>
<para>You can also attach a swap disk on boot with the <parameter>--swap</parameter>
flag, or you can attach an ephemeral disk on boot with the <parameter>--ephemeral</parameter> flag.</para>
<para>You can also attach a swap disk on boot with the
<parameter>--swap</parameter> flag, or you can attach an
ephemeral disk on boot with the
<parameter>--ephemeral</parameter> flag.</para>
<para>For example, you might enter the following command to boot
from a volume. The volume is not deleted when the instance is
terminated:</para>

79
doc/common/section_nova_cli_baremetal.xml
View File

@ -3,53 +3,51 @@
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0">
<title>Manage bare metal nodes</title>
<para>The bare metal driver for OpenStack Compute manages provisioning of
physical hardware using common cloud APIs and tools such as Orchestration
(Heat). The use case for this driver is for single tenant clouds such as a
high-performance computing cluster or deploying OpenStack itself.
Development efforts are focused on moving the driver out of the Compute code
base in the Icehouse release. If you use the bare metal driver, you must
create and add a network interface to a bare metal node. Then, you can
launch an instance from a bare metal image.</para>
<para>You can list and delete bare metal nodes. When you delete a node, any
associated network interfaces are removed. You can list and remove network
interfaces that are associated with a bare metal node.</para>
<para>The bare metal driver for OpenStack Compute manages
provisioning of physical hardware using common cloud APIs and
tools such as Orchestration (Heat). The use case for this driver
is for single tenant clouds such as a high-performance computing
cluster or deploying OpenStack itself. Development efforts are
focused on moving the driver out of the Compute code base in the
Icehouse release. If you use the bare metal driver, you must
create and add a network interface to a bare metal node. Then, you
can launch an instance from a bare metal image.</para>
<para>You can list and delete bare metal nodes. When you delete a
node, any associated network interfaces are removed. You can list
and remove network interfaces that are associated with a bare
metal node.</para>
<itemizedlist>
<title>Commands</title>
<listitem>
<para><command>baremetal-interface-add</command></para>
<para>Adds a network interface to a bare metal node.</para>
<para><command>baremetal-interface-add</command>. Adds a network
interface to a bare metal node.</para>
</listitem>
<listitem>
<para><command>baremetal-interface-list</command></para>
<para>Lists network interfaces associated with a bare metal node.</para>
<para><command>baremetal-interface-list</command>. Lists network
interfaces associated with a bare metal node.</para>
</listitem>
<listitem>
<para>
<command>baremetal-interface-remove</command></para>
<para>Removes a network interface from a bare metal node.</para>
<para><command>baremetal-interface-remove</command>. Removes a
network interface from a bare metal node.</para>
</listitem>
<listitem>
<para>
<command>baremetal-node-create</command></para>
<para>Creates a bare metal node.</para>
<para><command>baremetal-node-create</command>. Creates a bare
metal node.</para>
</listitem>
<listitem>
<para>
<command>baremetal-node-delete</command></para>
<para>Removes a bare metal node and any associated interfaces.</para>
<para><command>baremetal-node-delete</command>. Removes a bare
metal node and any associated interfaces.</para>
</listitem>
<listitem>
<para><command>baremetal-node-list</command></para>
<para>Lists available bare metal nodes.</para>
<para><command>baremetal-node-list</command>. Lists available
bare metal nodes.</para>
</listitem>
<listitem>
<para><command>baremetal-node-show</command></para>
<para>Shows information about a bare metal node.</para>
<para><command>baremetal-node-show</command>. Shows information
about a bare metal node.</para>
</listitem>
</itemizedlist>
<procedure>
<title>To manage bare metal nodes</title>
<step>
<para>Create a bare metal node:</para>
<screen><prompt>$</prompt> <userinput>nova baremetal-node-create --pm_address=1.2.3.4 --pm_user=ipmi --pm_password=ipmi $(hostname -f) 1 512 10 aa:bb:cc:dd:ee:ff</userinput></screen>
@ -80,24 +78,24 @@
| id | 1 |
| port_no | 0 |
| address | aa:bb:cc:dd:ee:ff |
+-------------+-------------------+</computeroutput> </screen>
+-------------+-------------------+</computeroutput></screen>
</step>
<step>
<para>Launch an instance from a bare metal image:</para>
<screen><prompt>$</prompt> <userinput>nova boot --image my-baremetal-image --flavor my-baremetal-flavor test</userinput> </screen>
<screen>+-----------------------------+--------------------------------------+
<screen><computeroutput>+-----------------------------+--------------------------------------+
| Property | Value |
+-----------------------------+--------------------------------------+
| status | BUILD |
| id | cc302a8f-cd81-484b-89a8-b75eb3911b1b |
... wait for instance to become active ... </screen>
... wait for instance to become active ...</computeroutput></screen>
</step>
<step>
<para>You can list bare metal nodes and interfaces, as follows:</para>
<para>List bare metal nodes and interfaces:</para>
<screen><prompt>$</prompt> <userinput>nova baremetal-node-list</userinput></screen>
<para>When a node is in use, its status includes the UUID of the instance
that runs on it:</para>
<para>When a node is in use, its status includes the UUID of the
instance that runs on it:</para>
<screen><computeroutput>+----+--------+------+-----------+---------+-------------------
+------+------------+-------------+-------------+---------------+
| ID | Host | CPUs | Memory_MB | Disk_GB | MAC Address
@ -132,10 +130,13 @@
</step>
</procedure>
<note>
<para>Set the <parameter>--availability_zone</parameter> parameter to
specify which zone or node to start the server. You can separate the zone
from the hostname with a comma. As an example:
<para>Set the <parameter>--availability_zone</parameter> parameter
to specify which zone or node to use to start the server.
Separate the zone from the host name with a comma. For
example:</para>
<screen><prompt>$</prompt> <userinput>nova boot --availability_zone=zone:<replaceable>host</replaceable>,<replaceable>node</replaceable></userinput></screen>
Specifying "host" is optional for the <parameter>--availability_zone</parameter> parameter, and "zone:,node" also works.</para>
<para><parameter>host</parameter> is optional for the
<parameter>--availability_zone</parameter> parameter.
<parameter>zone:,node</parameter> also works.</para>
</note>
</section>

14
doc/common/section_nova_cli_evacuate.xml
View File

@ -7,13 +7,13 @@
<para>If a cloud compute node fails due to a hardware malfunction
or another reason, you can evacuate instances to make them
available again.</para>
<para>You can choose evacuation parameters for your use case.</para>
<para>You can choose evacuation parameters for your use
case.</para>
<para>To preserve user data on server disk, you must configure
shared storage on the target host. Also, you must validate
that the current VM host is down. Otherwise the evacuation
fails with an error.</para>
<procedure xml:id="evacuate_shared">
<title>To evacuate your server</title>
<step>
<para>To find a different host for the evacuated instance,
run the following command to lists hosts:</para>
@ -40,9 +40,13 @@
</step>
<step>
<para>To preserve the user disk data on the evacuated
server, deploy OpenStack Compute with shared
filesystem. To configure your system, see <link xlink:href="http://docs.openstack.org/trunk/config-reference/content/configuring-openstack-compute-basics.html#section_configuring-compute-migrations">Configure migrations</link> in <citetitle>OpenStack Configuration Reference</citetitle>. In this
example, the password remains unchanged.</para>
server, deploy OpenStack Compute with shared file
system. To configure your system, see <link
xlink:href="http://docs.openstack.org/trunk/config-reference/content/configuring-openstack-compute-basics.html#section_configuring-compute-migrations"
>Configure migrations</link> in
<citetitle>OpenStack Configuration
Reference</citetitle>. In this example, the
password remains unchanged.</para>
<screen><prompt>$</prompt> <userinput>nova evacuate <replaceable>evacuated_server_name</replaceable> <replaceable>host_b</replaceable> --on-shared-storage</userinput> </screen>
</step>
</procedure>

25
doc/common/section_nova_cli_resizerebuild.xml
View File

@ -6,7 +6,6 @@
<title>Change the size of your server</title>
<para>You change the size of a server by changing its flavor.</para>
<procedure>
<title>To change the size of your server</title>
<step>
<para>List the available flavors:</para>
<screen><prompt>$</prompt> <userinput>nova flavor-list</userinput></screen>
@ -23,7 +22,8 @@
+----+-----------+-----------+------+-----------+------+-------+-------------+-----------+</computeroutput></screen>
</step>
<step>
<para>Show information about your server, including its size:</para>
<para>Show information about your server, including its
size:</para>
<screen><prompt>$</prompt> <userinput>nova show myCirrosServer</userinput></screen>
<screen><computeroutput>+-------------------------------------+----------------------------------------------------------------+
@ -57,14 +57,15 @@
| config_drive | |
+-------------------------------------+----------------------------------------------------------------+</computeroutput></screen>
<para>The size of the server is <literal>m1.small
(2)</literal>.</para></step>
(2)</literal>.</para>
</step>
<step>
<para>To resize the server, pass the server ID and the desired flavor to the nova
<command>resize</command> command.
Include the <literal>--poll</literal> parameter to report the resize
<para>To resize the server, pass the server ID and the desired
flavor to the nova <command>resize</command> command. Include
the <literal>--poll</literal> parameter to report the resize
progress.</para>
<screen><prompt>$</prompt> <userinput>nova resize myCirrosServer 4 --poll</userinput></screen>
<screen><computeroutput>Instance resizing... 100% complete
<screen><computeroutput>Instance resizing... 100% complete
Finished</computeroutput> </screen>
</step>
<step>
@ -78,12 +79,14 @@ Finished</computeroutput> </screen>
</step>
<step>
<para>When the resize completes, the status becomes
<literal>VERIFY_RESIZE</literal>. To confirm the resize:</para>
<literal>VERIFY_RESIZE</literal>. To confirm the
resize:</para>
<screen><prompt>$</prompt> <userinput>nova resize-confirm 6beefcf7-9de6-48b3-9ba9-e11b343189b3</userinput></screen>
<para>The server status becomes ACTIVE.</para> </step>
<para>The server status becomes ACTIVE.</para>
</step>
<step>
<para>If the resize fails or does not work as expected, you
can revert the resize:</para>
<para>If the resize fails or does not work as expected, you can
revert the resize:</para>
<screen><prompt>$</prompt> <userinput>nova resize-revert 6beefcf7-9de6-48b3-9ba9-e11b343189b3</userinput></screen>
<para>The server status becomes ACTIVE.</para>
</step>

8
doc/common/section_nova_cli_sshkeys.xml
View File

@ -2,15 +2,15 @@
<section xmlns="http://docbook.org/ns/docbook"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
xml:id="nova_cli_keygen"><title>Add keypair</title>
xml:id="nova_cli_keygen">
<title>Add keypair</title>
<para>Create at least one keypair for each project. If you have
generated a keypair with an external tool, you can import it into
OpenStack. The keypair can be used for multiple instances that
belong to a project.</para>
<procedure>
<title>To add a keypair</title>
<step>
<title>Create a key</title>
<para>Create a key.</para>
<para>To create a <literal>mykey</literal> key that you can
associate with instances, run the following command:</para>
<screen><prompt>$</prompt> <userinput>nova keypair-add mykey > mykey.pem</userinput></screen>
@ -19,7 +19,7 @@
the <literal>mykey</literal> key is associated.</para>
</step>
<step>
<title>Import a keypair</title>
<para>Alternatively, you can import a keypair.</para>
<para>To import an existing public key,
<literal>mykey.pub</literal>, and associate it with the
<literal>mykey</literal> key, run the following

30
doc/common/section_nova_cli_userdata.xml
View File

@ -1,24 +1,20 @@
<?xml version="1.0" encoding="UTF-8"?>
<!-- moved to launch instances file -->
<section
xmlns="http://docbook.org/ns/docbook"
<section xmlns="http://docbook.org/ns/docbook"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink"
version="5.0"
xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
xml:id="inserting_userdata">
<title>Providing User Data to Instances</title>
<para><literal>User Data</literal> is a special key in the metadata
service which holds a file that cloud aware applications within
the guest instance can access. For example the <link
<title>Provide user data to instances</title>
<para><firstterm>User data</firstterm> is a special key in the
metadata service that holds a file that cloud-aware applications
in the guest instance can access. For example the <link
xlink:href="https://help.ubuntu.com/community/CloudInit"
>cloudinit</link> system is an open source package from Ubuntu
that handles early initialization of a cloud instance that makes
use of this <literal>user data</literal>.</para>
<para>This user-data can be put in a file on your local system and
then passed in at instance creation with the flag
<literal>--user-data &lt;user-data-file&gt;</literal> for
example:
><package>cloudinit</package></link> system is a Ubuntu open
source package that handles early initialization of a cloud
instance and that makes use of <literal>user
data</literal>.</para>
<para>You can place user data in a local file and pass it through
the <parameter>--user-data &lt;user-data-file&gt;</parameter>
parameter at instance creation:</para>
<screen><prompt>$</prompt> <userinput>nova boot --image ubuntu-cloudimage --flavor 1 --user-data mydata.file</userinput></screen>
</para>
</section>

135
doc/common/section_rpc-for-networking.xml
View File

@ -4,26 +4,26 @@
xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
xml:id="networking-configuring-rpc">
<?dbhtml stop-chunking?>
<title>Configuration options for the Oslo RPC Messaging System</title>
<title>Configure the Oslo RPC messaging system</title>
<para>OpenStack projects use an open standard for messaging
middleware known as AMQP. This messaging middleware enables the
OpenStack services that run on multiple servers to talk to each
other. OpenStack Oslo RPC supports three implementations of AMQP:
<application>RabbitMQ</application>,
<application>Qpid</application>, and
<application>ZeroMQ</application>.</para>
<para>Many OpenStack Networking plug-ins use RPC to enable agents to communicate with the main
<systemitem class="service">neutron-server</systemitem> process. If your plugin requires
agents, they can use the same RPC mechanism used by other OpenStack components like Nova.
OpenStack projects use an open standard for messaging middleware known as AMQP. This messaging
middleware enables the OpenStack services which will exist across multiple servers to talk to
each other. OpenStack Oslo RPC supports three implementations of AMQP:
<application>RabbitMQ</application>, <application>Qpid</application>, and
<application>ZeroMQ</application>
</para>
<section xml:id="networking-configuration-rabbitmq">
<title>Configuration for RabbitMQ</title>
<title>Configure RabbitMQ</title>
<para>OpenStack Oslo RPC uses <application>RabbitMQ</application> by
default. This section discusses the configuration options that are
relevant when <application>RabbitMQ</application> is used. The
<literal>rpc_backend</literal> option is not required as long as
<application>RabbitMQ</application> is the default messaging system.
However, if it is included the configuration, it must be set to
<para>OpenStack Oslo RPC uses <application>RabbitMQ</application>
by default. Use these options to configure the
<application>RabbitMQ</application> message system. The
<option>rpc_backend</option> option is optional as long as
<application>RabbitMQ</application> is the default messaging
system. However, if it is included the configuration, you must
set it to
<literal>neutron.openstack.common.rpc.impl_kombu</literal>.</para>
@ -31,83 +31,92 @@
rpc_backend=neutron.openstack.common.rpc.impl_kombu
</programlisting>
<para>The following tables describe the rest of the options that
can be used when <application>RabbitMQ</application> is used
as the messaging system. You can configure the messaging
communication for different installation scenarios as well as
tune RabbitMQ's retries and the size of the RPC thread pool.
If you want to monitor notifications through RabbitMQ, you
must set the <literal>notification_driver</literal> option in
<filename>neutron.conf</filename> to
<literal>neutron.notifier.rabbit_notifier</literal>.
</para>
<para>Use these options to configure the
<application>RabbitMQ</application> messaging system. You can
configure messaging communication for different installation
scenarios, tune retries for RabbitMQ, and define the size of the
RPC thread pool. To monitor notifications through RabbitMQ, you
must set the <option>notification_driver</option> option to
<literal>neutron.notifier.rabbit_notifier</literal> in the
<filename>neutron.conf</filename> file:</para>
<xi:include href="tables/neutron-rabbitmq.xml"/>
<xi:include href="tables/neutron-kombu.xml"/>
</section>
<section xml:id="networking-configuration-qpid">
<title>Configuration for Qpid</title>
<para>This section discusses the configuration options that are relevant if
<application>Qpid</application> is used as the messaging system for OpenStack Oslo RPC.
<application>Qpid</application> is not the default messaging system, so it must be enabled
by setting the <literal>rpc_backend</literal> option in
<filename>neutron.conf</filename>.</para>
<title>Configure Qpid</title>
<para>Use these options to configure the
<application>Qpid</application> messaging system for OpenStack
Oslo RPC. <application>Qpid</application> is not the default
messaging system, so you must enable it by setting the
<option>rpc_backend</option> option in the
<filename>neutron.conf</filename> file:</para>
<programlisting language="ini">
rpc_backend=neutron.openstack.common.rpc.impl_qpid
</programlisting>
<para>This next critical option points the compute nodes to the <application>Qpid</application>
broker (server). Set <literal>qpid_hostname</literal> in <filename>neutron.conf</filename> to
be the hostname where the broker is running.</para>
<para>This critical option points the compute nodes to the
<application>Qpid</application> broker (server). Set the
<option>qpid_hostname</option> option to the host name where
the broker runs in the <filename>neutron.conf</filename>
file.</para>
<note>
<para>The -<literal>-qpid_hostname</literal> option accepts a value in the form of either a
hostname or an IP address.</para>
<para>The <option>--qpid_hostname</option> option accepts a host
name or IP address value.</para>
</note>
<programlisting language="ini">
qpid_hostname=hostname.example.com
</programlisting>
<para>If the <application>Qpid</application> broker is listening on a port other than the AMQP
default of <literal>5672</literal>, you will need to set the <literal>qpid_port</literal>
option:</para>
<para>If the <application>Qpid</application> broker listens on a
port other than the AMQP default of <literal>5672</literal>, you
must set the <option>qpid_port</option> option to that
value:</para>
<programlisting language="ini">
qpid_port=12345
</programlisting>
<para>If you configure the <application>Qpid</application> broker to require authentication, you
will need to add a username and password to the configuration:</para>
<para>If you configure the <application>Qpid</application> broker
to require authentication, you must add a user name and password
to the configuration:</para>
<programlisting language="ini">
qpid_username=username
qpid_password=password
</programlisting>
<para>By default, TCP is used as the transport. If you would like to enable SSL, set the
<literal>qpid_protocol</literal> option:</para>
<para>By default, TCP is used as the transport. To enable SSL, set
the <option>qpid_protocol</option> option:</para>
<programlisting language="ini">
qpid_protocol=ssl
</programlisting>
<para>The following table lists the rest of the options used by the Qpid messaging driver for
OpenStack Oslo RPC. It is not common that these options are used.</para>
<para>Use these additional options to configure the Qpid messaging
driver for OpenStack Oslo RPC. These options are used
infrequently.</para>
<xi:include href="tables/neutron-qpid.xml"/>
</section>
<section xml:id="networking-configuration-zeromq">
<title>Configuration for ZeroMQ</title>
<para>This section discusses the configuration options that are relevant
if <application>ZeroMQ</application> is used as the messaging system for
OpenStack Oslo RPC. <application>ZeroMQ</application> is not the default
messaging system, so it must be enabled by setting the
<literal>rpc_backend</literal> option in
<filename>neutron.conf</filename>.</para>
<title>Configure ZeroMQ</title>
<para>Use these options to configure the
<application>ZeroMQ</application> messaging system for
OpenStack Oslo RPC. <application>ZeroMQ</application> is not the
default messaging system, so you must enable it by setting the
<option>rpc_backend</option> option in the
<filename>neutron.conf</filename> file:</para>
<xi:include href="tables/neutron-zeromq.xml"/>
</section>
<section xml:id="networking-common-messaging-configuration">
<title>Common configuration for messaging</title>
<title>Configure messaging</title>
<para>This section lists options that are common between the
<application>RabbitMQ</application>, <application>Qpid</application>
and <application>ZeroMq</application>
messaging drivers.</para>
<para>Use these common options to configure the
<application>RabbitMQ</application>,
<application>Qpid</application>, and
<application>ZeroMq</application> messaging drivers:</para>
<xi:include href="tables/neutron-rpc.xml"/>
<xi:include href="tables/neutron-notifier.xml"/>
</section>
</section>

144
doc/common/section_rpc.xml
View File

@ -4,116 +4,88 @@
xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
xml:id="configuring-rpc">
<?dbhtml stop-chunking?>
<title>Configuring the Oslo RPC Messaging System</title>
<para>OpenStack projects use an open standard for messaging middleware
known as AMQP. This messaging middleware enables the OpenStack
services which will exist across multiple servers to talk to each other.
OpenStack Oslo RPC supports three implementations of AMQP:
<application>RabbitMQ</application>,
<title>Configure the Oslo RPC messaging system</title>
<para>OpenStack projects use AMQP, an open standard for messaging
middleware. OpenStack services that run on multiple servers to
talk to each other. OpenStack Oslo RPC supports three
implementations of AMQP: <application>RabbitMQ</application>,
<application>Qpid</application>, and
<application>ZeroMQ</application>.</para>
<section xml:id="configuration-rabbitmq">
<title>Configuration for RabbitMQ</title>
<para>OpenStack Oslo RPC uses <application>RabbitMQ</application> by
default. This section discusses the configuration options that are
relevant when <application>RabbitMQ</application> is used. The
<literal>rpc_backend</literal> option is not required as long as
<application>RabbitMQ</application> is the default messaging system.
However, if it is included the configuration, it must be set to
<title>Configure RabbitMQ</title>
<para>OpenStack Oslo RPC uses <application>RabbitMQ</application>
by default. Use these options to configure the
<application>RabbitMQ</application> message system. The
<literal>rpc_backend</literal> option is not required as long
as <application>RabbitMQ</application> is the default messaging
system. However, if it is included the configuration, you must
set it to
<literal>nova.openstack.common.rpc.impl_kombu</literal>.</para>
<programlisting language="ini">rpc_backend=nova.openstack.common.rpc.impl_kombu</programlisting>
<para>The following tables describe the rest of the options that
can be used when <application>RabbitMQ</application> is used
as the messaging system. You can configure the messaging
communication for different installation scenarios as well as
tune RabbitMQ's retries and the size of the RPC thread pool.
If you want to monitor notifications through RabbitMQ, you
must set the <literal>notification_driver</literal> option in
<filename>nova.conf</filename> to
<literal>nova.notifier.rabbit_notifier</literal>. The default
for sending usage data is 60 seconds plus a randomized 0-60 seconds.
</para>
<para>You can use these additional options to configure the
<application>RabbitMQ</application> messaging system. You can
configure messaging communication for different installation
scenarios, tune retries for RabbitMQ, and define the size of the
RPC thread pool. To monitor notifications through RabbitMQ, you
must set the <option>notification_driver</option> option to
<literal>nova.notifier.rabbit_notifier</literal> in the
<filename>nova.conf</filename> file. The default for sending
usage data is sixty seconds plus a random number of seconds from
zero to sixty.</para>
<xi:include href="tables/nova-rabbitmq.xml"/>
<xi:include href="tables/nova-kombu.xml"/>
</section>
<section xml:id="configuration-qpid">
<title>Configuration for Qpid</title>
<para>This section discusses the configuration options that are relevant
if <application>Qpid</application> is used as the messaging system for
OpenStack Oslo RPC. <application>Qpid</application> is not the default
messaging system, so it must be enabled by setting the
<literal>rpc_backend</literal> option in
<filename>nova.conf</filename>.</para>
<title>Configure Qpid</title>
<para>Use these options to configure the
<application>Qpid</application> messaging system for OpenStack
Oslo RPC. <application>Qpid</application> is not the default
messaging system, so you must enable it by setting the
<option>rpc_backend</option> option in the
<filename>nova.conf</filename> file.</para>
<programlisting language="ini">rpc_backend=nova.openstack.common.rpc.impl_qpid</programlisting>
<para>This next critical option points the compute nodes to the
<para>This critical option points the compute nodes to the
<application>Qpid</application> broker (server). Set
<literal>qpid_hostname</literal> in <filename>nova.conf</filename> to
be the hostname where the broker is running.</para>
<option>qpid_hostname</option> to the host name where the
broker runs in the <filename>nova.conf</filename> file.</para>
<note>
<para>The -<literal>-qpid_hostname</literal> option accepts a value in
the form of either a hostname or an IP address.</para>
<para>The <option>--qpid_hostname</option> option accepts a host
name or IP address value.</para>
</note>
<programlisting language="ini">qpid_hostname=hostname.example.com</programlisting>
<para>If the <application>Qpid</application> broker is listening on a
port other than the AMQP default of <literal>5672</literal>, you will
need to set the <literal>qpid_port</literal> option:</para>
<para>If the <application>Qpid</application> broker listens on a
port other than the AMQP default of <literal>5672</literal>, you
must set the <option>qpid_port</option> option to that
value:</para>
<programlisting language="ini">qpid_port=12345</programlisting>
<para>If you configure the <application>Qpid</application> broker to
require authentication, you will need to add a username and password to
the configuration:</para>
<para>If you configure the <application>Qpid</application> broker
to require authentication, you must add a user name and password
to the configuration:</para>
<programlisting language="ini">qpid_username=username
qpid_password=password</programlisting>
<para>By default, TCP is used as the transport. If you would like to
enable SSL, set the <literal>qpid_protocol</literal> option:</para>
<para>By default, TCP is used as the transport. To enable SSL, set
the <option>qpid_protocol</option> option:</para>
<programlisting language="ini">qpid_protocol=ssl</programlisting>
<para>The following table lists the rest of the options used by the Qpid
messaging driver for OpenStack Oslo RPC. It is not common that these
options are used.</para>
<para>This table lists additional options that you use to
configure the Qpid messaging driver for OpenStack Oslo RPC.
These options are used infrequently.</para>
<xi:include href="tables/nova-qpid.xml"/>
</section>
<section xml:id="configuration-zeromq">
<title>Configuration Options for ZeroMQ</title>
<para>This section discusses the configuration options that are relevant
if <application>ZeroMQ</application> is used as the messaging system for
OpenStack Oslo RPC. <application>ZeroMQ</application> is not the default
messaging system, so it must be enabled by setting the
<literal>rpc_backend</literal> option in
<filename>nova.conf</filename>.</para>
<title>Configure ZeroMQ</title>
<para>Use these options to configure the
<application>ZeroMQ</application> messaging system for
OpenStack Oslo RPC. <application>ZeroMQ</application> is not the
default messaging system, so you must enable it by setting the
<option>rpc_backend</option> option in the
<filename>nova.conf</filename> file.</para>
<xi:include href="tables/nova-zeromq.xml"/>
</section>
<section xml:id="common-messaging-configuration">
<title>Common Configuration for Messaging</title>
<para>This section lists options that are common between both the
<application>RabbitMQ</application> and <application>Qpid</application>
messaging drivers.</para>
<title>Configure messaging</title>
<para>Use these options to configure the
<application>RabbitMQ</application> and
<application>Qpid</application> messaging drivers.</para>
<xi:include href="tables/nova-rpc.xml"/>
</section>
</section>

235
doc/common/section_support-compute.xml
View File

@ -1,18 +1,26 @@
<?xml version="1.0" encoding="UTF-8"?>
<section xmlns="http://docbook.org/ns/docbook"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="section_compute-troubleshooting">
<title>Troubleshooting Compute</title>
<para>Common problems for Compute typically involve misconfigured networking or credentials that are not sourced properly in the environment. Also, most flat networking configurations do not enable ping or ssh from a compute node to the instances running on that node. Another common problem is trying to run 32-bit images on a 64-bit compute node. This section offers more information about how to troubleshoot Compute.</para>
<section xml:id="log-files-for-openstack-compute"><title>Log files for Compute</title>
xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
xml:id="section_compute-troubleshooting">
<title>Troubleshoot Compute</title>
<para>Common problems for Compute typically involve misconfigured
networking or credentials that are not sourced properly in the
environment. Also, most flat networking configurations do not
enable <command>ping</command> or <command>ssh</command> from
a compute node to the instances that run on that node. Another
common problem is trying to run 32-bit images on a 64-bit
compute node. This section shows you how to troubleshoot
Compute.</para>
<section xml:id="log-files-for-openstack-compute">
<title>Compute log files</title>
<para>Compute stores a log file for each service in
<filename>/var/log/nova</filename>. For example,
<filename>nova-compute.log</filename> is the log for the
<systemitem class="service">nova-compute</systemitem>
<filename>nova-compute.log</filename> is the log for
the <systemitem class="service">nova-compute</systemitem>
service. You can set the following options to format log
strings for the nova.log module in
<filename>nova.conf</filename>:
strings for the nova.log module in the
<filename>nova.conf</filename> file:</para>
<itemizedlist>
<listitem>
<para><literal>logging_context_format_string</literal></para>
@ -21,123 +29,152 @@
<para><literal>logging_default_format_string</literal></para>
</listitem>
</itemizedlist>
If the log level is set to <literal>debug</literal>, you can
also specify <literal>logging_debug_format_suffix</literal>
to append extra formatting. For information about what
variables are available for the formatter see:
<link xlink:href="http://docs.python.org/library/logging.html#formatter">http://docs.python.org/library/logging.html#formatter</link>.
</para>
<para>You have two options for logging for OpenStack Compute based on configuration
settings. In <filename>nova.conf</filename>, include the
<literal>logfile</literal> option to enable logging. Alternatively
you can set <literal>use_syslog=1</literal>, and then the nova
daemon logs to syslog.</para>
<para>If the log level is set to <literal>debug</literal>, you
can also specify
<literal>logging_debug_format_suffix</literal> to
append extra formatting. For information about what
variables are available for the formatter see: <link
xlink:href="http://docs.python.org/library/logging.html#formatter"
>http://docs.python.org/library/logging.html#formatter</link>.</para>
<para>You have two options for logging for OpenStack Compute
based on configuration settings. In
<filename>nova.conf</filename>, include the
<literal>logfile</literal> option to enable logging.
Alternatively you can set <literal>use_syslog=1</literal>
so that the nova daemon logs to syslog.</para>
</section>
<section xml:id="section_compute-common-errors-and-fixes">
<title>Common errors and fixes for Compute</title>
<para>The ask.openstack.org site offers a place to ask and
answer questions, and you can also mark questions as
<para>The <link xlink:href="ask.openstack.org"
>ask.openstack.org</link> site offers a place to ask
and answer questions, and you can also mark questions as
frequently asked questions. This section describes some
errors people have posted previously. We
are constantly fixing bugs, so online resources are a
great way to get the most up-to-date errors and
fixes.</para>
errors people have posted previously. Bugs are constantly
being fixed, so online resources are a great way to get
the most up-to-date errors and fixes.</para>
<section xml:id="section_credential-errors">
<title>Credential errors, 401, 403 forbidden errors</title>
<para>A 403 forbidden error is caused by missing credentials.
Through current installation methods, there are basically
two ways to get the <filename>novarc</filename> file. The manual method
requires getting it from within a project zipfile, and the
scripted method just generates <filename>novarc</filename> out of the project
zip file and sources it for you. If you use the manual
method through a zip file, before sourcing <filename>novarc</filename>
be sure to save any credentials that were created previously, as they
can be overridden.
</para>
<para>When you run <systemitem class="service">nova-api</systemitem> the
first time, it generates the certificate authority information,
including <filename>openssl.cnf</filename>. If the CA components are
started prior to this, you may not be able to create your zip file.
Restart the services, then once your CA information is available,
you should be able to create your zip file.</para>
<para>You may also need to check your http proxy settings to see if
they are causing problems with the <filename>novarc</filename>
<title>Credential errors, 401, and 403 forbidden
errors</title>
<para>Missing credentials cause a
<errorcode>403</errorcode>
<errortext>forbidden</errortext> error. To resolve
this issue, use one of these methods:<orderedlist>
<listitem>
<para><emphasis role="bold">Manual
method</emphasis>. Get get the
<filename>novarc</filename> file from
the project ZIP file, save existing
credentials in case of override. and
manually source the
<filename>novarc</filename>
file.</para>
</listitem>
<listitem>
<para><emphasis role="bold">Script
method</emphasis>. Generates
<filename>novarc</filename> from the
project ZIP file and sources it for
you.</para>
</listitem>
</orderedlist></para>
<para>When you run <systemitem class="service"
>nova-api</systemitem> the first time, it
generates the certificate authority information,
including <filename>openssl.cnf</filename>. If you
start the CA services before this, you might not be
able to create your ZIP file. Restart the services.
When your CA information is available, create your ZIP
file.</para>
<para>Also, check your HTTP proxy settings to see whether
they cause problems with <filename>novarc</filename>
creation.</para>
</section>
<section xml:id="section_instance-errors">
<title>Instance errors</title>
<para>Sometimes a particular instance shows "pending" or you
cannot SSH to it. Sometimes the image itself is the
problem. For example, when using flat manager networking,
you do not have a dhcp server, and certain images
don't support interface injection so you cannot connect
to them. The fix for this type of problem is to use an
image that does support this method, such as Ubuntu,
which should obtain an IP address correctly
with FlatManager network settings. To troubleshoot other
possible problems with an instance, such as one that stays
in a spawning state, first check the directory for the particular
instance under <filename>/var/lib/nova/instances</filename>
on the <systemitem class="service">nova-compute</systemitem>
host and make sure it has the following files:</para>
<para>Sometimes a particular instance shows
<literal>pending</literal> or you cannot SSH to
it. Sometimes the image itself is the problem. For
example, when you use flat manager networking, you do
not have a DHCP server and certain images do not
support interface injection; you cannot connect to
them. The fix for this problem is to use an image that
does support this method, such as Ubuntu, which
obtains an IP address correctly with FlatManager
network settings.</para>
<para>To troubleshoot other possible problems with an
instance, such as an instance that stays in a spawning
state, check the directory for the particular instance
under <filename>/var/lib/nova/instances</filename> on
the <systemitem class="service"
>nova-compute</systemitem> host and make sure that
these files are present:</para>
<itemizedlist>
<listitem>
<para>libvirt.xml</para>
<para><filename>libvirt.xml</filename></para>
</listitem>
<listitem>
<para>disk</para>
<para><filename>disk</filename></para>
</listitem>
<listitem>
<para>disk-raw</para>
<para><filename>disk-raw</filename></para>
</listitem>
<listitem>
<para>kernel</para>
<para><filename>kernel</filename></para>
</listitem>
<listitem>
<para>ramdisk</para>
<para><filename>ramdisk</filename></para>
</listitem>
<listitem>
<para>console.log (Once the instance actually starts you should
see a <filename>console.log</filename>.)</para>
<para>After the instance starts,
<filename>console.log</filename></para>
</listitem>
</itemizedlist>
<para>Check the file sizes to see if they are reasonable. If
any are missing/zero/very small then <systemitem class="service">nova-compute</systemitem> has
somehow not completed download of the images from
the Image service.</para>
<para>Also check <filename>nova-compute.log</filename> for exceptions.
Sometimes they don't show up in the console output.</para>
<para>Next, check the log file for the instance in the directory
<para>If any files are missing, empty, or very small, the
<systemitem class="service"
>nova-compute</systemitem> service did not
successfully download the images from the Image
Service.</para>
<para>Also check <filename>nova-compute.log</filename> for
exceptions. Sometimes they do not appear in the
console output.</para>
<para>Next, check the log file for the instance in the
<filename>/var/log/libvirt/qemu</filename>
to see if it exists and has any useful error messages
in it.</para>
<para>Finally, from the directory for the instance under
<filename>/var/lib/nova/instances</filename>, try
<screen><prompt>#</prompt> <userinput>virsh create libvirt.xml</userinput></screen> and see if you
get an error when running this.</para>
directory to see if it exists and has any useful error
messages in it.</para>
<para>Finally, from the
<filename>/var/lib/nova/instances</filename>
directory for the instance, see if this command
returns an error:</para>
<screen><prompt>#</prompt> <userinput>virsh create libvirt.xml</userinput></screen>
</section>
</section>
<section xml:id="reset-state">
<title>Manually reset the state of an instance</title>
<para>If an instance gets stuck in an intermediate state (e.g., "deleting"), you can
manually reset the state of an instance using the <command>nova
reset-state</command> command. This will reset it to an error state, which you
can then delete. For
example:<screen><prompt>$</prompt> <userinput>nova reset-state c6bbbf26-b40a-47e7-8d5c-eb17bf65c485</userinput>
<prompt>$</prompt> <userinput>nova delete c6bbbf26-b40a-47e7-8d5c-eb17bf65c485</userinput></screen></para>
<para>You can also use the <literal>--active</literal> to
force the instance back into an active state instead of an
error state, for
example:<screen><prompt>$</prompt> <userinput>nova reset-state --active c6bbbf26-b40a-47e7-8d5c-eb17bf65c485</userinput> </screen></para>
<title>Reset the state of an instance</title>
<para>If an instance remains in an intermediate state, such as
<literal>deleting</literal>, you can use the
<command>nova reset-state</command> command to
manually reset the state of an instance to an error state.
You can then delete the instance. For example:</para>
<screen><prompt>$</prompt> <userinput>nova reset-state c6bbbf26-b40a-47e7-8d5c-eb17bf65c485</userinput>
<prompt>$</prompt> <userinput>nova delete c6bbbf26-b40a-47e7-8d5c-eb17bf65c485</userinput></screen>
<para>You can also use the <parameter>--active</parameter>
parameter to force the instance back to an active state
instead of an error state. For example:</para>
<screen><prompt>$</prompt> <userinput>nova reset-state --active c6bbbf26-b40a-47e7-8d5c-eb17bf65c485</userinput></screen>
</section>
<section xml:id="problems-with-injection">
<title>Problems with injection</title>
<para>If you are diagnosing problems with instances not booting,
or booting slowly, consider investigating file injection as a
cause. Setting <literal>libvirt_inject_partition</literal>
to -2 disables injection in libvirt. This can be required if you want to make user
specified files available from the metadata server (and config drive is not enabled),
for performance reasons, and also to avoid boot failure if injection itself fails.</para>
</section>
<title>Injection problems</title>
<para>If instances do not boot or boot slowly, investigate
file injection as a cause.</para>
<para>To disable injection in libvirt, set
<option>libvirt_inject_partition</option> to
<literal>-2</literal>.</para>
<note>
<para>If you have not enabled the configuration drive and
you want to make user-specified files available from
the metadata server for to improve performance and
avoid boot failure if injection fails, you must
disable injection.</para>
</note>
</section>
</section>

165
doc/common/section_support-object-storage.xml
View File

@ -1,52 +1,92 @@
<?xml version="1.0" encoding="UTF-8"?>
<chapter xmlns="http://docbook.org/ns/docbook"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="troubleshooting-openstack-object-storage">
<title>Troubleshooting OpenStack Object Storage</title>
<para>For OpenStack Object Storage, everything is logged in /var/log/syslog (or messages on some distros). Several settings enable further customization of logging, such as log_name, log_facility, and log_level, within the object server configuration files.</para>
xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
xml:id="troubleshooting-openstack-object-storage">
<title>Troubleshoot Object Storage</title>
<para>For OpenStack Object Storage, everything is logged in
<filename>/var/log/syslog</filename> (or messages on some
distros). Several settings enable further customization of
logging, such as <option>log_name</option>,
<option>log_facility</option>, and
<option>log_level</option>, within the object server
configuration files.</para>
<section xml:id="handling-drive-failure">
<title>Handling Drive Failure</title>
<para>In the event that a drive has failed, the first step is to make sure the drive is unmounted. This will make it easier for OpenStack Object Storage to work around the failure until it has been resolved. If the drive is going to be replaced immediately, then it is just best to replace the drive, format it, remount it, and let replication fill it up.</para>
<para>If the drive can’t be replaced immediately, then it is best to leave it unmounted, and remove the drive from the ring. This will allow all the replicas that were on that drive to be replicated elsewhere until the drive is replaced. Once the drive is replaced, it can be re-added to the ring.</para>
<para>Rackspace has seen hints at drive failures by looking at error messages in /var/log/kern.log -
do consider checking this in your monitoring</para>
<title>Recover drive failures</title>
<para>If a drive fails, make sure the
drive is unmounted to make it easier for Object
Storage to work around the failure while you resolve
it. If you plan to replace the drive immediately, replace
the drive, format it, remount it, and let replication fill
it.</para>
<para>If you cannot replace the drive immediately, leave it
unmounted and remove the drive from the ring. This enables
you to replicate all the replicas on that drive elsewhere
until you can replace the drive. After you replace the
drive, you can add it to the ring again.</para>
<note>
<para>Rackspace has seen hints at drive failures by
looking at error messages in
<filename>/var/log/kern.log</filename>. Check this
file in your monitoring.</para>
</note>
</section>
<section xml:id="handling-server-failure">
<title>Handling Server Failure</title>
<para>If a server is having hardware issues, it is a good idea to make sure the OpenStack Object Storage services are not running. This will allow OpenStack Object Storage to work around the failure while you troubleshoot.</para>
<para>If the server just needs a reboot, or a small amount of work that should only last a couple of hours, then it is probably best to let OpenStack Object Storage work around the failure and get the machine fixed and back online. When the machine comes back online, replication will make sure that anything that is missing during the downtime will get updated.</para>
<para>If the server has more serious issues, then it is probably best to remove all of the server’s devices from the ring. Once the server has been repaired and is back online, the server’s devices can be added back into the ring. It is important that the devices are reformatted before putting them back into the ring as it is likely to be responsible for a different set of partitions than before.</para>
</section>
<title>Recover server failures</title>
<para>If a server has hardware issues, make sure that the
Object Storage services are not running. This enables
Object Storage to work around the failure while you
troubleshoot.</para>
<para>If the server needs a reboot or a minimal amount of
work, let Object Storage work around the failure while you
fix the machine and get it back online. When the machine
comes back online, replication updates anything that was
missing during the downtime.</para>
<para>If the server has more serious issues,remove all server
devices from the ring. After you repair and put the server
online, you can add the devices for the server back to the
ring. You must reformat the devices before you add them to
the ring because they might be responsible for a different
set of partitions than before.</para>
</section>
<section xml:id="detecting-failed-drives">
<title>Detecting Failed Drives</title>
<para>It has been our experience that when a drive is about to fail, error messages will spew into /var/log/kern.log. There is a script called swift-drive-audit that can be run via cron to watch for bad drives. If errors are detected, it will unmount the bad drive, so that OpenStack Object Storage can work around it. The script takes a configuration file with the following settings:
</para>
<title>Detect failed drives</title>
<para>When a drive is about to fail, many error messages
appear in the <filename>/var/log/kern.log</filename> file.
You can run the <package>swift-drive-audit</package>
script through <command>cron</command> to watch for bad
drives. If errors are detected, it unmounts the bad drive
so that Object Storage can work around it. The script uses
a configuration file with these settings:</para>
<xi:include href="tables/swift-drive-audit-drive-audit.xml"/>
<para>This script has only been tested on Ubuntu 10.04, so if you are using a different distro or OS, some care should be taken before using in production.
</para></section>
<para>This script has been tested on only Ubuntu 10.04. If you
use a different distribution or operating system, take
care before using the script in production.</para>
</section>
<section xml:id="recover-ring-builder-file">
<title>Emergency Recovery of Ring Builder Files</title>
<para>You should always keep a backup of Swift ring builder files.
However, if an emergency occurs, this procedure may assist in returning
your cluster to an operational state.</para>
<para>Using existing Swift tools, there is no way to recover a builder
file from a ring.gz file. However, if you have a knowledge of Python,
it is possible to construct a builder file that is pretty close to
the one you have lost. The following is what you will need to do.</para>
<warning><title>Warning</title>
<para>This procedure is a last-resort for emergency circumstances - it
requires knowledge of the swift python code and may not succeed.</para></warning>
<para>First, load the ring and a new ringbuilder object in a Python REPL:</para>
<title>Recover ring builder files (emergency)</title>
<para>You should always keep a backup of Swift ring builder
files. However, if an emergency occurs, use this procedure
to return your cluster to an operational state.</para>
<para>Existing Swift tools do not enable you to recover a
builder file from a <filename>ring.gz</filename> file.
However, if you have Python knowledge, you can construct a
builder file similar to the one you have lost.</para>
<warning>
<para>This procedure is a last-resort in an emergency. It
requires knowledge of the swift Python code and might
not succeed.</para>
</warning>
<procedure>
<step>
<para>Load the ring and a new ringbuilder object in a
Python REPL:</para>
<programlisting language="python">>>> from swift.common.ring import RingData, RingBuilder
>>> ring = RingData.load('/path/to/account.ring.gz')</programlisting>
<para>Now, start copying the data we have in the ring into the builder.</para>
</step>
<step>
<para>Copy the data in the ring into the
builder.</para>
<programlisting language="python">>>> import math
>>> partitions = len(ring._replica2part2dev_id[0])
>>> replicas = len(ring._replica2part2dev_id)
@ -62,26 +102,43 @@
>>> for p2d in builder._replica2part2dev:
for dev_id in p2d:
builder.devs[dev_id]['parts'] += 1</programlisting>
<para>This is the extent of the recoverable fields. For
<literal>min_part_hours</literal> you'll either have to remember
what the value you used was, or just make up a new one.</para>
<para>This is the extent of the recoverable
fields.</para>
</step>
<step>
<para>For <option>min_part_hours</option>, you must
remember the value that you used previously or
create a new value.</para>
<programlisting language="python">>>> builder.change_min_part_hours(24) # or whatever you want it to be</programlisting>
<para>Try some validation: if this doesn't raise an exception, you may
feel some hope. Not too much, though.</para>
<para>If validation succeeds without raising an
exception, you have succeeded.</para>
<programlisting language="python">>>> builder.validate()</programlisting>
</step>
<step>
<para>Save the builder.</para>
<programlisting language="python">>>> import pickle
>>> pickle.dump(builder.to_dict(), open('account.builder', 'wb'), protocol=2)</programlisting>
<para>You should now have a file called 'account.builder' in the current
working directory.
Next, run <literal>swift-ring-builder account.builder write_ring</literal>
and compare the new account.ring.gz to the account.ring.gz that you started
from. They probably won't be byte-for-byte identical, but if you load them
up in a REPL and their <literal>_replica2part2dev_id</literal> and
<literal>devs</literal> attributes are the same (or nearly so), then you're
in good shape.</para>
<para>Next, repeat the procedure for <literal>container.ring.gz</literal>
and <literal>object.ring.gz</literal>, and you might get usable builder
files.</para>
<para>The <filename>account.builder</filename> file
appears in the current working directory.</para>
</step>
<step>
<para>Run <literal>swift-ring-builder account.builder
write_ring</literal>.</para>
<para>Compare the new
<filename>account.ring.gz</filename> to the
original <filename>account.ring.gz</filename>
file. They might not be byte-for-byte identical,
but if you load them in REPL and their
<option>_replica2part2dev_id</option> and
<option>devs</option> attributes are the same
(or nearly so), you have succeeded.</para>
</step>
<step>
<para>Repeat this procedure for the
<filename>container.ring.gz</filename> and
<filename>object.ring.gz</filename> files, and
you might get usable builder files.</para>
</step>
</procedure>
</section>
</chapter>

67
doc/common/section_tenant-specific-image-storage.xml
View File

@ -3,33 +3,50 @@
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
xml:id="configuring-tenant-specific-storage-for-images">
<title>Configuring Tenant-specific Storage Locations for Images
with Object Storage</title>
<para>For some deployers, storing all images in a single place for
all tenants and users to access is not ideal. To enable access
control to specific images for cloud users, you can configure
the Image service with the ability to store image data in the
image owner-specific locations.</para>
<para>The relevant configuration options in the
<filename>glance-api.conf</filename> file are:</para>
<itemizedlist>
<title>Configure tenant-specific image locations with Object
Storage</title>
<para>For some deployers, it is not ideal to store all images in
one place to enable all tenants and users to access them. You
can configure the Image Service to store image data in
tenant-specific image locations. Then, only the following
tenants can use the Image Service to access the created image:<itemizedlist>
<listitem>
<para><literal>swift_store_multi_tenant</literal>: set to
<literal>True</literal> to enable tenant-specific storage locations (Default
value is <literal>False</literal>).</para>
<para>The tenant who owns the image</para>
</listitem>
<listitem>
<para><literal>swift_store_admin_tenants</literal>: Specify a list of tenants
by ID to which to grant read and write access to all Object Storage
containers created by the Image service.</para>
<para>Tenants that are defined in
<option>swift_store_admin_tenants</option> and
that have admin-level accounts</para>
</listitem>
</itemizedlist>
<para>Assuming you configured 'swift' as your default_store in
<filename>glance-api.conf</filename> and you enable this
feature as described above, images will be stored in an Object
Storage service (swift) endpoint pulled from the authenticated
user's service_catalog. The created image data will only be
accessible through the Image service by the tenant that owns
it and any tenants defined in swift_store_admin_tenants that
are identified as having admin-level accounts.</para>
</itemizedlist></para>
<procedure>
<title>To configure tenant-specific image locations</title>
<step>
<para>Configure swift as your
<option>default_store</option> in the
<filename>glance-api.conf</filename> file.</para>
</step>
<step>
<para>Set these configuration options in the
<filename>glance-api.conf</filename> file: <itemizedlist>
<listitem>
<para><option>swift_store_multi_tenant</option>.
Set to <literal>True</literal> to enable
tenant-specific storage locations. Default
is <literal>False</literal>.</para>
</listitem>
<listitem>
<para><option>swift_store_admin_tenants</option>.
Specify a list of tenant IDs that can
grant read and write access to all Object
Storage containers that are created by the
Image Service.</para>
</listitem>
</itemizedlist></para>
</step>
</procedure>
<para>With this configuration, images are stored in an
Object Storage service (swift) endpoint that is pulled
from the service catalog for the authenticated
user.</para>
</section>

170
doc/common/section_trusted-compute-pools.xml
View File

@ -1,98 +1,120 @@
<?xml version="1.0" encoding="UTF-8"?>
<section
xmlns="http://docbook.org/ns/docbook"
<section xmlns="http://docbook.org/ns/docbook"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink"
version="5.0"
xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
xml:id="trusted-compute-pools">
<title>Trusted Compute Pools</title>
<simplesect>
<title>Overview</title>
<para>Trusted compute pools enable administrators to designate a group of compute hosts as
"trusted". These hosts use hardware-based security features, such as Intel's Trusted
Execution Technology (TXT), to provide an additional level of security. Combined with an
external standalone web-based remote attestation server, cloud providers can ensure that
the compute node is running software with verified measurements, thus they can establish
the foundation for the secure cloud stack. Through the Trusted Computing Pools, cloud
subscribers can request services to be run on verified compute nodes.</para>
<para>The remote attestation server performs node verification through the following steps:<orderedlist>
<title>Trusted compute pools</title>
<para>Trusted compute pools enable administrators to designate a
group of compute hosts as <firstterm>trusted</firstterm>. These hosts use hardware-based
security features, such as the Intel Trusted Execution
Technology (TXT), to provide an additional level of security.
Combined with an external stand-alone web-based remote
attestation server, cloud providers can ensure that the
compute node runs only software with verified measurements and
can ensure a secure cloud stack.</para>
<para>Through the trusted compute pools, cloud subscribers can
request services to run on verified compute nodes.</para>
<para>The remote attestation server performs node verification as
follows:</para>
<orderedlist>
<listitem>
<para>Compute nodes boot with Intel TXT technology enabled.</para>
<para>Compute nodes boot with Intel TXT technology
enabled.</para>
</listitem>
<listitem>
<para>The compute node's BIOS, hypervisor and OS are measured.</para>
<para>The compute node BIOS, hypervisor, and OS are
measured.</para>
</listitem>
<listitem>
<para>These measured data is sent to the attestation server when challenged by
attestation server.</para>
<para>Measured data is sent to the attestation server when
challenged by attestation server.</para>
</listitem>
<listitem>
<para>The attestation server verifies those measurements against good/known
database to determine nodes' trustworthiness.</para>
<para>The attestation server verifies those measurements
against a good and known database to determine nodes'
trustworthiness.</para>
</listitem>
</orderedlist></para>
<para>A description of how to set up an attestation service is beyond the scope of this
document. See the <link xlink:href="https://github.com/OpenAttestation/OpenAttestation"
>Open Attestation</link> project for an open source project that can be used to
implement an attestation service.</para>
<para>
</orderedlist>
<para>A description of how to set up an attestation service is
beyond the scope of this document. For an open source project
that you can use to implement an attestation service, see the
<link
xlink:href="https://github.com/OpenAttestation/OpenAttestation"
>Open Attestation</link> project.</para>
<mediaobject>
<imageobject role="fo">
<imagedata fileref="figures/OpenStackTrustedComputePool1.png"
<imagedata
fileref="figures/OpenStackTrustedComputePool1.png"
format="PNG" contentwidth="6in"/>
</imageobject>
<imageobject role="html">
<imagedata fileref="figures/OpenStackTrustedComputePool1.png"
format="PNG"/>
<imagedata
fileref="figures/OpenStackTrustedComputePool1.png"
format="PNG" contentwidth="6in"/>
</imageobject>
</mediaobject>
</para>
</simplesect>
<simplesect>
<title>Configuring the Compute service to use Trusted Compute Pools</title>
<para>The Compute service must be configured to with the connection information for the attestation
service. The connection information is specified in the
<literal>trusted_computing</literal> section of nova.conf. Specify the following
parameters in this section.<variablelist>
<section xml:id="configure_trusted_compute_pools">
<title>Configure Compute to use trusted compute pools</title>
<procedure>
<step>
<para>Configure the Compute service with the
connection information for the attestation
service.</para>
<para>Specify these connection options in the
<literal>trusted_computing</literal> section
in the <filename>nova.conf</filename>
configuration file:</para>
<variablelist>
<varlistentry>
<term>server</term>
<listitem>
<para>Hostname or IP address of the host that runs the attestation
<para>Host name or IP address of the host
that runs the attestation
service</para>
</listitem>
</varlistentry>
<varlistentry>
<term>port</term>
<listitem>
<para>HTTPS port for the attestation service</para>
<para>HTTPS port for the attestation
service</para>
</listitem>
</varlistentry>
<varlistentry>
<term>server_ca_file</term>
<listitem>
<para>Certificate file used to verify the attestation server's
identity.</para>
<para>Certificate file used to verify the
attestation server's identity.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>api_url</term>
<listitem>
<para>The attestation service URL path.</para>
<para>The attestation service URL
path.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>auth_blob</term>
<listitem>
<para>An authentication blob, which is required by the attestation
<para>An authentication blob, which is
required by the attestation
service.</para>
</listitem>
</varlistentry>
</variablelist>Add the following lines to <filename>/etc/nova/nova.conf</filename> in
the <literal>DEFAULT</literal> and <literal>trusted_computing</literal> sections to
enable scheduling support for Trusted Compute Pools, and edit the details of the
<literal>trusted_computing</literal> section based on the details of your
attestation
service.<programlisting language="ini">[DEFAULT]
</variablelist>
</step>
<step>
<para>To enable scheduling support for trusted compute
pools, add the following lines to the
<literal>DEFAULT</literal> and
<literal>trusted_computing</literal> sections
in the <filename>/etc/nova/nova.conf</filename>
file. Edit the details in the
<literal>trusted_computing</literal> section
based on the details of your attestation
service:</para>
<programlisting language="ini">[DEFAULT]
compute_scheduler_driver=nova.scheduler.filter_scheduler.FilterScheduler
scheduler_available_filters=nova.scheduler.filters.all_filters
scheduler_default_filters=AvailabilityZoneFilter,RamFilter,ComputeFilter,TrustedFilter
@ -105,30 +127,44 @@ server_ca_file=/etc/nova/ssl.10.1.71.206.crt
api_url=/AttestationService/resources
# If using OAT pre-v1.5, use this api_url:
#api_url=/OpenAttestationWebServices/V1.0
auth_blob=i-am-openstack</programlisting></para>
<para>Restart the <systemitem class="service">nova-compute</systemitem> and <systemitem class="service">nova-scheduler</systemitem> services after making these changes.</para>
auth_blob=i-am-openstack</programlisting>
</step>
<step>
<para>Restart the <systemitem class="service"
>nova-compute</systemitem> and <systemitem
class="service">nova-scheduler</systemitem>
services.</para>
</step>
</procedure>
<section xml:id="config_ref">
<title>Configuration reference</title>
<xi:include href="tables/nova-trustedcomputing.xml"/>
</simplesect>
<simplesect>
</section>
</section>
<section xml:id="trusted_flavors">
<title>Specify trusted flavors</title>
<para>One or more flavors must be configured as "trusted". Users can then request trusted
nodes by specifying one of these trusted flavors when booting a new instance. Use the
<command>nova flavor-key set</command> command to set a flavor as
trusted. For example, to set the m1.tiny flavor as trusted:</para>
<para>
<para>You must configure one or more flavors as
<firstterm>trusted</firstterm>. Users can request
trusted nodes by specifying a trusted flavor when they
boot an instance.</para>
<para>Use the <command>nova flavor-key set</command> command
to set a flavor as trusted. For example, to set the
<literal>m1.tiny</literal> flavor as trusted:</para>
<screen><prompt>#</prompt> <userinput>nova flavor-key m1.tiny set trust:trusted_host trusted</userinput></screen>
</para>
<para>A user can request that their instance runs on a trusted host by specifying a trusted
flavor when invoking the <command>nova boot</command> command.</para>
<para>
<para>To request that their instances run on a trusted host,
users can specify a trusted flavor on the <command>nova
boot</command> command:</para>
<mediaobject>
<imageobject role="fo">
<imagedata fileref="figures/OpenStackTrustedComputePool2.png" format="PNG" contentwidth="6in"/>
<imagedata
fileref="figures/OpenStackTrustedComputePool2.png"
format="PNG" contentwidth="6in"/>
</imageobject>
<imageobject role="html">
<imagedata fileref="figures/OpenStackTrustedComputePool2.png" format="PNG"/>
<imagedata
fileref="figures/OpenStackTrustedComputePool2.png"
format="PNG" contentwidth="6in"/>
</imageobject>
</mediaobject>
</para>
</simplesect>
</section>
</section>

40
doc/common/section_using-vnc-console.xml
View File

@ -3,14 +3,12 @@
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
xml:id="using-vnc-console">
<title>Using VNC Console</title>
<para>There are several methods to interact with the VNC console,
using a VNC client directly, a special java client, or through the
web browser. For information about configuring the console,
see <xref linkend="installing-openstack-dashboard"/>.
</para>
<section xmlns="http://docbook.org/ns/docbook"
<title>Use the VNC console</title>
<para>To interact through the VNC console, you can use a VNC client
directly, a special Java client, or a web browser. For information
about how to configure the console, see <xref
linkend="installing-openstack-dashboard"/>.</para>
<section xmlns="http://docbook.org/ns/docbook"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
xml:id="getting-an-access-url">
@ -19,20 +17,18 @@
os-consoles extension. Support for accessing this URL is
provided by the nova client:</para>
<screen><prompt>$</prompt> <userinput>nova get-vnc-console <replaceable>[server_id]</replaceable> <replaceable>[novnc|xvpvnc]</replaceable></userinput></screen>
<para>Specify '<literal>novnc</literal>' to get a URL suitable
for pasting into a web browser.</para>
<para>Specify '<literal>novnc</literal>' to get a URL suitable for
pasting into a web browser.</para>
<para>Specify '<literal>xvpvnc</literal>' for a URL suitable for
pasting into the Java client.</para>
<para>To request a web browser URL:</para>
<screen><prompt>$</prompt> <userinput>nova get-vnc-console <replaceable>[server_id]</replaceable> novnc</userinput></screen>
</section>
<section xml:id="accessing-vnc-consoles-with-a-java-client">
<info>
<title>Access VNC consoles with a Java client</title>
</info>
<title>Access a VNC console with a Java client</title>
<para>To enable support for the OpenStack Java VNC client in
compute, run the <literal>nova-xvpvncproxy</literal> service.</para>
compute, run the <literal>nova-xvpvncproxy</literal>
service.</para>
<itemizedlist>
<listitem>
<para><literal>xvpvncproxy_port</literal>=<replaceable>[port]</replaceable>
@ -50,8 +46,8 @@
<prompt>$</prompt> <userinput>cd nova-xvpvncviewer/viewer</userinput>
<prompt>$</prompt> <userinput>make</userinput></screen>
<para>To create a session, request an access URL by using
<command>python-novaclient</command>. Then, run the client
as follows.</para>
<command>python-novaclient</command>. Then, run the client as
follows.</para>
<para>To get an access URL:</para>
<screen><prompt>$</prompt> <userinput>nova get-vnc-console <replaceable>[server_id]</replaceable> xvpvnc</userinput></screen>
<para>To run the client:</para>
@ -60,17 +56,17 @@
<section xml:id="accessing-a-vnc-console-through-a-web-browser">
<info>
<title>Access a VNC console through a web browser</title>
<title>Access a VNC console with a web browser</title>
</info>
<para>Retrieving an access_url for a web browser is similar to
the flow for the Java client.</para>
<para>Retrieving an access_url for a web browser is similar to the
flow for the Java client.</para>
<para>To get the access URL, run the following command:</para>
<screen><prompt>$</prompt> <userinput>nova get-vnc-console <replaceable>[server_id]</replaceable> novnc</userinput></screen>
<para>Paste the URL into your web browser.</para>
<para>Additionally, you can use the OpenStack dashboard, known
as horizon, to access browser-based VNC consoles for
<para>Additionally, you can use the OpenStack dashboard, known as
horizon, to access browser-based VNC consoles for
instances.</para>
</section>
</section>

35
doc/common/section_xapi-ami-setup.xml
View File

@ -3,26 +3,21 @@
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
xml:id="xapi-ami-setup">
<?dbhtml stop-chunking?>
<title>Prepare for AMI Type Images</title>
<para>In order to support AMI type images within your OpenStack
installation, a directory <literal>/boot/guest</literal> needs to be
created inside Dom0. The OpenStack VM will put the kernel and ramdisk
extracted from the AKI and ARI images to this location.</para>
<para>This directory's content will be maintained by OpenStack, and its
size should not increase during normal operation. However, in case of power
failures or accidental shutdowns, some files might be left over. In order
to prevent these files from filling up Dom0's disk, it is recommended to set up
this directory as a symlink pointing to a subdirectory of the local SR.
</para>
<para>Execute the following commands in Dom0 to achieve the above mentioned
setup:
<screen><prompt>#</prompt> <userinput>LOCAL_SR=$(xe sr-list name-label="Local storage" --minimal)</userinput>
<?dbhtml stop-chunking?>
<title>Prepare for AMI type images</title>
<para>To support AMI type images in your OpenStack installation,
you must create a <filename>/boot/guest</filename> directory
inside Dom0. The OpenStack VM extracts the kernel and ramdisk
from the AKI and ARI images puts them in this location.</para>
<para>OpenStack maintains the contents of this directory and its
size should not increase during normal operation. However, in
case of power failures or accidental shutdowns, some files
might be left over. To prevent these files from filling the
Dom0 disk, set up this directory as a symlink that points to a
subdirectory of the local SR.</para>
<para>Run these commands in Dom0 to achieve this setup:</para>
<screen><prompt>#</prompt> <userinput>LOCAL_SR=$(xe sr-list name-label="Local storage" --minimal)</userinput>
<prompt>#</prompt> <userinput>LOCALPATH="/var/run/sr-mount/$LOCAL_SR/os-guest-kernels"</userinput>
<prompt>#</prompt> <userinput>mkdir -p "$LOCALPATH"</userinput>
<prompt>#</prompt> <userinput>ln -s "$LOCALPATH" /boot/guest</userinput>
</screen>
</para>
<prompt>#</prompt> <userinput>ln -s "$LOCALPATH" /boot/guest</userinput></screen>
</section>

116
doc/common/section_xapi-install-plugins.xml
View File

@ -3,66 +3,73 @@
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
xml:id="xapi-install-plugins">
<?dbhtml stop-chunking?>
<title>Installing the XenAPI Plugins</title>
<para>When using Xen as the hypervisor for OpenStack Compute, you
can install a Python script (usually, but it can be any
executable) on the host side, and then call that through the
XenAPI. These scripts are called plugins. The XenAPI plugins
live in the nova code repository. These plugins have to be
copied to the hypervisor's Dom0, to the appropriate directory,
where xapi can find them. There are several options for the
installation. The important thing is to ensure that the
version of the plugins are in line with the nova installation
by only installing plugins from a matching nova
repository.</para>
<section xml:id="manual_install"> <title>Manual Installation</title>
<procedure><title>To manually install</title>
<step><para>Create temporary files/directories:
<?dbhtml stop-chunking?>
<title>Install the XenAPI plug-ins</title>
<para>When you use Xen as the hypervisor for OpenStack Compute,
you can install a Python script (or any executable) on the
host side, and call that through the XenAPI. These scripts are
called plug-ins. The XenAPI plug-ins live in the nova code
repository. These plug-ins have to be copied to the Dom0 for
the hypervisor, to the appropriate directory, where xapi can
find them. There are several options for the installation. The
important thing is to ensure that the version of the plug-ins
are in line with the nova installation by only installing
plug-ins from a matching nova repository.</para>
<section xml:id="manual_install">
<title>Manually install the plug-in</title>
<procedure>
<step>
<para>Create temporary files/directories:</para>
<screen><prompt>$</prompt> <userinput>NOVA_ZIPBALL=$(mktemp)</userinput>
<prompt>$</prompt> <userinput>NOVA_SOURCES=$(mktemp -d)</userinput></screen></para></step>
<step><para>Get the source from github. The example assumes the master
branch is used. Amend the URL to match the version
being used:
<prompt>$</prompt> <userinput>NOVA_SOURCES=$(mktemp -d)</userinput></screen>
</step>
<step>
<para>Get the source from github. The example assumes
the master branch is used. Amend the URL to match
the version being used:</para>
<screen><prompt>$</prompt> <userinput>wget -qO "$NOVA_ZIPBALL" https://github.com/openstack/nova/archive/master.zip</userinput>
<prompt>$</prompt> <userinput>unzip "$NOVA_ZIPBALL" -d "$NOVA_SOURCES"</userinput></screen>(Alternatively)
Should you wish to use the official Ubuntu
<prompt>$</prompt> <userinput>unzip "$NOVA_ZIPBALL" -d "$NOVA_SOURCES"</userinput></screen>
<para>(Alternatively) To use the official Ubuntu
packages, use the following commands to get the
nova code base:
nova code base:</para>
<screen><prompt>$</prompt> <userinput>( cd $NOVA_SOURCES &amp;&amp; apt-get source python-nova --download-only )</userinput>
<prompt>$</prompt> <userinput>( cd $NOVA_SOURCES &amp;&amp; for ARCHIVE in *.tar.gz; do tar -xzf $ARCHIVE; done )</userinput></screen></para></step>
<step><para>Copy the plugins to the hypervisor:
<prompt>$</prompt> <userinput>( cd $NOVA_SOURCES &amp;&amp; for ARCHIVE in *.tar.gz; do tar -xzf $ARCHIVE; done )</userinput></screen>
</step>
<step>
<para>Copy the plug-ins to the hypervisor:</para>
<screen><prompt>$</prompt> <userinput>PLUGINPATH=$(find $NOVA_SOURCES -path '*/xapi.d/plugins' -type d -print)</userinput>
<prompt>$</prompt> <userinput>tar -czf - -C "$PLUGINPATH" ./ | ssh root@xenserver tar -xozf - -C /etc/xapi.d/plugins/</userinput></screen></para></step>
<step><para>Remove the temporary files/directories:
<prompt>$</prompt> <userinput>tar -czf - -C "$PLUGINPATH" ./ | ssh root@xenserver tar -xozf - -C /etc/xapi.d/plugins/</userinput></screen>
</step>
<step>
<para>Remove the temporary files/directories:</para>
<screen><prompt>$</prompt> <userinput>rm "$NOVA_ZIPBALL"</userinput>
<prompt>$</prompt> <userinput>rm -rf "$NOVA_SOURCES"</userinput> </screen></para></step>
<prompt>$</prompt> <userinput>rm -rf "$NOVA_SOURCES"</userinput> </screen>
</step>
</procedure>
</section>
<section xml:id="packaged_install">
<title>Packaged Installation</title>
<para>Follow these steps to produce a supplemental
pack from the nova sources, and package it as a XenServer
<section xml:id="packaged_install">
<title>Package a XenServer supplemental pack</title>
<para>Follow these steps to produce a supplemental pack from
the nova sources, and package it as a XenServer
supplemental pack.</para>
<procedure><title>To package a XenServer supplemental pack</title>
<procedure>
<step>
<para>Create RPM packages. Given you have
the nova sources (use one of the methods mentioned
at Manual Installation):
<para>Create RPM packages. Given you have the nova
sources. Use one of the methods in <xref
linkend="manual_install"/>:</para>
<screen><prompt>$</prompt> <userinput>cd nova/plugins/xenserver/xenapi/contrib</userinput>
<prompt>$</prompt> <userinput>./build-rpm.sh</userinput></screen>These
commands leave an <literal>.rpm</literal> file in
the <literal>rpmbuild/RPMS/noarch/</literal>
<prompt>$</prompt> <userinput>./build-rpm.sh</userinput></screen>
<para>These commands leave an
<filename>.rpm</filename> file in the
<filename>rpmbuild/RPMS/noarch/</filename>
directory.</para>
</step>
<step>
<para>Pack the RPM packages to a
Supplemental Pack, using the XenServer DDK (the
following command should be issued on the
XenServer DDK virtual appliance, after the
produced rpm file has been copied over):
<para>Pack the RPM packages to a Supplemental Pack,
using the XenServer DDK (the following command
should be issued on the XenServer DDK virtual
appliance, after the produced rpm file has been
copied over):</para>
<screen><prompt>$</prompt> <userinput>/usr/bin/build-supplemental-pack.sh \</userinput>
<prompt>&gt;</prompt> <userinput>--output=output_directory \</userinput>
<prompt>&gt;</prompt> <userinput>--vendor-code=novaplugin \</userinput>
@ -70,16 +77,17 @@
<prompt>&gt;</prompt> <userinput>--label=novaplugins \</userinput>
<prompt>&gt;</prompt> <userinput>--text="nova plugins" \</userinput>
<prompt>&gt;</prompt> <userinput>--version=0 \</userinput>
<prompt>&gt;</prompt> <userinput>full_path_to_rpmfile</userinput></screen>This
command produces an <literal>.iso</literal> file
in the output directory specified. Copy that file
to the hypervisor.</para>
<prompt>&gt;</prompt> <userinput>full_path_to_rpmfile</userinput></screen>
<para>This command produces an
<filename>.iso</filename> file in the output
directory specified. Copy that file to the
hypervisor.</para>
</step>
<step>
<para>Install the Supplemental Pack. Log
in to the hypervisor, and issue:
<screen><prompt>#</prompt> <userinput>xe-install-supplemental-pack path_to_isofile</userinput></screen></para>
<para>Install the Supplemental Pack. Log in to the
hypervisor, and issue:</para>
<screen><prompt>#</prompt> <userinput>xe-install-supplemental-pack path_to_isofile</userinput></screen>
</step>
</procedure>
</section>
</section>
</section>

39
doc/common/section_xapi-resize-setup.xml
View File

@ -3,17 +3,16 @@
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
xml:id="xapi-resize-setup">
<?dbhtml stop-chunking?>
<title>Dom0 Modifications for Resize/Migration Support</title>
<para>To get resize to work with XenServer (and XCP) you need to:</para>
<?dbhtml stop-chunking?>
<title>Modify Dom0 for resize/migration support</title>
<para>To resize servers with XenServer and XCP, you must:</para>
<itemizedlist>
<listitem>
<para>Establish a root trust between all hypervisor nodes of your
deployment:</para>
<para>You can do so by generating an ssh key-pair (with
<command>ssh-keygen</command>) and then ensuring
that each of your dom0's
<para>Establish a root trust between all hypervisor nodes
of your deployment:</para>
<para>To do so, generate an ssh key-pair with the
<command>ssh-keygen</command> command. Ensure that
each of your dom0's
<filename>authorized_keys</filename> file (located
in <filename>/root/.ssh/authorized_keys</filename>)
contains the public key fingerprint (located in
@ -21,22 +20,20 @@
</listitem>
<listitem>
<para>Provide an <filename>/images</filename> mount point
to your hypervisor's dom0:</para>
<para>Dom0 space is a premium so creating a directory in
dom0 is kind of dangerous, and almost surely bound to
fail especially when resizing big servers. The least
to the dom0 for your hypervisor:</para>
<para>Dom0 space is at a premium so creating a directory
in dom0 is potentially dangerous and likely to fail
especially when you resize large servers. The least
you can do is to symlink <filename>/images</filename>
to your local storage SR. The instructions below work
for an English-based installation of XenServer (and
XCP) and in the case of ext3 based SR (with which the
resize functionality is known to work
to your local storage SR. The following instructions
work for an English-based installation of XenServer
(and XCP) and in the case of ext3-based SR (with which
the resize functionality is known to work
correctly).</para>
<screen><prompt>#</prompt> <userinput>LOCAL_SR=$(xe sr-list name-label="Local storage" --minimal)</userinput>
<screen><prompt>#</prompt> <userinput>LOCAL_SR=$(xe sr-list name-label="Local storage" --minimal)</userinput>
<prompt>#</prompt> <userinput>IMG_DIR="/var/run/sr-mount/$LOCAL_SR/images"</userinput>
<prompt>#</prompt> <userinput>mkdir -p "$IMG_DIR"</userinput>
<prompt>#</prompt> <userinput>ln -s "$IMG_DIR" /images</userinput>
</screen>
<prompt>#</prompt> <userinput>ln -s "$IMG_DIR" /images</userinput></screen>
</listitem>
</itemizedlist>
</section>

218
doc/common/section_xen-install.xml
View File

@ -3,140 +3,138 @@
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
xml:id="xenapi-install">
<title xml:id="xenapi-install.title">Installing XenServer and
<title xml:id="xenapi-install.title">Install XenServer and
XCP</title>
<para>Before you can run OpenStack with XCP or XenServer, you must
install the software on <link
xlink:href="http://docs.vmd.citrix.com/XenServer/6.0.0/1.0/en_gb/installation.html#sys_requirements"
> an appropriate server</link>.</para>
>an appropriate server</link>.</para>
<note>
<para>Xen is a type 1 hypervisor: When your server starts, Xen
is the first software that runs. Consequently, you must
install XenServer or XCP before you install the operating
system on which you want to run OpenStack code. The
OpenStack services then run in a virtual machine that you
install on top of XenServer.</para>
system where you want to run OpenStack code. The OpenStack
services then run in a virtual machine that you install on
top of XenServer.</para>
</note>
<para>Before you can install your system you must decide if you
want to install Citrix XenServer (either the free edition, or
one of the paid editions) or Xen Cloud Platform from Xen.org.
You can download the software from the following locations: <itemizedlist>
<para>Before you can install your system, decide whether to
install a free or paid edition of Citrix XenServer or Xen
Cloud Platform from Xen.org. Download the software from these
locations:</para>
<itemizedlist>
<listitem>
<para><link
xlink:href="http://www.citrix.com/XenServer/download"
> http://www.citrix.com/XenServer/download
</link></para>
>http://www.citrix.com/XenServer/download</link></para>
</listitem>
<listitem>
<para><link
xlink:href="http://www.xen.org/download/xcp/index.html"
> http://www.xen.org/download/xcp/index.html
</link></para>
>http://www.xen.org/download/xcp/index.html</link></para>
</listitem>
</itemizedlist> When installing many servers, you may find it
easier to perform <link
</itemizedlist>
<para>When you install many servers, you might find it easier to
perform <link
xlink:href="http://docs.vmd.citrix.com/XenServer/6.0.0/1.0/en_gb/installation.html#pxe_boot_install"
> PXE boot installations of XenServer or XCP</link>. You
can also package up any post install changes you wish to make
to your XenServer by <link
>PXE boot installations of XenServer or XCP</link>. You
can also package any post-installation changes that you want
to make to your XenServer by <link
xlink:href="http://docs.vmd.citrix.com/XenServer/6.0.0/1.0/en_gb/supplemental_pack_ddk.html"
> creating your own XenServer supplemental
>creating your own XenServer supplemental
pack</link>.</para>
<para>It is also possible to get XCP by installing the <emphasis
role="bold">xcp-xenapi</emphasis> package on Debian based
distributions. However, this is not as mature or feature
complete as above distributions. This will modify your boot
loader to first boot Xen, then boot your existing OS on top of
Xen as Dom0. It is in Dom0 that the xapi daemon will run. You
can find more details on the Xen.org wiki: <link
xlink:href="http://wiki.xen.org/wiki/Project_Kronos">
http://wiki.xen.org/wiki/Project_Kronos </link></para>
<para><important>
<para>Ensure you are using the EXT type of storage
repository (SR). Features that require access to VHD
files (such as copy on write, snapshot and migration)
do not work when using the LVM SR. Storage repository
(SR) is a XenAPI specific term relating to the
physical storage on which virtual disks are
stored.</para>
<para>On the XenServer/XCP installation screen, this is
selected by choosing "XenDesktop Optimized" option. In
case you are using an answer file, make sure you use
<literal>srtype="ext"</literal> within the
<literal>installation</literal> tag of the answer
<para>You can also install the <package>xcp-xenapi</package>
package on Debian-based distributions to get XCP. However,
this is not as mature or feature complete as above
distributions. This modifies your boot loader to first boot
Xen and boot your existing OS on top of Xen as Dom0. The xapi
daemon runs in Dom0. Find more details at <link
xlink:href="http://wiki.xen.org/wiki/Project_Kronos"
>http://wiki.xen.org/wiki/Project_Kronos</link>.</para>
<important>
<para>Make sure you use the EXT type of storage repository
(SR). Features that require access to VHD files (such as
copy on write, snapshot and migration) do not work when
you use the LVM SR. Storage repository (SR) is a
XenAPI-specific term relating to the physical storage
where virtual disks are stored.</para>
<para>On the XenServer/XCP installation screen, choose the
<guilabel>XenDesktop Optimized</guilabel> option. If
you use an answer file, make sure you use
<literal>srtype="ext"</literal> in the
<option>installation</option> tag of the answer
file.</para>
</important></para>
</important>
<section xml:id="xenapi-post-install">
<title>Post install steps</title>
<para>You are now ready to install OpenStack onto your
XenServer system. This process involves the following
steps: <itemizedlist>
<listitem>
<para>For resize and migrate functionality, please
perform the changes described in the <link
xlink:href="http://docs.openstack.org/trunk/config-reference/content/configuring-openstack-compute-basics.html#xenserver-resize"
> Configuring Resize</link> section of the
<citetitle>OpenStack Configuration Reference</citetitle>.
</para>
</listitem>
<listitem>
<para>Install the VIF isolation rules to help
prevent mac and ip address spoofing.</para>
</listitem>
<listitem>
<para>Install the XenAPI plugins - see the next
<title>Post-installation steps</title>
<para>Complete these steps to install OpenStack in your
XenServer system:</para>
<procedure>
<step>
<para>For resize and migrate functionality, complete
the changes described in the <citetitle>Configure
resize</citetitle> section in the <link
xlink:href="../config-reference/content/index.html"
><citetitle>OpenStack Configuration
Reference</citetitle></link>.</para>
</step>
<step>
<para>Install the VIF isolation rules to help prevent
mac and IP address spoofing.</para>
</step>
<step>
<para>Install the XenAPI plug-ins. See the following
section.</para>
</listitem>
<listitem>
</step>
<step>
<para>To support AMI type images, you must set up
<literal>/boot/guest</literal>
symlink/directory in Dom0. For detailed
instructions, see next section.</para>
</listitem>
<listitem>
<para>To support resize/migration, set up an ssh
trust relation between your XenServer hosts,
and ensure <literal>/images</literal> is
properly set up. See next section for more
details.</para>
</listitem>
<listitem>
<para>Create a Paravirtualized virtual machine
that can run the OpenStack compute
code.</para>
</listitem>
<listitem>
</step>
<step>
<para>To support resize/migration, set up an ssh trust
relation between your XenServer hosts, and ensure
<literal>/images</literal> is properly set up.
See next section for more details.</para>
</step>
<step>
<para>Create a Paravirtualized virtual machine that
can run the OpenStack compute code.</para>
</step>
<step>
<para>Install and configure the <systemitem
class="service">nova-compute</systemitem>
in the above virtual machine.</para>
</listitem>
</itemizedlist> For further information on these steps
look at how DevStack performs the last three steps when
doing developer deployments. For more information on
DevStack, take a look at the <link
class="service">nova-compute</systemitem> in
the above virtual machine.</para>
</step>
</procedure>
<para>For more information, see how DevStack performs the last
three steps for developer deployments. For more
information about DevStack, see <citetitle>Getting Started
With XenServer and Devstack</citetitle> (<link
xlink:href="https://github.com/openstack-dev/devstack/blob/master/tools/xen/README.md"
> DevStack and XenServer Readme</link>. More
information on the first step can be found in the <link
>https://github.com/openstack-dev/devstack/blob/master/tools/xen/README.md</link>).
Find more information about the first step, see
<citetitle>Multi Tenancy Networking Protections in
XenServer</citetitle> (<link
xlink:href="https://github.com/openstack/nova/blob/master/plugins/xenserver/doc/networking.rst"
> XenServer mutli-tenancy protection doc</link>. More
information on how to install the XenAPI plugins can be
found in the <link
>https://github.com/openstack/nova/blob/master/plugins/xenserver/doc/networking.rst</link>).
For information about how to install the XenAPI plug-ins,
see <citetitle>XenAPI README</citetitle> (<link
xlink:href="https://github.com/openstack/nova/blob/master/plugins/xenserver/xenapi/README"
> XenAPI plugins Readme</link>.</para>
>https://github.com/openstack/nova/blob/master/plugins/xenserver/xenapi/README</link>).</para>
<xi:include href="section_xapi-install-plugins.xml"/>
<xi:include href="section_xapi-ami-setup.xml"/>
<xi:include href="section_xapi-resize-setup.xml"/>
</section>
<section xml:id="xenapi-boot-from-iso">
<title>Xen Boot from ISO</title>
<para>XenServer, through the XenAPI integration with OpenStack
provides a feature to boot instances from an ISO file. To
activate the "Boot From ISO" feature, you must configure
the SR elements on XenServer host that way.</para>
<title>Xen boot from ISO</title>
<para>XenServer, through the XenAPI integration with
OpenStack, provides a feature to boot instances from an
ISO file. To activate the Boot From ISO feature, you must
configure the SR elements on XenServer host, as
follows:</para>
<procedure>
<title>To Xen boot from ISO</title>
<step>
<para>Create an ISO-typed SR, such as an NFS ISO
library, for instance. For this, using XenCenter
@ -145,32 +143,32 @@
in read-write mode.</para>
</step>
<step>
<para>On the compute host, find the uuid of this ISO
SR and write it down.
<screen><prompt>#</prompt> <userinput>xe host-list</userinput></screen></para>
<para>On the compute host, find and record the uuid of
this ISO SR:</para>
<screen><prompt>#</prompt> <userinput>xe host-list</userinput></screen>
</step>
<step>
<para>Locate the uuid of the NFS ISO library:
<screen><prompt>#</prompt> <userinput>xe sr-list content-type=iso</userinput> </screen></para>
<para>Locate the uuid of the NFS ISO library:</para>
<screen><prompt>#</prompt> <userinput>xe sr-list content-type=iso</userinput></screen>
</step>
<step>
<para>Set the uuid and configuration. Even if an NFS
mount point isn't local storage, you must specify
"local-storage-iso."</para>
mount point is not local, you must specify
<literal>local-storage-iso</literal>.</para>
<screen><prompt>#</prompt> <userinput>xe sr-param-set uuid=[iso sr uuid] other-config:i18n-key=local-storage-iso</userinput></screen>
</step>
<step>
<para>Make sure the host-uuid from "xe pbd-list"
equals the uuid of the host you found
earlier:</para>
<para>Make sure the host-uuid from <literal>xe
pbd-list</literal> equals the uuid of the host
you found previously:</para>
<screen><prompt>#</prompt> <userinput>xe sr-uuid=[iso sr uuid]</userinput></screen>
</step>
<step>
<para>You can now add images via the OpenStack Image
Registry, with <literal>disk-format=iso</literal>,
and boot them in OpenStack Compute.
<para>You can now add images through the OpenStack
Image Service with
<literal>disk-format=iso</literal>, and boot
them in OpenStack Compute:</para>
<screen><prompt>#</prompt> <userinput>glance image-create --name=fedora_iso --disk-format=iso --container-format=bare &lt; Fedora-16-x86_64-netinst.iso</userinput></screen>
</para>
</step>
</procedure>
</section>