openstack/openstack-manuals
Code Issues Proposed changes

Fixes to Cloud Admin Guide for Havana (testing with Anne G)

Browse Source 
Change-Id: I65a12cfdde82c069684e7fac0b53ae5720b6ebda
author: diane fleming
This commit is contained in:
Diane Fleming 2013-09-27 12:14:51 -05:00
parent 94c72ccb4e
commit c2bfed945d
25 changed files with 3721 additions and 3244 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
doc/admin-guide-cloud/bk-admin-guide-cloud.xml
View File

@ -7,7 +7,7 @@
xml:id="openstack-compute-admin-manual-grizzly">
<title>OpenStack Cloud Administrator Guide</title>
<?rax title.font.size="28px" subtitle.font.size="28px"?>
<titleabbrev>OpenStack Cloud Administrator Guide</titleabbrev>
<titleabbrev>Cloud Administrator Guide</titleabbrev>
<info>
<author>
<personname>

27
doc/admin-guide-cloud/ch_blockstorage.xml
View File

@ -3,6 +3,7 @@
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
xml:id="managing-volumes">
<?dbhtml stop-chunking?>
<title>Block Storage</title>
<para>The OpenStack Block Storage service works though the
interaction of a series of daemon processes named cinder-*
@ -26,6 +27,7 @@
service is similar to the Amazon EC2 Elastic Block Storage
(EBS) offering.</para>
</section>
<?hard-pagebreak?>
<section xml:id="section_manage-volumes">
<title>Manage volumes</title>
<para>The default OpenStack Block Storage service implementation
@ -45,8 +47,6 @@
<para>The following high-level procedure shows you how to create
and attach a volume to a server instance.</para>
<procedure>
<title>To create and attach a volume to a server
instance:</title>
<step><para>You must configure both OpenStack Compute and the
OpenStack Block Storage service through the
<filename>cinder.conf</filename> file.</para></step>
@ -83,14 +83,11 @@
<systemitem class="service">nova-compute</systemitem>. The walk through uses
a custom partitioning scheme that carves out 60GB of space
and labels it as LVM. The network uses
<literal>FlatManger</literal> is the
<literal>FlatManager</literal> is the
<literal>NetworkManager</literal> setting for
OpenStack Compute (Nova).</para>
<para>Please note that the network mode doesn't interfere at
all with the way cinder works, but networking must be set
up for cinder to work. Please refer to <link
xlink:href="http://docs.openstack.org/grizzly/openstack-network/admin/content/">Networking Administration</link> for more
details.</para>
<para>The network mode does not interfere with the way cinder works, but networking must be set
up for cinder to work. For details, see <xref linkend="ch_networking"/>.</para>
<para>To set up Compute to use volumes, ensure that Block
Storage is installed along with lvm2. This guide describes how to:</para>
<para>
@ -106,11 +103,15 @@
<section xml:id="boot-from-volume">
<title>Boot from volume</title>
<para>In some cases, instances can be stored and run from inside volumes. This is explained in further detail in the <link xlink:href="http://docs.openstack.org/user-guide/content/boot_from_volume.html">Boot From Volume</link>
section of the <citetitle>OpenStack End User Guide</citetitle>.</para>
</section>
<xi:include href="section_troubleshoot-cinder.xml"/>
<para>In some cases, instances can be stored and run from
inside volumes. For information, see the <link
xlink:href="http://docs.openstack.org/user-guide/content/boot_from_volume.html"
>Launch an instance from a volume</link> section in the
<link xlink:href="http://docs.openstack.org/user-guide/content/"><citetitle>OpenStack End User
Guide</citetitle></link>.</para>
</section>
<?hard-pagebreak?>
<xi:include href="section_troubleshoot-cinder.xml"/>
<xi:include href="section_multi_backend.xml"/>
<xi:include href="section_backup-block-storage-disks.xml"/>
<xi:include href="section_volume-migration.xml"/>

4152
doc/admin-guide-cloud/ch_compute.xml
View File

File diff suppressed because it is too large Load Diff

41
doc/admin-guide-cloud/ch_dashboard.xml
View File

@ -3,40 +3,41 @@
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
xml:id="ch_install-dashboard">
<?dbhtml stop-chunking?>
<title>Dashboard</title>
<para xmlns:raxm="http://docs.rackspace.com/api/metadata">The dashboard, also known as <link
xlink:href="https://github.com/openstack/horizon/">horizon</link>, is a Web interface
that allows cloud administrators and users to manage various OpenStack resources and
services.</para>
<para>The dashboard enables web-based interactions with the
OpenStack Compute cloud controller through the OpenStack APIs.</para>
<para>The following instructions show an example deployment
configured with an Apache web server.</para>
<para>After you <link linkend="installing-openstack-dashboard"
>install and configure the dashboard</link>, you can
complete the following tasks:</para>
<para xmlns:raxm="http://docs.rackspace.com/api/metadata">The
dashboard, also known as <link
xlink:href="https://github.com/openstack/horizon/"
>horizon</link>, enables cloud administrators and users to
manage various OpenStack resources and services through a
Web-based interface. The dashboard enables interactions with
the OpenStack Compute cloud controller through the OpenStack
APIs. For information about installing and configuring the
dashboard, see the <citetitle>OpenStack Installation
Guide</citetitle> for your distribution. After you install and
configure the dashboard, you can complete the
following tasks:</para>
<itemizedlist>
<listitem>
<para>Customize your dashboard. See <xref
linkend="dashboard-custom-brand"/>.</para>
linkend="dashboard-custom-brand"/>.</para>
</listitem>
<listitem>
<para>Set up session storage for the dashboard. See <xref
linkend="dashboard-sessions"/>.</para>
linkend="dashboard-sessions"/>.</para>
</listitem>
<listitem>
<para>Deploy the dashboard. See <link
xlink:href="http://docs.openstack.org/developer/horizon/topics/deployment.html"
>Deploying Horizon</link>.</para>
xlink:href="http://docs.openstack.org/developer/horizon/topics/deployment.html"
>Deploying Horizon</link>.</para>
</listitem>
<listitem xml:id="launch_instances">
<para>Launch instances with the dashboard. See the
<citetitle>OpenStack User
Guide</citetitle>.</para>
<para>Launch instances with the dashboard. See the <link
xlink:href="http://docs.openstack.org/user-guide/content/"
><citetitle>OpenStack End User
Guide</citetitle></link>.</para>
</listitem>
</itemizedlist>
<xi:include href="../common/section_dashboard-system-reqs.xml"/>
<xi:include href="../common/section_dashboard-install.xml"/>
<xi:include href="../common/section_dashboard_customizing.xml"/>
<xi:include href="../common/section_dashboard_sessions.xml"/>
</chapter>

284
doc/admin-guide-cloud/ch_identity_mgmt.xml
View File

@ -3,166 +3,135 @@
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
xml:id="ch-identity-mgmt-config">
<?dbhtml stop-chunking?>
<title>Identity Management</title>
<para>
The default identity management system for OpenStack is the OpenStack Identity Service, code-named Keystone.
Once Identity is installed, it is configured via a primary
configuration file (<filename>etc/keystone.conf</filename>), possibly
a separate logging configuration file, and initializing data into
keystone using the command line client.
</para>
<para>The default identity management system for OpenStack is the
OpenStack Identity Service, code-named Keystone. Once Identity is
installed, it is configured via a primary configuration file
(<filename>etc/keystone.conf</filename>), possibly a separate
logging configuration file, and initializing data into keystone
using the command line client.</para>
<xi:include href="../common/section_keystone-concepts.xml"/>
<section xml:id="user-crud">
<title>User CRUD</title>
<para>
Keystone provides a user CRUD filter that can be added to the
public_api pipeline. This user crud filter allows users to use a
HTTP PATCH to change their own password. To enable this extension
you should define a <literal>user_crud_extension</literal> filter, insert it after
<para>Keystone provides a user CRUD filter that can be added to
the public_api pipeline. This user crud filter enables users to
use a HTTP PATCH to change their own password. To enable this
extension you should define a
<literal>user_crud_extension</literal> filter, insert it after
the <literal>*_body</literal> middleware and before the
<literal>public_service</literal> app in the public_api WSGI
pipeline in <filename>keystone.conf</filename> e.g.:
</para>
<programlisting language="ini">
[filter:user_crud_extension]
<literal>public_service</literal> app in the public_api WSGI
pipeline in <filename>keystone.conf</filename> e.g.:</para>
<programlisting language="ini"><?db-font-size 75%?>[filter:user_crud_extension]
paste.filter_factory = keystone.contrib.user_crud:CrudExtension.factory
[pipeline:public_api]
pipeline = stats_monitoring url_normalize token_auth admin_token_auth xml_body json_body debug ec2_extension user_crud_extension public_service
</programlisting>
<para>
Each user can then change their own password with a HTTP PATCH
</para>
<programlisting language="ini">
&gt; curl -X PATCH http://localhost:5000/v2.0/OS-KSCRUD/users/&lt;userid&gt; -H &quot;Content-type: application/json&quot; \
-H &quot;X_Auth_Token: &lt;authtokenid&gt;&quot; -d '{&quot;user&quot;: {&quot;password&quot;: &quot;ABCD&quot;, &quot;original_password&quot;: &quot;DCBA&quot;}}'
</programlisting>
<para>
In addition to changing their password all of the users current
tokens will be deleted (if the backend used is kvs or sql)
</para>
pipeline = stats_monitoring url_normalize token_auth admin_token_auth xml_body json_body debug ec2_extension user_crud_extension public_service</programlisting>
<para>Each user can then change their own password with a HTTP
PATCH</para>
<programlisting language="ini"><?db-font-size 75%?>&gt; curl -X PATCH http://localhost:5000/v2.0/OS-KSCRUD/users/&lt;userid&gt; -H &quot;Content-type: application/json&quot; \
-H &quot;X_Auth_Token: &lt;authtokenid&gt;&quot; -d '{&quot;user&quot;: {&quot;password&quot;: &quot;ABCD&quot;, &quot;original_password&quot;: &quot;DCBA&quot;}}'</programlisting>
<para>In addition to changing their password all of the users
current tokens are deleted (if the back end is kvs or
sql).</para>
</section>
<section xml:id="keystone-logging">
<title>Logging</title>
<para> Logging is configured externally to the rest of Identity,
the file specifying the logging configuration is in the
<para>You configure logging externally to the rest of Identity.
The file specifying the logging configuration is in the
<literal>[DEFAULT]</literal> section of the
<filename>keystone.conf</filename> file under
<literal>log_config</literal>. If you wish to route all your
logging through syslog, set <literal>use_syslog=true</literal>
option in the <literal>[DEFAULT]</literal> section. </para>
<para>
A sample logging file is available with the project in the
directory <filename>etc/logging.conf.sample</filename>. Like other
OpenStack projects, Identity uses the `python logging module`,
which includes extensive configuration options for choosing the
output levels and formats.
</para>
<para>
In addition to this documentation page, you can check the
<filename>etc/keystone.conf</filename> sample configuration files
distributed with keystone for example configuration files for each
server application.
</para>
<para>For services which have separate paste-deploy ini file,
auth_token middleware can be alternatively configured in
[keystone_authtoken] section in the main config file, such as
<filename>nova.conf</filename>. For
example in Nova, all middleware parameters can be removed from
api-paste.ini like these:</para>
<programlisting language="ini"> [filter:authtoken]
paste.filter_factory =
keystoneclient.middleware.auth_token:filter_factory
</programlisting>
<para>and set in
<filename>nova.conf</filename> like these: </para>
<programlisting language="ini">[DEFAULT]
...
auth_strategy=keystone
<literal>log_config</literal>. To route logging through
syslog, set <literal>use_syslog=true</literal> option in the
<literal>[DEFAULT]</literal> section.</para>
<para>A sample logging file is available with the project in the
directory <filename>etc/logging.conf.sample</filename>. Like
other OpenStack projects, Identity uses the python logging
module, which includes extensive configuration options for
choosing the output levels and formats.</para>
<para>Review the <filename>etc/keystone.conf</filename> sample
configuration files distributed with keystone for example
configuration files for each server application.</para>
<para>For services which have separate paste-deploy ini file, you
can configure auth_token middleware in [keystone_authtoken]
section in the main config file, such as
<filename>nova.conf</filename>. For example in Compute, you
can remove the middleware parameters from
<filename>api-paste.ini</filename>, as follows:</para>
<programlisting language="ini"><?db-font-size 75%?>[filter:authtoken]
paste.filter_factory =
keystoneclient.middleware.auth_token:filter_factory</programlisting>
<para>And set the following values in
<filename>nova.conf</filename>, as follows:</para>
<programlisting language="ini"><?db-font-size 75%?>[DEFAULT]
...
auth_strategy=keystone
[keystone_authtoken]
auth_host = 127.0.0.1
auth_port = 35357
auth_protocol = http
auth_uri = http://127.0.0.1:5000/
admin_user = admin
admin_password = SuperSekretPassword
admin_tenant_name = service
</programlisting>
<para>Note that middleware parameters in
paste config take priority, they must be removed to use values
in [keystone_authtoken] section.</para>
[keystone_authtoken]
auth_host = 127.0.0.1
auth_port = 35357
auth_protocol = http
auth_uri = http://127.0.0.1:5000/
admin_user = admin
admin_password = SuperSekretPassword
admin_tenant_name = service </programlisting>
<note>
<para>Middleware parameters in paste config take priority. You
must remove them to use values in [keystone_authtoken]
section.</para>
</note>
</section>
<section xml:id="monitoring">
<title>Monitoring</title>
<para>
Keystone provides some basic request/response monitoring
statistics out of the box.
</para>
<para>
Enable data collection by defining a
<literal>stats_monitoring</literal> filter and including it at the
beginning of any desired WSGI pipelines:
</para>
<programlisting language="ini">
[filter:stats_monitoring]
<para>Keystone provides some basic request/response monitoring
statistics out of the box.</para>
<para>Enable data collection by defining a
<literal>stats_monitoring</literal> filter and including it at
the beginning of any desired WSGI pipelines:</para>
<programlisting language="ini"><?db-font-size 75%?>[filter:stats_monitoring]
paste.filter_factory = keystone.contrib.stats:StatsMiddleware.factory
[pipeline:public_api]
pipeline = stats_monitoring [...] public_service
</programlisting>
<para>
Enable the reporting of collected data by defining a
<literal>stats_reporting</literal> filter and including it near
the end of your <literal>admin_api</literal> WSGI pipeline (After
<literal>*_body</literal> middleware and before
<literal>*_extension</literal> filters is recommended):
</para>
<programlisting language="ini">
[filter:stats_reporting]
pipeline = stats_monitoring [...] public_service</programlisting>
<para>Enable the reporting of collected data by defining a
<literal>stats_reporting</literal> filter and including it
near the end of your <literal>admin_api</literal> WSGI pipeline
(After <literal>*_body</literal> middleware and before
<literal>*_extension</literal> filters is recommended):</para>
<programlisting language="ini"><?db-font-size 75%?>[filter:stats_reporting]
paste.filter_factory = keystone.contrib.stats:StatsExtension.factory
[pipeline:admin_api]
pipeline = [...] json_body stats_reporting ec2_extension [...] admin_service
</programlisting>
<para>
Query the admin API for statistics using:
</para>
pipeline = [...] json_body stats_reporting ec2_extension [...] admin_service</programlisting>
<para>Query the admin API for statistics using:</para>
<screen><prompt>$</prompt> <userinput>curl -H 'X-Auth-Token: ADMIN' http://localhost:35357/v2.0/OS-STATS/stats</userinput></screen>
<para>
Reset collected data using:
</para>
<screen><prompt>$</prompt> <userinput>curl -H 'X-Auth-Token: ADMIN' -X DELETE http://localhost:35357/v2.0/OS-STATS/stats</userinput></screen>
<para>Reset collected data using:</para>
<screen><prompt>$</prompt> <userinput>curl -H 'X-Auth-Token: ADMIN' -X DELETE \
http://localhost:35357/v2.0/OS-STATS/stats</userinput></screen>
</section>
<section xml:id="running-keystone">
<title>Running</title>
<para>
Running Identity is simply starting the services by using the
command:
</para>
<screen><prompt>$</prompt> <userinput>
keystone-all
</userinput></screen>
<para>
Invoking this command starts up two wsgi.Server instances,
configured by the <filename>keystone.conf</filename> file as
described above. One of these wsgi 'servers' is
<literal>admin</literal> (the administration API) and the other is
<literal>main</literal> (the primary/public API interface). Both
of these run in a single process.
</para>
<title>Start the Identity Service</title>
<para>To start the services for the Identity Service, run the
following command:</para>
<screen><prompt>$</prompt> <userinput>keystone-all</userinput></screen>
<para>This command starts two wsgi.Server instances configured by
the <filename>keystone.conf</filename> file as described
previously. One of these wsgi servers is
<literal>admin</literal> (the administration API) and the
other is <literal>main</literal> (the primary/public API
interface). Both run in a single process.</para>
</section>
<section xml:id="example-usage">
<title>Example usage</title>
<para>The <literal>keystone</literal> client is set up to expect commands
in the general form of <literal>keystone</literal>
<literal>command</literal>
<literal>argument</literal>, followed by flag-like keyword arguments to
provide additional (often optional) information. For example, the
command <literal>user-list</literal> and
<literal>tenant-create</literal> can be invoked as follows: </para>
<programlisting language="bash">
# Using token auth env variables
<section xml:id="example-usage">
<title>Example usage</title>
<para>The <literal>keystone</literal> client is set up to expect
commands in the general form of <literal>keystone</literal>
<literal>command</literal>
<literal>argument</literal>, followed by flag-like keyword
arguments to provide additional (often optional) information.
For example, the command <literal>user-list</literal> and
<literal>tenant-create</literal> can be invoked as
follows:</para>
<programlisting language="bash"><?db-font-size 65%?># Using token auth env variables
export SERVICE_ENDPOINT=http://127.0.0.1:5000/v2.0/
export SERVICE_TOKEN=secrete_token
keystone user-list
@ -181,25 +150,22 @@ keystone tenant-create --name=demo
# Using user + password + tenant_name flags
keystone --username=admin --password=secrete --tenant_name=admin user-list
keystone --username=admin --password=secrete --tenant_name=admin tenant-create --name=demo
</programlisting>
</section>
<section xml:id="auth-token-middleware-with-username-and-password">
<title>Auth-Token Middleware with Username and Password</title>
<para>
It is also possible to configure Keystone's auth_token
middleware using the 'admin_user' and 'admin_password' options.
When using the 'admin_user' and 'admin_password' options the
'admin_token' parameter is optional. If 'admin_token' is
specified it will by used only if the specified token is still
valid.
</para>
<para>
Here is an example paste config filter that makes use of the
'admin_user' and 'admin_password' parameters:
</para>
<screen>
[filter:authtoken]
keystone --username=admin --password=secrete --tenant_name=admin tenant-create --name=demo</programlisting>
</section>
<section xml:id="auth-token-middleware-with-username-and-password">
<title>Auth-Token middleware with user name and password</title>
<para>It is also possible to configure the Identity Service
Auth-Token middleware using the <option>admin_user</option> and
<option>admin_password</option> options. When using the
<option>admin_user</option> and
<option>admin_password</option> options the
<option>admin_token</option> parameter is optional. If
<option>admin_token</option> is specified it is used only if
the specified token is still valid.</para>
<para>Here is an example paste config filter that makes use of the
<option>admin_user</option> and
<option>admin_password</option> parameters:</para>
<screen>[filter:authtoken]
paste.filter_factory = keystoneclient.middleware.auth_token:filter_factory
service_port = 5000
service_host = 127.0.0.1
@ -207,13 +173,11 @@ auth_port = 35357
auth_host = 127.0.0.1
auth_token = 012345SECRET99TOKEN012345
admin_user = admin
admin_password = keystone123
</screen>
<para>
It should be noted that when using this option an admin
tenant/role relationship is required. The admin user is granted
access to the 'Admin' role on the 'admin' tenant.
</para>
</section>
admin_password = keystone123</screen>
<para>It should be noted that when using this option an admin
tenant/role relationship is required. The admin user is granted
access to the Admin role on the admin tenant.</para>
</section>
<?hard-pagebreak?>
<xi:include href="../common/section_identity-troubleshooting.xml"/>
</chapter>

21
doc/admin-guide-cloud/ch_networking.xml
View File

@ -3,6 +3,7 @@
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
xml:id="ch_networking">
<?dbhtml stop-chunking?>
<title>Networking</title>
<para>Learn Networking concepts, architecture, and basic and
advanced neutron and nova command-line interface (CLI)
@ -14,8 +15,7 @@
API for defining network connectivity and addressing in
the cloud. The Networking service enables operators to
leverage different networking technologies to power their
cloud networking.</para>
<para>The Networking service also provides an API to configure
cloud networking. The Networking service also provides an API to configure
and manage a variety of network services ranging from L3
forwarding and NAT to load balancing, edge firewalls, and
IPSEC VPN.</para>
@ -59,8 +59,7 @@
<para>You can configure rich network topologies by
creating and configuring networks and subnets, and
then instructing other OpenStack services like Compute
to attach virtual devices to ports on these networks.
In particular, Networking supports each tenant having
to attach virtual devices to ports on these networks.</para><para>In particular, Networking supports each tenant having
multiple private networks, and allows tenants to
choose their own IP addressing scheme (even if those
IP addresses overlap with those used by other
@ -195,7 +194,6 @@
number of plug-ins, the cloud administrator is able to
weigh different options and decide which networking
technology is right for the deployment.</para>
<?hard-pagebreak?>
<para>Not all Networking plug-ins are compatible with all
possible Compute drivers:</para>
<table rules="all">
@ -333,7 +331,6 @@
with each other and with other OpenStack services.</para>
<section xml:id="arch_overview">
<title>Overview</title>
<para>Networking is a standalone service, just like other
OpenStack services such as Compute, Image service,
Identity service, or the Dashboard. Like those
@ -433,7 +430,7 @@
<title>Network connectivity for physical hosts</title>
<mediaobject>
<imageobject>
<imagedata scale="60"
<imagedata scale="50"
fileref="../common/figures/Neutron-PhysNet-Diagram.png"
/>
</imageobject>
@ -552,6 +549,7 @@
first available IP address.</para>
</listitem>
</itemizedlist>
<?hard-pagebreak?>
<para>The following table summarizes the attributes
available for each networking abstraction. For
information about API abstraction and operations,
@ -734,6 +732,7 @@
</tr>
</tbody>
</table>
<?hard-pagebreak?>
<table rules="all">
<caption>Port attributes</caption>
<col width="20%"/>
@ -913,6 +912,7 @@
<screen><prompt>$</prompt> <userinput>keystone tenant-list</userinput></screen>
</note>
</section>
<?hard-pagebreak?>
<section xml:id="advanced_networking">
<title>Advanced Networking operations</title>
<para>The following table shows example neutron
@ -968,6 +968,7 @@
</table>
</section>
</section>
<?hard-pagebreak?>
<section xml:id="using_nova_with_neutron">
<title>Use Compute with Networking</title>
<section xml:id="basic_workflow_with_nova">
@ -1110,8 +1111,10 @@
<command>ping</command> and
<command>ssh</command> access to your
VMs.</para>
<screen><prompt>$</prompt> <userinput>neutron security-group-rule-create --protocol icmp --direction ingress default</userinput>
<prompt>$</prompt> <userinput>neutron security-group-rule-create --protocol tcp --port-range-min 22 --port-range-max 22 --direction ingress default</userinput></screen>
<screen><prompt>$</prompt> <userinput>neutron security-group-rule-create --protocol icmp \
--direction ingress default</userinput></screen>
<screen><prompt>$</prompt> <userinput>neutron security-group-rule-create --protocol tcp --port-range-min 22 \
--port-range-max 22 --direction ingress default</userinput></screen>
</listitem>
<listitem>
<para>Does not implement Networking security

14
doc/admin-guide-cloud/ch_objectstorage.xml
View File

@ -4,10 +4,16 @@
xmlns:xlink="http://www.w3.org/1999/xlink"
version="5.0"
xml:id="ch_admin-openstack-object-storage">
<?dbhtml stop-chunking?>
<title>Object Storage</title>
<para>OpenStack Object Storage is a scalable object storage system&#x2014;it is not a file system in
the traditional sense. You will not be able to mount this system like traditional SAN or NAS
volumes.</para>
<xi:include href="../common/section_about-object-storage.xml"/>
<para>Object Storage is a scalable object storage system. It is
not a file system in the traditional sense. You cannot mount
this system like traditional SAN or NAS volumes. Because Object
Storage requires a different way of thinking when it comes to
storage, take a few moments to review the key concepts in the
developer documentation at <link
xlink:href="http://docs.openstack.org/developer/swift/"
>docs.openstack.org/developer/swift/</link>.</para>
<!-- <xi:include href="../common/section_about-object-storage.xml"/> -->
<xi:include href="section_object-storage-monitoring.xml"/>
</chapter>

8
doc/admin-guide-cloud/section_networking_adv_features.xml
View File

@ -326,6 +326,7 @@
other hosts on the external network (and often to all
hosts on the Internet). You can allocate and map floating
IPs from one port to another, as needed.</para>
<?hard-pagebreak?>
<section xml:id="l3_api_abstractions">
<title>L3 API abstractions</title>
<table rules="all">
@ -463,8 +464,8 @@
</tr>
</tbody>
</table>
</section>
<?hard-pagebreak?>
<section xml:id="l3_workflow">
<title>Basic L3 operations</title>
<para>External networks are visible to all users. However,
@ -656,6 +657,7 @@
</table>
</section>
</section>
<?hard-pagebreak?>
<section xml:id="section_securitygroups">
<title>Security groups</title>
<para>Security groups and security group rules allows
@ -917,6 +919,7 @@
</table>
</section>
</section>
<?hard-pagebreak?>
<section xml:id="lbaas_workflow">
<title>Basic Load-Balancer-as-a-Service operations</title>
<note>
@ -994,6 +997,7 @@
</tbody>
</table>
</section>
<?hard-pagebreak?>
<section xml:id="fwaas">
<title>Firewall-as-a-Service</title>
<para>The Firewall-as-a-Service (FWaaS) API is an experimental
@ -1386,6 +1390,7 @@
</note>
</section>
</section>
<?hard-pagebreak?>
<section xml:id="section_allowed_address_pairs">
<title>Allowed-address-pairs</title>
<para>Allowed-address-pairs is an API extension that extends
@ -1433,6 +1438,7 @@
</note>
</section>
</section>
<?hard-pagebreak?>
<section xml:id="section_plugin_specific_extensions">
<title>Plug-in specific extensions</title>
<?dbhtml stop-chunking?>

58
doc/admin-guide-cloud/section_troubleshoot-cinder.xml
View File

@ -3,11 +3,14 @@
xmlns:xi="http://www.w3.org/2001/XInclude" xmlns:xlink="http://www.w3.org/1999/xlink"
version="1.0">
<title>Troubleshoot your cinder installation</title>
<para>This section is intended to help solve some basic and common errors that are encountered
during setup and configuration of Cinder. The focus here is on failed creation of volumes.
The most important thing to know is where to look in case of a failure. There are two log
files that are especially helpful in the case of a volume creation failure. The first is the
<systemitem class="service">cinder-api</systemitem> log, and the second is the <systemitem class="service">cinder-volume</systemitem> log.</para>
<para>This section is intended to help solve some basic and common
errors that are encountered during set up and configuration of
Cinder. The focus here is on failed creation of volumes. The
most important thing to know is where to look in case of a
failure. Two log files are especially helpful when volume
creation fails: <systemitem class="service"
>cinder-api</systemitem> log and <systemitem
class="service">cinder-volume</systemitem> log.</para>
<para>The <systemitem class="service">cinder-api</systemitem> log is useful in determining if you have
endpoint or connectivity issues. If you send a request to
create a volume and it fails, it's a good idea to look here
@ -15,8 +18,9 @@
service. If the request seems to be logged, and there are no
errors or trace-backs then you can move to the <systemitem class="service">cinder-volume</systemitem>
log and look for errors or trace-backs there.</para>
<para>There are some common issues to look out for. The following describes
some common issues hit during configuration and some suggested solutions.</para>
<para>There are some common issues to look out for. The following
describes some common configuration issues with suggested
solutions.</para>
<para><emphasis role="bold"><emphasis role="underline">Create commands are in <systemitem class="service">cinder-api</systemitem> log
with no error</emphasis></emphasis></para>
<para>
@ -48,10 +52,7 @@
simple entry in <filename>/etc/tgt/conf.d</filename>, and you should have created this when you went
through the install guide. If you haven't or you're running into issues, verify
that you have a file <filename>/etc/tgt/conf.d/cinder.conf</filename>.</para>
<para>If the file is not there, you can create it easily by doing the
following:<programlisting>
sudo sh -c "echo 'include /var/lib/cinder/volumes/*' >> /etc/tgt/conf.d/cinder.conf"
</programlisting></para>
<para>If the file is not there, create it, as follows:</para><screen><prompt>$</prompt> <userinput>sudo sh -c "echo 'include /var/lib/cinder/volumes/*' >> /etc/tgt/conf.d/cinder.conf"</userinput></screen>
</listitem>
</itemizedlist>
</para>
@ -60,26 +61,23 @@ sudo sh -c "echo 'include /var/lib/cinder/volumes/*' >> /etc/tgt/conf.d/cinder.c
<para>This is most likely going to be a minor adjustment to your
<filename>nova.conf</filename> file. Make sure that your
<filename>nova.conf</filename> has the following
entry:<programlisting>
volume_api_class=nova.volume.cinder.API
</programlisting></para>
<para>And make certain that you EXPLICITLY set enabled_apis as the default will include
osapi_volume:<programlisting>
enabled_apis=ec2,osapi_compute,metadata
</programlisting>
</para>
entry:<programlisting>volume_api_class=nova.volume.cinder.API </programlisting></para>
<para>Make certain that you explicitly set
<option>enabled_apis</option> because the default includes
<option>osapi_volume</option>:<programlisting>enabled_apis=ec2,osapi_compute,metadata</programlisting></para>
<para><emphasis role="bold">Failed to create iscsi target error in the <filename>cinder-volume.log</filename></emphasis></para>
<programlisting language="bash">2013-03-12 01:35:43 1248 TRACE cinder.openstack.common.rpc.amqp ISCSITargetCreateFailed: Failed to create iscsi target for volume volume-137641b2-af72-4a2f-b243-65fdccd38780.
</programlisting>
<para>You may see this error in <filename>cinder-volume.log</filename> after trying to create a volume that is 1 GB. To fix this issue:
</para>
<para>Change content of the <filename>/etc/tgt/targets.conf</filename> from "include /etc/tgt/conf.d/*.conf" to:
include /etc/tgt/conf.d/cinder_tgt.conf:</para>
<programlisting language="bash">
include /etc/tgt/conf.d/cinder_tgt.conf
include /etc/tgt/conf.d/cinder.conf
default-driver iscsi</programlisting>
<programlisting language="bash">2013-03-12 01:35:43 1248 TRACE cinder.openstack.common.rpc.amqp ISCSITargetCreateFailed: Failed to create iscsi target for volume volume-137641b2-af72-4a2f-b243-65fdccd38780.</programlisting>
<para>You might see this error in
<filename>cinder-volume.log</filename> after trying to
create a volume that is 1 GB. </para>
<para>To fix this issue, change the content of the
<filename>/etc/tgt/targets.conf</filename> from
<literal>include /etc/tgt/conf.d/*.conf</literal> to
<literal>include
/etc/tgt/conf.d/cinder_tgt.conf</literal>, as follows:</para>
<programlisting language="bash">include /etc/tgt/conf.d/cinder_tgt.conf
include /etc/tgt/conf.d/cinder.conf
default-driver iscsi</programlisting>
<para>Then restart tgt and <literal>cinder-*</literal> services so they pick up the new configuration.</para>
</section>

1327
doc/common/ch_getstart.xml
View File

File diff suppressed because it is too large Load Diff

287
doc/common/ch_support.xml
View File

@ -1,131 +1,166 @@
<?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="ch_support-and-troubleshooting">
<title>Support</title>
<para>Online resources aid in supporting OpenStack and there
are many community members willing and able to answer
questions and help with bug suspicions. We are constantly
improving and adding to the main features of OpenStack,
but if you have any problems, do not hesitate to ask.
Here are some ideas for supporting OpenStack and
troubleshooting your existing installations.</para>
<section xml:id="community-support">
<title>Community Support</title>
<para>Here are some places you can locate others who want to
help.</para>
<simplesect>
<title>ask.openstack.org</title>
<para>During setup or testing, you may have questions
about how to do something, or end up in a situation
where you can't seem to get a feature to work
correctly. The ask.openstack.org site is available for
questions and answers. When visiting the Ask site at
<link xlink:href="http://ask.openstack.org"
>http://ask.openstack.org</link>, it is usually
good to at least scan over recently asked questions to
see if your question has already been answered. If
that is not the case, then proceed to adding a new
question. Be sure you give a clear, concise summary in
the title and provide as much detail as possible in
the description. Paste in your command output or stack
traces, link to screenshots, and so on.</para>
</simplesect>
<simplesect><title>OpenStack mailing lists</title>
<para>Posting your question or scenario to the OpenStack
mailing list is a great way to get answers and
insights. You can learn from and help others who may
have the same scenario as you. Go to <link
xlink:href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack"
>http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack</link> to
subscribe or view the archives.
You may be interested in the other mailing lists for
specific projects or development - these can be found
<link
xlink:href="http://wiki.openstack.org/MailingLists"
>on the wiki</link>. A description of all the
additional mailing lists is available at
<link
xlink:href="http://wiki.openstack.org/MailingLists">http://wiki.openstack.org/MailingLists</link>.</para></simplesect><simplesect>
xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
xml:id="ch_support-and-troubleshooting">
<?dbhtml stop-chunking?>
<title>Community Support</title>
<para>Many OpenStack community members can answer questions and
help with bug suspicions. We are constantly improving and
adding to the main features of OpenStack, but if you have any
problems, do not hesitate to ask. Use the following resources
to get OpenStack support and troubleshoot your existing
installations.</para>
<simplesect>
<title>ask.openstack.org</title>
<para>During set up or testing, you might have questions about
how to do something or be in a situation where a feature
does not work correctly. Use the <link
xlink:href="ask.openstack.org"
>ask.openstack.org</link> site to ask questions and
get answers. When you visit the <link
xlink:href="http://ask.openstack.org"
>http://ask.openstack.org</link> site, scan the recently asked questions to see whether
your question was already answered. If not, ask a new question. Be sure
to give a clear, concise summary in the title and provide
as much detail as possible in the description. Paste in
your command output or stack traces, link to screen shots,
and so on.</para>
</simplesect>
<simplesect>
<title>OpenStack mailing lists</title>
<para>A great way to get answers and insights is to post your
question or scenario to the OpenStack mailing list. You
can learn from and help others who might have the same
scenario as you. To subscribe or view the archives, go to
<link
xlink:href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack"
>http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack</link>.
You might be interested in the other mailing lists for
specific projects or development, which you can find <link
xlink:href="http://wiki.openstack.org/MailingLists">on
the wiki</link>. A description of all mailing lists is
available at <link
xlink:href="http://wiki.openstack.org/MailingLists"
>http://wiki.openstack.org/MailingLists</link>.</para>
</simplesect>
<simplesect>
<title>The OpenStack Wiki search</title>
<para>The <link xlink:href="http://wiki.openstack.org/">OpenStack wiki</link> contains content
on a broad range of topics, but some of it sits a bit below the surface. Fortunately, the wiki
search feature is very powerful in that it can do both searches by title and by content. If
you are searching for specific information, say about "networking" or "api" for nova, you can
find lots of content using the search feature. More is being added all the time, so be sure to
check back often. You can find the search box in the upper right hand corner of any OpenStack wiki
page.</para></simplesect>
<simplesect><title>The Launchpad Bugs area</title>
<para>So you think you've found a bug. That's great! Seriously, it is. The OpenStack community
values your setup and testing efforts and wants your feedback. To log a bug you must
have a Launchpad account, so sign up at https://launchpad.net/+login if you do not
already have a Launchpad ID. You can view existing bugs and report your bug in the
Launchpad Bugs area. It is suggested that you first use the search facility to see
if the bug you found has already been reported (or even better, already fixed). If
it still seems like your bug is new or unreported then it is time to fill out a bug
report.</para>
<para>Some tips:</para>
<itemizedlist><listitem><para>Give a clear, concise summary!</para></listitem>
<listitem><para>Provide as much detail as possible
in the description. Paste in your command output or stack traces, link to
screenshots, etc.</para></listitem>
<listitem><para>Be sure to include what version of the software you are using.
This is especially critical if you are using a development branch eg. "Grizzly
release" vs git commit bc79c3ecc55929bac585d04a03475b72e06a3208.</para></listitem>
<listitem><para>Any deployment specific info is helpful as well, such as Ubuntu
12.04, multi-node install.</para></listitem> </itemizedlist>
<para>The Launchpad Bugs areas are available here - :</para>
<itemizedlist>
<listitem><para>OpenStack Compute: <link
xlink:href="https://bugs.launchpad.net/nova"
>https://bugs.launchpad.net/nova</link></para></listitem>
<listitem><para>OpenStack Object Storage: <link
xlink:href="https://bugs.launchpad.net/swift"
>https://bugs.launchpad.net/swift</link></para></listitem>
<listitem><para>OpenStack Image Delivery and Registration: <link
xlink:href="https://bugs.launchpad.net/glance"
>https://bugs.launchpad.net/glance</link></para></listitem>
<listitem><para>OpenStack Identity: <link
xlink:href="https://bugs.launchpad.net/keystone"
>https://bugs.launchpad.net/keystone</link></para></listitem>
<listitem><para>OpenStack Dashboard: <link
xlink:href="https://bugs.launchpad.net/horizon"
>https://bugs.launchpad.net/horizon</link></para></listitem>
<listitem><para>OpenStack Network Connectivity: <link
xlink:href="https://bugs.launchpad.net/neutron"
>https://bugs.launchpad.net/neutron</link></para></listitem>
<listitem><para>OpenStack Orchestration: <link
xlink:href="https://bugs.launchpad.net/heat"
>https://bugs.launchpad.net/heat</link></para></listitem>
<listitem><para>OpenStack Metering: <link
xlink:href="https://bugs.launchpad.net/ceilometer"
>https://bugs.launchpad.net/ceilometer</link></para></listitem>
</itemizedlist>
</simplesect>
<simplesect>
<title>The OpenStack IRC channel</title>
<para>The OpenStack community lives and breathes in the
#openstack IRC channel on the Freenode network. You
can come by to hang out, ask questions, or get
immediate feedback for urgent and pressing issues. To
get into the IRC channel you need to install an IRC
client or use a browser-based client by going to
http://webchat.freenode.net/. You can also use
Colloquy (Mac OS X, http://colloquy.info/) or mIRC
(Windows, http://www.mirc.com/) or XChat (Linux). When
you are in the IRC channel and want to share code or
command output, the generally accepted method is to
use a Paste Bin, the OpenStack project has one at
http://paste.openstack.org. Just paste your longer
amounts of text or logs in the web form and you get a
URL you can then paste into the channel. The OpenStack
IRC channel is: #openstack on irc.freenode.net. A list
of all the OpenStack-related IRC channels is at <link
xlink:href="https://wiki.openstack.org/wiki/IRC"
>https://wiki.openstack.org/wiki/IRC</link>.</para>
</simplesect>
</section>
<para>The <link xlink:href="http://wiki.openstack.org/"
>OpenStack wiki</link> contains content on a broad
range of topics but some of it sits a bit below the
surface. Fortunately, the wiki search feature enables you
to search by title or content. If you search for specific
information, such as about networking or nova, you can
find lots of content. More is being added all the time, so
be sure to check back often. You can find the search box
in the upper right corner of any OpenStack wiki
page.</para>
</simplesect>
<simplesect>
<title>The Launchpad Bugs area</title>
<para>So you think you've found a bug. That's great!
Seriously, it is. The OpenStack community values your set
up and testing efforts and wants your feedback. To log a
bug, you must sign up for a Launchpad account at <link
xlink:href="https://launchpad.net/+login"
>https://launchpad.net/+login</link>. You can view
existing bugs and report bugs in the Launchpad Bugs area.
Use the search feature to determine whether the bug was
already reported (or even better, already fixed). If it
still seems like your bug is unreported, fill out a bug
report.</para>
<para>Some tips:</para>
<itemizedlist>
<listitem>
<para>Give a clear, concise summary!</para>
</listitem>
<listitem>
<para>Provide as much detail as possible in the
description. Paste in your command output or stack
traces, link to screen shots, and so on.</para>
</listitem>
<listitem>
<para>Be sure to include the software version that you are using,
especially if you are using a development branch,
such as, <literal>"Grizzly release" vs git commit
bc79c3ecc55929bac585d04a03475b72e06a3208</literal>.</para>
</listitem>
<listitem>
<para>Any deployment specific information is helpful,
such as Ubuntu 12.04 or multi-node install.</para>
</listitem>
</itemizedlist>
<para>The Launchpad Bugs areas are available here:</para>
<itemizedlist>
<listitem>
<para><link
xlink:href="https://bugs.launchpad.net/nova"
>Bugs: OpenStack Compute (nova)</link></para>
</listitem>
<listitem>
<para><link
xlink:href="https://bugs.launchpad.net/swift"
>Bugs : OpenStack Object Storage (swift)</link></para>
</listitem>
<listitem>
<para><link
xlink:href="https://bugs.launchpad.net/glance"
>Bugs : OpenStack Image Service (glance)</link></para>
</listitem>
<listitem>
<para><link
xlink:href="https://bugs.launchpad.net/keystone"
>Bugs : OpenStack Identity (keystone)</link></para>
</listitem>
<listitem>
<para><link
xlink:href="https://bugs.launchpad.net/horizon"
>Bugs : OpenStack Dashboard (horizon)</link></para>
</listitem>
<listitem>
<para><link
xlink:href="https://bugs.launchpad.net/neutron"
>Bugs : OpenStack Networking (neutron)</link></para>
</listitem>
<listitem>
<para><link
xlink:href="https://bugs.launchpad.net/heat"
>Bugs : OpenStack Orchestration (heat)</link></para>
</listitem>
<listitem>
<para><link
xlink:href="https://bugs.launchpad.net/ceilometer"
>Bugs : OpenStack Metering (ceilometer)</link></para>
</listitem>
</itemizedlist>
</simplesect>
<simplesect>
<title>The OpenStack IRC channel</title>
<para>The OpenStack community lives and breathes in the
#openstack IRC channel on the Freenode network. You can
come by to hang out, ask questions, or get immediate
feedback for urgent and pressing issues. To get into the
IRC channel, you must install an IRC client or use a
browser-based client by going to <link
xlink:href="http://webchat.freenode.net"
>http://webchat.freenode.net/</link>. You can also use
Colloquy (Mac OS X, <link
xlink:href="http://colloquy.info/"
>http://colloquy.info/</link>), mIRC (Windows, <link
xlink:href="http://www.mirc.com/"
>http://www.mirc.com/</link>), or XChat (Linux). When
you are in the IRC channel and want to share code or
command output, the generally accepted method is to use a
Paste Bin. The OpenStack project has one at <link
xlink:href="http://paste.openstack.org"
>http://paste.openstack.org</link>. Just paste your
longer amounts of text or logs in the web form and you get
a URL you can paste into the channel. The OpenStack IRC
channel is: <literal>#openstack</literal> on
<literal>irc.freenode.net</literal>. You can find a
list of all OpenStack-related IRC channels at <link
xlink:href="https://wiki.openstack.org/wiki/IRC"
>https://wiki.openstack.org/wiki/IRC</link>.</para>
</simplesect>
</chapter>

15
doc/common/section_about-object-storage.xml
View File

@ -4,11 +4,14 @@
xmlns:xlink="http://www.w3.org/1999/xlink"
version="5.0"
xml:id="ch_introduction-to-openstack-object-storage">
<title>Introduction to OpenStack Object Storage</title>
<para>OpenStack Object Storage is a scalable object storage system - it is not a file system in the
traditional sense. You will not be able to mount this system like traditional SAN or NAS volumes.
Since OpenStack Object Storage is a different way of thinking when it comes to storage, take a few
moments to review the key concepts in the developer documentation at
<link xlink:href="http://docs.openstack.org/developer/swift/">docs.openstack.org/developer/swift/</link>.</para>
<title>Introduction to Object Storage</title>
<para>Object Storage is a scalable object storage system - it is
not a file system in the traditional sense. You cannot mount
this system like traditional SAN or NAS volumes. Because Object
Storage requires a different way of thinking when it comes to
storage, take a few moments to review the key concepts in the
developer documentation at <link
xlink:href="http://docs.openstack.org/developer/swift/"
>docs.openstack.org/developer/swift/</link>.</para>
<!-- TODO Is this really the best we can do?-->
</section>

34
doc/common/section_dashboard-configure-http.xml Normal file
View File

@ -0,0 +1,34 @@
<?xml version="1.0" encoding="UTF-8"?>
<section xml:id="configure-dashboard-http"
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>Configure the dashboard for HTTP</title>
<?dbhtml stop-chunking?>
<para>You can configure the dashboard for a simple HTTP deployment. The standard installation
uses a non-encrypted HTTP channel.</para>
<procedure xml:id="dashboard-config-http">
<step>
<para>Specify the host for your OpenStack Identity
Service endpoint in the
<filename>/etc/openstack-dashboard/local_settings.py</filename>
file with the <literal>OPENSTACK_HOST</literal>
setting.</para>
<para>The following example shows this setting:</para>
<programlisting language="python"><?db-font-size 65%?><xi:include parse="text" href="samples/local_settings.py"/></programlisting>
<para>The service catalog configuration in the
Identity Service determines whether a service appears
in the dashboard. For the full listing, see
<link
xlink:href="http://docs.openstack.org/developer/horizon/topics/settings.html"
>Horizon Settings and
Configuration</link>.</para>
</step>
<step>
<para>Restart Apache and memcached:</para>
<screen><prompt>#</prompt> <userinput>service apache2 restart</userinput>
<prompt>#</prompt> <userinput>service memcached restart</userinput></screen>
</step>
</procedure>
</section>

94
doc/common/section_dashboard-configure-https.xml Normal file
View File

@ -0,0 +1,94 @@
<?xml version="1.0" encoding="UTF-8"?>
<section xml:id="dashboard-config-https" 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>Configure the dashboard for HTTPS</title>
<para>You can configure the dashboard for a secured HTTPS deployment. While the standard installation
uses a non-encrypted HTTP channel, you can enable SSL support
for the dashboard.</para>
<procedure>
<para>The following example uses the domain,
"http://openstack.example.com." Use a domain that fits
your current setup.</para>
<step>
<para>In<filename>/etc/openstack-dashboard/local_settings.py</filename>
update the following
directives:</para><programlisting>USE_SSL = True
CSRF_COOKIE_SECURE = True
SESSION_COOKIE_SECURE = True
SESSION_COOKIE_HTTPONLY = True</programlisting>
<para>The first option is required to enable HTTPS.
The other recommended settings defend against
cross-site scripting and require HTTPS.</para>
</step>
<step>
<para>Edit
<filename>/etc/apache2/ports.conf</filename>
and add the following line:</para>
<programlisting>NameVirtualHost *:443</programlisting>
</step>
<step>
<para>Edit
<filename>/etc/apache2/conf.d/openstack-dashboard.conf:</filename></para>
<para>Before:</para>
<programlisting><?db-font-size 65%?>WSGIScriptAlias / /usr/share/openstack-dashboard/openstack_dashboard/wsgi/django.wsgi
WSGIDaemonProcess horizon user=www-data group=www-data processes=3 threads=10
Alias /static /usr/share/openstack-dashboard/openstack_dashboard/static/
&lt;Directory /usr/share/openstack-dashboard/openstack_dashboard/wsgi&gt;
Order allow,deny
Allow from all
&lt;/Directory&gt;</programlisting>
<para>After:</para>
<programlisting><?db-font-size 65%?>&lt;VirtualHost *:80&gt;
ServerName openstack.example.com
&lt;IfModule mod_rewrite.c&gt;
RewriteEngine On
RewriteCond %{HTTPS} off
RewriteRule (.*) https://%{HTTP_HOST}%{REQUEST_URI}
&lt;/IfModule&gt;
&lt;IfModule !mod_rewrite.c&gt;
RedirectPermanent / https://openstack.example.com
&lt;/IfModule&gt;
&lt;/VirtualHost&gt;
&lt;VirtualHost *:443&gt;
ServerName openstack.example.com
SSLEngine On
# Remember to replace certificates and keys with valid paths in your environment
SSLCertificateFile /etc/apache2/SSL/openstack.example.com.crt
SSLCACertificateFile /etc/apache2/SSL/openstack.example.com.crt
SSLCertificateKeyFile /etc/apache2/SSL/openstack.example.com.key
SetEnvIf User-Agent &quot;.*MSIE.*&quot; nokeepalive ssl-unclean-shutdown
# HTTP Strict Transport Security (HSTS) enforces that all communications
# with a server go over SSL. This mitigates the threat from attacks such
# as SSL-Strip which replaces links on the wire, stripping away https prefixes
# and potentially allowing an attacker to view confidential information on the
# wire
Header add Strict-Transport-Security "max-age=15768000"
WSGIScriptAlias / /usr/share/openstack-dashboard/openstack_dashboard/wsgi/django.wsgi
WSGIDaemonProcess horizon user=www-data group=www-data processes=3 threads=10
Alias /static /usr/share/openstack-dashboard/openstack_dashboard/static/
&lt;Directory /usr/share/openstack-dashboard/openstack_dashboard/wsgi&gt;
Order allow,deny
Allow from all
&lt;/Directory&gt;
&lt;/VirtualHost&gt;</programlisting>
<para>In this configuration, Apache listens on the
port 443 and redirects all the hits to the HTTPS
protocol for all the non-secured requests. The secured
section defines the private key, public key, and
certificate to use.</para>
</step>
<step>
<para>Restart Apache and memcached:</para>
<screen><prompt>#</prompt> <userinput>service apache2 restart</userinput>
<prompt>#</prompt> <userinput>service memcached restart</userinput></screen>
<para>If you try to access the dashboard through HTTP,
the browser redirects you to the HTTPS page.</para>
</step>
</procedure></section>

21
doc/common/section_dashboard-configure-vnc-window.xml Normal file
View File

@ -0,0 +1,21 @@
<?xml version="1.0" encoding="UTF-8"?>
<section xml:id="vnc-window"
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>Change the size of the dashboard VNC window</title>
<para>The <filename>_detail_vnc.html</filename> file defines
the size of the VNC window. To change the window size, edit
this file.</para>
<procedure xml:id="adjust-vnc-window">
<step>
<para>Edit
<filename>/usr/share/pyshared/horizon/dashboards/nova/instances/templates/instances/_detail_vnc.html.</filename></para>
</step>
<step>
<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>
</step>
</procedure>
</section>

141
doc/common/section_dashboard-configure.xml
View File

@ -5,134 +5,15 @@
xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0">
<title>Configure the dashboard</title>
<?dbhtml stop-chunking?>
<para>You can configure the dashboard for a simple HTTP deployment
or a secured HTTPS deployment. While the standard installation
uses a non-encrypted HTTP channel, you can enable SSL support
for the dashboard.</para>
<procedure xml:id="dashboard-config-http">
<title>To configure the dashboard for HTTP</title>
<step>
<para>Specify the host for your OpenStack Identity
Service endpoint in the
<filename>/etc/openstack-dashboard/local_settings.py</filename>
file with the <literal>OPENSTACK_HOST</literal>
setting.</para>
<para>The following example shows this setting:</para>
<programlisting language="python"><?db-font-size 65%?><xi:include parse="text" href="samples/local_settings.py"/></programlisting>
<para>The service catalog configuration in the
Identity Service determines whether a service appears
in the dashboard. For the full listing, see
<link
xlink:href="http://docs.openstack.org/developer/horizon/topics/settings.html"
>Horizon Settings and
Configuration</link>.</para>
</step>
<step>
<para>Restart Apache and memcached:</para>
<screen><prompt>#</prompt> <userinput>service apache2 restart</userinput>
<prompt>#</prompt> <userinput>service memcached restart</userinput></screen>
</step>
</procedure>
<procedure xml:id="dashboard-config-https">
<title>To configure the dashboard for HTTPS</title>
<para>The following example uses the domain,
"http://openstack.example.com." Use a domain that fits
your current setup.</para>
<step>
<para>In<filename>/etc/openstack-dashboard/local_settings.py</filename>
update the following
directives:<programlisting>USE_SSL = True
CSRF_COOKIE_SECURE = True
SESSION_COOKIE_SECURE = True
SESSION_COOKIE_HTTPONLY = True</programlisting></para>
<para>The first option is required to enable HTTPS.
The other recommended settings defend against
cross-site scripting and require HTTPS.</para>
</step>
<step>
<para>Edit
<filename>/etc/apache2/ports.conf</filename>
and add the following line:</para>
<programlisting>NameVirtualHost *:443</programlisting>
</step>
<step>
<para>Edit
<filename>/etc/apache2/conf.d/openstack-dashboard.conf:</filename></para>
<para>Before:</para>
<programlisting><?db-font-size 65%?>WSGIScriptAlias / /usr/share/openstack-dashboard/openstack_dashboard/wsgi/django.wsgi
WSGIDaemonProcess horizon user=www-data group=www-data processes=3 threads=10
Alias /static /usr/share/openstack-dashboard/openstack_dashboard/static/
&lt;Directory /usr/share/openstack-dashboard/openstack_dashboard/wsgi&gt;
Order allow,deny
Allow from all
&lt;/Directory&gt;</programlisting>
<para>After:</para>
<programlisting><?db-font-size 65%?>&lt;VirtualHost *:80&gt;
ServerName openstack.example.com
&lt;IfModule mod_rewrite.c&gt;
RewriteEngine On
RewriteCond %{HTTPS} off
RewriteRule (.*) https://%{HTTP_HOST}%{REQUEST_URI}
&lt;/IfModule&gt;
&lt;IfModule !mod_rewrite.c&gt;
RedirectPermanent / https://openstack.example.com
&lt;/IfModule&gt;
&lt;/VirtualHost&gt;
&lt;VirtualHost *:443&gt;
ServerName openstack.example.com
SSLEngine On
# Remember to replace certificates and keys with valid paths in your environment
SSLCertificateFile /etc/apache2/SSL/openstack.example.com.crt
SSLCACertificateFile /etc/apache2/SSL/openstack.example.com.crt
SSLCertificateKeyFile /etc/apache2/SSL/openstack.example.com.key
SetEnvIf User-Agent &quot;.*MSIE.*&quot; nokeepalive ssl-unclean-shutdown
# HTTP Strict Transport Security (HSTS) enforces that all communications
# with a server go over SSL. This mitigates the threat from attacks such
# as SSL-Strip which replaces links on the wire, stripping away https prefixes
# and potentially allowing an attacker to view confidential information on the
# wire
Header add Strict-Transport-Security "max-age=15768000"
WSGIScriptAlias / /usr/share/openstack-dashboard/openstack_dashboard/wsgi/django.wsgi
WSGIDaemonProcess horizon user=www-data group=www-data processes=3 threads=10
Alias /static /usr/share/openstack-dashboard/openstack_dashboard/static/
&lt;Directory /usr/share/openstack-dashboard/openstack_dashboard/wsgi&gt;
Order allow,deny
Allow from all
&lt;/Directory&gt;
&lt;/VirtualHost&gt;</programlisting>
<para>In this configuration, Apache listens on the
port 443 and redirects all the hits to the HTTPS
protocol for all the non-secured requests. The secured
section defines the private key, public key, and
certificate to use.</para>
</step>
<step>
<para>Restart Apache and memcached:</para>
<screen><prompt>#</prompt> <userinput>service apache2 restart</userinput>
<prompt>#</prompt> <userinput>service memcached restart</userinput></screen>
<para>If you try to access the dashboard through HTTP,
the browser redirects you to the HTTPS page.</para>
</step>
</procedure>
<procedure xml:id="adjust-vnc-window">
<title>To adjust the dimensions of the VNC window in the
Dashboard</title>
<para>The <filename>_detail_vnc.html</filename> file defines
the size of the VNC window. To change the window size, edit
this file.</para>
<step>
<para>Edit
<filename>/usr/share/pyshared/horizon/dashboards/nova/instances/templates/instances/_detail_vnc.html.</filename></para>
</step>
<step>
<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>
</step>
</procedure>
<para>You can configure the dashboard for a simple HTTP
deployment. </para>
<para>You can configure the dashboard for a secured HTTPS
deployment. While the standard installation uses a
non-encrypted HTTP channel, you can enable SSL support for the
dashboard.</para>
<para>Also, you can configure the size of the VNC window in the
dashboard. </para>
<xi:include href="section_dashboard-configure-http.xml"/>
<xi:include href="section_dashboard-configure-https.xml"/>
<xi:include href="section_dashboard-configure-vnc-window.xml"/>
</section>

91
doc/common/section_dashboard-install.xml
View File

@ -5,93 +5,99 @@
<!ENTITY mdash "&#x2014;">
<!ENTITY hellip "&#x2026;">
]>
<section xml:id="installing-openstack-dashboard"
<section xml:id="install_dashboard"
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>Install and configure the dashboard</title>
<?dbhtml stop-chunking?>
<title>Install the dashboard</title>
<para>Before you can install and configure the dashboard, meet the
requirements in <xref linkend="dashboard-system-requirements"/>.</para>
<para>For more information about how to deploy the dashboard, see <link
requirements in <xref linkend="dashboard-system-requirements"
/>.</para>
<para>For more information about how to deploy the dashboard, see
<link
xlink:href="http://docs.openstack.org/developer/horizon/topics/deployment.html"
>Deploying Horizon</link>.</para>
<procedure>
<title>To install the dashboard</title>
<step>
<para>Install the dashboard on the node that can contact the
Identity Service as root:</para>
<screen os="ubuntu"><prompt>#</prompt> <userinput>apt-get install memcached libapache2-mod-wsgi openstack-dashboard</userinput></screen>
<screen os="rhel;centos;fedora"><prompt>#</prompt> <userinput>yum install memcached python-memcached mod_wsgi openstack-dashboard</userinput></screen>
<screen os="opensuse"><prompt>#</prompt> <userinput>zypper install memcached python-python-memcached apache2-mod_wsgi openstack-dashboard</userinput></screen>
<para>Install the dashboard on the node that can contact
the Identity Service as root:</para>
<screen os="ubuntu" language="bash"><prompt>#</prompt> <userinput>apt-get install memcached libapache2-mod-wsgi openstack-dashboard</userinput></screen>
<screen os="rhel;centos;fedora" language="bash"><prompt>#</prompt> <userinput>yum install memcached python-memcached mod_wsgi openstack-dashboard</userinput></screen>
<screen os="opensuse" language="bash"><prompt>#</prompt> <userinput>zypper install memcached python-python-memcached apache2-mod_wsgi openstack-dashboard</userinput></screen>
</step>
<step>
<para>Modify the value of
<literal>CACHES['default']['LOCATION']</literal> in
<filename os="ubuntu"
<literal>CACHES['default']['LOCATION']</literal>
in <filename os="ubuntu"
>/etc/openstack-dashboard/local_settings.py</filename><filename
os="centos;fedora;rhel"
>/etc/openstack-dashboard/local_settings</filename><filename
os="opensuse">/usr/share/openstack-dashboard/openstack_dashboard/local/local_settings.py</filename>
to match the ones set in <filename os="ubuntu"
os="opensuse"
>/usr/share/openstack-dashboard/openstack_dashboard/local/local_settings.py</filename>
to match the ones set in <filename os="ubuntu"
>/etc/memcached.conf</filename><filename
os="centos;fedora;rhel;opensuse"
>/etc/sysconfig/memcached.conf</filename>.</para>
<para>Open <filename os="ubuntu"
>/etc/openstack-dashboard/local_settings.py</filename>
<filename os="centos;fedora;rhel"
>/etc/openstack-dashboard/local_settings</filename> and look
for this line:</para>
<programlisting language="bash" linenumbering="unnumbered">CACHES = {
'default': {
'BACKEND' : 'django.core.cache.backends.memcached.MemcachedCache',
'LOCATION' : '127.0.0.1:11211'
}
}</programlisting>
<filename os="centos;fedora;rhel"
>/etc/openstack-dashboard/local_settings</filename>
and look for this line:</para>
<programlisting language="bash" linenumbering="unnumbered"><?db-font-size 75%?>CACHES = {
'default': {
'BACKEND' : 'django.core.cache.backends.memcached.MemcachedCache',
'LOCATION' : '127.0.0.1:11211'
}
}</programlisting>
<note xlink:href="#installing-openstack-dashboard"
xlink:title="Notes">
<title>Notes</title>
<itemizedlist>
<listitem>
<para>The address and port must match the ones set in
<filename os="ubuntu"
<para>The address and port must match the ones
set in <filename os="ubuntu"
>/etc/memcached.conf</filename><filename
os="centos;fedora;rhel;opensuse"
>/etc/sysconfig/memcached</filename>.</para>
<para>If you change the memcached settings, you must
restart the Apache web server for the changes to
take effect.</para>
<para>If you change the memcached settings,
you must restart the Apache web server for
the changes to take effect.</para>
</listitem>
<listitem>
<para>You can use options other than memcached option
for session storage. Set the session back-end
through the <parameter>SESSION_ENGINE</parameter>
<para>You can use options other than memcached
option for session storage. Set the
session back-end through the
<parameter>SESSION_ENGINE</parameter>
option.</para>
</listitem>
<listitem>
<para>To change the timezone, use the dashboard or edit
the <filename os="centos;fedora;rhel"
<para>To change the timezone, use the
dashboard or edit the <filename
os="centos;fedora;rhel"
>/etc/openstack-dashboard/local_settings</filename><filename
os="ubuntu"
>/etc/openstack-dashboard/local_settings.py</filename><filename
os="opensuse"
>/usr/share/openstack-dashboard/openstack_dashboard/local/local_settings.py</filename>
file.</para>
<para>Change the following parameter: <code>TIME_ZONE =
"UTC"</code>
<para>Change the following parameter:
<code>TIME_ZONE = "UTC"</code>
</para>
</listitem>
</itemizedlist>
</note>
</step>
<step>
<para>Make sure that the web browser on your local machine supports
HTML5.</para>
<para>Make sure that the web browser on your local machine
supports HTML5.</para>
<para>Enable cookies and JavaScript.</para>
<note>
<para>To use the VNC client with the dashboard, the browser must
support HTML5 Canvas and HTML5 WebSockets.</para>
<para>For details about browsers that support noVNC, see <link
<para>To use the VNC client with the dashboard, the
browser must support HTML5 Canvas and HTML5
WebSockets.</para>
<para>For details about browsers that support noVNC,
see <link
xlink:href="https://github.com/kanaka/noVNC/blob/master/README.md"
>https://github.com/kanaka/noVNC/blob/master/README.md</link>,
and <link
@ -99,6 +105,5 @@
>https://github.com/kanaka/noVNC/wiki/Browser-support</link>.</para>
</note>
</step>
</procedure>
<xi:include href="section_dashboard-configure.xml"/>
</procedure>
</section>

2
doc/common/section_dashboard-system-reqs.xml
View File

@ -34,7 +34,7 @@
might differ by platform.</para>
</listitem>
</itemizedlist>
<para>Then, <link linkend="installing-openstack-dashboard"
<para>Then, <link linkend="ch_install-dashboard"
>install and configure the dashboard</link> on a node that
can contact the Identity Service.</para>
<para>Provide users with the following information so that they

18
doc/common/section_dashboard_customizing.xml
View File

@ -15,13 +15,14 @@
<para>Canonical also provides an
<literal>openstack-dashboard-ubuntu-theme</literal>
package that brands the Python-based Django interface.</para>
<para>The following example shows a customized dashboard with
<!-- The following diagrams are sized incorrectly and will add back later -->
<!--<para>The following example shows a customized dashboard with
custom colors, logo, and site title:</para>
<mediaobject>
<imageobject role="fo">
<imagedata
fileref="figures/Login-OpenStack-Dashboard.png"
format="PNG" scale="60"/>
format="PNG" scale="40"/>
</imageobject>
<imageobject role="html">
<imagedata
@ -33,16 +34,15 @@
<imageobject role="fo">
<imagedata
fileref="figures/Flavors-TGen-Cloud-Dashboard.png"
format="PNG" scale="60"/>
format="PNG" scale="40"/>
</imageobject>
<imageobject role="html">
<imagedata
fileref="figures/Flavors-TGen-Cloud-Dashboard.png"
format="PNG"/>
</imageobject>
</mediaobject>
</mediaobject>-->
<procedure>
<title>To customize the dashboard:</title>
<step>
<para>Create a graphical logo with a transparent
background. The text <literal>TGen Cloud</literal> in
@ -76,7 +76,7 @@
appropriate, though the relative directory paths
should be the same. The following example file shows
you how to customize your CSS
file:<programlisting><?db-font-size 65%?>/*
file:</para><programlisting><?db-font-size 65%?>/*
* New theme colors for dashboard that override the defaults:
* dark blue: #355796 / rgb(53, 87, 150)
* light blue: #BAD3E1 / rgb(186, 211, 225)
@ -108,7 +108,7 @@ border: none;
box-shadow: none;
background-color: #BAD3E1 !important;
text-decoration: none;
}</programlisting></para>
}</programlisting>
</step>
<step>
<para>Open the following HTML template in an editor:
@ -116,12 +116,12 @@ text-decoration: none;
</step>
<step>
<para>Add a line to include your
<filename>custom.css</filename> file:
<filename>custom.css</filename> file:</para>
<programlisting><?db-font-size 65%?>...
&lt;link href='{{ STATIC_URL }}bootstrap/css/bootstrap.min.css' media='screen' rel='stylesheet' /&gt;
&lt;link href='{{ STATIC_URL }}dashboard/css/{% choose_css %}' media='screen' rel='stylesheet' /&gt;
<emphasis>&lt;link href='{{ STATIC_URL }}dashboard/css/custom.css' media='screen' rel='stylesheet' /&gt;</emphasis>
...</programlisting></para>
...</programlisting>
</step>
<step>
<para>Restart apache:</para>

28
doc/common/section_dashboard_sessions.xml
View File

@ -6,9 +6,9 @@
<title>Set up session storage for the dashboard</title>
<para>The dashboard uses <link
xlink:href="https://docs.djangoproject.com/en/dev/topics/http/sessions/"
>Django’s sessions framework</link> to handle user session
data. However, you can use any available session backend. You
customize the session backend through the
>Django sessions framework</link> to handle user session
data. However, you can use any available session back end. You
customize the session back end through the
<literal>SESSION_ENGINE</literal> setting in your
<filename os="centos;fedora;rhel">
/etc/openstack-dashboard/local_settings</filename>
@ -20,7 +20,7 @@
<section xml:id="dashboard-session-local">
<title>Local memory cache</title>
<para>Local memory storage is the quickest and easiest session
backend to set up, as it has no external dependencies
back end to set up, as it has no external dependencies
whatsoever. It has the following significant
drawbacks:</para>
<itemizedlist>
@ -33,11 +33,11 @@
terminates.</para>
</listitem>
</itemizedlist>
<para>The local memory backend is enabled as the default for
<para>The local memory back end is enabled as the default for
Horizon solely because it has no dependencies. It is not
recommended for production use, or even for serious
development work. Enabled by:</para>
<programlisting language="python">SESSION_ENGINE = 'django.contrib.sessions.backends.cache'
<programlisting language="python"><?db-font-size 75%?>SESSION_ENGINE = 'django.contrib.sessions.backends.cache'
CACHES = {
'BACKEND': 'django.core.cache.backends.locmem.LocMemCache'
}</programlisting>
@ -62,7 +62,7 @@ CACHES = {
</listitem>
</itemizedlist>
<para>Enabled by:</para>
<programlisting language="python">SESSION_ENGINE = 'django.contrib.sessions.backends.cache'
<programlisting language="python"><?db-font-size 75%?>SESSION_ENGINE = 'django.contrib.sessions.backends.cache'
CACHES = {
'BACKEND': 'django.core.cache.backends.memcached.MemcachedCache'
'LOCATION': 'my_memcached_host:11211',
@ -82,7 +82,7 @@ CACHES = {
</listitem>
</itemizedlist>
<para>Enabled by:</para>
<programlisting language="python">SESSION_ENGINE = 'django.contrib.sessions.backends.cache'
<programlisting language="python"><?db-font-size 75%?>SESSION_ENGINE = 'django.contrib.sessions.backends.cache'
CACHES = {
"default": {
"BACKEND": "redis_cache.cache.RedisCache",
@ -136,7 +136,7 @@ CACHES = {
<filename os="opensuse"
>/usr/share/openstack-dashboard/openstack_dashboard/local/local_settings.py</filename>
file, change these options:</para>
<programlisting language="python">SESSION_ENGINE = 'django.core.cache.backends.db.DatabaseCache'
<programlisting language="python"><?db-font-size 75%?>SESSION_ENGINE = 'django.core.cache.backends.db.DatabaseCache'
DATABASES = {
'default': {
# Database configuration here
@ -189,20 +189,20 @@ No fixtures found.</computeroutput></screen>
<section xml:id="dashboard-session-cached-database">
<title>Cached database</title>
<para>To mitigate the performance issues of database queries,
you can use the Django cached_db session backend, which
you can use the Django cached_db session back end, which
utilizes both your database and caching infrastructure to
perform write-through caching and efficient retrieval.</para>
<para>Enable this hybrid setting by configuring both your
database and cache, as discussed previously. Then, set the
following value:</para>
<programlisting language="python">SESSION_ENGINE = "django.contrib.sessions.backends.cached_db"</programlisting>
<programlisting language="python"><?db-font-size 75%?>SESSION_ENGINE = "django.contrib.sessions.backends.cached_db"</programlisting>
</section>
<section xml:id="dashboard-session-cookies">
<title>Cookies</title>
<para>If you use Django 1.4 or later, the signed_cookies
backend avoids server load and scaling problems.</para>
<para>This backend stores session data in a cookie, which is
stored by the user’s browser. The backend uses a
back end avoids server load and scaling problems.</para>
<para>This back end stores session data in a cookie, which is
stored by the user’s browser. The back end uses a
cryptographic signing technique to ensure session data is
not tampered with during transport. This is not the same
as encryption; session data is still readable by an

2
doc/common/section_identity-troubleshooting.xml
View File

@ -161,7 +161,7 @@ arg_dict: {}
<parameter>--keystone-user</parameter> and
<parameter>--keystone-group</parameter> parameters,
you get an error, as follows:</para>
<screen><computeroutput>2012-07-31 11:10:53 ERROR [keystone.common.cms] Error opening signing key file
<screen><?db-font-size 75%?><computeroutput>2012-07-31 11:10:53 ERROR [keystone.common.cms] Error opening signing key file
/etc/keystone/ssl/private/signing_key.pem
140380567730016:error:0200100D:system library:fopen:Permission
denied:bss_file.c:398:fopen('/etc/keystone/ssl/private/signing_key.pem','r')

288
doc/common/section_keystone-concepts.xml
View File

@ -5,10 +5,12 @@
xml:id="keystone-concepts">
<?dbhtml stop-chunking?>
<title>Identity Service concepts</title>
<para>The Identity Service performs the following functions:</para>
<para>The Identity Service performs the following
functions:</para>
<itemizedlist spacing="compact">
<listitem>
<para>User management. Tracks users and their permissions.</para>
<para>User management. Tracks users and their
permissions.</para>
</listitem>
<listitem>
<para>Service catalog. Provides a catalog of available
@ -17,55 +19,47 @@
</itemizedlist>
<para>To understand the Identity Service, you must understand the
following concepts:</para>
<variablelist>
<variablelist wordsize="10">
<varlistentry>
<term>User</term>
<term><emphasis role="bold">User</emphasis></term>
<listitem>
<para>Digital representation of a person, system, or service
who uses OpenStack cloud services. Identity authentication
services will validate that incoming request are being made
by the user who claims to be making the call. Users have a
login and may be assigned tokens to access resources. Users
may be directly assigned to a particular tenant and behave
as if they are contained in that tenant.
</para>
<para>Digital representation of a person, system, or
service who uses OpenStack cloud services. The
Identity Service validates that incoming requests
are made by the user who claims to be making the
call. Users have a login and may be assigned
tokens to access resources. Users can be directly
assigned to a particular tenant and behave as if
they are contained in that tenant.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Credentials</term>
<term><emphasis role="bold">Credentials</emphasis></term>
<listitem>
<para>Data that is known only by a user that proves
who they are. In the Identity Service, examples
are:</para>
<itemizedlist>
<listitem>
<para>Username and password</para>
</listitem>
<listitem>
<para>Username and API key</para>
</listitem>
<listitem>
<para>An authentication token provided by the
Identity Service</para>
</listitem>
</itemizedlist>
who they are. In the Identity Service, examples
are: User name and password, user name and API
key, or an authentication token provided by the
Identity Service.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Authentication</term>
<term><emphasis role="bold"
>Authentication</emphasis></term>
<listitem>
<para>The act of confirming the identity of a user.
The Identity Service confirms an incoming request
by validating a set of credentials supplied by the
user. These credentials are initially a username
and password or a username and API key. In
response to these credentials, the Identity
Service issues the user an authentication token,
which the user provides in subsequent requests.</para>
user. </para>
<para>These credentials are initially a user name and
password or a user name and API key. In response
to these credentials, the Identity Service issues
an authentication token to the user, which the
user provides in subsequent requests.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Token</term>
<term><emphasis role="bold">Token</emphasis></term>
<listitem>
<para>An arbitrary bit of text that is used to access
resources. Each token has a scope which describes
@ -82,7 +76,7 @@
</listitem>
</varlistentry>
<varlistentry>
<term>Tenant</term>
<term><emphasis role="bold">Tenant</emphasis></term>
<listitem>
<para>A container used to group or isolate resources
and/or identity objects. Depending on the service
@ -91,16 +85,17 @@
</listitem>
</varlistentry>
<varlistentry>
<term>Service</term>
<term><emphasis role="bold">Service</emphasis></term>
<listitem>
<para>An OpenStack service, such as Compute (Nova),
Object Storage (Swift), or Image Service (Glance).
Provides one or more endpoints through which users
can access resources and perform operations.</para>
can access resources and perform
operations.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Endpoint</term>
<term><emphasis role="bold">Endpoint</emphasis></term>
<listitem>
<para>An network-accessible address, usually described
by URL, from where you access a service. If using
@ -111,7 +106,7 @@
</listitem>
</varlistentry>
<varlistentry>
<term>Role</term>
<term><emphasis role="bold">Role</emphasis></term>
<listitem>
<para>A personality that a user assumes that enables
them to perform a specific set of operations. A
@ -119,28 +114,29 @@
user assuming that role inherits those rights and
privileges.</para>
<para>In the Identity Service, a token that is issued
to a user includes the list of roles that user can
assume. Services that are being called by that
user determine how they interpret the set of roles
a user has and which operations or resources each
role grants access to.</para>
to a user includes the list of roles that user
has. Services that are being called by that user
determine how they interpret the set of roles a
user has and to which operations or resources each
role grants access.</para>
</listitem>
</varlistentry>
</variablelist>
<para>
<mediaobject>
<imageobject role="fo">
<imagedata
fileref="figures/SCH_5002_V00_NUAC-Keystone.png"
format="PNG" scale="50"/>
</imageobject>
<imageobject role="html">
<imagedata
fileref="figures/SCH_5002_V00_NUAC-Keystone.png"
format="PNG" scale="10"/>
</imageobject>
</mediaobject>
</para>
<para>The following diagram shows the Identity Service process
flow:</para>
<mediaobject>
<imageobject role="fo">
<imagedata
fileref="figures/SCH_5002_V00_NUAC-Keystone.png"
format="PNG" scale="40"/>
</imageobject>
<imageobject role="html">
<imagedata
fileref="figures/SCH_5002_V00_NUAC-Keystone.png"
format="PNG" scale="10"/>
</imageobject>
</mediaobject>
<?hard-pagebreak?>
<section xml:id="keystone-user-management">
<title>User management</title>
<para>The main components of Identity user management are: <itemizedlist>
@ -155,15 +151,17 @@
</listitem>
</itemizedlist></para>
<para>A <emphasis>user</emphasis> represents a human user, and
has associated information such as username, password and
email. This example creates a user named "alice":</para>
<screen><prompt>$</prompt> <userinput>keystone user-create --name=alice --pass=mypassword123 --email=alice@example.com</userinput></screen>
has associated information such as user name, password,
and email. This example creates a user named
"alice":</para>
<screen><prompt>$</prompt> <userinput>keystone user-create --name=alice \
--pass=mypassword123 --email=alice@example.com</userinput></screen>
<para>A <emphasis>tenant</emphasis> can be a project, group,
or organization. Whenever you make requests to OpenStack
services, you must specify a tenant. For example, if you
query the Compute service for a list of running instances,
you will receive a list of all of the running instances in
the tenant you specified in your query. This example
you receive a list of all of the running instances in the
tenant that you specified in your query. This example
creates a tenant named "acme":</para>
<screen><prompt>$</prompt> <userinput>keystone tenant-create --name=acme</userinput></screen>
<note>
@ -185,10 +183,11 @@
roles. As far as the Identity service is concerned, a
role is simply a name.</para>
</note>
<?hard-pagebreak?>
<para>The Identity service associates a user with a tenant and
a role. To continue with our previous examples, we may
wish to assign the "alice" user the "compute-user" role in
the "acme" tenant:</para>
a role. To continue with the previous examples, you might
to assign the "alice" user the "compute-user" role in the
"acme" tenant:</para>
<screen><prompt>$</prompt> <userinput>keystone user-list</userinput></screen>
<screen><computeroutput>+--------+---------+-------------------+--------+
| id | enabled | email | name |
@ -209,44 +208,47 @@
+--------+------+---------+</computeroutput></screen>
<screen><prompt>$</prompt> <userinput>keystone user-role-add --user=892585 --role=9a764e --tenant-id=6b8fd2</userinput> </screen>
<para>A user can be assigned different roles in different
tenants: for example, Alice may also have the "admin" role
in the "Cyberdyne" tenant. A user can also be assigned
multiple roles in the same tenant.</para>
tenants: for example, Alice might also have the "admin"
role in the "Cyberdyne" tenant. A user can also be
assigned multiple roles in the same tenant.</para>
<para>The
<filename>/etc/<replaceable>[SERVICE_CODENAME]</replaceable>/policy.json</filename>
file controls what users are allowed to do for a given service.
For example, <filename>/etc/nova/policy.json</filename>
specifies the access policy for the Compute service,
file controls the tasks that users can perform for a given
service. For example,
<filename>/etc/nova/policy.json</filename> specifies
the access policy for the Compute service,
<filename>/etc/glance/policy.json</filename> specifies
the access policy for the Image service, and
<filename>/etc/keystone/policy.json</filename>
specifies the access policy for the Identity service.</para>
specifies the access policy for the Identity
service.</para>
<para>The default <filename>policy.json</filename> files in
the Compute, Identity, and Image service recognize only
the <literal>admin</literal> role: all operations that do
not require the <literal>admin</literal> role will be
accessible by any user that has any role in a tenant.</para>
not require the <literal>admin</literal> role are
accessible by any user that has any role in a
tenant.</para>
<para>If you wish to restrict users from performing operations
in, say, the Compute service, you need to create a role in
the Identity service and then modify
<filename>/etc/nova/policy.json</filename> so that
this role is required for Compute operations.</para>
<?hard-pagebreak?>
<para>For example, this line in
<filename>/etc/nova/policy.json</filename> specifies
that there are no restrictions on which users can create
volumes: if the user has any role in a tenant, they will
be able to create volumes in that tenant.</para>
volumes: if the user has any role in a tenant, they can
create volumes in that tenant.</para>
<programlisting language="json">"volume:create": [],</programlisting>
<para>If we wished to restrict creation of volumes to users
who had the <literal>compute-user</literal> role in a
particular tenant, we would add
<literal>"role:compute-user"</literal>, like so:</para>
<para>To restrict creation of volumes to users who had the
<literal>compute-user</literal> role in a particular
tenant, you would add
<literal>"role:compute-user"</literal>, like
so:</para>
<programlisting language="json">"volume:create": ["role:compute-user"],</programlisting>
<para>
If we wished to restrict all Compute service requests to require
this role, the resulting file would look like:
</para>
<programlisting language="json">{
<para>To restrict all Compute service requests to require this
role, the resulting file would look like:</para>
<programlisting language="json"><?db-font-size 50%?>{
"admin_or_owner": [["role:admin"], ["project_id:%(project_id)s"]],
"default": [["rule:admin_or_owner"]],
@ -363,59 +365,81 @@
</listitem>
</itemizedlist>
<para>The Identity Service also maintains a user that
corresponds to each service (such as, a user named
<emphasis>nova</emphasis>, for the Compute service)
and a special service tenant, which is called
corresponds to each service, such as, a user named
<emphasis>nova</emphasis> for the Compute service, and
a special service tenant called
<emphasis>service</emphasis>.</para>
<para>The commands for creating services and endpoints are
described in a later section.</para>
<para>For information about how to create services and
endpoints, see the <link
xlink:href="http://docs.openstack.org/user-guide-admin/content/index.html"
><citetitle>OpenStack Admin User
Guide</citetitle></link>.</para>
</section>
<?hard-pagebreak?>
<section xml:id="identity-groups">
<title>Groups</title>
<para>
A group is a collection of users.
Administrators can create groups and add users to them.
Then, rather than assign a role to each user individually,
assign a role to the group.
</para>
<para>
Every group is in a domain. Groups were introduced with version 3 of the
Identity API (the Grizzly release of Keystone).
</para>
<para>
Identity API V3 provides the following group-related operations:
</para>
<para>A group is a collection of users. Administrators can
create groups and add users to them. Then, rather than
assign a role to each user individually, assign a role to
the group. Every group is in a domain. Groups were
introduced with version 3 of the Identity API (the Grizzly
release of Keystone).</para>
<para>Identity API V3 provides the following group-related
operations:</para>
<itemizedlist>
<listitem><para>Create a group</para></listitem>
<listitem><para>Delete a group</para></listitem>
<listitem><para>Update a group (change its name or description)</para></listitem>
<listitem><para>Add a user to a group</para></listitem>
<listitem><para>Remove a user from a group</para></listitem>
<listitem><para>List group members</para></listitem>
<listitem><para>List groups for a user</para></listitem>
<listitem><para>Assign a role on a tenant to a group</para></listitem>
<listitem><para>Assign a role on a domain to a group</para></listitem>
<listitem><para>Query role assignments to groups</para></listitem>
<listitem>
<para>Create a group</para>
</listitem>
<listitem>
<para>Delete a group</para>
</listitem>
<listitem>
<para>Update a group (change its name or
description)</para>
</listitem>
<listitem>
<para>Add a user to a group</para>
</listitem>
<listitem>
<para>Remove a user from a group</para>
</listitem>
<listitem>
<para>List group members</para>
</listitem>
<listitem>
<para>List groups for a user</para>
</listitem>
<listitem>
<para>Assign a role on a tenant to a group</para>
</listitem>
<listitem>
<para>Assign a role on a domain to a group</para>
</listitem>
<listitem>
<para>Query role assignments to groups</para>
</listitem>
</itemizedlist>
<note>
<para>
Not all of these operations may be allowed by the Identity server.
For example, if using the Keystone server with the LDAP Identity backend and
group updates are disabled, then a request to create, delete, or update a group
will fail.
</para>
<para>The Identity service server might not allow all
operations. For example, if using the Keystone server
with the LDAP Identity back end and group updates are
disabled, then a request to create, delete, or update
a group fails.</para>
</note>
<para>
Here's a couple examples:
</para><para>
Group A is granted Role A on Tenant A. If User A is a member of Group A,
then when User A gets a token scoped to Tenant A then the token will also
include Role A.
</para><para>
Group B is granted Role B on Domain B. If User B is a member of Domain B,
then if User B gets a token scoped to Domain B then the token will also
include Role B.
</para>
<para>Here are a couple examples:</para>
<itemizedlist>
<listitem>
<para>Group A is granted Role A on Tenant A. If User A
is a member of Group A, when User A gets a token
scoped to Tenant A, the token also includes Role
A.</para>
</listitem>
<listitem>
<para>Group B is granted Role B on Domain B. If User B
is a member of Domain B, if User B gets a token
scoped to Domain B, the token also includes Role
B.</para>
</listitem>
</itemizedlist>
</section>
</section>

1
doc/common/section_storage-concepts.xml
View File

@ -54,6 +54,7 @@
</tr>
</tbody>
</table>
<?hard-pagebreak?>
<para>Other points of note include: <itemizedlist>
<listitem>
<para><emphasis>OpenStack Object Storage is not used like a

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

@ -123,9 +123,10 @@
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>
<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>
</section>
<section xml:id="problems-with-injection">
<title>Problems with Injection</title>

2
doc/install-guide/ch_installdashboard.xml
View File

@ -14,7 +14,7 @@
OpenStack Compute cloud controller through the OpenStack APIs.</para>
<para>The following instructions show an example deployment
configured with an Apache web server.</para>
<para>After you <link linkend="installing-openstack-dashboard"
<para>After you <link linkend="ch_install-dashboard"
>install and configure the dashboard</link>, you can
complete the following tasks:</para>
<itemizedlist>