openstack/openstack-manuals
Code Issues Proposed changes

More changes to the User Guide, including changes to common files

Browse Source 
bug: #1110146

Change-Id: Ifb3e3f464baa611a99cc6a5b62907cdfe52856ad
author: diane fleming
This commit is contained in:
Diane Fleming 2013-06-14 09:42:53 -05:00
parent f461639821
commit 8163b71614
52 changed files with 1812 additions and 852 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

14
doc/src/docbkx/basic-install/src/basic-install_architecture.xml
View File

@ -19,11 +19,10 @@
of the cloud except actually hosting virtual machines
or providing network services. See the "Compute Node"
and "Network Controller" for details about those
roles. This server will host the OpenStack Image
Service, the OpenStack Block Storage Service, the
OpenStack Identity Service, and the OpenStack
Dashboard. It will also run portions of the OpenStack
Compute service such as the API server, the scheduler,
roles. This server hosts the OpenStack Image
Service, Block Storage Service, Identity Service, and the
dashboard. It also runs portions of the OpenStack
Compute service, such as the API server, the scheduler,
conductor, console authenticator, and VNC service.
Finally, it hosts the API endpoint for the OpenStack
Network service. </para>
@ -41,7 +40,7 @@
Network service agent (in this case, the Open vSwitch
plugin agent). This server also manages an
OpenStack-compatible hypervisor such as KVM or Xen.
This server will host the actual virtual machines
This server hosts the actual virtual machines
(instances). </para>
</listitem>
</itemizedlist>
@ -56,8 +55,7 @@
Network setup can have up to four distinct physical data
center networks. Note that these networks can be combined and
re-used. For example, the Management, Data, and API networks
are commonly the same network. For simplicity, this will be
done in this guide.</para>
are commonly the same network. For simplicity, this guide shows this configuration.</para>
<itemizedlist>
<listitem>
<para><emphasis role="bold">Management

6
doc/src/docbkx/basic-install/src/basic-install_compute-common.xml
View File

@ -21,7 +21,7 @@
<para>Packages: <emphasis role="bold">OpenSSH-Server</emphasis></para>
</listitem>
</itemizedlist></para>
<para>Once installation has finished, the server will reboot.</para>
<para>Once installation has finished, the server reboots.</para>
</listitem>
<listitem>
<para os="ubuntu">Since the default OpenStack release in Ubuntu 12.04 LTS is older,
@ -40,8 +40,8 @@
<listitem>
<para>Configure the network:</para>
<note>
<para>This will change later on in the guide
when Open vSwitch is configured</para>
<para>Later in this guide, this changes
when Open vSwitch is configured.</para>
</note>
<para os="ubuntu">
<itemizedlist>

2
doc/src/docbkx/basic-install/src/basic-install_compute-intro.xml
View File

@ -4,7 +4,7 @@
xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
xml:id="basic-install_compute-intro">
<title>Introduction</title>
<para>The Compute node will provide :
<para>The Compute node provides:
<itemizedlist>
<listitem>
<para>Hypervisor (KVM)</para>

12
doc/src/docbkx/basic-install/src/basic-install_controller-common.xml
View File

@ -33,7 +33,7 @@
</itemizedlist>
</para>
<para>
Once installation has finished, the server will reboot.
Once installation has finished, the server reboots.
</para>
</listitem>
<listitem>
@ -163,8 +163,8 @@ ONBOOT=yes
</para>
</listitem>
<listitem>
<para>Install NTP. NTP will ensure that the server has the correct time. This is important because if an OpenStack server's time is
not correct, it will be removed from the rest of the cloud.<itemizedlist>
<para>Install NTP. NTP ensures that the server has the correct time. This is important because if an OpenStack server's time is
not correct, it is removed from the rest of the cloud.<itemizedlist>
<listitem>
<para>
<screen os="ubuntu;deb"><prompt>#</prompt> <userinput>apt-get install ntp</userinput></screen>
@ -187,14 +187,14 @@ ONBOOT=yes
<para>Install the packages: <screen os="ubuntu;deb"><prompt>#</prompt> <userinput>apt-get install python-mysqldb mysql-server</userinput></screen>
<screen os="rhel;fedora;centos"><prompt>#</prompt> <userinput>yum install mysql mysql-server MySQL-python</userinput></screen>
<note os="ubuntu;deb">
<para><literal>apt-get</literal> will
prompt you to set the MySQL root
<para><literal>apt-get</literal>
prompts you to set the MySQL root
password.</para>
</note>
</para>
</listitem>
<listitem>
<para>By default, MySQL will only accept
<para>By default, MySQL only accepts
connections from localhost. This needs changed
so that the compute nodes can access the
OpenStack Networking service. Database

4
doc/src/docbkx/basic-install/src/basic-install_controller-glance.xml
View File

@ -5,8 +5,8 @@
xml:id="basic-install_controller-glance">
<title>OpenStack Image Service</title>
<para>The Image Service provides the cloud environment with a catalog of virtual machine "templates". These templates are used as the basis
of instances. For example, if the catalog contains an image for an Ubuntu 12.04 distribution, the users of the cloud will be able
to launch Ubuntu 12.04 instances.
of instances. For example, if the catalog contains an image for an Ubuntu 12.04 distribution, cloud users can
launch Ubuntu 12.04 instances.
<orderedlist>
<listitem>
<para>Install the Glance packages:

2
doc/src/docbkx/basic-install/src/basic-install_controller-intro.xml
View File

@ -4,7 +4,7 @@
xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
xml:id="basic-install_controller-intro">
<title>Introduction</title>
<para>The Controller node will provide :
<para>The Controller node provides:
<itemizedlist>
<listitem>
<para>Databases (with MySQL)</para>

4
doc/src/docbkx/basic-install/src/basic-install_controller-keystone.xml
View File

@ -46,7 +46,7 @@ connection = mysql://keystone:password@localhost/keystone</programlisting></para
<itemizedlist>
<listitem>
<para>Create a file called <emphasis role="bold">~/openrc</emphasis>. This
file contains the OpenStack admin credentials that will be used when interacting with the OpenStack
file contains the OpenStack admin credentials that are used when interacting with the OpenStack
environment on the command line.
<programlisting>export OS_TENANT_NAME=admin
export OS_USERNAME=admin
@ -70,7 +70,7 @@ export SERVICE_TOKEN=password</programlisting></para>
</itemizedlist>
</listitem>
<listitem>
<para>The following bash script will populate Keystone with some initial data:
<para>The following bash script populates Keystone with some initial data:
<itemizedlist>
<listitem><para>Projects: admin and services</para></listitem>
<listitem><para>Roles: admin, Member</para></listitem>

2
doc/src/docbkx/basic-install/src/basic-install_controller-nova.xml
View File

@ -41,7 +41,7 @@ auth_version = v2.0</programlisting>
<para>Add the following to the <emphasis role="bold">/etc/nova/nova.conf</emphasis> file. This file is
the main configuration file of Nova. There is a large amount of configuration options
that can go in this file. This guide illustrates the minimum needed for a simple environment.
Note that the nova.conf file supplied by your distribution will have some options already set. Leave
Note that the nova.conf file supplied by your distribution has some options already set. Leave
them as-is.
<programlisting os="ubuntu">[DEFAULT]

2
doc/src/docbkx/basic-install/src/basic-install_controller-quantum.xml
View File

@ -58,7 +58,7 @@ firewall_driver = quantum.agent.linux.iptables_firewall.OVSHybridIptablesFirewal
<emphasis role="bold">tunnel mode</emphasis> since you don't
have to configure your physical
switches for VLANs.</para>
<para os="centos;rhel;fedora">The Fedora kernel module for OpenVSwitch has been compiled without support for tunnels. To use gre tunnels the module will have to be recompiled.</para>
<para os="centos;rhel;fedora">The Fedora kernel module for OpenVSwitch has been compiled without support for tunnels. To use gre tunnels, the module must be recompiled.</para>
</note>
</listitem>
<listitem os="centos;rhel;fedora">

3
doc/src/docbkx/basic-install/src/basic-install_intro.xml
View File

@ -25,8 +25,7 @@
<para>The OpenStack configuration files contain several commented
options. These options specify the default setting. You only
need to uncomment these lines if you are changing the setting
to a non-default value. Additionally, the only options that
will be shown throughout this guide are options that are being
to a non-default value. Additionally, this guide only shows options that are being
modified from their default value. </para>
<para>Finally, please be aware that the use of <literal>password</literal>
as a password throughout this guide is for simplicity and

5
doc/src/docbkx/basic-install/src/basic-install_network-common.xml
View File

@ -20,7 +20,7 @@
<para>Packages: <emphasis role="bold">OpenSSH-Server</emphasis></para>
</listitem>
</itemizedlist></para>
<para>Once installation has finished, the server will reboot.</para>
<para>Once installation has finished, the server reboots.</para>
</listitem>
<listitem>
<para os="ubuntu">Since the default OpenStack release
@ -44,8 +44,7 @@
<listitem>
<para>Edit <emphasis role="bold">/etc/network/interfaces</emphasis>:
<note>
<para>This will change later on in
the guide when Open vSwitch is
<para>Later in this guide, this changes when Open vSwitch is
configured.</para>
</note>
<programlisting># Internal Network

2
doc/src/docbkx/basic-install/src/basic-install_network-intro.xml
View File

@ -4,7 +4,7 @@
xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
xml:id="basic-install_network-intro">
<title>Introduction</title>
<para>The Network node will provide:
<para>The Network node provides:
<itemizedlist>
<listitem>
<para>Virtual Bridging (Open-vSwitch + Quantum Agent) with tunneling</para>

10
doc/src/docbkx/basic-install/src/basic-install_network-operating.xml
View File

@ -14,7 +14,7 @@
<itemizedlist>
<listitem>
<para>Create a file called <emphasis role="bold">~/openrc</emphasis>. This
file contains the OpenStack admin credentials that will be used when interacting with the OpenStack
file contains the OpenStack admin credentials that are used when interacting with the OpenStack
environment on the command line.
<programlisting>export OS_TENANT_NAME=admin
export OS_USERNAME=admin
@ -38,7 +38,7 @@ export SERVICE_TOKEN=password</programlisting></para>
</itemizedlist>
</listitem>
<listitem>
<para>The following bash script will create an internal network for the "demo" project.
<para>The following bash script creates an internal network for the "demo" project.
<programlisting>#!/bin/bash
TENANT_NAME="demo"
TENANT_NETWORK_NAME="demo-net"
@ -58,11 +58,11 @@ quantum router-interface-add $ROUTER_ID $TENANT_SUBNET_ID</programlisting></para
<section xml:id="configure-l3">
<title>L3 Configuration</title>
<para>The Quantum L3 service enables instances to have external network access. If this service is not configured, your instances
will only be able to communicate with each other. Please note that this configuration is highly dependant on your environment.
For example, make note of the <literal>subnet-create</literal> command below. You will need to verify your own network settings
can only communicate with each other. Note that this configuration is highly dependant on your environment.
For example, make note of the <literal>subnet-create</literal> command below. You must verify your own network settings
for the external subnet (<literal>10.0.0.0/24</literal> in this case) as well as an allocation pool. The allocation pool
is used to provide each Project with an IP address to access the external network. The pool consists of 50 IPs and therefore
only 50 projects will be able to get a gateway IP.</para>
only 50 projects can get a gateway IP.</para>
<itemizedlist>
<listitem>
<para>Create an external network:

2
doc/src/docbkx/cli-guide/pom.xml
View File

@ -53,7 +53,7 @@
<webhelpDirname>cli-guide</webhelpDirname>
<includeDateInPdfFilename>0</includeDateInPdfFilename>
<pdfFilenameBase>cli-guide.pdf</pdfFilenameBase>
<pdfFilenameBase>cli-guide</pdfFilenameBase>
</configuration>
</execution>
<execution>

73
doc/src/docbkx/common/about-dashboard.xml
View File

@ -2,22 +2,57 @@
<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="about-the-dashboard">
<title>About the Dashboard</title>
<!--<?dbhtml stop-chunking?>-->
<para>The OpenStack 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. The dashboard enables web-based interactions
with the OpenStack Compute cloud controller through the
OpenStack APIs. The following instructions show you an example
deployment that is configured with an Apache web server. </para>
<xi:include href="../common/dashboard-system-reqs.xml"/>
<xi:include href="../common/dashboard-install.xml"/>
<xi:include href="../common/dashboard-configure.xml"/>
<xi:include href="../common/dashboard-verify.xml"/>
<xi:include href="../common/dashboard_customizing.xml"/>
<xi:include href="../common/dashboard_sessions.xml"/>
<xi:include href="../common/dashboardlaunchinginstances.xml"/>
</section>
xml:id="about-dashboard">
<title>About the OpenStack dashboard</title>
<para>To install the OpenStack dashboard, complete the
following high-level steps: </para>
<orderedlist>
<listitem>
<para>Meet the system requirements for accessing the
dashboard. See <xref
linkend="dashboard-system-requirements"
/>.</para>
</listitem>
<listitem>
<para>Install the OpenStack Dashboard framework,
including Apache and related modules. See <xref
linkend="installing-openstack-dashboard"
/>.</para>
</listitem>
<listitem>
<para>Configure the dashboard.</para>
<para>Then, restart and run the Apache server.</para>
<para>See <xref linkend="configure-dashboard"
/>.</para>
</listitem>
<listitem>
<para>Verify your installation. See <xref
linkend="verify-dashboard"/>.</para>
</listitem>
</orderedlist>
<simplesect>
<title>Next steps:</title>
<para>After you install the dashboard, you can complete the following tasks:</para>
<itemizedlist>
<listitem>
<para>To customize your dashboard, see <xref
linkend="dashboard-custom-brand"/>.
</para>
</listitem>
<listitem>
<para>To set up session storage for the dashboard,
see <xref linkend="dashboard-sessions"
/>.</para>
</listitem>
<listitem>
<para>To deploy the
dashboard, see <link
xlink:href="http://docs.openstack.org/developer/horizon/topics/deployment.html"
>Deploying Horizon</link>.</para>
</listitem>
<listitem xml:id="launch_instances">
<para>To launch instances with the dashboard, see the
<citetitle>OpenStack User Guide</citetitle>.</para></listitem>
</itemizedlist>
</simplesect>
</section>

94
doc/src/docbkx/common/ch_installdashboard.xml
View File

@ -1,51 +1,69 @@
<?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"
xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
xml:id="ch_install-dashboard">
<title>Installing the OpenStack Dashboard</title>
<para>OpenStack has components that provide a view of the
OpenStack installation such as a Django-built website that
serves as a dashboard. </para>
<para>You can use a dashboard interface with an OpenStack
Compute installation with a web-based console provided by
the Openstack-Dashboard project. It provides web-based
interactions with the OpenStack Compute cloud controller
through the OpenStack APIs. For more information about the
Openstack-Dashboard project, please visit: <link
xlink:href="https://github.com/openstack/horizon/"
>https://github.com/openstack/horizon/</link>. These
instructions are for an example deployment configured with
an Apache web server. </para>
<section xml:id="task_flow"><title>Dashboard Installation Task Flow</title>
<para>To install the OpenStack Dashboard, complete the
following high-level steps: </para>
<orderedlist>
<title>Install the OpenStack dashboard</title>
<para xmlns:raxm="http://docs.rackspace.com/api/metadata">The
OpenStack 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>To install the OpenStack dashboard, complete the following
high-level steps: </para>
<orderedlist>
<listitem>
<para>Meet the system requirements for accessing the
dashboard. See <xref
linkend="dashboard-system-requirements"/>.</para>
</listitem>
<listitem>
<para>Install the OpenStack Dashboard framework, including
Apache and related modules. See <xref
linkend="installing-openstack-dashboard"/>.</para>
</listitem>
<listitem>
<para>Configure the dashboard.</para>
<para>Then, restart and run the Apache server.</para>
<para>See <xref linkend="configure-dashboard"/>.</para>
</listitem>
<listitem>
<para>Verify your installation. See <xref
linkend="verify-dashboard"/>.</para>
</listitem>
</orderedlist> -->
<para>After you install the dashboard, you can complete the
following tasks:</para> <itemizedlist>
<title>Next steps:</title>
<listitem>
<para>Meet the system requirements for the dashboard.</para>
<para>To customize your dashboard, see <xref
linkend="dashboard-custom-brand"/>. </para>
</listitem>
<listitem>
<para>Install the OpenStack Dashboard framework,
including Apache and related modules.</para>
<para>To set up session storage for the dashboard, see
<xref linkend="dashboard-sessions"/>.</para>
</listitem>
<listitem>
<para>Configure the dashboard.</para>
</listitem>
<listitem>
<para>Restart and run the Apache server.</para>
</listitem>
<listitem>
<para>Deploy the dashboard. See <link
<para>To deploy the dashboard, see <link
xlink:href="http://docs.openstack.org/developer/horizon/topics/deployment.html"
>Deploying Horizon</link>.</para>
</listitem>
</orderedlist></section>
<xi:include href="../common/dashboard-system-reqs.xml"/>
<xi:include href="../common/dashboard-install.xml"/>
<xi:include href="../common/dashboard-configure.xml"/>
<xi:include href="../common/dashboard-verify.xml"/>
<xi:include href="../common/dashboard_customizing.xml" />
<xi:include href="../common/dashboard_sessions.xml" />
<xi:include href="../common/compute-vnc-console.xml"/>
<listitem xml:id="launch_instances">
<para>To launch instances with the dashboard, see the
<citetitle>OpenStack User
Guide</citetitle>.</para>
</listitem>
</itemizedlist>
<!-- <xi:include href="dashboard-system-reqs.xml"/> -->
<xi:include href="dashboard-install.xml"/>
<xi:include href="dashboard-configure.xml"/>
<xi:include href="dashboard-verify.xml"/>
<xi:include href="dashboard_customizing.xml"/>
<xi:include href="dashboard_sessions.xml"/>
</chapter>

2
doc/src/docbkx/common/compute-vnc-console.xml
View File

@ -245,7 +245,7 @@
<section xml:id="faq-about-vnc">
<info>
<title>Frequently asked questions about VNC access to
VMs</title>
virtual machines</title>
</info>
<itemizedlist>
<listitem>

135
doc/src/docbkx/common/dashboard-configure.xml
View File

@ -3,57 +3,69 @@
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</title>
<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>
<section xml:id="dashboard-config-http"><title>Configure the Dashboard for HTTP</title><procedure><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><xi:include parse="text" href="samples/local_settings.py"/></programlisting>
<para>The <literal>HORIZON_CONFIG</literal> dictionary
contains all the settings for the dashboard. Whether
or not a service is in the Dashboard depends on the
Service Catalog configuration in the Identity service.
For the full listing, see <link
xlink:href="http://docs.openstack.org/developer/horizon/topics/settings.html"
>Horizon Settings and Configuration</link>.</para>
</step></procedure></section>
<section xml:id="dashboard-config-https"><title>Configure the Dashboard for HTTPS</title><procedure><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
directive:<programlisting>USE_SSL = True</programlisting></para>
</step>
<step>
<para> Edit <filename>/etc/apache2/ports.conf</filename> and add the following
line: <programlisting>NameVirtualHost *:443</programlisting></para>
</step>
<step>
<para>
Edit <filename>/etc/apache2/conf.d/openstack-dashboard.conf:</filename></para>
<para> Before:
<programlisting>WSGIScriptAlias / /usr/share/openstack-dashboard/openstack_dashboard/wsgi/django.wsgi
<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>
<section xml:id="dashboard-config-http">
<title>Configure the dashboard for HTTP</title>
<procedure>
<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 <literal>HORIZON_CONFIG</literal> dictionary
contains all the settings for the dashboard.
Whether or not a service is in the Dashboard
depends on the Service Catalog configuration in
the Identity service. For the full listing, see
<link
xlink:href="http://docs.openstack.org/developer/horizon/topics/settings.html"
>Horizon Settings and
Configuration</link>.</para>
</step>
</procedure>
</section>
<section xml:id="dashboard-config-https">
<title>Configure the dashboard for HTTPS</title>
<procedure>
<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
directive:<programlisting>USE_SSL = True</programlisting></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>
<para> After:
<programlisting>&lt;VirtualHost *:80&gt;
&lt;/Directory&gt;</programlisting>
<para>After:</para>
<programlisting><?db-font-size 65%?>&lt;VirtualHost *:80&gt;
ServerName openstack.example.com
RedirectPermanent / https://openstack.example.com
&lt;/VirtualHost&gt;
@ -73,20 +85,21 @@ Alias /static /usr/share/openstack-dashboard/openstack_dashboard/static/
Order allow,deny
Allow from all
&lt;/Directory&gt;
&lt;/VirtualHost&gt; </programlisting></para>
<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. In the secured
section, the private key, public key, and
certificate to use are defined.</para>
</step>
<step>
<para>Restart Apache and memcached:</para>
<screen><prompt>#</prompt> <userinput>service apache2 restart</userinput>
&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. In the
secured section, the private key, public key, and
certificate to use are defined.</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 call the HTTP version of the dashboard
through your browser, you are redirected to the HTTPS
page.</para>
</step>
</procedure></section>
<para>If you call the HTTP version of the dashboard
through your browser, you are redirected to the
HTTPS page.</para>
</step>
</procedure>
</section>
</section>

141
doc/src/docbkx/common/dashboard-install.xml
View File

@ -1,44 +1,119 @@
<?xml version="1.0" encoding="UTF-8"?>
<section xml:id="installing-openstack-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 the OpenStack Dashboard</title>
<procedure><title>To install the OpenStack Dashboard:</title><step><para>Install the OpenStack Dashboard as root:</para>
<screen os="ubuntu"><prompt>#</prompt> <userinput>apt-get install -y memcached libapache2-mod-wsgi openstack-dashboard</userinput></screen>
<screen os="rhel;centos;fedora"><prompt>#</prompt> <userinput>yum install -y memcached python-memcached mod_wsgi openstack-dashboard</userinput></screen></step>
<step><para>Modify the <literal>CACHE_BACKEND</literal> environment variable
in <filename os="ubuntu"
<section xml:id="installing-openstack-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>
<para>Before you can install and configure the dashboard, meet the
following system requirements:</para>
<itemizedlist role="compact">
<title>Dashboard system requirements:</title>
<listitem>
<para>OpenStack Compute installation. The cloud operator must set up an OpenStack Compute
installation and enable the Identity Service for user
and project management. </para>
<para><emphasis role="bold">User:</emphasis> Note the URLs
of the Identity Service and Compute endpoints.</para>
</listitem>
<listitem>
<para>Identity Service user with sudo privileges. Because Apache does not serve content from a root
user, the cloud operator must set up an Identity
Service user with sudo privileges. </para>
<para><emphasis role="bold">User:</emphasis> Note the
credentials of this user.</para>
</listitem>
<listitem>
<para>git. Install <emphasis role="bold">git</emphasis> by
running the following command:</para>
<programlisting language="bash" linenumbering="unnumbered"><prompt>$</prompt> sudo apt-get install git-core</programlisting>
</listitem>
<listitem>
<para>Python 2.6 or 2.7. The Python version must support Django. These
instructions were tested with Ubuntu 10.10. </para>
<para>The Python version should run on any system,
including Mac OS X. </para>
<para>The installation prerequisites might differ by
platform. </para>
</listitem>
</itemizedlist>
<procedure>
<title>To install the dashboard:</title>
<step>
<para>Install the dashboard on the node that can contact
the Identity Service as root:</para>
<programlisting language="bash" linenumbering="unnumbered" os="ubuntu"><prompt>#</prompt> <userinput>apt-get install -y memcached libapache2-mod-wsgi openstack-dashboard</userinput></programlisting>
<programlisting language="bash" linenumbering="unnumbered" os="rhel;centos;fedora"><prompt>#</prompt> <userinput>yum install -y memcached python-memcached mod_wsgi openstack-dashboard</userinput></programlisting>
</step>
<step>
<para>Modify the <literal>CACHE_BACKEND</literal>
environment variable in <filename os="ubuntu"
>/etc/openstack-dashboard/local_settings.py</filename><filename
os="centos;fedora;rhel"
>/etc/openstack-dashboard/local_settings</filename>
to match the ones set in <filename os="ubuntu"
>/etc/memcached.conf</filename><filename
os="centos;fedora;rhel"
>/etc/sysconfig/memcached.conf</filename>.</para><para>Open
<filename os="ubuntu"
>/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>CACHE_BACKEND = 'memcached://127.0.0.1:11211/'</programlisting>
<note><para>The address and port must match the ones set in <filename
os="ubuntu"
>/etc/memcached.conf</filename><filename
os="centos;fedora;rhel"
>/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></note>
<note><para>In this example, memcached is the session store for the OpenStack Dashboard. You can use other options. Each
option has benefits and drawbacks. You can use any available session back-end by setting the SESSION_ENGINE option.</para></note>
<para>
<note>
<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>
file. </para>
<para>Change the following parameter:
<programlisting>TIME_ZONE = "UTC"</programlisting>
</para>
</note>
</para></step></procedure>
and look for this line: <code>CACHE_BACKEND =
'memcached://127.0.0.1:11211/'</code></para>
<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"
>/etc/memcached.conf</filename><filename
os="centos;fedora;rhel"
>/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>
</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>
option.</para>
</listitem>
<listitem>
<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>
file. </para>
<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>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
xlink:href="https://github.com/kanaka/noVNC/blob/master/README.md"
>https://github.com/kanaka/noVNC/blob/master/README.md</link>,
and <link
xlink:href="https://github.com/kanaka/noVNC/wiki/Browser-support"
>https://github.com/kanaka/noVNC/wiki/Browser-support</link>,
respectively. </para>
</note>
</step>
</procedure>
</section>

145
doc/src/docbkx/common/dashboard-system-reqs.xml
View File

@ -4,66 +4,87 @@
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0">
<title>System requirements</title>
<para>You must meet the following system requirements to access
the OpenStack dashboard: </para><itemizedlist>
<listitem>
<para>The cloud operator has set up an <emphasis
role="bold">OpenStack Compute
installation</emphasis> with the Identity
Service enabled for identity management. Note the
URLs of your Identity Service and Compute
endpoints. </para>
</listitem>
<listitem>
<para>The cloud operator has set up an <emphasis
role="bold">Identity Service user with sudo
privileges</emphasis>. Because Apache does not
serve content from a root user, you must run the
dashboard as an Identity Service user with sudo
privileges. Note the credentials of this user.</para>
</listitem>
<listitem>
<para>You have a recent <emphasis role="bold">Web browser
that supports HTML5</emphasis> and has cookies and
JavaScript enabled. </para>
<para>To use the dashboard's VNC client, which is based on
noVNC, your browser must support HTML5 Canvas and
HTML5 WebSockets. </para>
<para>For more details and a list of 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.m</link>d,
and
https://github.com/kanaka/noVNC/wiki/Browser-support,
respectively. </para></listitem><listitem>
<para>Install the <emphasis role="bold">OpenStack
dashboard</emphasis> on the node that can contact
the Identity Service.</para>
</listitem>
<listitem>
<para>Install <emphasis role="bold">git</emphasis> by
running the following
command:<programlisting language="bash"><prompt>$</prompt> sudo apt-get install git-core</programlisting></para>
</listitem>
<listitem>
<para>Install <emphasis role="bold">Python 2.6 or 2.7
</emphasis>. Your version of Python must be capable of
running Django. These instructions have been tested
with Ubuntu 10.10. </para>
<para>The version of Python that you use should run on any
system, including Mac OS X. The installation
prerequisites might differ by platform. </para>
</listitem>
</itemizedlist>
<para>The following components are optional:</para>
<itemizedlist>
<listitem><para>Image store (<emphasis role="italic">Glance</emphasis>)
endpoint</para></listitem>
<listitem><para>Object store (<emphasis role="italic">Swift</emphasis>)
endpoint</para></listitem>
<listitem><para>Networking (<link xlink:href="http://wiki.openstack.org/Quantum"
>Quantum</link>) endpoint</para></listitem>
</itemizedlist>
<para>Meet the following system requirements to access the
OpenStack dashboard:</para>
<table rules="all">
<caption>Dashboard system requirements</caption>
<thead>
<tr>
<th>Requirement</th>
<th>Who?</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>OpenStack Compute installation</td>
<td>Cloud operator</td>
<td>
<para>Set up an OpenStack Compute installation. </para>
<para>Enable the Identity Service for user and
project management. </para>
<para><emphasis role="bold">User:</emphasis> Note
the URLs of the Identity Service and Compute
endpoints.</para>
</td>
</tr>
<tr>
<td>Identity Service user with sudo privileges</td>
<td>Cloud operator</td>
<td><para>Because Apache does not serve content from a
root user, you must run the dashboard as an
Identity Service user with sudo privileges. </para>
<para><emphasis role="bold">User:</emphasis> Note
the credentials of this user.</para></td>
</tr>
<tr>
<td>OpenStack dashboard</td>
<td>Cloud operator</td>
<td><para>Install the dashboard on the node that can
contact the Identity Service.</para></td>
</tr>
<tr>
<td>git</td>
<td>Cloud operator</td>
<td><para>Install <emphasis role="bold">git</emphasis>
by running the following
command:</para><programlisting language="bash"><prompt>$</prompt> sudo apt-get install git-core</programlisting></td>
</tr>
<tr>
<td>Python 2.6 or 2.7</td>
<td>Cloud operator</td>
<td>
<para>The Python version must support Django.
These instructions have been tested with
Ubuntu 10.10. </para>
<para>The Python version should run on any system,
including Mac OS X. </para>
<para>The installation prerequisites might differ
by platform. </para>
</td>
</tr>
<tr>
<td>Web browser that supports HTML5</td>
<td>User</td>
<td>
<para>Install a web browser on your local machine
that 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
xlink:href="https://github.com/kanaka/noVNC/blob/master/README.md"
>https://github.com/kanaka/noVNC/blob/master/README.md</link>,
and <link
xlink:href="https://github.com/kanaka/noVNC/wiki/Browser-support"
>https://github.com/kanaka/noVNC/wiki/Browser-support</link>,
respectively. </para>
</note>
</td>
</tr>
</tbody>
</table>
</section>

30
doc/src/docbkx/common/dashboard-verify.xml
View File

@ -1,18 +1,24 @@
<?xml version="1.0" encoding="UTF-8"?>
<section xml:id="verify-dashboard"
<section xml:id="verify-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>Validate the Dashboard Installation</title>
<procedure><title>To validate the dashboard installation:</title><step><para>Point your browser to http://192.168.206.130.</para></step><step><para>After you connect to the dashboard through the URL, a login
window appears. Enter the credentials for any user
that you created with the OpenStack Identity Service. </para>
<title>Verify the installation</title>
<procedure>
<title>To verify the dashboard installation:</title>
<step>
<para>Point your browser to the public IP address for your
instance: For example:</para>
<para><code>http://192.168.206.130</code></para>
</step>
<step>
<para>After you connect to the dashboard through the URL,
a login page appears. </para>
<para>Enter the credentials for any user that you created
with the OpenStack Identity Service. </para>
<para>For example, enter <literal>admin</literal> for the
username and <literal>secrete</literal> as the
password:</para>
<mediaobject>
<imageobject>
<imagedata fileref="figures/dashboard-overview.png"
format="PNG" scale="30" width="4in"/>
</imageobject>
</mediaobject></step></procedure></section>
password.</para>
</step>
</procedure>
</section>

143
doc/src/docbkx/common/dashboard_customizing.xml
View File

@ -1,22 +1,22 @@
<?xml version="1.0" encoding="UTF-8"?>
<section xml:id="dashboard-custom-brand"
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>Custom Brand the Dashboard</title>
<para>Adapted from a <link xlink:href="http://www.prestonlee.com/2012/05/09/how-to-custom-brand-the-openstack-horizon-dashboard/">blog post by Preston Lee</link>. </para>
<para>When you deploy OpenStack
on <link xlink:href="http://www.ubuntu.com/">Ubuntu Server</link> 12.04, you can have the
<literal>openstack-dashboard</literal> package installed to provide the web-based “Horizon”
GUI component. Canonical also provides an
<literal>openstack-dashboard-ubuntu-theme</literal> package that brands the Python-based Django GUI.
</para>
<para><link
xlink:href="http://horizon.openstack.org/topics/branding.html"
>The Horizon documents briefly mention branding
customization</link> to provide a head start. The
following example shows a custom-branded Horizon dashboard
with custom colors, logo, and site title:</para>
xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0">
<title>Customize the dashboard</title>
<para>Adapted from <link
xlink:href="http://www.prestonlee.com/2012/05/09/how-to-custom-brand-the-openstack-horizon-dashboard/"
>How To Custom Brand The OpenStack “Horizon”
Dashboard</link>. </para>
<para>You install the OpenStack dashboard through the
<literal>openstack-dashboard</literal> package. You can
customize the dashboard with your own colors, logo, and site
title through a CSS file.</para>
<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
custom colors, logo, and site title:</para>
<mediaobject>
<imageobject role="fo">
<imagedata
@ -30,37 +30,53 @@
</imageobject>
</mediaobject>
<mediaobject>
<imageobject role="fo">
<imagedata
fileref="figures/Flavors-–-TGen-Cloud-Dashboard.png"
format="PNG" contentwidth="6in"/>
</imageobject>
<imageobject role="html">
<imagedata
fileref="figures/Flavors-–-TGen-Cloud-Dashboard.png"
format="PNG"/>
</imageobject>
</mediaobject>
<procedure><title>To customize the dashboard:</title>
<step><para>Create a graphical logo with a transparent background. The text “TGen Cloud”
in this example is actually rendered via .png files of multiple sizes created with
a graphics program. Use a 200×27 for the logged-in banner graphic, and 365×50 for
the login screen graphic.</para></step>
<step><para>Set the HTML title (shown at the top of the browser window) by adding the
following line to <filename>/etc/openstack-dashboard/local_settings.py</filename>: <code>SITE_BRANDING = "Example, Inc. Cloud"</code></para>
</step>
<step><para>Upload your new graphic files to:
<screen>/usr/share/openstack-dashboard/openstack_dashboard/static/dashboard/img/</screen></para>
</step>
<step><para>Create a new CSS style sheet — we’ll call ours custom.css — in the directory:
<screen>/usr/share/openstack-dashboard/openstack_dashboard/static/dashboard/css/</screen></para>
</step>
<step><para>Edit your CSS file using the
following as a starting point for customization, which simply overrides the Ubuntu
customizations made in the ubuntu.css file. </para>
<para>Change the colors and image file names as appropriate, though the relative directory paths should be the same.
<programlisting language="bash">/*
<imageobject role="fo">
<imagedata
fileref="figures/Flavors-–-TGen-Cloud-Dashboard.png"
format="PNG" scale="60"/>
</imageobject>
<imageobject role="html">
<imagedata
fileref="figures/Flavors-–-TGen-Cloud-Dashboard.png"
format="PNG"/>
</imageobject>
</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
this example is rendered through
<filename>.png</filename> files of multiple sizes
created with a graphics program. </para>
<para>Use a 200×27 for the logged-in banner graphic, and
365×50 for the login screen graphic.</para>
</step>
<step>
<para>Set the HTML title, which appears at the top of the
browser window, by adding the following line to
<filename>/etc/openstack-dashboard/local_settings.py</filename>: </para>
<para><code>SITE_BRANDING = "Example, Inc.
Cloud"</code></para>
</step>
<step>
<para>Upload your new graphic files to the following
location:
<screen>/usr/share/openstack-dashboard/openstack_dashboard/static/dashboard/img/</screen></para>
</step>
<step>
<para>Create a CSS style sheet in the following directory:
<screen>/usr/share/openstack-dashboard/openstack_dashboard/static/dashboard/css/</screen></para>
</step>
<step>
<para>Edit your CSS file to override the Ubuntu
customizations in the <filename>ubuntu.css</filename>
file. </para>
<para>Change the colors and image file names as
appropriate, though the relative directory paths
should be the same. The following example file shows
you how to customize your CSS
file:<programlisting language="bash"><?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)
@ -92,19 +108,30 @@ border: none;
box-shadow: none;
background-color: #BAD3E1 !important;
text-decoration: none;
}</programlisting></para></step>
<step><para>Open the following HTML template in an editor:
<screen>/usr/share/openstack-dashboard/openstack_dashboard/templates/_stylesheets.html</screen></para></step>
<step><para>Add a line to include your new style sheet pointing to
custom.css: (I’ve highlighted the new line in
<emphasis>bold</emphasis>.)
<programlisting language="bash">...
}</programlisting></para>
</step>
<step>
<para>Open the following HTML template in an editor:
<screen>/usr/share/openstack-dashboard/openstack_dashboard/templates/_stylesheets.html</screen></para>
</step>
<step>
<para>Add a line to include your
<filename>custom.css</filename> file:
<programlisting language="bash"><?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></step>
<step><para>Restart apache just for good measure: <code os="ubuntu">sudo service apache2 restart</code><code os="centos;fedora;rhel">sudo service httpd restart</code></para>
...</programlisting></para>
</step>
<step><para>Reload the dashboard in your browser and fine tune your CSS appropriate.</para></step>
</procedure>
<step>
<para>Restart apache:</para>
<programlisting language="bash" os="ubuntu">sudo service apache2 restart</programlisting>
<programlisting language="bash" os="centos;fedora;rhel">sudo service httpd restart</programlisting>
</step>
<step>
<para>Reload the dashboard in your browser to view your
changes.</para>
<para>Modify your CSS file as appropriate.</para>
</step>
</procedure>
</section>

274
doc/src/docbkx/common/dashboard_sessions.xml
View File

@ -1,90 +1,113 @@
<?xml version="1.0" encoding="UTF-8"?>
<section xml:id="dashboard-sessions"
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>Set up Dashboard Session Storage</title>
<para>The dashboard uses <link
xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0">
<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 back-end. You
customize the session back-end through the
data. However, you can use any available session backend. You
customize the session backend through the
<literal>SESSION_ENGINE</literal> setting in your
<filename os="centos;fedora;rhel">
/etc/openstack-dashboard/local_settings</filename>
<filename os="ubuntu">local_settings.py</filename> file. </para>
<para>The following sections describe the pros and cons of each
option as it pertains to deploying the dashboard. </para>
<section xml:id="dashboard-session-local">
<title>Local Memory Cache</title>
<para>Local memory storage is the quickest and easiest session
option as it pertains to deploying the dashboard. </para>
<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
whatsoever. It has the following significant
drawbacks:</para>
<orderedlist>
<listitem><para>No shared storage across processes or workers.</para></listitem>
<listitem><para>No persistence after a process terminates.</para></listitem>
</orderedlist>
<para>The local memory backend 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'
<itemizedlist>
<listitem>
<para>No shared storage across processes or
workers.</para>
</listitem>
<listitem>
<para>No persistence after a process
terminates.</para>
</listitem>
</itemizedlist>
<para>The local memory backend 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'
CACHES = {
'BACKEND': 'django.core.cache.backends.locmem.LocMemCache'
}</programlisting>
</section>
<section xml:id="dashboard-session-memcache">
<title>Memcached</title>
<para>External caching using an application such as memcached
offers persistence and shared storage, and can be very useful
for small-scale deployment and/or development. However, for
distributed and high-availability scenarios memcached has
inherent problems which are beyond the scope of this documentation.</para>
<para>Memcached is an extremely fast and efficient cache backend for
cases where it fits the deployment need, but it’s not
appropriate for all scenarios.</para>
<para>Requirements:</para>
<orderedlist>
<listitem><para>Memcached service running and accessible.</para></listitem>
<listitem><para>Python memcached module installed.</para></listitem>
</orderedlist>
<para>Enabled by:</para>
<programlisting language="python">SESSION_ENGINE = 'django.contrib.sessions.backends.cache'
</section>
<section xml:id="dashboard-session-memcache">
<title>Memcached</title>
<para>External caching using an application such as memcached
offers persistence and shared storage, and can be very
useful for small-scale deployment and/or development.
However, for distributed and high-availability scenarios
memcached has inherent problems which are beyond the scope
of this documentation.</para>
<para>Memcached is an extremely fast and efficient cache
backend for cases where it fits the deployment need, but
it’s not appropriate for all scenarios.</para>
<para>Requirements:</para>
<itemizedlist>
<listitem>
<para>Memcached service running and accessible.</para>
</listitem>
<listitem>
<para>Python memcached module installed.</para>
</listitem>
</itemizedlist>
<para>Enabled by:</para>
<programlisting language="python">SESSION_ENGINE = 'django.contrib.sessions.backends.cache'
CACHES = {
'BACKEND': 'django.core.cache.backends.memcached.MemcachedCache'
'LOCATION': 'my_memcached_host:11211',
}</programlisting>
</section>
<section xml:id="dashboard-session-database">
<title>Database</title>
<para>Database-backed sessions are scalable (using an appropriate
database strategy), persistent, and can be made high-concurrency
and highly-available.</para>
<para>The downside to this approach is that database-backed sessions
are one of the slower session storages, and incur a high overhead
under heavy usage. Proper configuration of your database deployment
can also be a substantial undertaking and is far beyond the scope
of this documentation. To enable, follow the below steps to
initialise the database and configure it for use</para>
<para>Start the mysql command line client by running:</para>
<screen><prompt>$ </prompt><userinput>mysql -u root -p</userinput></screen>
<para>Enter the MySQL root user's password when prompted.</para>
<para>To configure the MySQL database, create the dash database. </para>
<para><screen><prompt>mysql></prompt> <userinput>CREATE DATABASE dash;</userinput></screen></para>
<para>Create a MySQL user for the newly-created dash database that
has full control of the database. </para>
<para><screen><prompt>mysql></prompt> <userinput>GRANT ALL ON dash.* TO 'dash'@'%' IDENTIFIED BY
'yourpassword';</userinput></screen></para>
<para>Enter quit at the <literal>mysql></literal> prompt to exit MySQL.</para>
<para>In the <filename os="ubuntu">/etc/openstack-dashboard/local_settings.py</filename>
<filename os="centos;fedora;rhel">/etc/openstack-dashboard/local_settings</filename>
file, change these options:</para>
<programlisting language="python">SESSION_ENGINE = 'django.core.cache.backends.db.DatabaseCache'
</section>
<section xml:id="dashboard-session-database">
<title>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
session storages and incur a high overhead under heavy
usage. Proper configuration of your database deployment
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>
</step>
<step>
<para>Enter the MySQL root user's password when
prompted.</para>
</step>
<step>
<para>To configure the MySQL database, create the dash
database:</para>
<para><screen><prompt>mysql></prompt> <userinput>CREATE DATABASE dash;</userinput></screen></para>
</step>
<step>
<para>Create a MySQL user for the newly-created dash
database that has full control of the
database:</para>
<para><screen><prompt>mysql></prompt> <userinput>GRANT ALL ON dash.* TO 'dash'@'%' IDENTIFIED BY 'yourpassword';</userinput></screen></para>
</step>
<step>
<para>Enter quit at the <literal>mysql></literal>
prompt to exit MySQL.</para>
</step>
<step>
<para>In the <filename os="ubuntu"
>/etc/openstack-dashboard/local_settings.py</filename>
<filename os="centos;fedora;rhel"
>/etc/openstack-dashboard/local_settings</filename>
file, change these options:</para>
<programlisting language="python">SESSION_ENGINE = 'django.core.cache.backends.db.DatabaseCache'
DATABASES = {
'default': {
# Database configuration here
@ -96,57 +119,74 @@ DATABASES = {
'default-character-set': 'utf8'
}
}</programlisting>
<para>After configuring the <filename os="ubuntu">local_settings.py</filename>
<filename os="centos;fedora;rhel">/etc/openstack-dashboard/local_settings</filename>
as shown, you can run
the <command>manage.py syncdb</command> command to populate this newly-created
database.</para>
<screen><prompt>$</prompt> /usr/share/openstack-dashboard/manage.py syncdb </screen>
<para>As a result, you should see the following at the end of what returns:</para>
<screen><computeroutput>Installing custom SQL ...
</step>
<step>
<para>After configuring the <filename os="ubuntu"
>local_settings.py</filename>
<filename os="centos;fedora;rhel"
>/etc/openstack-dashboard/local_settings</filename>
as shown, you can run the <command>manage.py
syncdb</command> command to populate this
newly-created database.</para>
<screen><prompt>$</prompt> /usr/share/openstack-dashboard/manage.py syncdb </screen>
<para>As a result, the following output is
returned:</para>
<screen><computeroutput>Installing custom SQL ...
Installing indexes ...
DEBUG:django.db.backends:(0.008) CREATE INDEX `django_session_c25c2c28` ON `django_session` (`expire_date`);; args=()
No fixtures found.</computeroutput></screen>
<para os="ubuntu">If you want to avoid a warning when restarting apache2, create a blackhole directory in the dashboard directory like so:</para>
<screen os="ubuntu"><prompt>#</prompt> <userinput> sudo mkdir -p /var/lib/dash/.blackhole</userinput></screen>
<para>Restart Apache to pick up the default site and symbolic link settings.</para>
<screen os="ubuntu"><prompt>#</prompt> <userinput>/etc/init.d/apache2 restart</userinput></screen>
<screen os="centos;fedora;rhel"><prompt>#</prompt> <userinput>service httpd restart</userinput></screen>
<para os="ubuntu">Restart the nova-api service to ensure the API server can connect to the Dashboard and to
avoid an error displayed in the Dashboard. </para>
<screen os="ubuntu"><userinput>sudo restart nova-api</userinput></screen>
</section>
<section xml:id="dashboard-session-cached-database">
<title>Cached Database</title>
<para>To mitigate the performance issues of database queries, you
can also consider using Django’s cached_db session backend which
utilizes both your database and caching infrastructure to perform
write-through caching and efficient retrieval. You can enable this
hybrid setting by configuring both your database and cache as
discussed above and then using:</para>
<programlisting language="python">SESSION_ENGINE = "django.contrib.sessions.backends.cached_db" </programlisting>
</section>
<section xml:id="dashboard-session-cookies">
<title>Cookies</title>
<para>If you’re using Django 1.4 or later, a new session backend
is available to you which avoids server load and scaling problems:
the signed_cookies backend!</para>
<para>This backend stores session data in a cookie which is stored
by the user’s browser. The backend 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 attacker).</para>
<para>The pros of this session engine are that it doesn’t require
any additional dependencies or infrastructure overhead, and it
scales indefinitely as long as the quantity of session data being
stored fits into a normal cookie.</para>
<para>The biggest downside is that it places session data into
storage on the user’s machine and transports it over the wire. It
also limits the quantity of session data which can be stored.</para>
<para>For a thorough discussion of the security implications of
this session backend, please read the Django documentation on
<link xlink:href="https://docs.djangoproject.com/en/dev/topics/http/sessions/#using-cookie-based-sessions">cookie-based sessions.</link></para>
</section>
</step>
<step os="ubuntu">
<para>If you want to avoid a warning when you restart
apache2, create a blackhole directory in the
dashboard directory, as follows:</para>
<screen><prompt>#</prompt> <userinput> sudo mkdir -p /var/lib/dash/.blackhole</userinput></screen>
</step>
<step>
<para>Restart Apache to pick up the default site and
symbolic link settings:</para>
<screen os="ubuntu"><prompt>#</prompt> <userinput>/etc/init.d/apache2 restart</userinput></screen>
<screen os="centos;fedora;rhel"><prompt>#</prompt> <userinput>service httpd restart</userinput></screen>
</step>
<step os="ubuntu">
<para>Restart the nova-api service to ensure that the
API server can connect to the dashboard without
error: </para>
<screen><prompt>#</prompt> <userinput>sudo restart nova-api</userinput></screen>
</step>
</procedure>
</section>
<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
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>
</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
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
attacker.</para>
<para>The pros of this engine are that it requires no
additional dependencies or infrastructure overhead, and it
scales indefinitely as long as the quantity of session
data being stored fits into a normal cookie.</para>
<para>The biggest downside is that it places session data into
storage on the user’s machine and transports it over the
wire. It also limits the quantity of session data that can
be stored.</para>
<para>See the Django <link
xlink:href="https://docs.djangoproject.com/en/dev/topics/http/sessions/#using-cookie-based-sessions"
>cookie-based sessions</link> documentation.</para>
</section>
</section>

203
doc/src/docbkx/common/dashboardlaunchinginstances.xml
View File

@ -1,203 +0,0 @@
<?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="Launching_Instances_using_Dashboard">
<title>Launch instances</title>
<?dbhtml stop-chunking?>
<para>Instances are virtual machines that run inside the cloud.
You can launch an instance directly from one of the available OpenStack
images or from an image that you have copied to a persistent volume.
The OpenStack Image Service provides a pool of images that are accessible
to members of different projects.</para>
<section xml:id="Modify_Security_Groups">
<title>Add security group rules</title>
<para>Before you launch a virtual machine, you can add
security group rules to enable users to ping and SSH to
the instances. To do so, you either add rules to the
default security group or add a security group with rules. </para>
<para>The following procedure shows you how to add rules to
the default security group.</para>
<!-- <mediaobject>
<imageobject role="fo">
<imagedata
fileref="figures/Security-Group.png"
format="PNG" scale="60"/>
</imageobject>
<imageobject role="html">
<imagedata
fileref="figures/Security-Group.png"
format="PNG"/>
</imageobject>
</mediaobject> -->
<procedure><title>To add rules to the default security group:</title>
<step>
<para>Log in to the OpenStack dashboard.</para>
</step>
<step>
<para>If you are a member of multiple projects,
select a project from the drop-down list at
the top of the <guilabel>Project</guilabel>
tab. </para>
</step>
<step>
<para>Click the <guilabel>Access &amp;
Security</guilabel> category. </para>
<para>The dashboard shows the security groups that
are available for this project. </para><figure>
<title>OpenStack dashboard - Security Groups</title>
<mediaobject>
<imageobject role="fo">
<imagedata
fileref="figures/access_security.png"
format="PNG" scale="60"/>
</imageobject>
<imageobject role="html">
<imagedata
fileref="figures/access_security.png"
format="PNG"/>
</imageobject>
</mediaobject>
</figure>
</step>
<step>
<para>Select the default security group and click
<guibutton>Edit Rules</guibutton>. The
<guilabel>Security Group Rules</guilabel> page
appears: </para><figure>
<title>OpenStack dashboard - Security Group Rules</title>
<mediaobject>
<imageobject role="fo">
<imagedata
fileref="figures/add_rule.png"
format="PNG" scale="60"/>
</imageobject>
<imageobject role="html">
<imagedata
fileref="figures/add_rule.png"
format="PNG"/>
</imageobject>
</mediaobject>
</figure>
</step>
<step><title>Add a TCP rule</title><para>Click <guibutton>Add Rule</guibutton>. The <guilabel>Add
Rule</guilabel> window appears. </para><substeps><step><para>Select IP protocol TCP and enter 22 in "From Port"
and "To Port" and CIDR 0.0.0.0/0. This opens port 22
for requests from any IP. If you want requests from
particular range of IP, provide it in CIDR
field.</para></step></substeps>
</step>
<step><title>Add an ICMP rule</title><para>Select IP protocol ICMP and enter -1 in "From Port"
and "To Port" and CIDR 0.0.0.0/0. This allows ping
from any IP. If you want ping requests from particular
range of IP, provide it in CIDR field.</para></step></procedure>
</section>
<section xml:id="Adding_Keypair">
<title>Adding Keypair</title>
<para>Next add a Keypair. Once a Keypair is added, the
public key would be downloaded. This key can be used
to SSH to the launched instance.</para>
<para>
<mediaobject>
<imageobject role="fo">
<imagedata fileref="figures/KeyPair.png"
format="PNG" scale="60"/>
</imageobject>
<imageobject role="html">
<imagedata fileref="figures/KeyPair.png"
format="PNG"/>
</imageobject>
</mediaobject>
</para>
<para>Once this is done, we are now all set to launch an
Instance</para>
</section>
<section xml:id="Launching_Instance">
<title>Launching Instance</title>
<para>Click Images &amp; Snapshots and launch a required
instance from the list of images available.</para>
<para>
<mediaobject>
<imageobject role="fo">
<imagedata fileref="figures/Images.png"
format="PNG" scale="60"/>
</imageobject>
<imageobject role="html">
<imagedata fileref="figures/Images.png"
format="PNG"/>
</imageobject>
</mediaobject>
</para>
<para>Click launch on the required image. Provide a Server
Name, select the flavor, the keypair added above and
the default security group. Provide the number of
instances required. Once these details are provided,
click Launch Instance.</para>
<para>
<mediaobject>
<imageobject role="fo">
<imagedata
fileref="figures/LaunchInstance.png"
format="PNG" scale="60"/>
</imageobject>
<imageobject role="html">
<imagedata
fileref="figures/LaunchInstance.png"
format="PNG"/>
</imageobject>
</mediaobject>
</para>
<para>Once the status is Active, the instance is ready and
we can ping and SSH to the instance.</para>
<para>
<mediaobject>
<imageobject role="fo">
<imagedata fileref="figures/InstanceReady.png"
format="PNG" scale="60"/>
</imageobject>
<imageobject role="html">
<imagedata fileref="figures/InstanceReady.png"
format="PNG"/>
</imageobject>
</mediaobject>
</para>
</section>
<section xml:id="ssh-into-instance"><title>Make a secure connection to the launched instance</title>
<para>Here are the steps to SSH into an instance using the
downloaded keypair file. The username is ubuntu for the
Ubuntu cloud images on TryStack.</para>
<para>
<orderedlist>
<listitem>
<para>Download the <filename>MyKey.pem</filename> file from the OpenStack Dashboard.
</para>
</listitem>
<listitem>
<para>In a command line interface, modify the
access to the .pem file:</para>
<para>
<screen><userinput><prompt>$</prompt> chmod 0600 MyKey.pem</userinput></screen>
</para>
</listitem>
<listitem><para>Use the <command>ssh-add</command> command to ensure that the
keypair is known to
SSH:<screen><userinput><prompt>$</prompt> ssh-add MyKey.pem</userinput></screen></para></listitem>
<listitem>
<para>Copy the IP address from the
MyFirstInstance. </para>
</listitem>
<listitem>
<para>Use the SSH command to make a secure
connection to the
instance:<screen><userinput><prompt>$</prompt> ssh -i MyKey.pem ubuntu@10.0.0.2</userinput></screen></para>
<para>You should see a prompt asking "Are you sure you want to continue connection (yes/no)?" Type yes and you have successfully connected. </para>
</listitem>
</orderedlist>
</para></section>
</section>

BIN
doc/src/docbkx/common/figures/add_rule.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 38 KiB

After

Width:  |  Height:  |  Size: 267 KiB

BIN
doc/src/docbkx/common/figures/create_keypair.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 100 KiB

0
doc/src/docbkx/openstack-user/src/figures/instances.png → doc/src/docbkx/common/figures/instances.png
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 65 KiB

After

Width:  |  Height:  |  Size: 65 KiB

BIN
doc/src/docbkx/common/figures/keypairs.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 44 KiB

0
doc/src/docbkx/openstack-user/src/figures/launch_instances.png → doc/src/docbkx/common/figures/launch_instances.png
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 191 KiB

After

Width:  |  Height:  |  Size: 191 KiB

BIN
doc/src/docbkx/common/figures/security_group_rules.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 38 KiB

4
doc/src/docbkx/common/host_aggregates.xml
View File

@ -195,8 +195,8 @@ xml:id="host-aggregates">
<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
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>
create these kinds of host aggregates to support live migration. --></para>
</simplesect>
</section>

172
doc/src/docbkx/common/section_dashboard_launch_instances_from_image.xml Normal file
View File

@ -0,0 +1,172 @@
<?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="dashboard_launch_instances_from_image">
<title>Launch an instance from an image</title>
<?dbhtml stop-chunking?>
<para>Instances are virtual machines that run inside the
cloud.</para>
<para>You can launch an instance directly from one of the
available OpenStack images. The OpenStack Image Service
provides a pool of images that are accessible to members of
different projects. When you launch an instance from an image,
OpenStack creates a local copy of the image on the respective
compute node where the instance is started.</para>
<para>Alternatively, you can launch an instance from an image that
you have copied to a persistent volume.</para>
<para>To launch an instance, specify the following
parameters:</para>
<itemizedlist>
<listitem>
<para>The <guilabel>instance source</guilabel>, which is
an image or snapshot. Alternatively, you can boot from
a volume, which is block storage, to which you've
copied an image or snapshot.</para>
</listitem>
<listitem>
<para>The <guilabel>image</guilabel> or
<guilabel>snapshot</guilabel>, which represents
the operating system.</para>
</listitem>
<listitem>
<para>A <guilabel>name</guilabel> for your instance.
</para>
</listitem>
<listitem>
<para>The <emphasis role="bold">flavor</emphasis> for your
instance, which defines the compute, memory, and
storage capacity of nova computing instances. A flavor
is an available hardware configuration for a server.
It defines the size of a virtual server that can be
launched.</para>
</listitem>
<listitem>
<para>Access and security credentials, which include one
or both of the following credentials:</para>
<itemizedlist>
<listitem>
<para>A <emphasis role="bold">keypair</emphasis>
for your instance, which are SSH credentials
that are injected into images when they are
launched. For this to work, the image must
contain the <literal>cloud-init</literal>
package. Create at least one keypair for each
project. If you already have generated a
keypair with an external tool, you can import
it into OpenStack. You can use the keypair for
multiple instances that belong to that
project. </para>
</listitem>
<listitem>
<para>A <emphasis role="bold">security
group</emphasis>, which defines which
incoming network traffic is forwarded to
instances. Security groups hold a set of
firewall policies, known as <emphasis
role="italic">security group
rules</emphasis>. </para>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<para>If needed, you can assign a <emphasis role="bold"
>floating (public) IP address</emphasis> to a
running instance and attach a block storage device, or
volume, for persistent storage.</para>
</listitem>
</itemizedlist>
<procedure>
<title>To launch an instance:</title>
<step>
<para>Log in to the OpenStack dashboard.</para>
</step>
<step>
<para>If you are a member of multiple projects, select a
project from the drop-down list at the top of the
<guilabel>Project</guilabel> tab. </para>
</step>
<step>
<para>Click the <guilabel>Images &amp; Snapshot</guilabel>
category. </para>
<para>The dashboard shows the images that have been
uploaded to OpenStack Image Service and are available
for this project. </para>
</step>
<step>
<para>Select an image and click
<guibutton>Launch</guibutton>. The
<guilabel>Launch Image</guilabel> window appears: <figure>
<title>OpenStack dashboard - Launch Instances
window</title>
<mediaobject>
<imageobject>
<imagedata
fileref="figures/launch_instances.png"
width="6in" contentwidth="6in"/>
</imageobject>
</mediaobject>
</figure></para>
</step>
<step>
<para>Specify the following parameters: </para>
<itemizedlist>
<listitem>
<para>Enter an instance name to assign to the
virtual machine. </para>
</listitem>
<listitem>
<para>From the <guilabel>Flavor</guilabel>
drop-down list, select the size of the virtual
machine to launch. </para>
</listitem>
<listitem>
<para>Optionally, select a keypair. </para>
<para>In case an image uses a static root password
or a static key set (neither is recommended),
you do not need to provide a keypair on
starting the instance. </para>
</listitem>
<listitem>
<para>In <guilabel>Instance Count</guilabel>,
enter the number of virtual machines to launch
from this image. </para>
</listitem>
<listitem>
<para>Assign the instance to the default security
group. If you added rules to this group, the
instance implements these rules.</para>
</listitem>
<!-- <listitem>
<para>If you want to boot from volume, click the
respective entry to expand its options. Set
the options as described in Launching
Instances from a Volume. </para>
</listitem> -->
</itemizedlist>
</step>
<step>
<para>Click <guibutton>Launch Instance</guibutton>. The
instance is launched on any of the compute nodes in
the cloud. </para>
</step>
</procedure>
<para>After you have launched an instance, switch to the
<guilabel>Instances &amp; Volumes</guilabel> category to
view the instance name, its (private or public) IP address,
size, status, task, and power state.</para>
<figure>
<title>OpenStack dashboard - Instances</title>
<mediaobject>
<imageobject>
<imagedata fileref="figures/instances.png" width="6in"
contentwidth="6in"/>
</imageobject>
</mediaobject>
</figure>
<para>If you did not provide a keypair on starting and have not
touched security groups or rules so far, by default the
instance can only be accessed from inside the cloud through
VNC at this point. Even pinging the instance is not possible. </para>
</section>

258
doc/src/docbkx/common/wadl/security-groups.wadl Normal file
View File

@ -0,0 +1,258 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE application [<!ENTITY % common SYSTEM "../common.ent">
%common;]>
<!-- (C) 2013 OpenStack Foundation, All Rights Reserved -->
<application xmlns="http://wadl.dev.java.net/2009/02"
xmlns:xsdxt="http://docs.rackspacecloud.com/xsd-ext/v1.0"
xmlns:wadl="http://wadl.dev.java.net/2009/02"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:csapi="http://www.w3.org/2001/XMLSchema">
<resources base="https://servers.api.openstack.com/">
<resource id="version" path="v2">
<resource id="tenant_id" path="{tenant_id}">
<param name="tenant_id" style="template"
type="csapi:uuid">
<doc>
<p xmlns="http://www.w3.org/1999/xhtml">The
unique identifier of the tenant or
account. </p>
</doc>
</param>
<resource id="security_groups" path="security-groups">
<method href="#listSecGroups"/>
<method href="#createSecGroup"/>
<resource id="get_security_group"
path="{security_group_id}">
<param name="security_group_id"
style="template" type="csapi:uuid">
<doc><p
xmlns="http://www.w3.org/1999/xhtml"
>The unique identifier of the
security group. </p></doc>
</param>
<method href="#getSecGroup"/>
<method href="#deleteSecGroup"/>
</resource>
</resource>
<resource id="security_groups_rules"
path="security-group-rules">
<method href="#listSecGroupRules"/>
<method href="#createSecGroupRule"/>
<resource path="{rules-security-groups-id}">
<param name="rules-security-groups-id"
style="template" type="csapi:uuid">
<doc><p
xmlns="http://www.w3.org/1999/xhtml"
>The unique identifier of the
security group rule. </p></doc>
</param>
<method href="#getSecGroupRule"/>
<method href="#deleteSecGroupRule"/>
</resource>
</resource>
<resource id="Servers" path="servers">
<resource path="{server_id}">
<param name="server_id" style="template"
type="csapi:UUID">
<doc>
<p
xmlns="http://www.w3.org/1999/xhtml"
>The UUID for the server of
interest to you. </p>
</doc>
</param>
<resource path="os-security-groups">
<method href="#listSecGroupsByServer"/>
</resource>
</resource>
</resource>
</resource>
</resource>
</resources>
<method name="GET" id="listSecGroups">
<wadl:doc xmlns="http://www.w3.org/1999/xhtml" xml:lang="EN">
<p xmlns="http://www.w3.org/1999/xhtml" role="shortdesc"
>Lists a summary of all Quantum-defined security groups that are accessible to the specified tenant. </p><p
xmlns="http://www.w3.org/1999/xhtml">The list provides
the unique ID for each security group.</p>
</wadl:doc>
<request>
<representation mediaType="application/json">
<doc xml:lang="EN"><xsdxt:code
href="../api_samples/security-groups/security-groups-list-get-req.json"
/></doc>
</representation>
<representation mediaType="application/xml">
<doc xml:lang="EN"><xsdxt:code
href="../api_samples/security-groups/security-groups-list-get-req.xml"
/></doc>
</representation>
</request>
<response status="200">
<representation mediaType="application/xml">
<doc xml:lang="EN">
<xsdxt:code
href="../api_samples/security-groups/security-groups-list-get-resp.xml"
/>
</doc>
</representation>
<representation mediaType="application/json">
<doc xml:lang="EN">
<xsdxt:code
href="../api_samples/security-groups/security-groups-list-get-resp.json"
/>
</doc>
</representation>
</response>
<response status="401"/>
</method>
<method name="GET" id="getSecGroup">
<wadl:doc xmlns="http://www.w3.org/1999/xhtml" xml:lang="EN">
<p xmlns="http://www.w3.org/1999/xhtml">Shows information
for a specified security group. </p>
</wadl:doc>
<response status="200">
<representation mediaType="application/xml">
<doc xml:lang="EN">
<xsdxt:code
href="../api_samples/security-groups/security-groups-get-resp.xml"
/>
</doc>
</representation>
<representation mediaType="application/json">
<doc xml:lang="EN">
<xsdxt:code
href="../api_samples/security-groups/security-groups-get-resp.json"
/>
</doc>
</representation>
</response>
</method>
<method name="POST" id="createSecGroup">
<wadl:doc xmlns="http://www.w3.org/1999/xhtml" xml:lang="EN">
<p xmlns="http://www.w3.org/1999/xhtml">Creates a security
group. </p>
</wadl:doc>
<request>
<representation mediaType="application/xml">
<doc xml:lang="EN">
<xsdxt:code
href="../api_samples/security-groups/security-groups-create-req.xml"
/>
</doc>
</representation>
<representation mediaType="application/json">
<doc xml:lang="EN">
<xsdxt:code
href="../api_samples/security-groups/security-groups-create-req.json"
/>
</doc>
</representation>
</request>
<response status="200">
<representation mediaType="application/xml">
<doc xml:lang="EN">
<xsdxt:code
href="../api_samples/security-groups/security-groups-create-resp.xml"
/>
</doc>
</representation>
<representation mediaType="application/json">
<doc xml:lang="EN">
<xsdxt:code
href="../api_samples/security-groups/security-groups-create-resp.json"
/>
</doc>
</representation>
</response>
</method>
<method name="DELETE" id="deleteSecGroup">
<wadl:doc xmlns="http://www.w3.org/1999/xhtml" xml:lang="EN">
<p xmlns="http://www.w3.org/1999/xhtml">Deletes a security
group.</p>
</wadl:doc>
<response status="202"/>
</method>
<method name="GET" id="listSecGroupRules">
<wadl:doc xmlns="http://www.w3.org/1999/xhtml" xml:lang="EN">
<p xmlns="http://www.w3.org/1999/xhtml">Lists security
group rules. </p>
</wadl:doc>
<response status="200">
<representation mediaType="application/xml">
<doc xml:lang="EN">
<xsdxt:code
href="../api_samples/security-groups/security-groups-list-get-resp.xml"
/>
</doc>
</representation>
<representation mediaType="application/json">
<doc xml:lang="EN">
<xsdxt:code
href="../api_samples/security-groups/security-groups-list-get-resp.json"
/>
</doc>
</representation>
</response>
</method>
<method name="POST" id="createSecGroupRule">
<wadl:doc xmlns="http://www.w3.org/1999/xhtml" xml:lang="EN">
<p xmlns="http://www.w3.org/1999/xhtml">Creates a security
group rule. </p>
</wadl:doc>
<request>
<representation mediaType="application/json">
<doc xml:lang="EN">
<xsdxt:code
href="../api_samples/security-groups/rules-security-groups-create-req.json"
/>
</doc>
</representation>
</request>
<response status="200">
<representation mediaType="application/xml">
<doc xml:lang="EN">
<xsdxt:code
href="../api_samples/security-groups/rules-security-groups-create-resp.xml"
/>
</doc>
</representation>
<representation mediaType="application/json">
<doc xml:lang="EN">
<xsdxt:code
href="../api_samples/security-groups/rules-security-groups-create-resp.json"
/>
</doc>
</representation>
</response>
</method>
<method name="DELETE" id="deleteSecGroupRule">
<wadl:doc xmlns="http://www.w3.org/1999/xhtml" xml:lang="EN">
<p xmlns="http://www.w3.org/1999/xhtml">Deletes a
specified Quantum security group rule from a security
group. </p>
</wadl:doc>
<response status="204"/>
</method>
</application>

5
doc/src/docbkx/openstack-compute-admin/bk-compute-adminguide.xml
View File

@ -228,14 +228,15 @@
<xi:include href="../common/getstart.xml"/>
<xi:include href="aboutcompute.xml"/>
<xi:include href="computeinstall.xml"/>
<xi:include href="computeconfigure.xml"/>
<xi:include href="../openstack-config/ch_compute-options-reference.xml"/>
<!--<xi:include href="computeconfigure.xml"/> -->
<!--<xi:include href="compute-options-reference.xml"/> -->
<xi:include href="../common/ch_identity_mgmt.xml"/>
<xi:include href="../common/ch_image_mgmt.xml"/>
<xi:include href="ch_instance_mgmt.xml"/>
<xi:include href="../openstack-config/ch_computehypervisors.xml"/>
<xi:include href="computenetworking.xml"/>
<xi:include href="computevolumes.xml"/>
<!-- next two files previously commented out - but build fails -->
<xi:include href="computescheduler.xml"/>
<xi:include href="computecells.xml"/>
<xi:include href="computeadmin.xml"/>

26
doc/src/docbkx/openstack-compute-admin/ch_instance_mgmt.xml
View File

@ -6,14 +6,15 @@
<title>Instance Management</title>
<para>Instances are the running virtual machines within an
OpenStack cloud. The <link linkend="images-and-instances"
>Images and Instances</link> section of the <link
linkend="ch_introduction-to-openstack-compute"
>Introduction to OpenStack Compute</link> Chapter provides
a high level overview of instances and their life cycle</para>
OpenStack cloud. </para>
<para><!--<phrase>The <link linkend="images-and-instances"
>Images and Instances</link> section</phrase>-->See <xref
linkend="ch_introduction-to-openstack-compute"/>
for
a high level overview of instances and their life cycle.</para>
<para>This chapter deals with the details of how to manage that
life cycle</para>
<para>This chapter describes how to manage that
life cycle.</para>
<section xml:id="instance-mgmt-interfaces">
<?dbhtml stop-chunking?>
@ -151,10 +152,10 @@ header: Date: Thu, 13 Sep 2012 20:27:36 GMT
provides an EC2 compatible API. This allows legacy
workflows built for EC2 to work with OpenStack.</para>
<para><link linkend="configuring-ec2-API">Configuring the
<!--<para><link linkend="configuring-ec2-API">Configuring the
EC2 API</link> lists configuration options for
customizing this compatibility API on your OpenStack
cloud.</para>
cloud.</para> -->
</simplesect>
<simplesect xml:id="instance-mgmt-3rdparty">
@ -401,8 +402,7 @@ header: Date: Thu, 13 Sep 2012 20:27:36 GMT
<section xml:id="instance-scheduling-constraints">
<title>Controlling where instances run</title>
<para>The <link linkend="scheduler-filters">scheduler
filters</link> section provides detailed information
<para>The <xref linkend="ch_scheduling"/> provides detailed information
on controlling where your instances run, including
ensuring a set of instances run on <link
linkend="differenthostfilter">different</link> compute
@ -457,10 +457,10 @@ header: Date: Thu, 13 Sep 2012 20:27:36 GMT
or you are trying to debug a problem image OpenStack can
be configured to provide a VNC console, be aware that VNC
is an unencrypted protocol so you should be cautious what
you type across that link. See the <link
you type across that link. </para><!--<para>See the <link
linkend="getting-started-with-vnc-proxy">Getting
Started With VNC Proxy</link> section for details on
how to configure and connect to this service.</para>
how to configure and connect to this service.</para> -->
</section>
<xi:include href="../common/nova_cli_startstop.xml"/>

16
doc/src/docbkx/openstack-compute-admin/computeadmin.xml
View File

@ -341,8 +341,8 @@ local0.error @@172.20.1.43:1024</programlisting></para>
<section xml:id="live-migration-usage">
<title>Using Migration</title>
<para>Before starting migrations, review the <link linkend="configuring-migrations"
>Configuring Migrations</link> section.</para>
<!--<para>Before starting migrations, review the <link linkend="configuring-migrations"
>Configuring Migrations</link> section.</para>-->
<para>Migration provides a scheme to migrate running instances from one OpenStack Compute
server to another OpenStack Compute server. This feature can be used as described below. </para>
@ -437,9 +437,9 @@ HostC p2 5 10240 150
list</command>. If instances are still running on HostB, check logfiles
(src/dest nova-compute and nova-scheduler) to determine why.
<note><para>While the nova command is called <command>live-migration</command>, under the default Compute
configuration options the instances are suspended before migration. See
configuration options the instances are suspended before migration.</para></note><!--<para>See
the <link linkend="configuring-migrations">Configuring Migrations</link>
section for more details.</para></note></para>
section for more details.</para>--></para>
</listitem>
</itemizedlist>
</section>
@ -447,10 +447,10 @@ HostC p2 5 10240 150
<title>Recovering from a failed compute node</title>
<para>If you have deployed OpenStack Compute with a shared filesystem,
you can quickly recover from a failed compute node. </para>
<section xml:id="nova-compute-node-down-evacuate-api">
<title>Using the evacuate API for KVM/libvirt</title>
<para>Refer to <link linkend="nova_cli_evacuate">Evacuate API Reference</link> section for more details.</para>
</section>
<!--<section xml:id="nova-compute-node-down-evacuate-api">
<title>Using the evacuate API for KVM/libvirt</title> -->
<!--<para>Refer to <link linkend="nova_cli_evacuate">Evacuate API Reference</link> section for more details.</para>-->
<!-- </section> -->
<section xml:id="nova-compute-node-down-manual-recovery">
<title>Manual recovery</title>
<para>For KVM/libvirt compute node recovery refer to section above, while the guide below may be applicable for other hypervisors.</para>

17
doc/src/docbkx/openstack-compute-admin/computeinstall.xml
View File

@ -175,10 +175,10 @@ URI: http://download.opensuse.org/repositories/Cloud:/OpenStack:/Grizzly/openSUS
<para>When using OpenStack Compute with Citrix XenServer or XCP hypervisor,
OpenStack Compute should be installed in a virtual machine running on
your hypervisor, rather than installed directly on the hypervisor,
as you would do when using the Libvirt driver.
For more information see:
as you would do when using the Libvirt driver.</para>
<!--<para>For more information see:
<link linkend="xenapi-install">XenAPI Install</link>.
</para>
</para>-->
<para>
Given how you should deploy OpenStack with XenServer, the first step when
@ -186,11 +186,10 @@ URI: http://download.opensuse.org/repositories/Cloud:/OpenStack:/Grizzly/openSUS
is to install XenServer and install the required XenServer plugins.
You can install XCP by installing Debian or Ubuntu, but generally rather
than installing the operating system of your choice on your compute nodes,
you should first install XenServer.
For more information see:
you should first install XenServer.</para>
<!-- <para>For more information see:
<link linkend="xenapi-deployment-architecture">XenAPI Deployment Architecture</link>.
</para>
</para> -->
<para>Once you have installed XenServer and the XenAPI plugins
on all your compute nodes, you next need to create a virtual machine
on each of those compute nodes.
@ -199,8 +198,8 @@ URI: http://download.opensuse.org/repositories/Cloud:/OpenStack:/Grizzly/openSUS
You can follow the previous distribution specific instructions to get the
OpenStack code running in your Virtual Machine.
Once installed, you will need to configure OpenStack Compute to talk to
your XenServer or XCP installation. For more information see:
your XenServer or XCP installation.</para><!--<para>For more information see:
<link linkend="introduction-to-xen">Introduction to Xen</link>.
</para>
</para>-->
</section>
</chapter>

13
doc/src/docbkx/openstack-compute-admin/computeinterfaces.xml
View File

@ -5,8 +5,13 @@
version="5.0"
xml:id="ch_openstack-interfaces">
<title>OpenStack Interfaces</title>
<para>The OpenStack dashboard, a Web interface,
enables you to connect to running instances through a VNC connection.</para>
<xi:include href="../common/about-dashboard.xml"/>
<xi:include href="remote-console-access.xml"/>
<para>You can interact with an OpenStack cloud in the following ways:
<itemizedlist><listitem>
<para>The OpenStack dashboard.</para>
</listitem>
<listitem>
<para>A VNC connection through a VNC proxy.</para>
</listitem></itemizedlist></para>
<xi:include href="section_dashboard.xml"/>
<xi:include href="remote-console-access.xml"/>
</chapter>

8
doc/src/docbkx/openstack-compute-admin/computenetworking.xml
View File

@ -446,9 +446,9 @@ echo 'Extra user data here'</computeroutput></screen>
Before reading how to configure networking using the XenAPI compute
driver, you may find it useful to read the Citrix article on
<link xlink:href="http://support.citrix.com/article/CTX117915">
Understanding XenServer Networking</link> and the section of this
Understanding XenServer Networking</link>. <!--<phrase>and the section of this
document that describes
<link linkend="introduction-to-xen">XenAPI and OpenStack</link>.
<link linkend="introduction-to-xen">XenAPI and OpenStack</link>.</phrase>-->
</para>
<section xml:id="configuring-flat-networking">
@ -2125,8 +2125,8 @@ enabled_apis=ec2,osapi_compute,osapi_volume,metadata</programlisting></para>
hosts networks will send all network related commands to the host that the specific
VM is on. You need to edit the configuration option <literal>enabled_apis</literal>
such that it includes <literal>metadata</literal> in the list of enabled APIs.
Other options become available when you configure <literal>multi_host</literal> nova networking please
refer to <link linkend="list-of-compute-config-options"> Configuration: nova.conf</link>.</para>
Other options become available when you configure <literal>multi_host</literal> nova networking.
</para><!--<para>See <link linkend="list-of-compute-config-options">Configuration: nova.conf</link>.</para>-->
<note>
<para>You must specify the <literal>multi_host</literal> option on the command line
when creating fixed networks. For example:

8
doc/src/docbkx/openstack-compute-admin/pom.xml
View File

@ -44,11 +44,11 @@
appendix toc,title
article/appendix nop
article toc,title
book title,figure,table,example,equation
chapter toc,title
book toc,title,figure,table,example,equation
chapter toc
section toc
part toc,title
preface toc,title
part toc
preface toc
qandadiv toc
qandaset toc
reference toc,title

2
doc/src/docbkx/openstack-compute-admin/remote-console-access.xml
View File

@ -4,7 +4,7 @@
xmlns:xlink="http://www.w3.org/1999/xlink"
version="5.0"
xml:id="remote-console-access">
<title>Remote Console Access</title>
<title>Access OpenStack through a remote console</title>
<!--<?dbhtml stop-chunking?>-->
<para>OpenStack has two main methods for providing a remote
console or remote desktop access to guest Virtual

69
doc/src/docbkx/openstack-compute-admin/section_dashboard.xml Normal file
View File

@ -0,0 +1,69 @@
<?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="ch_install-dashboard">
<title>The OpenStack dashboard</title>
<para xmlns:raxm="http://docs.rackspace.com/api/metadata">The
OpenStack 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>To install the OpenStack dashboard, complete the following
high-level steps: </para>
<orderedlist>
<listitem>
<para>Meet the system requirements for accessing the
dashboard. See <xref
linkend="dashboard-system-requirements"/>.</para>
</listitem>
<listitem>
<para>Install the OpenStack Dashboard framework, including
Apache and related modules. See <xref
linkend="installing-openstack-dashboard"/>.</para>
</listitem>
<listitem>
<para>Configure the dashboard.</para>
<para>Then, restart and run the Apache server.</para>
<para>See <xref linkend="configure-dashboard"/>.</para>
</listitem>
<listitem>
<para>Verify your installation. See <xref
linkend="verify-dashboard"/>.</para>
</listitem>
</orderedlist>
<itemizedlist>
<title>Next steps:</title>
<para>After you install the dashboard, you can complete the
following tasks:</para>
<listitem>
<para>To customize your dashboard, see <xref
linkend="dashboard-custom-brand"/>. </para>
</listitem>
<listitem>
<para>To set up session storage for the dashboard, see
<xref linkend="dashboard-sessions"/>.</para>
</listitem>
<listitem>
<para>To deploy the dashboard, see <link
xlink:href="http://docs.openstack.org/developer/horizon/topics/deployment.html"
>Deploying Horizon</link>.</para>
</listitem>
<listitem xml:id="launch_instances">
<para>To launch instances with the dashboard, see the
<citetitle>OpenStack User
Guide</citetitle>.</para>
</listitem>
</itemizedlist>
<xi:include href="../common/dashboard-system-reqs.xml"/>
<xi:include href="../common/dashboard-install.xml"/>
<xi:include href="../common/dashboard-configure.xml"/>
<xi:include href="../common/dashboard-verify.xml"/>
<xi:include href="../common/dashboard_sessions.xml"/>
<xi:include href="../common/dashboard_customizing.xml"/>
</section>

10
doc/src/docbkx/openstack-user/pom.xml
View File

@ -7,6 +7,14 @@
<version>1.0.0-SNAPSHOT</version>
<packaging>jar</packaging>
<name>OpenStack Guides</name>
<properties>
<!-- This is set by Jenkins according to the branch. -->
<release.path.name>grizzly</release.path.name>
<comments.enabled>1</comments.enabled>
<operating.system>apt</operating.system>
<!-- This is set by Jenkins to run twice for each similar operating system group -->
<profile.os>ubuntu</profile.os>
</properties>
<!-- ################################################ -->
<!-- USE "mvn clean generate-sources" to run this POM -->
<!-- ################################################ -->
@ -52,7 +60,7 @@ set toc,title
<sectionLabelIncludesComponentLabel>0</sectionLabelIncludesComponentLabel>
<webhelpDirname>user-guide</webhelpDirname>
<includeDateInPdfFilename>0</includeDateInPdfFilename>
<pdfFilenameBase>user-guide.pdf</pdfFilenameBase>
<pdfFilenameBase>user-guide</pdfFilenameBase>
</configuration>
</execution>
<execution>

13
doc/src/docbkx/openstack-user/src/ch_cli.xml
View File

@ -12,7 +12,18 @@
<para>The OpenStack project provides a variety of command-line
clients that let you manage the services within your cloud and
automate tasks by using scripts. Each of the core OpenStack
components has its own command-line client.</para>
components has its own command-line client. These open-source
Python clients run on Linux or Mac OS X systems and are easy
to learn and use. </para>
<para>You can use the OpenStack command-line clients to run simple
commands that make API calls. You can specify a <parameter
xmlns:svg="http://www.w3.org/2000/svg"
xmlns:m="http://www.w3.org/1998/Math/MathML"
xmlns:html="http://www.w3.org/1999/xhtml"
xmlns:db="http://docbook.org/ns/docbook">debug</parameter>
parameter on any client command to show the underlying API
request for the command. This is a good way to become familiar
with the OpenStack API requests. </para>
<para>These examples walk
you through the steps to create a server instance with 2 GB
of physical memory.</para>

37
doc/src/docbkx/openstack-user/src/ch_dashboard.xml
View File

@ -7,14 +7,40 @@
xmlns:raxm="http://docs.rackspace.com/api/metadata" version="5.0"
xml:id="ch_dashboard">
<info>
<title>OpenStack dashboard</title>
<title>The OpenStack dashboard</title>
<?dbhtml stop-chunking?>
</info>
<para>The OpenStack 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>
>horizon</link>, is a Web-based interface that enables
cloud administrators and users to manage various OpenStack
resources and services. </para>
<para xmlns:svg="http://www.w3.org/2000/svg"
xmlns:m="http://www.w3.org/1998/Math/MathML"
xmlns:html="http://www.w3.org/1999/xhtml"
xmlns:db="http://docbook.org/ns/docbook">You can customize the
dashboard with your own brand and other features.</para>
<para xmlns:svg="http://www.w3.org/2000/svg"
xmlns:m="http://www.w3.org/1998/Math/MathML"
xmlns:html="http://www.w3.org/1999/xhtml"
xmlns:db="http://docbook.org/ns/docbook">As a cloud
administrator, the dashboard provides you with an overall view
of the size and state of your cloud. You can create users and
projects, assign users to projects and set limits on the
resources for those projects. </para>
<para xmlns:svg="http://www.w3.org/2000/svg"
xmlns:m="http://www.w3.org/1998/Math/MathML"
xmlns:html="http://www.w3.org/1999/xhtml"
xmlns:db="http://docbook.org/ns/docbook">As a cloud user, the
dashboard enables you to provision your own resources within
the limits set by administrators. </para>
<para xmlns:svg="http://www.w3.org/2000/svg"
xmlns:m="http://www.w3.org/1998/Math/MathML"
xmlns:html="http://www.w3.org/1999/xhtml"
xmlns:db="http://docbook.org/ns/docbook">To see a demo of the
dashboard, go to <link
xlink:href="http://www.openstack.org/software/openstack-dashboard/"
>OpenStack Dashboard</link>.</para>
<para>After a short introduction, learn how to use the install and
configure the dashboard. </para>
<para>Then use the simple
@ -26,8 +52,7 @@
<xi:include href="section_dashboard_install.xml"/>
<xi:include href="section_dashboard_overview.xml"/>
<xi:include href="section_dashboard_manage_images.xml"/>
<xi:include href="../../common/dashboardlaunchinginstances.xml"/>
<xi:include href="section_dashboard_launch_instances_from_image.xml"/>
<xi:include href="section_dashboard_launch_instances.xml"/>
<xi:include href="section_dashboard_launch_instances_from_volume.xml"/>
<xi:include href="section_dashboard_configure_instances.xml"/>
<xi:include href="section_dashboard_manage_instances.xml"/>

104
doc/src/docbkx/openstack-user/src/ch_openstack_what_and_how.xml
View File

@ -14,70 +14,56 @@
images and snapshots, set up cloud access and security, and
track usage. Cloud administrators can also create and manage
users and projects. </para>
<db:para>As a cloud administrator, the dashboard provides you with
an overall view of the size and state of your cloud. You can
create users and projects, assign users to projects and set
limits on the resources for those projects. As a cloud user,
the dashboard enables you to provision your own resources
within the limits set by administrators. </db:para>
<para>You can achieve most of these tasks with the OpenStack
dashboard or the OpenStack command-line clients. The dashboard
and the command-line clients are not the only ways to interact
with OpenStack resources and services. You can automate access
or build tools to manage resources and services by using the
native OpenStack APIs or the EC2 compatibility API.</para>
<para>This guide helps OpenStack cloud administrators and users
launch and manage instances and manage volumes. </para>
<para>For each exercise in this guide, you choose one of the
following methods to complete tasks in the cloud: <itemizedlist>
<listitem>
<para><emphasis role="bold">The OpenStack
dashboard</emphasis>. The OpenStack dashboard
provides administrators and users a graphical
interface to access, provision, and automate
cloud-based resources. You can customize the
dashboard with your own brand. The dashboard is an
extensible web app that allows cloud
administrators and users to control their compute,
storage, and networking resources. </para>
<para>As a cloud administrator, the dashboard provides
an overall view of the size and state of your
cloud. You can create users and projects, assign
users to projects and set limits on the resources
for those projects. The dashboard provides users a
self-service portal to provision their own
resources within the limits set by administrators.
To see a demo of the dashboard, go to <link
xlink:href="http://www.openstack.org/software/openstack-dashboard/"
>OpenStack Dashboard</link>.</para>
</listitem>
<listitem>
<para><emphasis role="bold">The OpenStack command-line
clients</emphasis>. We recommend that you use
the OpenStack command-line clients to run simple
commands that make API calls. These open-source
Python clients run on Linux or Mac OS X systems
and are easy to learn and use. You can specify a
<parameter>debug</parameter> parameter on any
client command to show the underlying API request
for the command. This is a good way to become
familiar with the OpenStack API requests. </para>
</listitem>
<listitem>
<para><emphasis role="bold">Other methods</emphasis>. <itemizedlist>
<listitem>
<para><emphasis role="bold"><link
xlink:href="http://curl.haxx.se/"
>cURL</link> commands</emphasis>.
If you are familiar with or want to
learn cURL commands, choose this
method. With cURL, you send HTTP
requests with embedded API calls from
the command line. The cURL examples in
this guide include request bodies that
are in JSON format. </para>
</listitem>
<listitem>
<para>Rackspace SDKs. <link
xlink:href="http://developer.rackspace.com"
>Rackspace Developer
Center</link>.</para>
</listitem>
</itemizedlist>
</para>
</listitem>
</itemizedlist>
</para>
following methods to complete tasks in the cloud:</para>
<itemizedlist>
<listitem>
<para>OpenStack dashboard, also known as <link
xlink:href="https://github.com/openstack/horizon/"
>horizon</link>, is a Web-based graphical
interface that enables cloud administrators and users
to access, provision, and automate cloud-based
resources.</para>
</listitem>
<listitem>
<para>OpenStack command-line clients let cloud
administrators and users run simple commands to manage
resources and services within a cloud and automate
tasks by using scripts. Each of the core OpenStack
projects has its own command-line client. </para>
</listitem>
</itemizedlist>
<para>You can also interact with an OpenStack cloud in the
following ways:</para>
<itemizedlist>
<listitem>
<para><link
xlink:href="http://curl.haxx.se/">cURL</link>
commands. If you are familiar with or
want to learn cURL commands, choose this method. With
cURL, you send HTTP requests with embedded API calls
from the command line. The cURL examples in this guide
include request bodies that are in JSON format.
</para>
</listitem>
<listitem>
<para>Rackspace SDKs. See <link
xlink:href="http://developer.rackspace.com"
>Rackspace Developer Center</link>.</para>
</listitem>
</itemizedlist>
</chapter>

34
doc/src/docbkx/openstack-user/src/ch_overview.xml
View File

@ -9,43 +9,25 @@
xml:id="openstack_user_guide">
<title>OpenStack User Guide</title>
<?dbhtml stop-chunking?>
<para>OpenStack is a global collaboration of developers and cloud
computing technologists producing the ubiquitous open source
cloud computing platform for public and private clouds. </para>
<para>The project delivers solutions for all types of clouds by
being simple to implement, massively scalable, and feature
rich. </para>
<para>The technology consists of a series of interrelated projects
that deliver various components for a cloud infrastructure
solution. </para>
<para>OpenStack is an open source cloud computing platform for
public and private clouds. The technology consists of a series
of interrelated projects that deliver various components for a
cloud infrastructure solution. </para>
<para>This guide helps OpenStack cloud administrators and users
launch and manage instances and manage volumes. You can
achieve most of these tasks with the OpenStack dashboard or
the OpenStack command-line clients. </para>
<para>The OpenStack 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. The dashboard enables web-based interactions
with the OpenStack Compute cloud controller through the
OpenStack APIs.</para>
<para>The OpenStack project also provides a variety of
command-line clients that let you manage resources and
services within your cloud and automate tasks by using
scripts. Each of the core OpenStack components has its own
command-line client.</para>
<para>The exercises help you learn how cURL commands and the
OpenStack APIs work.</para>
<para>To use the OpenStack APIs, it helps to be familiar with
HTTP/1.1, RESTful web services, the OpenStack services, and
JSON or XML data serialization formats.</para>
<xi:include href="section_dochistory.xml"/>
<section xml:id="resources">
<title>Resources</title>
<para>For the available documentation, see <link
<para>For the available OpenStack documentation, see <link
xlink:href="http://docs.openstack.org"
>docs.openstack.org</link>. </para>
<para>For the Rackspace SDKs, see <link
xlink:href="http://developer.rackspace.com"/>.</para>
<para>For the Rackspace SDKs, see the <link
xlink:href="http://developer.rackspace.com">Rackspace
Developer Center</link>.</para>
</section>
</preface>

73
doc/src/docbkx/openstack-user/src/section_cli_overview.xml
View File

@ -6,49 +6,64 @@
<title>Command-line clients overview</title>
<para>The following command-line clients are available for the
respective services' APIs:</para>
<variablelist><varlistentry>
<term>keystone</term>
<listitem><para>Identity Service</para>
<variablelist wordsize="10">
<varlistentry>
<term>keystone</term>
<listitem>
<para>Identity Service</para>
<para>Manage users and projects.</para>
<para><literal>python-keystoneclient</literal></para></listitem>
</varlistentry>
<varlistentry>
<term>nova</term><listitem>
<para><literal>python-keystoneclient</literal></para>
</listitem>
</varlistentry>
<varlistentry>
<term>nova</term>
<listitem>
<para>Compute, Compute extensions</para>
<para>Manage instances and flavors.</para>
<para><literal>python-novaclient</literal></para></listitem>
</varlistentry>
<varlistentry>
<term>glance</term><listitem>
<para><literal>python-novaclient</literal></para>
</listitem>
</varlistentry>
<varlistentry>
<term>glance</term>
<listitem>
<para>Image Service</para>
<para>Manage images. </para>
<para><literal>python-glanceclient</literal></para></listitem>
</varlistentry>
<varlistentry>
<term>cinder</term><listitem>
<para><literal>python-glanceclient</literal></para>
</listitem>
</varlistentry>
<varlistentry>
<term>cinder</term>
<listitem>
<para>Block Storage Service</para>
<para>Manage volumes.</para>
<para><literal>python-cinderclient</literal></para></listitem>
</varlistentry>
<varlistentry>
<term>quantum</term><listitem>
<para><literal>python-cinderclient</literal></para>
</listitem>
</varlistentry>
<varlistentry>
<term>quantum</term>
<listitem>
<para>Networking</para>
<para>Configure networks for guest servers.</para>
<para><literal>python-quantumclient</literal></para></listitem>
</varlistentry>
<varlistentry>
<term>swift</term><listitem>
<para><literal>python-quantumclient</literal></para>
</listitem>
</varlistentry>
<varlistentry>
<term>swift</term>
<listitem>
<para>Object Storage</para>
<para>Manage the object store. </para>
<para><literal>python-swiftclient</literal></para></listitem>
</varlistentry>
<varlistentry>
<term>heat</term><listitem>
<para><literal>python-swiftclient</literal></para>
</listitem>
</varlistentry>
<varlistentry>
<term>heat</term>
<listitem>
<para>Orchestration</para>
<para>Launch stacks from templates and manage
stacks.</para>
<para><literal>python-heatclient</literal></para></listitem>
</varlistentry>
<para><literal>python-heatclient</literal></para>
</listitem>
</varlistentry>
</variablelist>
<para>All clients have tab completion. </para>
<para>Help and detailed information about the individual commands

70
doc/src/docbkx/openstack-user/src/section_dashboard_install.xml
View File

@ -5,29 +5,53 @@
xml:id="section_dashboad_install">
<title>Install the OpenStack dashboard</title>
<?dbhtml stop-chunking?>
<para>To install the OpenStack dashboard, complete the following
high-level tasks: </para>
<orderedlist>
<listitem>
<para>Meet the system requirements for the
dashboard.</para>
</listitem>
<listitem>
<para>Install the OpenStack dashboard framework, including
Apache and related modules.</para>
</listitem>
<listitem>
<para>Configure the dashboard.</para>
</listitem>
<listitem>
<para>Restart and run the Apache server.</para>
</listitem>
<listitem>
<para>Deploy the dashboard. See <link
xlink:href="http://docs.openstack.org/developer/horizon/topics/deployment.html"
>Deploying Horizon</link>.</para>
</listitem>
</orderedlist>
<para>The following instructions show an example dashboard
deployment configured with an Apache web server. </para>
<para>To install the OpenStack dashboard, complete the
following high-level steps: </para>
<orderedlist>
<listitem>
<para>Meet the system requirements for accessing the
dashboard. See <xref
linkend="dashboard-system-requirements"
/>.</para>
</listitem>
<listitem>
<para>Install the OpenStack Dashboard framework,
including Apache and related modules. See <xref
linkend="installing-openstack-dashboard"
/>.</para>
</listitem>
<listitem>
<para>Configure the dashboard.</para>
<para>Then, restart and run the Apache server.</para>
<para>See <xref linkend="configure-dashboard"
/>.</para>
</listitem>
<listitem>
<para>Verify your installation. See <xref
linkend="verify-dashboard"/>.</para>
</listitem>
</orderedlist>
<itemizedlist><title>Next steps:</title>
<para>After you install the dashboard, you can complete
the following tasks:</para>
<listitem>
<para>To customize your dashboard, see <xref
linkend="dashboard-custom-brand"/>.
</para>
</listitem>
<listitem>
<para>To set up session storage for the dashboard,
see <xref linkend="dashboard-sessions"
/>.</para>
</listitem>
<listitem>
<para>To deploy the dashboard, see <link
xlink:href="http://docs.openstack.org/developer/horizon/topics/deployment.html"
>Deploying Horizon</link>.</para>
</listitem>
</itemizedlist>
<xi:include href="../../common/dashboard-system-reqs.xml"/>
<xi:include href="../../common/dashboard-install.xml"/>
<xi:include href="../../common/dashboard-configure.xml"/>

367
doc/src/docbkx/openstack-user/src/section_dashboard_launch_instances.xml Normal file
View File

@ -0,0 +1,367 @@
<?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="Launching_Instances_using_Dashboard">
<title>Launch an instance</title>
<?dbhtml stop-chunking?>
<para>Instances are virtual machines that run inside the cloud.
You can launch an instance directly from one of the available
OpenStack images or from an image that you have copied to a
persistent volume. The OpenStack Image Service provides a pool
of images that are accessible to members of different
projects.</para>
<para>You can optionally add security group rules to the default
security group, and create a keypair to enable SSH access to
your instance.</para>
<section xml:id="Modify_Security_Groups">
<title>Add security group rules</title>
<para>Before you launch a virtual machine, you can add
security group rules to enable users to ping and SSH to
the instances. To do so, you either add rules to the
default security group or add a security group with rules. </para>
<para>The following procedure shows you how to add rules to
the default security group.</para>
<procedure>
<title>To add rules to the default security group:</title>
<step>
<para>Log in to the OpenStack dashboard.</para>
</step>
<step>
<para>If you are a member of multiple projects, select
a project from the drop-down list at the top of
the <guilabel>Project</guilabel> tab. </para>
</step>
<step>
<para>Click the <guilabel>Access &amp;
Security</guilabel> category. </para>
<para>The dashboard shows the security groups that are
available for this project. </para>
<figure>
<title>OpenStack dashboard - Security
Groups</title>
<mediaobject>
<imageobject role="fo">
<imagedata
fileref="../../common/figures/access_security.png"
format="PNG" scale="60"/>
</imageobject>
<imageobject role="html">
<imagedata
fileref="../../common/figures/access_security.png"
format="PNG"/>
</imageobject>
</mediaobject>
</figure>
</step>
<step>
<para>Select the default security group and click
<guibutton>Edit Rules</guibutton>. </para>
<para>The <guilabel>Security Group Rules</guilabel>
page appears: </para>
<figure>
<title>OpenStack dashboard - Security Group
Rules</title>
<mediaobject>
<imageobject role="fo">
<imagedata
fileref="../../common/figures/security_group_rules.png"
format="PNG" scale="60"/>
</imageobject>
<imageobject role="html">
<imagedata
fileref="../../common/figures/security_group_rules.png"
format="PNG"/>
</imageobject>
</mediaobject>
</figure>
</step>
<step>
<title>Add a TCP rule</title>
<para>Click <guibutton>Add Rule</guibutton>. </para>
<para>The <guilabel>Add Rule</guilabel> window
appears. </para>
<figure>
<title>OpenStack dashboard - Add Rule</title>
<mediaobject>
<imageobject role="fo">
<imagedata fileref="../../common/figures/add_rule.png"
format="PNG" scale="60"/>
</imageobject>
<imageobject role="html">
<imagedata fileref="../../common/figures/add_rule.png"
format="PNG"/></imageobject>
</mediaobject>
</figure>
<substeps>
<step>
<para>In the <guilabel>IP Protocol</guilabel>
list, select <literal>TCP</literal>.
</para>
</step>
<step>
<para>In the <guilabel>Open</guilabel> list,
select <literal>Port</literal>.</para>
</step>
<step>
<para>In the <guilabel>Port</guilabel> box,
enter <literal>22</literal>. </para>
</step>
<step>
<para>In the <guilabel>Source</guilabel> list,
select <literal>CIDR</literal>. </para>
</step>
<step>
<para>In the <guilabel>CIDR</guilabel> box,
enter <literal>0.0.0.0/0</literal>.</para>
</step>
<step>
<para>Click <guibutton>Add</guibutton>.</para>
<para>Port 22 is now open for requests from
any IP address. </para>
<para>If you want to accept requests from a
particular range of IP addresses, specify
the IP address block in the
<guilabel>CIDR</guilabel> box.</para>
</step>
</substeps>
</step>
<step>
<title>Add an ICMP rule</title>
<para>Click <guibutton>Add Rule</guibutton>. </para>
<para>The <guilabel>Add Rule</guilabel> window
appears. </para>
<substeps>
<step>
<para>In the <guilabel>IP Protocol</guilabel>
list, select <literal>ICMP</literal>.
</para>
</step>
<step>
<para>In the <guilabel>Type</guilabel> box,
enter <literal>-1</literal>.</para>
</step>
<step>
<para>In the <guilabel>Code</guilabel> box,
enter <literal>-1</literal>. </para>
</step>
<step>
<para>In the <guilabel>Source</guilabel> list,
select <literal>CIDR</literal>. </para>
</step>
<step>
<para>In the <guilabel>CIDR</guilabel> box,
enter <literal>0.0.0.0/0</literal>.</para>
</step>
<step>
<para>Click <guibutton>Add</guibutton>.</para>
<para>If you want to accept requests from a
particular range of IP addresses, specify
the IP address block in the
<guilabel>CIDR</guilabel> box.</para>
</step>
</substeps>
</step>
</procedure>
</section>
<section xml:id="Adding_Keypair">
<title>Add keypair</title>
<para>Keypairs are SSH credentials that are injected into
images when they are launched. For this to work, the image
must contain the <literal>cloud-init</literal> package. </para>
<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>
<para>Log in to the OpenStack dashboard.</para>
</step>
<step>
<para>If you are a member of multiple projects, select
a project from the drop-down list at the top of
the <guilabel>Project</guilabel> tab. </para>
</step>
<step>
<para>Click the <guilabel>Access &amp;
Security</guilabel> category. </para>
</step>
<step>
<para>Click the <guilabel>Keypairs</guilabel> tab. The
dashboard shows the keypairs that are available
for this project. </para>
</step>
<step>
<title>To add a keypair:</title>
<para>Click <guibutton>Create Keypair</guibutton>. </para>
<para>The <guilabel>Create Keypair</guilabel> window
appears. </para>
<figure>
<title>OpenStack dashboard - Create
Keypair</title>
<mediaobject>
<imageobject role="fo">
<imagedata
fileref="../../common/figures/create_keypair.png"
format="PNG" scale="60"/>
</imageobject>
<imageobject role="html">
<imagedata
fileref="../../common/figures/create_keypair.png"
format="PNG"/>
</imageobject>
</mediaobject>
</figure>
<substeps>
<step>
<para>In the <guilabel>Keypair Name</guilabel>
box, enter a name for your keypair.
</para>
</step>
<step>
<para>Click <guibutton>Create
Keypair</guibutton>.</para>
</step>
<step>
<para>Respond to the prompt to download the
keypair.</para>
</step>
</substeps>
</step>
<step>
<title>To import a keypair:</title>
<para>Click <guibutton>Import Keypair</guibutton>. </para>
<para>The <guilabel>Import Keypair</guilabel> window
appears.</para>
<substeps>
<step>
<para>In the <guilabel>Keypair Name</guilabel>
box, enter the name of your keypair.
</para>
</step>
<step>
<para>In the <guilabel>Public Key</guilabel>
box, copy the public key. </para>
</step>
<step>
<para>Click <guibutton>Import
Keypair</guibutton>.</para>
</step>
</substeps>
</step>
<step>
<para>Save the <filename>*.pem</filename> file locally
and change its permissions so that only you can
read and write to the file:</para>
<para>
<screen><userinput><prompt>$</prompt> chmod 0600 MY_PRIV_KEY.pem</userinput></screen>
</para>
</step>
<step>
<para>Use the <command>ssh-add</command> command to
make the keypair known to
SSH:<screen><userinput><prompt>$</prompt> ssh-add MY_PRIV_KEY.pem</userinput></screen></para>
</step>
</procedure>
<para>The public key of the keypair is registered in the Nova
database. </para>
<para>The dashboard lists the keypair in the <guilabel>Access
&amp; Security</guilabel> category, as follows:</para>
<figure>
<title>OpenStack dashboard - Keypairs</title>
<mediaobject>
<imageobject role="fo">
<imagedata fileref="../../common/figures/keypairs.png"
format="PNG" scale="60"/>
</imageobject>
<imageobject role="html">
<imagedata fileref="../../common/figures/keypairs.png"
format="PNG"/>
</imageobject>
</mediaobject>
</figure>
</section>
<!--<section xml:id="Launching_Instance">
<title>Launching Instance</title>
<para>Click Images &amp; Snapshots and launch a required
instance from the list of images available.</para>
<para>
<mediaobject>
<imageobject role="fo">
<imagedata fileref="figures/Images.png"
format="PNG" scale="60"/>
</imageobject>
<imageobject role="html">
<imagedata fileref="figures/Images.png"
format="PNG"/>
</imageobject>
</mediaobject>
</para>
<para>Click launch on the required image. Provide a Server
Name, select the flavor, the keypair added above and
the default security group. Provide the number of
instances required. Once these details are provided,
click Launch Instance.</para>
<para>
<mediaobject>
<imageobject role="fo">
<imagedata
fileref="figures/LaunchInstance.png"
format="PNG" scale="60"/>
</imageobject>
<imageobject role="html">
<imagedata
fileref="figures/LaunchInstance.png"
format="PNG"/>
</imageobject>
</mediaobject>
</para>
<para>Once the status is Active, the instance is ready and
we can ping and SSH to the instance.</para>
<para>
<mediaobject>
<imageobject role="fo">
<imagedata fileref="figures/InstanceReady.png"
format="PNG" scale="60"/>
</imageobject>
<imageobject role="html">
<imagedata fileref="figures/InstanceReady.png"
format="PNG"/>
</imageobject>
</mediaobject>
</para>
</section>-->
<xi:include
href="section_dashboard_launch_instances_from_image.xml"/>
<section xml:id="ssh-into-instance">
<title>SSH in to your instance</title>
<para>To SSH into your instance, you use the downloaded
keypair file.</para>
<note>
<para>The username is ubuntu for the Ubuntu cloud images
on TryStack.</para>
</note>
<procedure>
<title>To SSH in to your instance:</title>
<step>
<para>Copy the IP address for your instance. </para>
</step>
<step>
<para>Use the SSH command to make a secure connection
to the instance. For
example:<screen><userinput><prompt>$</prompt> ssh -i MyKey.pem ubuntu@10.0.0.2</userinput></screen></para>
</step>
<step>
<para>A prompt asks, "Are you sure you want to
continue connection (yes/no)?" Type
<literal>yes</literal> and you have
successfully connected. </para>
</step>
</procedure>
</section>
</section>

35
doc/src/docbkx/openstack-user/src/section_dashboard_launch_instances_from_image.xml
View File

@ -117,17 +117,22 @@
<para>Select an image and click
<guibutton>Launch</guibutton>. The
<guilabel>Launch Image</guilabel> window
appears: <figure>
<title>OpenStack dashboard - Launch
Instances window</title>
appears:</para>
<figure>
<title>OpenStack dashboard - Launch Instances</title>
<mediaobject>
<imageobject>
<imagedata
fileref="figures/launch_instances.png"
width="6in" contentwidth="6in"/>
<imageobject role="fo">
<imagedata
fileref="../../common/figures/launch_instances.png"
format="PNG" scale="60"/>
</imageobject>
<imageobject role="html">
<imagedata
fileref="../../common/figures/launch_instances.png"
format="PNG"/>
</imageobject>
</mediaobject>
</figure></para>
</figure>
</step>
<step>
<para>, specify the following: </para>
@ -194,11 +199,17 @@
public) IP address, size, status, task, and power
state.</para>
<figure>
<title>OpenStack dashboard - Instances screen</title>
<title>OpenStack dashboard - Instances</title>
<mediaobject>
<imageobject>
<imagedata fileref="figures/instances.png"
width="6in" contentwidth="6in"/>
<imageobject role="fo">
<imagedata
fileref="../../common/figures/instances.png"
format="PNG" scale="60"/>
</imageobject>
<imageobject role="html">
<imagedata
fileref="../../common/figures/instances.png"
format="PNG"/>
</imageobject>
</mediaobject>
</figure>

13
doc/src/docbkx/openstack-user/src/section_dashboard_launch_instances_from_volume.xml
View File

@ -132,8 +132,7 @@
Guide</citetitle>.</para>
</step>
<step>
<para>Launch an instance as described in <xref
linkend="launch_instance"/>. </para>
<para>Launch an instance. </para>
</step>
<step>
<para>Attach the volume to the instance as
@ -163,11 +162,11 @@
<para>As only <emphasis role="italic"
>detached</emphasis> volumes are available
for booting, detach the volume. </para>
<para>For details, see xxxx. </para>
</step>
<step>
<step>
<para>To boot an instance from the volume,
continue with <xref linkend="launch_instance"
continue with <xref linkend="launch_instance_from_volume"
/>.</para>
</step>
</procedure>
@ -188,7 +187,7 @@
iSCSI.</para>
<para>For preparation details, see <xref
linkend="create_volume"/>. </para>
<para>To boot an instance from the volume, follow
<!--<para>To boot an instance from the volume, follow
<xref linkend="launch_instance"/>. </para>
<para>Especially note the following steps: <itemizedlist>
<listitem>
@ -213,7 +212,7 @@
images or <literal>xvda</literal> for
Xen images.</para>
</listitem>
</itemizedlist></para>
</itemizedlist></para>-->
</note>
</section>
</section>