openstack/openstack-manuals
Code Issues Proposed changes

Update nova client in CLI Guide, User Guide, and common files

Browse Source 
bug: #1198051

Change-Id: I73b640cd53eaf2988735e78f9dab9ca91bcec568
author: diane fleming
This commit is contained in:
Diane Fleming 2013-07-16 16:10:17 -05:00
parent 54af51bc36
commit 609f675cc6
60 changed files with 2640 additions and 2384 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -1,19 +1,15 @@
<project xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
<modelVersion>4.0.0</modelVersion>
<groupId>org.openstack.docs</groupId>
<artifactId>openstack-cli-guide</artifactId>
<version>1.0.0-SNAPSHOT</version>
<packaging>jar</packaging>
<name>OpenStack CLI Guides</name>
<!-- ################################################ -->
<!-- USE "mvn clean generate-sources" to run this POM -->
<!-- ################################################ -->
<!-- ################################################ -->
<build>
<plugins>
<plugin>
@ -37,8 +33,9 @@
appendix toc,title
article/appendix nop
article toc,title
book toc,title,figure,table,example,equation
chapter toc,title
book toc,title,figure,example,equation
chapter toc
section toc
part toc,title
preface toc,title
qandadiv toc
@ -77,7 +74,6 @@
</postProcess>
</configuration>
</execution>
</executions>
<configuration>
<!-- These parameters apply to pdf and webhelp -->
@ -88,6 +84,7 @@
</includes>
<!--<canonicalUrlBase>http://docs.openstack.org/cli/content/</canonicalUrlBase>-->
<profileSecurity>reviewer</profileSecurity>
<profileAudience>users</profileAudience>
<branding>openstack</branding>
</configuration>
</plugin>
@ -115,5 +112,4 @@
</pluginRepositories>
</profile>
</profiles>
</project>

17
doc/src/docbkx/cli-guide/src/bk-cli-guide.xml
View File

@ -56,7 +56,6 @@
</copyright>
<releaseinfo>trunk</releaseinfo>
<productname>OpenStack Clients</productname>
<pubdate>2013-05-13</pubdate>
<legalnotice role="apache2">
<annotation>
@ -78,7 +77,6 @@
<revhistory>
<!-- ... continue addding more revisions here as you change this document using the markup shown below... -->
<revision>
<date>2013-05-13</date>
<revdescription>
<itemizedlist spacing="compact">
@ -94,9 +92,9 @@
<revdescription>
<itemizedlist spacing="compact">
<listitem>
<para>Grizzly release of this document</para>
</listitem>
<para>Grizzly release of this
document.</para>
</listitem>
</itemizedlist>
</revdescription>
</revision>
@ -109,7 +107,6 @@
<command>image-update</command>
command.</para>
</listitem>
</itemizedlist>
</revdescription>
</revision>
@ -137,11 +134,7 @@
</revision>
</revhistory>
</info>
<xi:include href="cli_overview.xml"/>
<xi:include href="cli_install.xml"/>
<xi:include href="cli_credentials.xml"/>
<xi:include href="cli_version.xml"/>
<xi:include href="cli_help.xml"/>
<xi:include href="ch_client_overview.xml"/>
<xi:include href="keystone_cli_howto.xml"/>
<xi:include href="glance_cli_howto.xml"/>
<xi:include href="neutron_cli_howto.xml"/>
@ -149,6 +142,4 @@
<xi:include href="cinder_cli_howto.xml"/>
<xi:include href="swift_cli_howto.xml"/>
<xi:include href="heat_cli_howto.xml"/>
</book>

44
doc/src/docbkx/cli-guide/src/ch_client_overview.xml Normal file
View File

@ -0,0 +1,44 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter [
<!-- Some useful entities borrowed from HTML -->
<!ENTITY ndash "&#x2013;">
<!ENTITY mdash "&#x2014;">
<!ENTITY hellip "&#x2026;">
<!ENTITY plusmn "&#xB1;">
<!-- Useful for describing APIs -->
<!ENTITY GET '<command xmlns="http://docbook.org/ns/docbook">GET</command>'>
<!ENTITY PUT '<command xmlns="http://docbook.org/ns/docbook">PUT</command>'>
<!ENTITY POST '<command xmlns="http://docbook.org/ns/docbook">POST</command>'>
<!ENTITY DELETE '<command xmlns="http://docbook.org/ns/docbook">DELETE</command>'>
<!ENTITY CHECK '<inlinemediaobject xmlns="http://docbook.org/ns/docbook">
<imageobject>
<imagedata fileref="figures/Check_mark_23x20_02.svg"
format="SVG" scale="60"/>
</imageobject>
</inlinemediaobject>'>
<!ENTITY ARROW '<inlinemediaobject xmlns="http://docbook.org/ns/docbook">
<imageobject>
<imagedata fileref="figures/Arrow_east.svg"
format="SVG" scale="60"/>
</imageobject>
</inlinemediaobject>'>
]>
<chapter xmlns="http://docbook.org/ns/docbook"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
xml:id="overview">
<title>Overview</title>
<?dbhtml stop-chunking?>
<para>To manage your servers, images, volumes, isolated networks,
and other cloud resources from the command line, install and
use the OpenStack clients. </para>
<xi:include href="../../openstack-user/src/cli_install.xml"/>
<xi:include href="../../openstack-user/src/section_cli_openrc.xml"/>
<xi:include href="../../openstack-user/src/cli_version.xml"/>
<xi:include href="../../openstack-user/src/cli_help.xml"/>
</chapter>

10
doc/src/docbkx/cli-guide/src/cinder_cli_howto.xml
View File

@ -6,11 +6,7 @@
xmlns:html="http://www.w3.org/1999/xhtml" version="5.0"
xml:id="cinder_client">
<?dbhtml stop-chunking?>
<title>cinder Client</title>
<para>This chapter describes how to use the cinder client.</para>
<para>To install the client, see <xref linkend="install_clients"
/>.</para>
<!-- <xi:include href="swift_cli_install.xml"/> -->
<xi:include href="cinder_cli_commands.xml"/>
<title>cinder command-line client</title>
<para>Learn how to use the cinder client.</para>
<xi:include href="../../openstack-user/src/cinder_cli_commands.xml"/>
</chapter>

260
doc/src/docbkx/cli-guide/src/cli_install.xml
View File

@ -1,260 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter [
<!-- Some useful entities borrowed from HTML -->
<!ENTITY ndash "&#x2013;">
<!ENTITY mdash "&#x2014;">
<!ENTITY hellip "&#x2026;">
<!ENTITY plusmn "&#xB1;">
<!-- Useful for describing APIs -->
<!ENTITY GET '<command xmlns="http://docbook.org/ns/docbook">GET</command>'>
<!ENTITY PUT '<command xmlns="http://docbook.org/ns/docbook">PUT</command>'>
<!ENTITY POST '<command xmlns="http://docbook.org/ns/docbook">POST</command>'>
<!ENTITY DELETE '<command xmlns="http://docbook.org/ns/docbook">DELETE</command>'>
<!ENTITY CHECK '<inlinemediaobject xmlns="http://docbook.org/ns/docbook">
<imageobject>
<imagedata fileref="figures/Check_mark_23x20_02.svg"
format="SVG" scale="60"/>
</imageobject>
</inlinemediaobject>'>
<!ENTITY ARROW '<inlinemediaobject xmlns="http://docbook.org/ns/docbook">
<imageobject>
<imagedata fileref="figures/Arrow_east.svg"
format="SVG" scale="60"/>
</imageobject>
</inlinemediaobject>'>
]>
<chapter xmlns="http://docbook.org/ns/docbook"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
xml:id="install_clients">
<title>Install the OpenStack Clients</title>
<para>To manage your servers, images, volumes, isolated networks,
and other cloud resources from the command line, install and
use the open-source clients. </para>
<para>To install the clients, first install some prerequisite
software. Then, install the Python packages. Each Python
package is an OpenStack client. </para>
<section xml:id="prereq_software">
<title>Before You Begin</title>
<para>Before you begin, install the following prerequisite
software:<table rules="all" width="85%">
<caption>OpenStack Clients Prerequisite
Software</caption>
<col width="25%"/>
<col width="75%"/>
<thead>
<tr>
<th>Prerequisite</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td valign="top">
<para>Python 2.6 or later</para>
</td>
<td>
<para>Currently, the clients do not
support Python 3. </para>
</td>
</tr>
<tr>
<td valign="top">
<para><command>setuptools</command>
package </para>
</td>
<td>
<para>Installed by default on Mac OS X. </para>
<para>Many Linux distributions provide
packages to make
<command>setuptools</command> easy
to install.</para>
<para>Search your package manager for
<command>setuptools</command> to
find an installation package. If you
cannot find one, download the
<command>setuptools</command>
package directly from <link
xlink:href="http://pypi.python.org/pypi/setuptools"
>http://pypi.python.org/pypi/setuptools</link>.
</para>
</td>
</tr>
<tr>
<td valign="top"><command>pip</command>
package</td>
<td>
<para>To install the clients on a Mac OS X
or Linux system, use
<command>pip</command>. It is easy
to use and ensures that you get the
latest version of the clients from the
<link
xlink:href="http://pypi.python.org/pypi/python-novaclient/"
>Python Package Index</link>. Also,
it lets you update or remove the
packages later on.</para>
<para>Install <command>pip</command>
through the package manager for your system:<itemizedlist>
<listitem>
<para>Mac OS X
<screen><prompt>$</prompt> sudo easy_install pip</screen></para>
</listitem>
<listitem>
<para>Ubuntu 12.04</para>
<para>A packaged version enables
you to use <command>dpkg</command>
or <command>aptitude</command> to
install the
python-novaclient.</para>
<screen><prompt>#</prompt> aptitude install python-novaclient</screen>
</listitem>
<listitem>
<para>Ubuntu
<screen><prompt>#</prompt> aptitude install python-pip</screen></para>
</listitem>
<listitem>
<para>RHEL, CentOS, or Fedora</para>
<para>
A packaged version available in
<link
xlink:href="http://openstack.redhat.com/"
>RDO</link> enables you to use
<command>yum</command> to install the
clients:
<screen><prompt>#</prompt> yum install python-<replaceable>PROJECT</replaceable>client</screen>
Replace <replaceable>PROJECT</replaceable>
with the lower case name of the client to
install, such as <literal>nova</literal>.
Repeat this step for each desired client.
</para>
<para>
Alternatively install <command>pip</command>
and use it to manage client installation:
<screen><prompt>#</prompt> yum install python-pip</screen>
</para>
</listitem>
<listitem>
<para>openSUSE 12.2 and
earlier</para>
<para>A <link
xlink:href="https://build.opensuse.org/package/show?package=python-novaclient&amp;project=Cloud:OpenStack:Master"
>packaged version available in the
Open Build Service</link> enables
you to use <command>rpm</command>
or <command>zypper</command> to
install the the python-novaclient.
<screen><prompt>#</prompt> zypper install python-<replaceable>PROJECT</replaceable></screen>
Replace <replaceable>PROJECT</replaceable>
with the lower case name of the client to
install, such as <literal>nova</literal>.
Repeat this step for each desired client.
</para>
<para>
Alternatively install <command>pip</command>
and use it to manage client installation:
<screen><prompt>#</prompt> zypper install python-pip</screen>
</para>
</listitem>
<listitem>
<para>openSUSE 12.3</para>
<para>A packaged version enables
you to use <command>rpm</command>
or <command>zypper</command> to
install the clients:
<screen><prompt>#</prompt> zypper install python-<replaceable>PROJECT</replaceable>client</screen>
Replace <replaceable>PROJECT</replaceable>
with the lower case name of the client to
install, such as <literal>nova</literal>.
Repeat this step for each desired client.
</para>
</listitem>
</itemizedlist></para>
</td>
</tr>
</tbody>
</table></para>
</section>
<section xml:id="install-clients">
<title>Install the OpenStack Clients</title>
<para>
Follow the steps listed in this procedure to install the OpenStack
clients using <command>pip</command>.
</para>
<note>
<para>
If you already installed the OpenStack client packages using the
package management tools provided by your distribution then these
steps are not required. Skip this procedure and move on to
<xref linkend="authenticate" />
</para>
</note>
<procedure>
<title>To install the OpenStack clients:</title>
<step>
<title>Install or update the client packages</title>
<para>You must install each client separately.</para>
<para>Run the following command to install or update a
client package:</para>
<screen><prompt>$</prompt> sudo pip install [--update] python-&lt;project&gt;client</screen>
<para>Where &lt;project&gt; is the project name and is
one of the following values:</para>
<itemizedlist>
<listitem>
<para><literal>nova</literal>. Compute
API.</para>
</listitem>
<listitem>
<para><literal>neutron</literal>. Networking
API.</para>
</listitem>
<listitem>
<para><literal>keystone</literal>. Identity
service API.</para>
</listitem>
<listitem>
<para><literal>glance</literal>. Image service
API.</para>
</listitem>
<listitem>
<para><literal>swift</literal>. Object storage
API.</para>
</listitem>
<listitem>
<para><literal>cinder</literal>. Block storage
API.</para>
</listitem>
<listitem>
<para><literal>heat</literal>. Orchestration
API.</para>
</listitem>
</itemizedlist>
<para>For example, to install the nova client, run the
following command:</para>
<screen><prompt>$</prompt> sudo pip install python-novaclient</screen>
<para>To update the nova client, run the following
command:</para>
<screen><prompt>$</prompt> sudo pip install --upgrade python-novaclient</screen>
<para>To remove the nova client, run the following
command:</para>
<screen><prompt>$</prompt> sudo pip uninstall python-novaclient</screen>
</step>
<step>
<title>Set environment variables and
authenticate</title>
<para>Before you can issue client commands, you must
set environment variables and authenticate. See
<xref linkend="authenticate"/>.</para>
</step>
</procedure>
</section>
</chapter>

154
doc/src/docbkx/cli-guide/src/cli_overview.xml
View File

@ -1,154 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE ch [
<!-- Some useful entities borrowed from HTML -->
<!ENTITY ndash "&#x2013;">
<!ENTITY mdash "&#x2014;">
<!ENTITY hellip "&#x2026;">
<!ENTITY plusmn "&#xB1;">
<!-- Useful for describing APIs -->
<!ENTITY GET '<command xmlns="http://docbook.org/ns/docbook">GET</command>'>
<!ENTITY PUT '<command xmlns="http://docbook.org/ns/docbook">PUT</command>'>
<!ENTITY POST '<command xmlns="http://docbook.org/ns/docbook">POST</command>'>
<!ENTITY DELETE '<command xmlns="http://docbook.org/ns/docbook">DELETE</command>'>
<!ENTITY CHECK '<inlinemediaobject xmlns="http://docbook.org/ns/docbook">
<imageobject>
<imagedata fileref="figures/Check_mark_23x20_02.svg"
format="SVG" scale="60"/>
</imageobject>
</inlinemediaobject>'>
<!ENTITY CLIall 'command-line interface (CLI)'>
<!ENTITY CLIallp 'command-line interfaces (CLIs)'>
<!ENTITY ARROW '<inlinemediaobject xmlns="http://docbook.org/ns/docbook">
<imageobject>
<imagedata fileref="figures/Arrow_east.svg"
format="SVG" scale="60"/>
</imageobject>
</inlinemediaobject>'>
]>
<chapter xmlns="http://docbook.org/ns/docbook"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
xml:id="client_overview">
<title>OpenStack Clients Overview</title>
<para>The OpenStack clients are command-line interfaces (CLIs)
that let you run simple commands to make OpenStack API calls.
These open-source Python clients are easy to learn and use. </para>
<para>The OpenStack APIs are RESTful APIs that use all aspects of
the HTTP protocol, including methods, URIs, media types, and
response codes. Internally, each client command runs cURL
commands that embed API requests. </para>
<para>To install an OpenStack client, see <xref
linkend="install_clients"/>.</para>
<para>To request OpenStack services either through the clients or
through the APIs directly, you must first issue an
authentication request to the OpenStack Identity Service v2.0.
To do so, you can run the <command>credentials</command>
command, which is a nova client command.</para>
<para>For example, to use the OpenStack Compute API from the
command line, complete these steps:</para>
<para>
<orderedlist>
<listitem>
<para>Install the nova client. </para>
</listitem>
<listitem>
<para>Issue the nova <command>credentials</command>
command.</para>
</listitem>
<listitem>
<para>Issue other nova client commands, such as
<command>boot</command>,
<command>list</command>, and so on.</para>
</listitem>
</orderedlist>
</para>
<note>
<para>An OpenStack common client is in development.</para>
</note>
<para>To install the OpenStack clients on a Mac OS X or Linux
system, use <command>pip</command> because it is easy and
ensures that you get the latest version of the client from the
<link xlink:href="http://pypi.python.org/pypi">Python
Package Index</link>. Also, <command>pip</command> lets
you update or remove a package later on. </para>
<para>Use the following OpenStack clients to access the
CLIs:<table rules="all" width="100%">
<caption>OpenStack Clients</caption>
<col width="15%"/>
<col width="15%"/>
<col width="55%"/>
<col width="15%"/>
<thead>
<tr>
<th>Client</th>
<th>Associated API</th>
<th>Description</th>
<th>See</th>
</tr>
</thead>
<tbody>
<tr>
<td>cinder</td>
<td>Block storage</td>
<td>Create and delete volumes, attach volumes to
and detach volumes from servers, create and
delete snapshots, create volumes from
snapshots, and get volume statistics.</td>
<td><xref linkend="cinder_client"/></td>
</tr>
<tr>
<td>glance</td>
<td>Image service</td>
<td>Manage images. For example, add and set
permissions on images.</td>
<td><xref linkend="glance_client"/></td>
</tr>
<tr>
<td>keystone</td>
<td>Identity service</td>
<td>Create and manage users, tenants, roles,
endpoints, and credentials.</td>
<td><xref linkend="keystone_client"/></td>
</tr>
<tr>
<td>nova</td>
<td>Compute, Compute extensions</td>
<td>Authenticate, launch servers, set security
groups, control IP addresses on servers,
control volumes, and create images. </td>
<td><xref linkend="nova_client"/></td>
</tr>
<tr>
<td>neutron</td>
<td>Networking</td>
<td>Configure networks for guest servers.</td>
<td><xref linkend="neutron_client"/></td>
</tr>
<tr>
<td>swift</td>
<td>Object storage</td>
<td>Gather statistics, list items, update
metadata, upload, download and delete files
stored by the object storage service. Provides
access to a swift installation for ad hoc
processing.</td>
<td><xref linkend="swift_client"/></td>
</tr>
<tr>
<td>heat</td>
<td>Orchestration</td>
<td>Launch stacks from templates, view details of running stacks (including
events and resources), update and delete stacks.</td>
<td><xref linkend="heat_client"/></td>
</tr>
</tbody>
</table></para>
<note>
<para>
The <literal>neutron</literal> client was previously known as
<literal>quantum</literal>.
</para>
</note>
</chapter>

30
doc/src/docbkx/cli-guide/src/glance_cli_howto.xml
View File

@ -6,15 +6,14 @@
xmlns:html="http://www.w3.org/1999/xhtml" version="5.0"
xml:id="glance_client">
<?dbhtml stop-chunking?>
<title>glance Client</title>
<para>This chapter describes how to use the glance client. </para>
<para>To install the client, see <xref linkend="install_clients"
/>.</para>
<title>glance command-line client</title>
<para>Learn how to use the glance client. </para>
<section xml:id="glance-image-list">
<title>List Images</title>
<para>To see what images are available to you, use this
command:
<screen><prompt>$</prompt> <userinput>glance image-list</userinput>
command:</para>
<screen><prompt>$</prompt> <userinput>glance image-list</userinput></screen>
<screen><computeroutput>
+--------------------------------------+----------------+--------+--------+
| ID | Name | Status | Server |
+--------------------------------------+----------------+--------+--------+
@ -22,15 +21,15 @@
| 588d93af-645d-4312-a5b0-81347715a91b | tty-image | ACTIVE | |
| ac6f83b7-078c-47bd-b4c2-4053282da49e | oneiric-image | ACTIVE | |
| e110fb7d-2a9e-4da5-923f-5565867ce87a | maverick-image | ACTIVE | |
+--------------------------------------+----------------+--------+--------+ </screen></para>
+--------------------------------------+----------------+--------+--------+ </computeroutput></screen>
<para>You can also narrow down the list by using grep to find
only the CentOS images with a command like this: </para>
<para>
<screen><prompt>$</prompt> <userinput>glance image-list | grep 'natty'</userinput>
<screen><prompt>$</prompt> <userinput>glance image-list | grep 'natty'</userinput></screen>
<screen><computeroutput>
| 12 | natty-server-cloudimg-amd64-kernel | ACTIVE | |
| 13 | natty-server-cloudimg-amd64 | ACTIVE | |</screen>
</para>
| 13 | natty-server-cloudimg-amd64 | ACTIVE | |</computeroutput></screen>
</section>
<section xml:id="glance-image-create">
<title>Add a New Image</title>
@ -53,7 +52,6 @@
</itemizedlist></para>
<section xml:id="glance-image-prereqs">
<title>Before You Add an Image</title>
<para>Ensure you have created an image that is OpenStack
compatible. For details, see the <link
xlink:href="../openstack-compute/admin/content/ch_image_mgmt.html"
@ -61,7 +59,6 @@
<citetitle>OpenStack Compute Administration
Manual</citetitle>.</para>
</section>
<section xml:id="glance-create-image">
<title>Upload an image to glance</title>
<para>Assuming you had a CentOS 6.3 image in qcow2 format
@ -188,8 +185,6 @@
instance to fail to launch.</para>
</section>
</section>
<section xml:id="managing-images-glance">
<title>Managing Images</title>
<para>Adding images and setting the access to them can be
@ -197,8 +192,7 @@
snapshot of a running instance and view available images,
set or delete image metadata, and delete an image, using
the nova client.</para>
</section>
<xi:include href="glance_cli_commands.xml"/>
<xi:include
href="../../openstack-user/src/glance_cli_commands.xml"/>
</chapter>

9
doc/src/docbkx/cli-guide/src/heat_cli_howto.xml
View File

@ -6,11 +6,10 @@
xmlns:html="http://www.w3.org/1999/xhtml" version="5.0"
xml:id="heat_client">
<?dbhtml stop-chunking?>
<title>heat Client</title>
<para>This chapter describes how to use the heat client. This service orchestrates multiple
<title>heat command-line client</title>
<para>Learn how to use the heat client. This service orchestrates multiple
composite cloud applications using a REST API that emulates the AWS CloudFormation
API.</para>
<para>To install the client, see <xref linkend="install_clients"/>.</para>
<xi:include href="section_cli_heat.xml"/>
<xi:include href="heat_cli_commands.xml"/>
<xi:include href="../../openstack-user/src/section_cli_heat.xml"/>
<xi:include href="../../openstack-user/src/heat_cli_commands.xml"/>
</chapter>

11
doc/src/docbkx/cli-guide/src/keystone_cli_howto.xml
View File

@ -6,11 +6,8 @@
xmlns:html="http://www.w3.org/1999/xhtml" version="5.0"
xml:id="keystone_client">
<?dbhtml stop-chunking?>
<title>keystone Client</title>
<para>This chapter describes how to use the keystone
client.</para>
<para>To install the client, see <xref linkend="install_clients"
/>.</para>
<!-- <xi:include href="keystone_cli_install.xml"/> -->
<xi:include href="keystone_cli_commands.xml"/>
<title>keystone command-line client</title>
<para>Learn how to use the keystone client.</para>
<xi:include
href="../../openstack-user/src/keystone_cli_commands.xml"/>
</chapter>

84
doc/src/docbkx/cli-guide/src/keystone_cli_install.xml
View File

@ -1,84 +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="install_openstack_keystone_cli">
<title>Install the keystone Client</title>
<para>This example walks through installing the keystone client. After
you install a client, you must configure environment variables
for authentication. </para>
<procedure>
<title>To install the keystone client:</title>
<step>
<title>Install Python</title>
<para>Install Python 2.6 or later. Currently, the keystone
client does not support Python 3. </para>
</step>
<step>
<title>Install the keystone client package</title>
<para>Choose one of the following methods to install the
keystone client package. <itemizedlist>
<listitem>
<para><emphasis role="bold">Recommended
method:</emphasis>
<command>pip</command></para>
<para>Install <command>pip</command> through
the package manager for your
system:<informaltable rules="all">
<col width="20%"/>
<col width="80%"/>
<thead>
<tr>
<th>System</th>
<th>Command</th>
</tr>
</thead>
<tbody>
<tr>
<td>Mac OS X</td>
<td>
<programlisting language="bash" role="gutter: false"><prompt>$</prompt> sudo easy_install pip</programlisting>
</td>
</tr>
<tr>
<td>Ubuntu 12.04</td>
<td>
<para>There is a packaged version so you can use dpkg or aptitude to install python-keystoneclient.</para>
<programlisting language="bash" role="gutter: false"><prompt>$</prompt> aptitude install python-keystoneclient </programlisting>
</td>
</tr>
<tr>
<td>RHEL, CentOS, or Fedora:</td>
<td>
<programlisting language="bash" role="gutter: false"><prompt>$</prompt> yum install python-pip</programlisting>
</td>
</tr>
</tbody>
</informaltable></para>
<para>Run the following command to install the
keystone client package:
<programlisting language="bash" role="gutter: false"><prompt>$</prompt> sudo pip install python-keystoneclient</programlisting></para>
</listitem>
<listitem>
<para><emphasis role="bold"
>easy_install</emphasis></para>
<para>Run the following command to install the
keystone client package: </para>
<programlisting language="bash" role="gutter: false"><prompt>$</prompt> sudo easy_install python-keystoneclient</programlisting>
</listitem>
</itemizedlist></para>
</step>
<step>
<title>Test the keystone client</title>
<para>To verify that you can talk to the API server, run
the following commands: </para>
<programlisting language="bash" role="gutter: false"><prompt>$</prompt> keystone discover</programlisting>
<para>The <code>keystone discover</code> command shows the
keystone servers available. </para>
</step>
</procedure></section>

481
doc/src/docbkx/cli-guide/src/neutron_cli_howto.xml
View File

@ -6,57 +6,60 @@
xmlns:html="http://www.w3.org/1999/xhtml" version="5.0"
xml:id="neutron_client">
<?dbhtml stop-chunking?>
<title>neutron Client</title>
<para>This chapter describes how to use the neutron client.</para>
<para>To install the client, see <xref linkend="install_clients"/>.</para>
<section xml:id="neutron_overview">
<title>Overview</title>
<section xml:id="neutron_overview_command">
<title>Argument parts of API 2.0 command</title>
<para>In general, neutron client command arguments divide
into three parts:</para>
<section xml:id="neutron_overview_command_known">
<title>Known options</title>
<para>These options are listed in the command's help usage text.</para>
</section>
<section xml:id="neutron_overview_command_pos">
<title>Positional arguments</title>
<para>Positional arguments are mandatory information
for an API resource. They must be given in the
order. </para>
</section>
<section xml:id="neutron_overview_command_unknown">
<title>Unknown options</title>
<para>Unknown options are complementary to known options.
To define an unknown option, the format is
<literal>--optionname [type=int|bool|dict...] [list=true]
[optionvalue]*</literal>. There can be multiple option
values for a certain optionname. When there is no
optionvalue given, the option is regarded as a
<literal>bool</literal> one and value is <literal>true</literal>. The type is python
built-in type, such as <literal>int</literal>, <literal>bool</literal>,
<literal>float</literal> and <literal>dict</literal>,
defaulted to string if not given.
Unknown options can be used to provide values
for creating, updating a resource and to provide filters
to list resources. It is also useful
to implement API extension when the known options are not
included in the command.
pseudo argument <literal>‘--’</literal> can be used if the options after it need
take advantage of unknown options parser.</para>
</section>
</section>
<section xml:id="neutron_overview_cliff">
<title>Features from cliff</title>
<section xml:id="neutron_overview_cliff_interactive">
<title>Interactive mode</title>
<para>If there is no command specified, the neutron
client will enter into interactive mode:</para>
<screen>
<prompt>$</prompt><userinput>neutron --os-username admin --os-password password --os-tenant-name admin --os-auth-url http://localhost:5000/v2.0</userinput>
<prompt>(neutron)</prompt> <userinput>help</userinput>
Shell commands (type help &lt;topic&gt;):
<title>neutron command-line client</title>
<para>Learn how to use the neutron commands.</para>
<section xml:id="neutron_overview_command">
<title>Command arguments</title>
<para>The neutron client command arguments and options are: </para>
<itemizedlist>
<listitem>
<para><emphasis role="bold">Known
arguments</emphasis>. Listed in the help usage
text for the command.</para>
</listitem>
<listitem xml:id="neutron_overview_command_pos">
<para><emphasis role="bold">Positional
arguments</emphasis>. Mandatory arguments that
must be specified in a specific order. </para>
</listitem>
<listitem xml:id="neutron_overview_command_unknown">
<para><emphasis role="bold">Unknown
options</emphasis>. Complement the known
arguments. </para>
<para>To define an unknown option, use the
format:</para>
<screen><userinput>--optionname [type=int|bool|dict...][list=true] [optionvalue]*</userinput></screen>
<para>You can specify multiple option values for an
option name. When no option value is specified,
the option defaults to <literal>bool</literal>
with a value of <literal>true</literal>. </para>
<para>The type is python built-in type, such as
<literal>int</literal>,
<literal>bool</literal>,
<literal>float</literal>,
<literal>dict</literal>, and
<literal>string</literal>, which is the
default. You can use unknown options to provide
values for creating, updating a resource and to
provide filters to list resources. It is also
useful to implement API extension when the known
options are not included in the command. You can
use the pseudo argument <literal>--</literal> if
the options that follow require the use of an
unknown options parser.</para>
</listitem>
</itemizedlist>
</section>
<section xml:id="neutron_overview_cliff">
<title>Features from cliff</title>
<section xml:id="neutron_overview_cliff_interactive">
<title>Interactive mode</title>
<para>If no command is specified, the neutron client goes
into interactive mode:</para>
<screen><prompt>$</prompt> <userinput>neutron --os-username admin --os-password password --os-tenant-name admin --os-auth-url http://localhost:5000/v2.0</userinput></screen>
<screen><userinput>(neutron) help</userinput></screen>
<screen><computeroutput>Shell commands (type help &lt;topic&gt;):
===================================
cmdenvironment edit hi l list pause r save shell show
ed help history li load py run set shortcuts
@ -112,294 +115,124 @@ lb-vip-show security-group-rule-delete
lb-vip-update security-group-rule-list
net-create security-group-rule-show
net-delete security-group-show
<prompt>(neutron)</prompt> <userinput>net-list</userinput>
+--------------------------------------+----------------+--------------------------------------+
</computeroutput></screen>
<screen><prompt>(neutron)</prompt> <userinput>net-list</userinput></screen>
<screen><computeroutput>+--------------------------------------+----------------+--------------------------------------+
| id | name | subnets |
+--------------------------------------+----------------+--------------------------------------+
| 11fc08b7-c3b2-4b0c-bd04-66e279d9c470 | public_net1 | 13cc61f6-b33b-495a-a49f-83bdc9e439ab |
| 22f53ed1-3f3d-49c7-9162-7ba94d9c0a7e | private_mynet1 | b5a9b952-dd4f-445a-89c5-f15d0707b8bd |
| 2a405f54-aea0-47d7-8a43-4d5129e22b35 | test1 | |
| d322e1ae-e068-4249-b9b3-7ed8b820bfa2 | mynetwork | |
+--------------------------------------+----------------+--------------------------------------+
</screen>
</section>
<section xml:id="neutron_overview_cliff_oFormat">
<title>Output format</title>
<para>We can use <literal>-h</literal> after each command to show the
usage of each command:</para>
<screen>
<prompt>(neutron)</prompt> <userinput>net-list -h</userinput>
usage: neutron net-list [-h] [-f {csv,html,json,table,yaml}] [-c COLUMN]
[--quote {all,minimal,none,nonnumeric}]
[--request-format {json,xml}] [-D] [-F FIELD]
[-P SIZE] [--sort-key FIELD] [--sort-dir {asc,desc}]
List networks that belong to a given tenant.
optional arguments:
-h, --help show this help message and exit
--request-format {json,xml}
the xml or json request format
-D, --show-details show detailed info
-F FIELD, --field FIELD
specify the field(s) to be returned by server, can be
repeated
-P SIZE, --page-size SIZE
specify retrieve unit of each request, then split one
request to several requests
--sort-key FIELD sort list by specified fields (This option can be
repeated), The number of sort_dir and sort_key should
match each other, more sort_dir specified will be
omitted, less will be filled with asc as default
direction
--sort-dir {asc,desc}
sort list in specified directions (This option can be
repeated)
output formatters:
output formatter options
-f {csv,html,json,table,yaml}, --format {csv,html,json,table,yaml}
the output format, defaults to table
-c COLUMN, --column COLUMN
specify the column(s) to include, can be repeated
CSV Formatter:
--quote {all,minimal,none,nonnumeric}
when to include quotes, defaults to nonnumeric
</screen>
<para>We can see the output formatters cliff provides
to each command. By default, the output format is
<literal>table</literal>. Now we choose <literal>csv</literal> output to run the command
<literal>net-list</literal>:</para>
<screen>
<prompt>(neutron)</prompt> <userinput>net-list -f csv</userinput>
"id","name","subnets"
+--------------------------------------+----------------+--------------------------------------+</computeroutput> </screen>
</section>
<section xml:id="neutron_overview_cliff_oFormat">
<title>Output format</title>
<para>We can use <literal>-h</literal> after each command
to show the usage of each command:</para>
<screen><prompt>(neutron)</prompt> <userinput>net-list -h</userinput></screen>
<screen>usage: neutron net-list [-h] [-f {csv,html,json,table,yaml}] [-c COLUMN]
[--quote {all,minimal,none,nonnumeric}]
[--request-format {json,xml}] [-D] [-F FIELD]
[-P SIZE] [--sort-key FIELD] [--sort-dir {asc,desc}]
List networks that belong to a given tenant.
optional arguments:
-h, --help show this help message and exit
--request-format {json,xml}
the xml or json request format
-D, --show-details show detailed info
-F FIELD, --field FIELD
specify the field(s) to be returned by server, can be
repeated
-P SIZE, --page-size SIZE
specify retrieve unit of each request, then split one
request to several requests
--sort-key FIELD sort list by specified fields (This option can be
repeated), The number of sort_dir and sort_key should
match each other, more sort_dir specified will be
omitted, less will be filled with asc as default
direction
--sort-dir {asc,desc}
sort list in specified directions (This option can be
repeated)
output formatters:
output formatter options
-f {csv,html,json,table,yaml}, --format {csv,html,json,table,yaml}
the output format, defaults to table
-c COLUMN, --column COLUMN
specify the column(s) to include, can be repeated
CSV Formatter:
--quote {all,minimal,none,nonnumeric}
when to include quotes, defaults to nonnumeric
</screen>
<para>We can see the output formatters cliff provides to
each command. By default, the output format is
<literal>table</literal>. Now we choose
<literal>csv</literal> output to run the command
<literal>net-list</literal>:</para>
<screen><prompt>(neutron)</prompt> <userinput>net-list -f csv</userinput></screen>
<screen>"id","name","subnets"
"11fc08b7-c3b2-4b0c-bd04-66e279d9c470","public_net1","13cc61f6-b33b-495a-a49f-83bdc9e439ab"
"22f53ed1-3f3d-49c7-9162-7ba94d9c0a7e","private_mynet1","b5a9b952-dd4f-445a-89c5-f15d0707b8bd"
"2a405f54-aea0-47d7-8a43-4d5129e22b35","test1",""
"d322e1ae-e068-4249-b9b3-7ed8b820bfa2","mynetwork",""
</screen>
</section>
<section xml:id="neutron_overview_cliff_column">
<title>Column selection</title>
<para>We can see <literal>-c COLUMN</literal> in previous usage output.
It can be used to limit the output fields:</para>
<screen>
<prompt>(neutron)</prompt> <userinput>net-list -c id -c name</userinput>
+--------------------------------------+----------------+
"d322e1ae-e068-4249-b9b3-7ed8b820bfa2","mynetwork","" </screen>
</section>
<section xml:id="neutron_overview_cliff_column">
<title>Column selection</title>
<para>We can see <literal>-c COLUMN</literal> in previous
usage output. It can be used to limit the output
fields:</para>
<screen><prompt>(neutron)</prompt> <userinput>net-list -c id -c name</userinput></screen>
<screen>+--------------------------------------+----------------+
| id | name |
+--------------------------------------+----------------+
| 11fc08b7-c3b2-4b0c-bd04-66e279d9c470 | public_net1 |
| 22f53ed1-3f3d-49c7-9162-7ba94d9c0a7e | private_mynet1 |
| 2a405f54-aea0-47d7-8a43-4d5129e22b35 | test1 |
| d322e1ae-e068-4249-b9b3-7ed8b820bfa2 | mynetwork |
+--------------------------------------+----------------+
</screen>
</section>
</section>
<section xml:id="neutron_overview_API">
<title>Features from API</title>
<section xml:id="neutron_overview_API_fields">
<title>Fields selection</title>
<para>If there are <literal>‘fields’</literal> in request URL, V2.0 API
will extract the list of fields to return. A
sample of such URLs is
<literal>http://localhost:9696/v2.0/networks.json?fields=id&amp;fields=name</literal></para>
<para> Neutron client supports this feature by <literal>-F</literal>
option in known options part and <literal>--fields</literal> in
unknown options part. For example, <literal>neutron -F id
net-list -- --fields name</literal>. Only <literal>xx-list</literal> and
<literal>xx-show</literal> commands support this feature.</para>
</section>
<section xml:id="neutron_overview_API_filtering">
<title>Value filtering</title>
<para>Any other fields except the <literal>‘fields’</literal> are used to filter
resources. A sample of such URLs is
<literal>http://localhost:9696/v2.0/networks.json?name=test1&amp;name=test2</literal>.
By the current neutron server's sample DB plugin,
the filtering has the same meaning as a SQL
clause: <literal>name in [‘test1’, ‘test2’]</literal>. Neutron client
supports this feature by any key options in
unknown option part. For example <literal>neutron net-list
-- --name test1 test2</literal>. Only <literal>xx-list</literal> commands support this feature. </para>
</section>
+--------------------------------------+----------------+ </screen>
</section>
</section>
<section xml:id="neutron_client_sample_commands">
<title>Sample neutron command</title>
<para>All commands are run with following environment varialbes set:</para>
<screen>export OS_USERNAME=admin
export OS_PASSWORD=password
export OS_TENANT_NAME=admin
export OS_AUTH_URL=http://localhost:5000/v2.0
</screen>
<para><itemizedlist>
<listitem>
<para>List the extensions of the system:</para>
<screen>
$ neutron ext-list -c alias -c name
+-----------------+--------------------------+
| alias | name |
+-----------------+--------------------------+
| agent_scheduler | Agent Schedulers |
| binding | Port Binding |
| quotas | Quota management support |
| agent | agent |
| provider | Provider Network |
| router | Neutron L3 Router |
| lbaas | LoadBalancing service |
| extraroute | Neutron Extra Route |
+-----------------+--------------------------+
</screen>
</listitem>
<listitem>
<para>Create a network:</para>
<screen>
$ neutron net-create net1
Created a new network:
+---------------------------+--------------------------------------+
| Field | Value |
+---------------------------+--------------------------------------+
| admin_state_up | True |
| id | 2d627131-c841-4e3a-ace6-f2dd75773b6d |
| name | net1 |
| provider:network_type | vlan |
| provider:physical_network | physnet1 |
| provider:segmentation_id | 1001 |
| router:external | False |
| shared | False |
| status | ACTIVE |
| subnets | |
| tenant_id | 3671f46ec35e4bbca6ef92ab7975e463 |
+---------------------------+--------------------------------------+
</screen>
<para><emphasis role='bold'>Note:</emphasis>Some fields of the created network
are invisible to non-admin users.</para>
</listitem>
<listitem>
<para>Create a network with specified provider network type:</para>
<screen>
$ neutron net-create net2 --provider:network-type local
Created a new network:
+---------------------------+--------------------------------------+
| Field | Value |
+---------------------------+--------------------------------------+
| admin_state_up | True |
| id | 524e26ea-fad4-4bb0-b504-1ad0dc770e7a |
| name | net2 |
| provider:network_type | local |
| provider:physical_network | |
| provider:segmentation_id | |
| router:external | False |
| shared | False |
| status | ACTIVE |
| subnets | |
| tenant_id | 3671f46ec35e4bbca6ef92ab7975e463 |
+---------------------------+--------------------------------------+
</screen>
<para>Just as shown above, the unknown option <literal>--provider:network-type</literal>
is used to create a <literal>local</literal> provider network.</para>
</listitem>
<listitem>
<para>Create a subnet:</para>
<screen>
$ neutron subnet-create net1 192.168.2.0/24 --name subnet1
Created a new subnet:
+------------------+--------------------------------------------------+
| Field | Value |
+------------------+--------------------------------------------------+
| allocation_pools | {"start": "192.168.2.2", "end": "192.168.2.254"} |
| cidr | 192.168.2.0/24 |
| dns_nameservers | |
| enable_dhcp | True |
| gateway_ip | 192.168.2.1 |
| host_routes | |
| id | 15a09f6c-87a5-4d14-b2cf-03d97cd4b456 |
| ip_version | 4 |
| name | subnet1 |
| network_id | 2d627131-c841-4e3a-ace6-f2dd75773b6d |
| tenant_id | 3671f46ec35e4bbca6ef92ab7975e463 |
+------------------+--------------------------------------------------+
</screen>
<para>In the above command line, <literal>net1</literal> is the network name,
<literal>192.168.2.0/24</literal> is the subnet's CIDR. They are positional arguments.
<literal>--name subnet1</literal> is an unknown option, which specifies the subnet's name.</para>
</listitem>
<listitem>
<para>Create a port with specified IP address:</para>
<screen>
$ neutron port-create net1 --fixed-ip ip_address=192.168.2.40
Created a new port:
+----------------------+-------------------------------------------------------------------------------------+
| Field | Value |
+----------------------+-------------------------------------------------------------------------------------+
| admin_state_up | True |
| binding:capabilities | {"port_filter": false} |
| binding:vif_type | ovs |
| device_id | |
| device_owner | |
| fixed_ips | {"subnet_id": "15a09f6c-87a5-4d14-b2cf-03d97cd4b456", "ip_address": "192.168.2.40"} |
| id | f7a08fe4-e79e-4b67-bbb8-a5002455a493 |
| mac_address | fa:16:3e:97:e0:fc |
| name | |
| network_id | 2d627131-c841-4e3a-ace6-f2dd75773b6d |
| status | DOWN |
| tenant_id | 3671f46ec35e4bbca6ef92ab7975e463 |
+----------------------+-------------------------------------------------------------------------------------+
</screen>
<para>In the above command line, <literal>net1</literal> is the network name,
which is a positional argument.
<literal>--fixed-ip ip_address=192.168.2.40</literal> is an option,
which specifies the port's fixed IP address we wanted.</para>
</listitem>
<listitem>
<para>Create a port without specified IP address:</para>
<screen>
$ neutron port-create net1
Created a new port:
+----------------------+------------------------------------------------------------------------------------+
| Field | Value |
+----------------------+------------------------------------------------------------------------------------+
| admin_state_up | True |
| binding:capabilities | {"port_filter": false} |
| binding:vif_type | ovs |
| device_id | |
| device_owner | |
| fixed_ips | {"subnet_id": "15a09f6c-87a5-4d14-b2cf-03d97cd4b456", "ip_address": "192.168.2.2"} |
| id | baf13412-2641-4183-9533-de8f5b91444c |
| mac_address | fa:16:3e:f6:ec:c7 |
| name | |
| network_id | 2d627131-c841-4e3a-ace6-f2dd75773b6d |
| status | DOWN |
| tenant_id | 3671f46ec35e4bbca6ef92ab7975e463 |
+----------------------+------------------------------------------------------------------------------------+
</screen>
<para>We can see that the system will allocate one IP address
if we don't specify the IP address in command line.</para>
</listitem>
<listitem>
<para>Query ports with speficied fixed IP addresses:</para>
<screen>
$ neutron port-list --fixed-ips ip_address=192.168.2.2 ip_address=192.168.2.40
+--------------------------------------+------+-------------------+-------------------------------------------------------------------------------------+
| id | name | mac_address | fixed_ips |
+--------------------------------------+------+-------------------+-------------------------------------------------------------------------------------+
| baf13412-2641-4183-9533-de8f5b91444c | | fa:16:3e:f6:ec:c7 | {"subnet_id": "15a09f6c-87a5-4d14-b2cf-03d97cd4b456", "ip_address": "192.168.2.2"} |
| f7a08fe4-e79e-4b67-bbb8-a5002455a493 | | fa:16:3e:97:e0:fc | {"subnet_id": "15a09f6c-87a5-4d14-b2cf-03d97cd4b456", "ip_address": "192.168.2.40"} |
+--------------------------------------+------+-------------------+-------------------------------------------------------------------------------------+
</screen>
<para><literal>--fixed-ips ip_address=192.168.2.2 ip_address=192.168.2.40</literal>
is one unknown option.</para>
<para><emphasis role='bold'>How to find unknown options?</emphasis>
The unknown options can be easily found by
watching the output of <literal>create_xxx</literal> or <literal>show_xxx</literal>
command. For example, in the port creation command, we see the fixed_ips fields, which
can be used as an unknown option.</para>
</listitem>
</itemizedlist></para>
</section>
<xi:include href="neutron_cli_commands.xml"/>
<section xml:id="neutron_overview_API">
<title>API features</title>
<section xml:id="neutron_overview_API_fields">
<title>Fields selection</title>
<para>If there are <literal>‘fields’</literal> in request
URL, V2.0 API will extract the list of fields to
return. A sample of such URLs is
<literal>http://localhost:9696/v2.0/networks.json?fields=id&amp;fields=name</literal></para>
<para> Neutron client supports this feature by
<literal>-F</literal> option in known options part
and <literal>--fields</literal> in unknown options
part. For example, <literal>neutron -F id net-list --
--fields name</literal>. Only
<literal>xx-list</literal> and
<literal>xx-show</literal> commands support this
feature.</para>
</section>
<section xml:id="neutron_overview_API_filtering">
<title>Value filtering</title>
<para>Any other fields except the
<literal>‘fields’</literal> are used to filter
resources. A sample of such URLs is
<literal>http://localhost:9696/v2.0/networks.json?name=test1&amp;name=test2</literal>.
By the current neutron server's sample DB plugin, the
filtering has the same meaning as a SQL clause:
<literal>name in [‘test1’, ‘test2’]</literal>.
Neutron client supports this feature by any key
options in unknown option part. For example
<literal>neutron net-list -- --name test1
test2</literal>. Only <literal>xx-list</literal>
commands support this feature. </para>
</section>
</section>
<xi:include
href="../../openstack-user/src/section_cli_manage_networks.xml"/>
<xi:include
href="../../openstack-user/src/neutron_cli_commands.xml"/>
</chapter>

198
doc/src/docbkx/cli-guide/src/nova_cli_howto.xml
View File

@ -5,194 +5,12 @@
xmlns:svg="http://www.w3.org/2000/svg"
xmlns:html="http://www.w3.org/1999/xhtml" version="5.0"
xml:id="nova_client">
<?dbhtml stop-chunking?>
<title>nova Client</title>
<para>This chapter describes how to use the nova client.</para>
<para>To install the client, see <xref linkend="install_clients"
/>.</para>
<section xml:id="listing">
<title>List Instances, Images, and Flavors</title>
<para>Before you can build a cloud, you must discover which
images are available by asking the image service which
configurations are available. To list images, their names,
status, and ID, use this command:
<screen>
<prompt>$</prompt> <userinput>nova image-list</userinput>
+--------------------------------------+----------------+--------+--------+
| ID | Name | Status | Server |
+--------------------------------------+----------------+--------+--------+
| 53b205cc-7abc-46eb-aa60-eabc449b4217 | natty-image | ACTIVE | |
| 588d93af-645d-4312-a5b0-81347715a91b | tty-image | ACTIVE | |
| ac6f83b7-078c-47bd-b4c2-4053282da49e | oneiric-image | ACTIVE | |
| e110fb7d-2a9e-4da5-923f-5565867ce87a | maverick-image | ACTIVE | |
+--------------------------------------+----------------+--------+--------+
</screen></para>
<para>Next you need to know the relative sizes of each of
these. </para>
<para><screen>
<prompt>$</prompt> <userinput>nova flavor-list</userinput>
+----+-----------+-----------+------+-----------+------+-------+-------------+
| ID | Name | Memory_MB | Disk | Ephemeral | Swap | VCPUs | RXTX_Factor |
+----+-----------+-----------+------+-----------+------+-------+-------------+
| 1 | m1.tiny | 512 | 1 | N/A | 0 | 1 | |
| 2 | m1.small | 2048 | 20 | N/A | 0 | 1 | |
| 3 | m1.medium | 4096 | 40 | N/A | 0 | 2 | |
| 4 | m1.large | 8192 | 80 | N/A | 0 | 4 | |
| 5 | m1.xlarge | 16384 | 160 | N/A | 0 | 8 | |
+----+-----------+-----------+------+-----------+------+-------+-------------+
</screen></para>
<para>You can also narrow down the list by using grep to find
only the CentOS images with a command like this: </para>
<para>
<screen>
<prompt>$</prompt> <userinput>nova image-list | grep 'natty'</userinput>
| 12 | natty-server-cloudimg-amd64-kernel | ACTIVE | |
| 13 | natty-server-cloudimg-amd64 | ACTIVE | |
</screen>
</para>
</section>
<section xml:id="launch_instance">
<title>Launch an Instance</title>
<para>Launching a new instance on OpenStack.</para>
<section xml:id="launch_commands_used">
<title>Commands Used</title>
<para>This process uses the following commands: <itemizedlist>
<listitem>
<para><command>nova boot</command></para>
</listitem>
<listitem>
<para><command>nova list</command></para>
</listitem>
<listitem>
<para><command>nova show</command></para>
</listitem>
</itemizedlist></para>
</section>
<section xml:id="launch_procedure">
<title>Before Launch</title>
<para>Now you have the information you need to create your
virtual servers and launch instances. </para>
</section>
<xi:include href="../../common/nova_cli_boot.xml"/>
<xi:include href="../../common/boot_from_volume.xml"/>
<xi:include href="../../common/nova_cli_sshkeys.xml"/>
<xi:include href="../../common/nova_cli_metadata.xml"/>
<xi:include href="../../common/nova_cli_userdata.xml"/>
<xi:include href="../../common/nova_cli_fileinjection.xml"/>
</section>
<xi:include href="../../common/nova_cli_resizerebuild.xml"/>
<xi:include href="../../common/nova_cli_evacuate.xml"/>
<xi:include href="../../common/nova_cli_startstop.xml"/>
<section xml:id="reboot">
<title>Rebooting an instance</title>
<para><command>nova reboot</command> performs a reboot of a
running instance. By default, this is a "soft" reboot,
which will attempt a graceful shutdown and restart of the
instance. To perform a "hard" reboot (a power cycle
of the instance), pass the <literal>--hard</literal> flag
as an argument.</para>
</section>
<xi:include href="../../common/nova_cli_secgroups.xml"/>
<xi:include href="../../common/nova_cli_floatingip.xml"/>
<xi:include href="../../common/nova_cli_images.xml"/>
<xi:include href="../../common/nova_cli_volumes.xml"/>
<xi:include href="../../common/nova_cli_terminate.xml"/>
<section xml:id="instance_console">
<title>Get an Instance Console</title>
<para>When you need to get a VNC console directly to a server,
you can use the <code>nova get-vnc-console</code> command
to connect.</para>
</section>
<section xml:id="baremetal">
<title>Managing Bare metal Nodes</title>
<para>If you are using the Bare metal driver, you must inform
each Nova Compute host of the physical hardware that it
should manage. This is done through the bare metal admin
extension.</para>
<para>Create a node with <command>nova
baremetal-node-create</command>, and then add network
interface information to it with <command>nova
baremetal-interface-add </command>. Nodes and
interfaces can be listed and deleted. When a node is in
use, its status includes the UUID of the Nova instance
that is running on it.</para>
<screen>
<prompt>$</prompt> <userinput>nova baremetal-node-create</userinput> --pm_address=1.2.3.4 --pm_user=ipmi --pm_password=ipmi $(hostname -f) 1 512 10 aa:bb:cc:dd:ee:ff
+------------------+-------------------+
| Property | Value |
+------------------+-------------------+
| instance_uuid | None |
| pm_address | 1.2.3.4 |
| interfaces | [] |
| prov_vlan_id | None |
| cpus | 1 |
| memory_mb | 512 |
| prov_mac_address | aa:bb:cc:dd:ee:ff |
| service_host | ubuntu |
| local_gb | 10 |
| id | 1 |
| pm_user | ipmi |
| terminal_port | None |
+------------------+-------------------+
<prompt>$</prompt> <userinput>nova baremetal-interface-add</userinput> 1 aa:bb:cc:dd:ee:ff
+-------------+-------------------+
| Property | Value |
+-------------+-------------------+
| datapath_id | 0 |
| id | 1 |
| port_no | 0 |
| address | aa:bb:cc:dd:ee:ff |
+-------------+-------------------+
<prompt>$</prompt> <userinput>nova baremetal-node-list</userinput>
+----+--------+------+-----------+---------+-------------------
+------+------------+-------------+-------------+---------------+
| ID | Host | CPUs | Memory_MB | Disk_GB | MAC Address
| VLAN | PM Address | PM Username | PM Password | Terminal Port |
+----+--------+------+-----------+---------+-------------------
+------+------------+-------------+-------------+---------------+
| 1 | ubuntu | 1 | 512 | 10 | aa:bb:cc:dd:ee:ff
| None | 1.2.3.4 | ipmi | | None |
+----+--------+------+-----------+---------+-------------------
+------+------------+-------------+-------------+---------------+
<prompt>$</prompt> <userinput>nova boot --image my-baremetal-image --flavor my-baremetal-flavor test</userinput>
+-----------------------------+--------------------------------------+
| Property | Value |
+-----------------------------+--------------------------------------+
| status | BUILD |
| id | cc302a8f-cd81-484b-89a8-b75eb3911b1b |
... wait for instance to become active ...
<prompt>$</prompt> <userinput>nova baremetal-node-show</userinput> 1
+------------------+--------------------------------------+
| Property | Value |
+------------------+--------------------------------------+
| instance_uuid | cc302a8f-cd81-484b-89a8-b75eb3911b1b |
| pm_address | 1.2.3.4 |
| interfaces |
[{u'datapath_id': u'0', u'id': 1, u'port_no': 0, u'address': u'aa:bb:cc:dd:ee:ff'}] |
| prov_vlan_id | None |
| cpus | 1 |
| memory_mb | 512 |
| prov_mac_address | aa:bb:cc:dd:ee:ff |
| service_host | ubuntu |
| local_gb | 10 |
| id | 1 |
| pm_user | ipmi |
| terminal_port | None |
+------------------+--------------------------------------+</screen>
</section>
<xi:include href="../../common/nova_cli_usage_statistics.xml"/>
<xi:include href="nova_cli_commands.xml"/>
<title>nova command-line client</title>
<para>Learn how to use the nova command-line
client.</para>
<xi:include href="../../openstack-user/src/section_cli_configure_instances.xml"/>
<xi:include href="../../common/nova_cli_boot.xml"/>
<!-- <xi:include href="../../common/nova_cli_userdata.xml"/> -->
<xi:include href="../../common/nova_cli_manage_instances.xml"/>
<xi:include href="../../openstack-user/src/nova_cli_commands.xml"/>
</chapter>

10
doc/src/docbkx/cli-guide/src/swift_cli_howto.xml
View File

@ -6,11 +6,7 @@
xmlns:html="http://www.w3.org/1999/xhtml" version="5.0"
xml:id="swift_client">
<?dbhtml stop-chunking?>
<title>swift Client</title>
<para>This chapter describes how to use the swift client.</para>
<para>To install the client, see <xref linkend="install_clients"
/>.</para>
<!-- <xi:include href="swift_cli_install.xml"/> -->
<xi:include href="swift_cli_commands.xml"/>
<title>swift command-line client</title>
<para>Learn how to use the swift client.</para>
<xi:include href="../../openstack-user/src/swift_cli_commands.xml"/>
</chapter>

341
doc/src/docbkx/common/boot_from_volume.xml
View File

@ -1,170 +1,177 @@
<?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="boot_from_volume">
<title>Launch from a Volume</title>
<para>The Compute service has support for booting an instance from a
volume.</para>
<simplesect>
<title>Manually Creating a Bootable Volume</title>
<para>To manually create a bootable volume, mount the volume to an existing instance, and then
build a volume-backed image. Here is an example based on <link
xlink:href="https://github.com/openstack-dev/devstack/blob/master/exercises/boot_from_volume.sh"
>exercises/boot_from_volume.sh</link>. This example assumes that you have a
running instance with a 1GB volume mounted at <literal>/dev/vdc</literal>. These
commands will make the mounted volume bootable using a CirrOS image. As
root:<screen><prompt>#</prompt> <userinput>mkfs.ext3 -b 1024 /dev/vdc 1048576</userinput>
<prompt>#</prompt> <userinput>mkdir /tmp/stage</userinput>
<prompt>#</prompt> <userinput>mount /dev/vdc /tmp/stage</userinput>
<prompt>#</prompt> <userinput>cd /tmp</userinput>
<prompt>#</prompt> <userinput>wget https://launchpad.net/cirros/trunk/0.3.0/+download/cirros-0.3.0-x86_64-rootfs.img.gz</userinput>
<prompt>#</prompt> <userinput>gunzip cirros-0.3.0-x86_64-rootfs.img.gz</userinput>
<prompt>#</prompt> <userinput>mkdir /tmp/cirros</userinput>
<prompt>#</prompt> <userinput>mount /tmp/cirros-0.3.0-x86_64-rootfs.img /tmp/cirros</userinput>
<prompt>#</prompt> <userinput>cp -pr /tmp/cirros/* /tmp/stage</userinput>
<prompt>#</prompt> <userinput>umount /tmp/cirros</userinput>
<prompt>#</prompt> <userinput>sync</userinput>
<prompt>#</prompt> <userinput>umount /tmp/stage</userinput></screen></para>
<para>Detach the volume once you are done.</para>
</simplesect>
<simplesect>
<title>Creating a Bootable Volume from an Image</title>
<para>Cinder has the ability to create a bootlable volume from an image stored in Glance.
<screen>
<prompt>#</prompt> <userinput>cinder create --image-id &lt;image_id> --display-name my-bootable-vol &lt;size></userinput>
</screen>
</para>
<para>This feature is also mirrored in Nova:
<screen>
<prompt>#</prompt> <userinput>nova volume-create --image-id &lt;image_id> --display-name my-bootable-vol &lt;size></userinput>
</screen>
</para>
<para>
<section xmlns="http://docbook.org/ns/docbook"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
xml:id="boot_from_volume">
<title>Launch an instance from a volume</title>
<para>After you <link xlink:href="create_volume_from_image">create a
bootable volume</link>, you <link
xlink:href="#launch_image_from_volume">launch an instance from
the volume</link>.</para>
<procedure xml:id="create_volume_from_image">
<title>To launch an instance from a volume</title>
<step>
<title>To create a bootable volume</title>
<para>Enter the following command to create a volume from an
image:
<screen><prompt>#</prompt> <userinput>cinder create --image-id 397e713c-b95b-4186-ad46-6126863ea0a9 --display-name my-bootable-vol 8</userinput> </screen>
</para>
<note>
<para>As of Grizzly, the following block storage drivers are compatible: iSCSI-based, LVM, and Ceph.</para>
<para>You can also use the <command>nova</command>
<option>volume-create</option> command to complete the same
action:
<screen><prompt>#</prompt> <userinput>nova volume-create --image-id 397e713c-b95b-4186-ad46-6126863ea0a9 --display-name my-bootable-vol 8</userinput> </screen>
</para>
</note>
</para>
<para>Make sure you configure Cinder with the relevant Glance options:</para>
<table rules="all">
<caption>List of configuration flags for NFS</caption>
<col width="35%"/>
<col width="15%"/>
<col width="15%"/>
<col width="35%"/>
<thead>
<tr>
<td>Flag Name</td>
<td>Type</td>
<td>Default</td>
<td>Description</td>
</tr>
</thead>
<tbody>
<tr>
<td><para><literal>glance_host</literal></para></td>
<td><para>Optional</para></td>
<td><para><literal>$my_ip</literal></para></td>
<td><para>(StrOpt) default glance hostname or ip</para></td>
</tr>
<tr>
<td><para><literal>glance_port</literal></para></td>
<td><para>Optional</para></td>
<td><para><literal>9292</literal></para></td>
<td><para>(IntOpt) default glance port</para></td>
</tr>
<tr>
<td><para><literal>glance_api_servers</literal></para></td>
<td><para>Optional</para></td>
<td><para><literal>$glance_host:$glance_port</literal></para></td>
<td><para>(ListOpt) A list of the glance api servers available to cinder: <literal>([hostname|ip]:port) (list value)</literal></para></td>
</tr>
<tr>
<td><para><literal>glance_api_version</literal></para></td>
<td><para>Optional</para></td>
<td><para><literal>1</literal></para></td>
<td><para>(IntOpt) default version of the glance api to use</para></td>
</tr>
<tr>
<td><para><literal>glance_num_retries</literal></para></td>
<td><para>Optional</para></td>
<td><para><literal>0</literal></para></td>
<td><para>(IntOpt) Number retries when downloading an image from glance</para></td>
</tr>
<tr>
<td><para><literal>glance_api_insecure</literal></para></td>
<td><para>Optional</para></td>
<td><para><literal>false</literal></para></td>
<td><para>(BoolOpt) Allow to perform insecure SSL (https) requests to glance</para></td>
</tr>
</tbody>
</table>
</simplesect>
<simplesect>
<title>Booting an instance from the volume</title>
<para>To boot a new instance from the volume, use the
<command>nova boot</command> command with the
<literal>--block_device_mapping</literal> flag.
The output for <command>nova help boot</command> shows
the following documentation about this
flag:<screen><computeroutput> --block_device_mapping &lt;dev_name=mapping>
Block device mapping in the format &lt;dev_name>=&lt;id>:&lt;type>:&lt;size(GB)>:&lt;delete_on_terminate>.
</computeroutput></screen></para>
<para>The command arguments are:<variablelist>
<varlistentry>
<term><literal>dev_name</literal></term>
<listitem>
<para>A device name where the volume will be attached in the system at
<filename>/dev/<replaceable>dev_name</replaceable></filename>.
This value is typically <literal>vda</literal>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>id</literal></term>
<listitem>
<para>The ID of the volume to boot from, as shown in the output of
<command>nova volume-list</command>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>type</literal></term>
<listitem>
<para>This is either <literal>snap</literal>, which means that the
volume was created from a snapshot, or anything other than
<literal>snap</literal> (a blank string is valid). In the
example above, the volume was not created from a snapshot, so we
will leave this field blank in our example below.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>size (GB)</literal></term>
<listitem>
<para>The size of the volume, in GB. It is safe to leave this blank and
have the Compute service infer the size.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>delete_on_terminate</literal></term>
<listitem>
<para>A boolean to indicate whether the volume should be deleted when
the instance is terminated. True can be specified as
<literal>True</literal> or <literal>1</literal>. False can be
specified as <literal>False</literal> or
<literal>0</literal>.</para>
</listitem>
</varlistentry>
</variablelist></para>
<para><note>
<para>Because of bug <link xlink:href="https://bugs.launchpad.net/nova/+bug/1163566">#1163566</link>,
you must specify an image when booting from a volume in Horizon, even though this image will not be used.</para>
</note>The following example will attempt boot from volume on the command line with
ID=<literal>13</literal>, it will not delete on terminate. Replace the
<literal>--key_name</literal> with a valid keypair
name:<screen><prompt>$</prompt> <userinput>nova boot --flavor 2 --key_name <replaceable>mykey</replaceable> --block_device_mapping vda=13:::0 boot-from-vol-test</userinput></screen></para>
</simplesect>
</section>
<para>Optionally, to configure your volume, see the
<citetitle>Configuring Image Service and Storage for
Compute</citetitle> chapter in the <citetitle>OpenStack
Configuration Reference</citetitle>.</para>
</step>
<step>
<title>To list volumes</title>
<para>Enter the following command:</para>
<screen><userinput><prompt>$</prompt> nova volume-list</userinput></screen>
<screen><computeroutput>+--------------------------------------+-----------+-----------------+------+-------------+-------------+
| ID | Status | Display Name | Size | Volume Type | Attached to |
+--------------------------------------+-----------+-----------------+------+-------------+-------------+
| bd7cf584-45de-44e3-bf7f-f7b50bf235e3 | available | my-bootable-vol | 8 | None | |
+--------------------------------------+-----------+-----------------+------+-------------+-------------+</computeroutput></screen>
<para>Copy the value in the <literal>ID</literal> field for your
volume.</para>
</step>
<step xml:id="launch_image_from_volume">
<title>To launch an instance</title>
<para>Enter the <command>nova</command>
<option>boot</option> command with the
<parameter>--block_device_mapping</parameter> parameter, as
follows: </para>
<screen><prompt>$</prompt> <userinput>nova boot --flavor &lt;flavor> --block_device_mapping &lt;dev_name>=&lt;id>:&lt;type>:&lt;size>:&lt;delete_on_terminate> &lt;name></userinput></screen>
<para>The command arguments are:</para>
<variablelist>
<varlistentry>
<term><parameter>--flavor</parameter>
<replaceable>flavor</replaceable></term>
<listitem>
<para>The flavor ID.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>--block_device_mapping</parameter>
<replaceable>dev-
name</replaceable>=<replaceable>id</replaceable>:<replaceable>type</replaceable>:<replaceable>size</replaceable>:<replaceable>delete-on-terminate</replaceable></term>
<listitem>
<itemizedlist>
<listitem>
<para><replaceable>dev-name</replaceable>. A device
name where the volume is attached in the system at
<filename>/dev/<replaceable>dev_name</replaceable></filename>.
This value is typically
<literal>vda</literal>.</para>
</listitem>
<listitem>
<para><replaceable>id</replaceable>. The ID of the
volume to boot from, as shown in the output of
<command>nova volume-list</command>.</para>
</listitem>
<listitem>
<para><replaceable>type</replaceable>. Either
<literal>snap</literal> or any other value,
including a blank string. <literal>snap</literal>
means that the volume was created from a
snapshot.</para>
</listitem>
<listitem>
<para><replaceable>size</replaceable>. The size of the
volume, in GBs. It is safe to leave this blank and
have the Compute service infer the size.</para>
</listitem>
<listitem>
<para><replaceable>delete-on-terminate</replaceable>.
A boolean that indicates whether the volume should
be deleted when the instance is terminated. You can
specify <itemizedlist>
<listitem>
<para><literal>True</literal> or
<literal>1</literal>
</para>
</listitem>
<listitem>
<para><literal>False</literal> or
<literal>0</literal></para>
</listitem>
</itemizedlist></para>
</listitem>
</itemizedlist>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable>name</replaceable></term>
<listitem>
<para>The name for the server.</para>
</listitem>
</varlistentry>
</variablelist>
<para><note>
<para>Because of bug <link
xlink:href="https://bugs.launchpad.net/nova/+bug/1163566"
>#1163566</link>, you must specify an image when booting
from a volume, even though the specified image is not
used. Otherwise, the <literal>Attempt to boot from volume
- no image supplied</literal> error is returned.</para>
</note>For example, you might enter the following command to
boot from a volume with ID
bd7cf584-45de-44e3-bf7f-f7b50bf235e. The volume is not deleted
when the instance is terminated:</para>
<screen><prompt>$</prompt> <userinput>nova boot --flavor 2 --image 397e713c-b95b-4186-ad46-6126863ea0a9 --block_device_mapping vda=bd7cf584-45de-44e3-bf7f-f7b50bf235e3:::0 myInstanceFromVolume</userinput></screen>
<screen><computeroutput>+-------------------------------------+-------------------------------------------------+
| Property | Value |
+-------------------------------------+-------------------------------------------------+
| OS-EXT-STS:task_state | scheduling |
| image | cirros-0.3.1-x86_64-uec |
| OS-EXT-STS:vm_state | building |
| OS-EXT-SRV-ATTR:instance_name | instance-00000003 |
| flavor | m1.small |
| id | 8a99547e-7385-4ad1-ae50-4ecfaaad5f42 |
| security_groups | [{u'name': u'default'}] |
| user_id | 376744b5910b4b4da7d8e6cb483b06a8 |
| OS-DCF:diskConfig | MANUAL |
| accessIPv4 | |
| accessIPv6 | |
| progress | 0 |
| OS-EXT-STS:power_state | 0 |
| OS-EXT-AZ:availability_zone | nova |
| config_drive | |
| status | BUILD |
| updated | 2013-07-16T20:14:19Z |
| hostId | |
| OS-EXT-SRV-ATTR:host | None |
| key_name | None |
| OS-EXT-SRV-ATTR:hypervisor_hostname | None |
| name | myInstanceFromVolume |
| adminPass | LhwEmx5Ho22M |
| tenant_id | 66265572db174a7aa66eba661f58eb9e |
| created | 2013-07-16T20:14:18Z |
| metadata | {} |
+-------------------------------------+-------------------------------------------------+</computeroutput></screen>
<para>Now when you list volumes, you can see that the volume is
attached to a server:</para>
<screen><prompt>$</prompt> <userinput>nova volume-list</userinput></screen>
<screen><computeroutput>+--------------------------------------+--------+-----------------+------+-------------+--------------------------------------+
| ID | Status | Display Name | Size | Volume Type | Attached to |
+--------------------------------------+--------+-----------------+------+-------------+--------------------------------------+
| bd7cf584-45de-44e3-bf7f-f7b50bf235e3 | in-use | my-bootable-vol | 8 | None | 8a99547e-7385-4ad1-ae50-4ecfaaad5f42 |
+--------------------------------------+--------+-----------------+------+-------------+--------------------------------------+</computeroutput></screen>
<para>Additionally, when you list servers, you see the server
that you booted from a volume:</para>
<screen><prompt>$</prompt> <userinput>nova list</userinput></screen>
<screen><computeroutput>+--------------------------------------+----------------------+--------+------------+-------------+------------------+
| ID | Name | Status | Task State | Power State | Networks |
+--------------------------------------+----------------------+--------+------------+-------------+------------------+
| b3cdc6c0-85a7-4904-ae85-71918f734048 | myCirrosServer | ACTIVE | None | Running | private=10.0.0.3 |
| 8a99547e-7385-4ad1-ae50-4ecfaaad5f42 | myInstanceFromVolume | ACTIVE | None | Running | private=10.0.0.4 |
+--------------------------------------+----------------------+--------+------------+-------------+------------------+</computeroutput></screen>
</step>
</procedure>
</section>

27
doc/src/docbkx/common/nova_cli_access_and_security.xml Normal file
View File

@ -0,0 +1,27 @@
<?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="access_and_security">
<title>Set up access and security</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>A security group is a named collection of network access
rules that you use to limit the types of traffic that have
access to instances. When you launch an instance, you can
assign it to one or more security groups. The associated rules
in each security group control the traffic to instances in the
group. Any incoming traffic that is not matched by a rule is
denied access by default. You can add rules to or remove rules from a
security group. Rules are automatically enforced as soon as
you create or modify them.</para>
<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>
<!-- <xi:include href="nova_cli_secgroups.xml"/>
<xi:include href="nova_cli_sshkeys.xml"/>
<xi:include href="nova_cli_floatingip.xml"/> -->
<xi:include href="../openstack-user/src/section_cli_configure_instances.xml"/>
</section>

356
doc/src/docbkx/common/nova_cli_boot.xml
View File

@ -1,58 +1,304 @@
<?xml version="1.0" encoding="UTF-8"?>
<section
xmlns="http://docbook.org/ns/docbook"
<section xmlns="http://docbook.org/ns/docbook"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink"
version="5.0"
xml:id="nova_create_server">
<title>Create Your Server with the nova Client</title>
<procedure xml:id="create_server_procedure">
<title>To create and boot your server with the nova
client:</title>
<step>
<para>Issue the following command. In the command,
specify the server name, flavor ID, and image
ID:</para>
<programlisting language="bash" role="gutter: false"><prompt>$</prompt> <?db-font-size 75%?>nova boot myUbuntuServer --image "3afe97b2-26dc-49c5-a2cc-a2fc8d80c001" --flavor 6</programlisting>
<para>The command returns a list of server
properties. The status field indicates whether
the server is being built or is active. A
status of <literal>BUILD</literal> indicates
that your server is being built. </para>
<informalexample>
<screen><computeroutput><?db-font-size 70%?>+-------------------------+--------------------------------------+
| Property | Value |
+-------------------------+--------------------------------------+
| OS-DCF:diskConfig | AUTO |
| accessIPv4 | |
| accessIPv6 | |
| adminPass | ZbaYPZf6r2an |
| config_drive | |
| created | 2012-07-27T19:59:31Z |
| flavor | 8GB Standard Instance |
| hostId | |
| id | d8093de0-850f-4513-b202-7979de6c0d55 |
| image | Ubuntu 12.04 |
| metadata | {} |
| name | myUbuntuServer |
| progress | 0 |
| status | BUILD |
| tenant_id | 345789 |
| updated | 2012-07-27T19:59:31Z |
| user_id | 170454 |
+-------------------------+--------------------------------------+</computeroutput></screen>
</informalexample>
</step>
<step>
<para>Copy the server ID value from the
<literal>id</literal> field in the output. You use
this ID to get details for your server to determine if
it built successfully. </para>
<para>Copy the administrative password value from the
<literal>adminPass</literal> field. You use this
value to log into your server.</para>
</step>
</procedure>
xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
xml:id="cli_launch_instances">
<title>Launch instances</title>
<para>Instances are virtual machines that run inside the
cloud.</para>
<para>Before you can launch an instance, you must gather
parameters such as the image and flavor from which you want to
launch your instance.</para>
<para>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="gather_parms">
<title>Gather parameters to launch an instance</title>
<para>To launch an instance, you must specify the following
parameters:</para>
<itemizedlist xml:id="instance_parameters" spacing="compact">
<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. For more details and
a list of default flavors available, see Section
1.5, "Managing Flavors," (↑ User Guide for
Administrators ). </para>
</listitem>
<listitem>
<para><literal>User Data</literal> is a special key in
the metadata service which holds a file that cloud
aware applications within the guest instance can
access. For example the <link
xlink:href="https://help.ubuntu.com/community/CloudInit"
>cloudinit</link> system is an open source
package from Ubuntu that handles early
initialization of a cloud instance that makes use
of this <literal>user data</literal>. </para>
</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. For details,
refer to Section 1.5.1, Creating or
Importing Keys. </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>. For details, see xx.
</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. For details, see Section
1.5.3, Managing IP Addresses and Section 1.7,
Managing Volumes.</para>
</listitem>
</itemizedlist>
<para>After you gather the parameters you need to launch an
instance, you can launch it from an <link
xlink:href="launch_from_image">image</link> or a <link
xlink:href="boot_from_volume">volume</link>.</para>
<procedure>
<title>To gather the parameters you need to launch an
instance</title>
<step>
<para>On a shell, source the OpenStack RC file.
See <xref
linkend="cli_openrc"/>.</para>
</step>
<step>
<para>List the available flavors:</para>
<screen><prompt>$</prompt> nova flavor-list</screen>
<screen><computeroutput>+----+-----------+-----------+------+-----------+------+-------+-------------+-----------+
| ID | Name | Memory_MB | Disk | Ephemeral | Swap | VCPUs | RXTX_Factor | Is_Public |
+----+-----------+-----------+------+-----------+------+-------+-------------+-----------+
| 1 | m1.tiny | 512 | 0 | 0 | | 1 | 1.0 | True |
| 2 | m1.small | 2048 | 20 | 0 | | 1 | 1.0 | True |
| 3 | m1.medium | 4096 | 40 | 0 | | 2 | 1.0 | True |
| 4 | m1.large | 8192 | 80 | 0 | | 4 | 1.0 | True |
| 42 | m1.nano | 64 | 0 | 0 | | 1 | 1.0 | True |
| 5 | m1.xlarge | 16384 | 160 | 0 | | 8 | 1.0 | True |
| 84 | m1.micro | 128 | 0 | 0 | | 1 | 1.0 | True |
+----+-----------+-----------+------+-----------+------+-------+-------------+-----------+</computeroutput></screen>
<para>Note the ID of the flavor that you want to use
for your instance. </para>
</step>
<step>
<para>List the available images:</para>
<screen><prompt>$</prompt> <userinput>nova image-list</userinput></screen>
<screen><computeroutput>+--------------------------------------+---------------------------------+--------+--------+
| ID | Name | Status | Server |
+--------------------------------------+---------------------------------+--------+--------+
| 397e713c-b95b-4186-ad46-6126863ea0a9 | cirros-0.3.1-x86_64-uec | ACTIVE | |
| df430cc2-3406-4061-b635-a51c16e488ac | cirros-0.3.1-x86_64-uec-kernel | ACTIVE | |
| 3cf852bd-2332-48f4-9ae4-7d926d50945e | cirros-0.3.1-x86_64-uec-ramdisk | ACTIVE | |
+--------------------------------------+---------------------------------+--------+--------+</computeroutput></screen>
<para>You can also filter the image list by using grep
to find a specific image, like this: </para>
<screen><prompt>$</prompt> <userinput>nova image-list | grep 'kernel'</userinput></screen>
<screen><computeroutput>| df430cc2-3406-4061-b635-a51c16e488ac | cirros-0.3.1-x86_64-uec-kernel | ACTIVE | |</computeroutput></screen>
<para>Note the ID of the image that you want to boot
your instance from. </para>
</step>
<step>
<para>List the available security groups:</para>
<note>
<para>If you are an admin user, specify the
<literal>--all-tenants</literal> parameter
to list groups for all tenants. </para>
</note>
<screen><prompt>$</prompt> <userinput>nova secgroup-list --all-tenants</userinput></screen>
<screen><computeroutput>+----+---------+-------------+----------------------------------+
| Id | Name | Description | Tenant_ID |
+----+---------+-------------+----------------------------------+
| 2 | default | default | 66265572db174a7aa66eba661f58eb9e |
| 1 | default | default | b70d90d65e464582b6b2161cf3603ced |
+----+---------+-------------+----------------------------------+</computeroutput></screen>
<para>If you have not created any security groups, you
can assign the instance to only the default
security group. </para>
<para>You can also list rules for a specified security
group:</para>
<screen><prompt>$</prompt> <userinput>nova secgroup-list-rules default</userinput> </screen>
<screen><computeroutput>+-------------+-----------+---------+----------+--------------+
| IP Protocol | From Port | To Port | IP Range | Source Group |
+-------------+-----------+---------+----------+--------------+
+-------------+-----------+---------+----------+--------------+</computeroutput></screen>
<para>In this example, the default security group has
been modified to allow HTTP traffic on the
instance by permitting TCP traffic on Port
80.</para>
</step>
<step>
<para>List the available keypairs. </para>
<screen><prompt>$</prompt> <userinput>nova keypair-list</userinput></screen>
<screen><computeroutput>+------+-------------+
| Name | Fingerprint |
+------+-------------+
+------+-------------+</computeroutput></screen>
<para>Note the name of the keypair that you use for
SSH access.</para>
</step>
</procedure>
</section>
<?hard page-break?>
<section xml:id="launch_from_image">
<title>Launch an instance from an image</title>
<para>Use this procedure to launch an instance from an
image.</para>
<procedure>
<title>To launch an instance from an image</title>
<step>
<para>Now you have all parameters required to launch
an instance, run the following command. Specify
the server name, flavor ID, and image ID.
Optionally, you can provide a key name for access
control and security group for security. You can
also include metadata key and value pairs. For
example you can add a description for your server
by providing the <parameter>--meta description="My
Server"</parameter> parameter.</para>
<para>You can pass user data in a file on your local
system and pass it at instance launch by using the
flag <literal>--user-data
&lt;user-data-file&gt;</literal>.</para>
<screen><prompt>$</prompt> <userinput>nova boot --flavor FLAVOR_ID --image IMAGE_ID --key_name KEY_NAME --user-data mydata.file \
--security_group NAME_OF_SEC_GROUP NAME_FOR_INSTANCE --meta KEY=VALUE --meta KEY=VALUE</userinput></screen>
<para>The command returns a list of server properties,
depending on which parameters you provide.</para>
<para>A status of <literal>BUILD</literal> indicates
that the instance has started, but is not yet
online. </para>
<para>A status of <literal>ACTIVE</literal> indicates
that your server is active. </para>
<informalexample>
<screen><computeroutput><?db-font-size 70%?>+-------------------------------------+--------------------------------------+
| Property | Value |
+-------------------------------------+--------------------------------------+
| OS-EXT-STS:task_state | scheduling |
| image | cirros-0.3.1-x86_64-uec |
| OS-EXT-STS:vm_state | building |
| OS-EXT-SRV-ATTR:instance_name | instance-00000002 |
| flavor | m1.small |
| id | b3cdc6c0-85a7-4904-ae85-71918f734048 |
| security_groups | [{u'name': u'default'}] |
| user_id | 376744b5910b4b4da7d8e6cb483b06a8 |
| OS-DCF:diskConfig | MANUAL |
| accessIPv4 | |
| accessIPv6 | |
| progress | 0 |
| OS-EXT-STS:power_state | 0 |
| OS-EXT-AZ:availability_zone | nova |
| config_drive | |
| status | BUILD |
| updated | 2013-07-16T16:25:34Z |
| hostId | |
| OS-EXT-SRV-ATTR:host | None |
| key_name | None |
| OS-EXT-SRV-ATTR:hypervisor_hostname | None |
| name | myCirrosServer |
| adminPass | tVs5pL8HcPGw |
| tenant_id | 66265572db174a7aa66eba661f58eb9e |
| created | 2013-07-16T16:25:34Z |
| metadata | {} |
+-------------------------------------+--------------------------------------</computeroutput></screen>
</informalexample>
<para>Copy the server ID value from the
<literal>id</literal> field in the output. You
use this ID to get details for or delete your
server. </para>
<para>Copy the administrative password value from the
<literal>adminPass</literal> field. You use
this value to log into your server.</para>
<note>
<para>Arbitrary local files can also be placed
into the instance file system at creation time
using the <literal>--file
&lt;dst-path=src-path&gt;</literal>
option. You may store up to 5 files. For
example if you have a special authorized_keys
file named
<filename>special_authorized_keysfile</filename>
that you want to put on the instance rather
than using the regular ssh key injection, you
can use the following
command:<screen> <prompt>$</prompt><userinput>nova boot --image ubuntu-cloudimage --flavor 1 --file /root/.ssh/authorized_keys=special_authorized_keysfile</userinput></screen></para>
</note>
</step>
<step>
<para>Check if the instance is online:</para>
<screen><prompt>$</prompt> <userinput>nova list</userinput></screen>
<screen><computeroutput>+--------------------------------------+----------------------+--------+------------+-------------+------------------+
| ID | Name | Status | Task State | Power State | Networks |
+--------------------------------------+----------------------+--------+------------+-------------+------------------+
| 84c6e57d-a6b1-44b6-81eb-fcb36afd31b5 | myCirrosServer | ACTIVE | None | Running | private=10.0.0.3 |
| 8a99547e-7385-4ad1-ae50-4ecfaaad5f42 | myInstanceFromVolume | ACTIVE | None | Running | private=10.0.0.4 |
+--------------------------------------+----------------------+--------+------------+-------------+------------------+</computeroutput></screen>
<para>This command lists all instances of the project
you belong to, including their ID, their name,
their status, and their private (and if assigned,
their public) IP addresses. </para>
<para>If the status for the instance is ACTIVE, the
instance is online. </para>
<para>To view the available options for the
<command>nova list</command> command, run the
following command:</para>
<screen><prompt>$</prompt> <userinput>nova help list</userinput></screen>
</step>
<step>
<para>If you did not provide a keypair, security
groups, or rules, you can only access the instance
from inside the cloud through VNC. Even pinging
the instance is not possible. </para>
<!-- <para>To change this, proceed to <xref
linkend="cli_configure_instances"/>.</para> -->
</step>
</procedure>
</section>
<?hard page-break?>
<xi:include href="boot_from_volume.xml"/>
</section>

110
doc/src/docbkx/common/nova_cli_evacuate.xml
View File

@ -1,73 +1,51 @@
<?xml version="1.0" encoding="UTF-8"?>
<section xmlns="http://docbook.org/ns/docbook" xmlns:xi="http://www.w3.org/2001/XInclude"
<section xmlns="http://docbook.org/ns/docbook"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
xml:id="nova_cli_evacuate">
<title>Instance evacuation</title>
<para>As cloud administrator, while you are managing your cloud, you
may get to the point where one of the cloud compute nodes fails.
For example, due to hardware malfunction.
At that point you may use server evacuation in order to make managed
instances available again.
</para>
<section xml:id="evacuation_procedure">
<title>Before Evacuation</title>
<para>
With the information about instance configuration, like if
it is running on shared storage, you can choose the required
evacuation parameters for your case. Use the
<command>nova host-list</command>
command to list the hosts and find new host for the evacuated
instance.
In order to preserve user data on server disk, target host has to
have preconfigured shared storage with down host.
As well, you have to validate that the current vm host is down.
Otherwise the evacuation will fail with error.
</para>
</section>
<section xml:id="evacuate_shared">
<title>To evacuate your server without shared storage:</title>
<para>
<command>nova evacuate</command>
performs an instance evacuation from down host to specified
host. The instance will be booted from a new disk,
but will preserve the configuration, e.g. id, name, uid, ip...etc.
New instance password can be passed to the command using the <literal>--password &lt;pwd&gt;</literal> option.
If not given it will be generated and printed after the command finishes successfully.
</para>
<programlisting language="bash" role="gutter: false">
<prompt>$</prompt> <userinput>nova evacuate <replaceable>evacuated_server_name</replaceable> <replaceable>host_b</replaceable></userinput>
</programlisting>
<para>
The command returns a new server password.
<informalexample>
<screen>
<computeroutput><?db-font-size 70%?>
+-----------+--------------+
<title>Evacuate instances</title>
<para>If a cloud compute node fails due to a hardware malfunction
or another reason, you can evacuate instances to make them
available again. </para>
<para>You can choose evacuation parameters for your use case. </para>
<para>To preserve user data on server disk, you must configure
shared storage on the target host. Also, you must validate
that the current VM host is down. Otherwise the evacuation
fails with an error. </para>
<procedure xml:id="evacuate_shared">
<title>To evacuate your server</title>
<step>
<para>To find a different host for the evacuated instance,
run the following command to lists hosts:</para>
<screen><prompt>$</prompt> <userinput>nova host-list</userinput></screen>
</step>
<step>
<para>You can pass the instance password to the command by
using the <literal>--password &lt;pwd&gt;</literal>
option. If you do not specify a password, one is
generated and printed after the command finishes
successfully. The following command evacuates a server
without shared storage:</para>
<screen><prompt>$</prompt><userinput> nova evacuate <replaceable>evacuated_server_name</replaceable> <replaceable>host_b</replaceable></userinput> </screen>
<para>The command evacuates an instance from a down host
to a specified host. The instance is booted from a new
disk, but preserves its configuration including its
ID, name, uid, IP address, and so on. The command
returns a password:</para>
<screen><computeroutput><?db-font-size 70%?>+-----------+--------------+
| Property | Value |
+-----------+--------------+
| adminPass | kRAJpErnT4xZ |
+-----------+--------------+
</computeroutput>
</screen>
</informalexample>
</para>
</section>
<section xml:id="evacuate_non_shared">
<title>Evacuate server to specified host and preserve user data</title>
<para>
In order to preserve the user disk data on the evacuated
server the OpenStack Compute should be deployed with shared
filesystem.
Refer to the shared storage section in the
<link xlink:href="http://docs.openstack.org/trunk/openstack-compute/admin/content/configuring-migrations.html">Configure migrations guide</link>
in order to configure your system. In this scenario the password will remain unchanged.
</para>
<programlisting language="bash" role="gutter: false">
<prompt>$</prompt> <userinput>nova evacuate <replaceable>evacuated_server_name</replaceable> <replaceable>host_b</replaceable> --on-shared-storage</userinput>
</programlisting>
</section>
+-----------+--------------+</computeroutput></screen>
</step>
<step>
<para>To preserve the user disk data on the evacuated
server, deploy OpenStack Compute with shared
filesystem. To configure your system, see <link
xlink:href="http://docs.openstack.org/trunk/openstack-compute/admin/content/configuring-migrations.html"
>Configure migrations guide</link>. In this
example, the password remains unchanged. </para>
<screen><prompt>$</prompt><userinput> nova evacuate <replaceable>evacuated_server_name</replaceable> <replaceable>host_b</replaceable> --on-shared-storage</userinput> </screen>
</step>
</procedure>
</section>

3
doc/src/docbkx/common/nova_cli_fileinjection.xml
View File

@ -11,8 +11,7 @@
&lt;dst-path=src-path&gt;</literal> option. You may store up to
5 files. For example if you have a special authorized_keys file
named <filename>special_authorized_keysfile</filename> that you
want to put on the instance rather than using the regular <link
linkend="nova_cli_associatekey">ssh key injection</link> for
want to put on the instance rather than using the regular ssh key injection for
some reason you can use the following
command:<screen>
<prompt>$</prompt> <userinput>nova boot --image ubuntu-cloudimage --flavor 1 --file /root/.ssh/authorized_keys=special_authorized_keysfile</userinput></screen>

224
doc/src/docbkx/common/nova_cli_images.xml
View File

@ -5,100 +5,138 @@
xmlns:xlink="http://www.w3.org/1999/xlink"
version="5.0"
xml:id="images">
<title>Manage Images</title>
<para>
Adding images and setting the access to them can be managed in Glance, but you
can create images by taking a snapshot of a running instance and view
available images, set or delete image metadata, and delete an image, using the
nova CLI.
</para>
<itemizedlist>
<listitem>
<para>
<emphasis role="bold">Write data to disk</emphasis></para>
<para> Before creating the image, ensure that you are not missing any buffered
content that wouldn't have been written to the instance's disk. See the <link
<title>Manage images</title>
<para>You can use the glance client to add images and set access for
images. </para>
<para>You can also use the nova client to take a snapshot of a
running instance to create a new image, list images, set and
delete image metadata, and delete images. </para>
<para>The safest approach is to shut down the instance before you
take a snapshot.</para>
<para>You cannot create a snapshot from an instance that has an
attached volume. Detach the volume, create the image, and
re-mount the volume.</para>
<procedure><title>To create an image</title>
<step>
<para>Write any buffered data to disk.</para>
<para>For more information, see the <link
xlink:href="http://docs.openstack.org/trunk/openstack-ops/content/snapsnots.html"
>Taking Snapshots Section of the OpenStack Operations Guide</link> for
information on how to do this. The safest approach is to shut down the instance
before taking a snapshot.</para>
</listitem>
<listitem>
<para>
<emphasis role="bold">Create the image</emphasis>
</para>
<para> To create the image, get the server ID:
<screen><prompt>$</prompt> <userinput>nova list</userinput>
<computeroutput>+--------------------------------------+------------+--------+--------------------+
| ID | Name | Status | Networks |
+--------------------------------------+------------+--------+--------------------+
| 5717b98d-3766-43af-8570-51d6e5d38aaf | my-server | ACTIVE | private=20.10.0.14 |
+--------------------------------------+------------+--------+--------------------+
</computeroutput></screen>In
this example, the server's name is <literal>my-server</literal>::
<screen><prompt>$</prompt> <userinput>nova image-create my-server my-image</userinput></screen>
The command creates a qemu snapshot and automatically uploads the image to your repository. <note>
<para> The created image is flagged as "Private" (In glance,
<literal>--is-public=False</literal>). Only the tenant has access to the image. </para>
</note>
>Taking Snapshots</link> in the
<citetitle>OpenStack Operations Guide</citetitle>. </para>
</step>
<step>
<para>To create the image, list instances to get
the server ID:</para>
<screen><prompt>$</prompt> <userinput>nova list</userinput></screen><screen><computeroutput>+--------------------------------------+----------------------+--------+------------+-------------+------------------+
| ID | Name | Status | Task State | Power State | Networks |
+--------------------------------------+----------------------+--------+------------+-------------+------------------+
| 84c6e57d-a6b1-44b6-81eb-fcb36afd31b5 | myCirrosServer | ACTIVE | None | Running | private=10.0.0.3 |
+--------------------------------------+----------------------+--------+------------+-------------+------------------+</computeroutput></screen><para>In this example, the server is named
<literal>myCirrosServer</literal>. Use this server
to create a snapshot, as follows:
<screen><prompt>$</prompt> <userinput>nova image-create myCirrosServer myCirrosImage</userinput></screen>The
command creates a qemu snapshot and automatically
uploads the image to your repository. Only the tenant
that creates the image has access to it.
</para>
</listitem>
<listitem>
<para>
<emphasis role="bold">Check image status</emphasis>
</para>
<para> After a while the image state will change from <literal>SAVING</literal>
state to <literal>ACTIVE</literal>. Use the <command>nova image-list</command>
command to check the
status.<programlisting><prompt>$</prompt> <userinput>nova image-list</userinput>
<computeroutput>+--------------------------------------+----------------- ---+--------+--------------------------------------+
| ID | Name | Status | Server |
+--------------------------------------+---------------------+--------+--------------------------------------+
| e4d3dabb-c258-4458-9a48-3e1237b44cfa | my-image | SAVING | 5717b98d-3766-43af-8570-51d6e5d38aaf |
| a75be4af-ac35-4704-9f90-f2c903471b5f | cirros-0.3.0-x86_64 | ACTIVE | |
+--------------------------------------+---------------------+--------+--------------------------------------+
</computeroutput> </programlisting>
</para>
</listitem>
<listitem>
<para>
<emphasis role="bold">Create an instance from the image</emphasis>
</para>
<para>You can now create an instance based on this image as you normally do for
other images
:<screen><prompt>$</prompt> <userinput>nova boot --flavor m1.medium --image my-image New_server</userinput></screen>
</para>
</listitem>
<listitem>
<para>
<emphasis role="bold"> Troubleshooting </emphasis>
</para>
<para>In general, it shouldn't take more than about five minutes for the image
to transition from SAVING" to <literal>ACTIVE</literal> . If this takes longer than
five minutes, here are several hints: </para>
<itemizedlist>
<listitem>
<para>The feature doesn't work while you have attached a volume to the instance.
Thus, you should detach the volume first, create the image, and re-mount the
volume.</para>
</listitem>
<listitem>
<para>Make sure the version of qemu you are using is version 0.14 or greater.
Using an older version of qemu will result in an "<literal>unknown option
-s</literal>" error message in
</step>
<step>
<para>Get details for your image to check its
status:</para><screen><prompt>$</prompt> <userinput>nova image-show <replaceable>IMAGE</replaceable></userinput></screen><screen><computeroutput>+-------------------------------------+--------------------------------------+
| Property | Value |
+-------------------------------------+--------------------------------------+
| metadata owner_id | 66265572db174a7aa66eba661f58eb9e |
| minDisk | 0 |
| metadata instance_type_name | m1.small |
| metadata instance_type_id | 5 |
| metadata instance_type_memory_mb | 2048 |
| id | 7e5142af-1253-4634-bcc6-89482c5f2e8a |
| metadata instance_type_root_gb | 20 |
| metadata instance_type_rxtx_factor | 1 |
| metadata ramdisk_id | 3cf852bd-2332-48f4-9ae4-7d926d50945e |
| metadata image_state | available |
| metadata image_location | snapshot |
| minRam | 0 |
| metadata instance_type_vcpus | 1 |
| status | ACTIVE |
| updated | 2013-07-22T19:46:42Z |
| metadata instance_type_swap | 0 |
| metadata instance_type_vcpu_weight | None |
| metadata base_image_ref | 397e713c-b95b-4186-ad46-6126863ea0a9 |
| progress | 100 |
| metadata instance_type_flavorid | 2 |
| OS-EXT-IMG-SIZE:size | 14221312 |
| metadata image_type | snapshot |
| metadata user_id | 376744b5910b4b4da7d8e6cb483b06a8 |
| name | myCirrosImage |
| created | 2013-07-22T19:45:58Z |
| metadata instance_uuid | 84c6e57d-a6b1-44b6-81eb-fcb36afd31b5 |
| server | 84c6e57d-a6b1-44b6-81eb-fcb36afd31b5 |
| metadata kernel_id | df430cc2-3406-4061-b635-a51c16e488ac |
| metadata instance_type_ephemeral_gb | 0 |
+-------------------------------------+--------------------------------------+</computeroutput></screen>
<para>After a while, the image status changes from
<literal>SAVING</literal> to
<literal>ACTIVE</literal>. Only the tenant who
creates the image has access to it. </para>
</step>
<step>
<para>You can launch an instance from this image.
Include the image ID and flavor ID, as follows:</para>
<screen><prompt>$</prompt> <userinput>nova boot newServer --image 7e5142af-1253-4634-bcc6-89482c5f2e8a --flavor 3</userinput></screen>
<screen><computeroutput>+-------------------------------------+--------------------------------------+
| Property | Value |
+-------------------------------------+--------------------------------------+
| OS-EXT-STS:task_state | scheduling |
| image | myCirrosImage |
| OS-EXT-STS:vm_state | building |
| OS-EXT-SRV-ATTR:instance_name | instance-00000007 |
| flavor | m1.medium |
| id | d7efd3e4-d375-46d1-9d57-372b6e4bdb7f |
| security_groups | [{u'name': u'default'}] |
| user_id | 376744b5910b4b4da7d8e6cb483b06a8 |
| OS-DCF:diskConfig | MANUAL |
| accessIPv4 | |
| accessIPv6 | |
| progress | 0 |
| OS-EXT-STS:power_state | 0 |
| OS-EXT-AZ:availability_zone | nova |
| config_drive | |
| status | BUILD |
| updated | 2013-07-22T19:58:33Z |
| hostId | |
| OS-EXT-SRV-ATTR:host | None |
| key_name | None |
| OS-EXT-SRV-ATTR:hypervisor_hostname | None |
| name | newServer |
| adminPass | jis88nN46RGP |
| tenant_id | 66265572db174a7aa66eba661f58eb9e |
| created | 2013-07-22T19:58:33Z |
| metadata | {} |
+-------------------------------------+--------------------------------------+</computeroutput></screen>
</step>
</procedure>
<simplesect xml:id="troubleshoot"><title>Troubleshoot image creation</title>
<itemizedlist>
<listitem>
<para>You cannot create a snapshot from an instance
that has an attached volume. Detach the volume,
create the image, and re-mount the volume.</para>
</listitem>
<listitem>
<para>Make sure the version of qemu you are using is
version 0.14 or greater. Older versions of qemu
result in an "<literal>unknown option
-s</literal>" error message in the
<filename>nova-compute.log</filename>.</para>
</listitem>
<listitem>
<para>Examine the <filename>/var/log/nova-api.log</filename> and
<filename>/var/log/nova-compute.log</filename> log files for
error messages.</para>
</listitem>
</itemizedlist>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<para>Examine the
<filename>/var/log/nova-api.log</filename> and
<filename>/var/log/nova-compute.log</filename>
log files for error messages.</para>
</listitem>
</itemizedlist></simplesect>
</section>

23
doc/src/docbkx/common/nova_cli_manage_instances.xml Normal file
View File

@ -0,0 +1,23 @@
<?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="cli_manage_instances">
<title>Manage instances and hosts</title>
<para>Instances are virtual machines that run inside the
cloud.</para>
<xi:include
href="../openstack-user/src/section_cli_floating_ips.xml"/>
<xi:include href="nova_cli_resizerebuild.xml"/>
<!-- <xi:include href="nova_cli_evacuate.xml"/> -->
<xi:include href="nova_cli_startstop.xml"/>
<xi:include href="section_cli_reboot.xml"/>
<xi:include href="nova_cli_evacuate.xml"/>
<xi:include href="nova_cli_images.xml"/>
<!-- point user to cinder instead -->
<!-- <xi:include href="nova_cli_volumes.xml"/> -->
<xi:include href="nova_cli_terminate.xml"/>
<xi:include href="section_cli_get_console.xml"/>
<xi:include href="section_cli_baremetal.xml"/>
<xi:include href="nova_cli_usage_statistics.xml"/>
</section>

1
doc/src/docbkx/common/nova_cli_metadata.xml
View File

@ -1,4 +1,5 @@
<?xml version="1.0" encoding="UTF-8"?>
<!-- moved this information to "launch a server" section -->
<section
xmlns="http://docbook.org/ns/docbook"
xmlns:xi="http://www.w3.org/2001/XInclude"

176
doc/src/docbkx/common/nova_cli_resizerebuild.xml
View File

@ -1,94 +1,92 @@
<?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="nova_cli_resizerebuild">
<title>Change Server Configuration</title>
<para>After you have created a server, you may need to increase its
size, change the image used to build it, or perform other
configuration changes.</para>
<section xml:id="resizerebuild_commands_used">
<title>Commands Used</title>
<para>This process uses the following commands:
<itemizedlist>
<listitem><para><command>nova
resize*</command></para></listitem>
<listitem><para><command>nova rebuild</command></para></listitem>
</itemizedlist>
</para>
</section>
<section xml:id="nova_cli_resize">
<title>Increase or Decrease Server Size</title>
<para>Server size is changed by applying a different
flavor to the server. Before you begin, use nova
flavor-list to review the flavors available to
you.</para>
<screen>
<prompt>$</prompt> <userinput>nova flavor-list</userinput>
+----+-----------+-----------+------+-----------+------+-------+-------------+
| ID | Name | Memory_MB | Disk | Ephemeral | Swap | VCPUs | RXTX_Factor |
+----+-----------+-----------+------+-----------+------+-------+-------------+
| 1 | m1.tiny | 512 | 1 | N/A | 0 | 1 | |
| 2 | m1.small | 2048 | 20 | N/A | 0 | 1 | |
| 3 | m1.medium | 4096 | 40 | N/A | 0 | 2 | |
| 4 | m1.large | 8192 | 80 | N/A | 0 | 4 | |
| 5 | m1.xlarge | 16384 | 160 | N/A | 0 | 8 | |
+----+-----------+-----------+------+-----------+------+-------+-------------+
</screen>
<para>In this example, we'll take a server originally configured with the <code>m1.tiny</code> flavor and resize it to <code>m1.small</code>.</para>
<screen>
<prompt>$</prompt> <userinput>nova show acdfb2c4-38e6-49a9-ae1c-50182fc47e35</userinput>
+------------------------+----------------------------------------------------------+
| Property | Value |
+------------------------+----------------------------------------------------------+
| OS-DCF:diskConfig | MANUAL |
| OS-EXT-STS:power_state | 1 |
| OS-EXT-STS:task_state | None |
| OS-EXT-STS:vm_state | active |
| accessIPv4 | |
| accessIPv6 | |
| config_drive | |
| created | 2012-05-09T15:47:48Z |
| flavor | m1.tiny |
| hostId | de0c201e62be88c61aeb52f51d91e147acf6cf2012bb57892e528487 |
| id | acdfb2c4-38e6-49a9-ae1c-50182fc47e35 |
| image | maverick-image |
| key_name | |
| metadata | {} |
| name | resize-demo |
| private network | 172.16.101.6 |
| progress | 0 |
| public network | 10.4.113.6 |
| status | ACTIVE |
| tenant_id | e830c2fbb7aa4586adf16d61c9b7e482 |
| updated | 2012-05-09T15:47:59Z |
| user_id | de3f4e99637743c7b6d27faca4b800a9 |
+------------------------+----------------------------------------------------------+
</screen>
<para>Use the resize command with the server's ID (6beefcf7-9de6-48b3-9ba9-e11b343189b3) and the ID of the desired flavor (2):</para>
<screen>
<prompt>$</prompt> <userinput>nova resize 6beefcf7-9de6-48b3-9ba9-e11b343189b3 2</userinput>
</screen>
<para>While the server is rebuilding, its status will be displayed as RESIZING. </para>
<screen>
<prompt>$</prompt> <userinput>nova list</userinput>
+--------------------------------------+-------------+--------+-----------------------------------------+
<section xmlns="http://docbook.org/ns/docbook"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
xml:id="nova_cli_resize">
<title>Change the size of your server</title>
<para>You change the size of a server by changing its flavor.</para>
<procedure>
<title>To change the size of your server</title>
<step>
<para>List the available flavors:</para>
<screen><prompt>$</prompt> <userinput>nova flavor-list</userinput></screen>
<screen><computeroutput>+----+-----------+-----------+------+-----------+------+-------+-------------+-----------+
| ID | Name | Memory_MB | Disk | Ephemeral | Swap | VCPUs | RXTX_Factor | Is_Public |
+----+-----------+-----------+------+-----------+------+-------+-------------+-----------+
| 1 | m1.tiny | 512 | 0 | 0 | | 1 | 1.0 | True |
| 2 | m1.small | 2048 | 20 | 0 | | 1 | 1.0 | True |
| 3 | m1.medium | 4096 | 40 | 0 | | 2 | 1.0 | True |
| 4 | m1.large | 8192 | 80 | 0 | | 4 | 1.0 | True |
| 42 | m1.nano | 64 | 0 | 0 | | 1 | 1.0 | True |
| 5 | m1.xlarge | 16384 | 160 | 0 | | 8 | 1.0 | True |
| 84 | m1.micro | 128 | 0 | 0 | | 1 | 1.0 | True |
+----+-----------+-----------+------+-----------+------+-------+-------------+-----------+</computeroutput></screen>
</step>
<step>
<para>Show information about your server, including its size:</para>
<screen><prompt>$</prompt> <userinput>nova show myCirrosServer</userinput></screen>
<screen><computeroutput>+-------------------------------------+----------------------------------------------------------------+
| Property | Value |
+-------------------------------------+----------------------------------------------------------------+
| status | ACTIVE |
| updated | 2013-07-18T15:08:20Z |
| OS-EXT-STS:task_state | None |
| OS-EXT-SRV-ATTR:host | devstack-grizzly |
| key_name | None |
| image | cirros-0.3.1-x86_64-uec (397e713c-b95b-4186-ad46-6126863ea0a9) |
| private network | 10.0.0.3 |
| hostId | 6e1e69b71ac9b1e6871f91e2dfc9a9b9ceca0f05db68172a81d45385 |
| OS-EXT-STS:vm_state | active |
| OS-EXT-SRV-ATTR:instance_name | instance-00000005 |
| OS-EXT-SRV-ATTR:hypervisor_hostname | devstack-grizzly |
| flavor | m1.small (2) |
| id | 84c6e57d-a6b1-44b6-81eb-fcb36afd31b5 |
| security_groups | [{u'name': u'default'}] |
| user_id | 376744b5910b4b4da7d8e6cb483b06a8 |
| name | myCirrosServer |
| created | 2013-07-18T15:07:59Z |
| tenant_id | 66265572db174a7aa66eba661f58eb9e |
| OS-DCF:diskConfig | MANUAL |
| metadata | {u'description': u'Small test image', u'creator': u'joecool'} |
| accessIPv4 | |
| accessIPv6 | |
| progress | 0 |
| OS-EXT-STS:power_state | 1 |
| OS-EXT-AZ:availability_zone | nova |
| config_drive | |
+-------------------------------------+----------------------------------------------------------------+</computeroutput></screen>
<para>The size of the server is <literal>m1.small
(2)</literal>.</para></step>
<step>
<para>To resize the server, pass the server ID and the desired flavor to the nova
<command>resize</command> command.
Include the <literal>--poll</literal> parameter to report the resize
progress.</para>
<screen><prompt>$</prompt> <userinput>nova resize myCirrosServer 4 --poll</userinput></screen>
<screen><computeroutput>Instance resizing... 100% complete
Finished</computeroutput> </screen>
</step>
<step>
<para>Show the status for your server:</para>
<screen>
<prompt>$</prompt> <userinput>nova list</userinput></screen>
<screen><computeroutput>+--------------------------------------+-------------+--------+-----------------------------------------+
| ID | Name | Status | Networks |
+--------------------------------------+-------------+--------+-----------------------------------------+
| 970e4ca0-f9b7-4c44-80ed-bf0152c96ae1 | resize-demo | RESIZE | private=172.16.101.6, public=10.4.113.6 |
+--------------------------------------+-------------+--------+-----------------------------------------+
</screen>
<para>When the resize operation is completed, the status displayed is VERIFY_RESIZE. This prompts
the user to verify that the operation has been successful; to confirm:</para>
<screen>
<prompt>$</prompt> <userinput>nova resize-confirm 6beefcf7-9de6-48b3-9ba9-e11b343189b3</userinput>
</screen>
<para>However, if the operation has not worked as expected, you can revert it by doing:</para>
<screen>
<prompt>$</prompt> <userinput>nova resize-revert 6beefcf7-9de6-48b3-9ba9-e11b343189b3</userinput>
</screen>
<para>In both cases, the server status should go back to ACTIVE.</para>
</section>
+--------------------------------------+-------------+--------+-----------------------------------------+</computeroutput></screen>
</step>
<step>
<para>When the resize completes, the status becomes
<literal>VERIFY_RESIZE</literal>. To confirm the resize:</para>
<screen><prompt>$</prompt> <userinput>nova resize-confirm 6beefcf7-9de6-48b3-9ba9-e11b343189b3</userinput></screen>
<para>The server status becomes ACTIVE.</para> </step>
<step>
<para>If the resize fails or does not work as expected, you
can revert the resize:</para>
<screen><prompt>$</prompt> <userinput>nova resize-revert 6beefcf7-9de6-48b3-9ba9-e11b343189b3</userinput></screen>
<para>The server status becomes ACTIVE.</para>
</step>
</procedure>
</section>

32
doc/src/docbkx/common/nova_cli_secgroups.xml
View File

@ -5,35 +5,9 @@
xmlns:xlink="http://www.w3.org/1999/xlink"
version="5.0"
xml:id="nova_cli_security_groups">
<title>Manage Security Groups</title>
<para>A security group is a named collection of network access rules that can be used to
limit the types of traffic that have access to instances. When you spawn an instance,
you can assign it to one or more groups. For each security group, the associated rules
permit you to manage the allowed traffic to instances within the group. Any incoming
traffic which is not matched by a rule is denied by default. At any time, it is possible
to add or remove rules within a security group. Rules are automatically enforced as soon
as they are created.</para>
<para>Before you begin, use <command>nova
secgroup-list</command> to view the available security
groups (specify <literal>--all-tenants</literal> if you are a cloud administrator
wanting to view all tenants' groups) . You can also view the rules for a security group
with <command>nova secgroup-list-rules</command>.
<screen>
<prompt>$</prompt> <userinput>nova secgroup-list</userinput>
+---------+-------------+
| Name | Description |
+---------+-------------+
| default | default |
+---------+-------------+
<prompt>$</prompt> <userinput>nova secgroup-list-rules default</userinput>
+-------------+-----------+---------+-----------+--------------+
| IP Protocol | From Port | To Port | IP Range | Source Group |
+-------------+-----------+---------+-----------+--------------+
| tcp | 80 | 80 | 0.0.0.0/0 | |
+-------------+-----------+---------+-----------+--------------+
</screen>
In this example, the default security group has been modified to allow HTTP traffic on the instance by permitting TCP traffic on Port 80.</para>
<title>Add security group and rules</title>
<para>The following procedure shows you how to add security
groups and add rules to the default security group.</para>
<section xml:id="secgroup_add-delete">
<title>Add or delete a security group</title>
<para>Security groups can be added with <command>nova

69
doc/src/docbkx/common/nova_cli_sshkeys.xml
View File

@ -1,41 +1,34 @@
<?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="inserting_sshkeys">
<title>Associating ssh keys with instances</title>
<simplesect xml:id="nova_cli_keygen">
<title>Creating New Keys</title>
<para>The
command:<screen>
<section xmlns="http://docbook.org/ns/docbook"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
xml:id="nova_cli_keygen"><title>Add keypair</title>
<para>Create at least one keypair for each project. If you have
generated a keypair with an external tool, you can import it into
OpenStack. The keypair can be used for multiple instances that
belong to a project.</para>
<procedure>
<title>To add a keypair</title>
<step>
<title>Create a key</title>
<para>To create a <literal>mykey</literal> key that you can
associate with instances, run the following command:</para>
<screen>
<prompt>$</prompt> <userinput>nova keypair-add mykey > mykey.pem</userinput></screen>
will create a key named <literal>mykey</literal> which you can
associate with instances. Save the file
<filename>mykey.pem</filename> to a secure location as it will
allow root access to instances the <literal>mykey</literal>key
is associated with. </para>
</simplesect>
<simplesect xml:id="nova_cli_keyupload">
<title>Uploading Existing Keys</title>
<para>The
command:<screen>
<prompt>$</prompt> <userinput>nova keypair-add --pub-key mykey.pub mykey</userinput></screen>
will upload the existing public key <literal>mykey.pub</literal>
and associate it with the name <literal>mykey</literal>. You
will need to have the matching private key to access instances
associated with this key. </para>
</simplesect>
<simplesect xml:id="nova_cli_associatekey">
<title>Adding Keys to Your Instance</title>
<para>To associate a key with an instance on boot add <literal>--key_name mykey</literal> to your command line for example:<screen>
<prompt>$</prompt> <userinput>nova boot --image ubuntu-cloudimage --flavor 1 --key_name mykey</userinput></screen>
</para>
</simplesect>
<para>Save the <filename>mykey.pem</filename> file to a secure
location. It enables root access to any instances with which
the <literal>mykey</literal> key is associated. </para>
</step>
<step>
<title>Import a keypair</title>
<para>To import an existing public key,
<literal>mykey.pub</literal>, and associate it with the
<literal>mykey</literal> key, run the following
command:</para>
<screen>
<prompt>$</prompt> <userinput>nova keypair-add --pub-key mykey.pub mykey</userinput></screen>
<para>You must have the matching private key to access instances
that are associated with this key. </para>
</step>
</procedure>
</section>

48
doc/src/docbkx/common/nova_cli_startstop.xml
View File

@ -5,27 +5,29 @@
xmlns:xlink="http://www.w3.org/1999/xlink"
version="5.0"
xml:id="nova_cli_stop_start">
<title>Stop and Start an Instance</title>
<para>There are two methods for stopping and starting an
instance: <itemizedlist>
<listitem><para><command>nova pause</command> / <command>nova unpause</command></para></listitem>
<listitem><para><command>nova suspend</command> / <command>nova resume</command></para></listitem>
</itemizedlist></para>
<section xml:id="nova_cli_pause_unpause">
<title>Pause and Unpause</title>
<para><command>nova pause</command> stores the state of the VM in
RAM. A paused instance continues to run, albeit in a "frozen"
state.</para>
</section>
<section xml:id="nova_cli_suspend_resume">
<title>Suspend and Resume</title>
<para><command>nova suspend</command> initiates a hypervisor-level
suspend operation. Suspending an instance stores the state of the
VM on disk; all memory is written to disk and the virtual machine
is stopped. Suspending an instance is thus similar to placing a
device in hibernation, and makes memory and vCPUs
available. Administrators may want to suspend an instance for
system maintenance, or if the instance is not frequently
used.</para>
</section>
<title>Stop and start an instance</title>
<para>Use one of the following methods to stop and start an
instance.</para>
<section xml:id="pause_server"><title>Pause and un-pause an instance</title><procedure xml:id="nova_cli_pause_unpause">
<title>To pause and un-pause a server</title>
<step> <para>To pause a server, run the following command:</para><screen><prompt>$</prompt> <userinput>nova pause</userinput> <replaceable>SERVER</replaceable></screen>
<para>This command stores the state of the VM in
RAM. A paused instance continues to run in a frozen
state. </para>
<para>To un-pause the server, run the following command:</para><screen><prompt>$</prompt> <userinput>nova unpause</userinput> <replaceable>SERVER</replaceable></screen></step>
</procedure></section>
<section xml:id="suspend_resume"><title>Suspend and resume an instance</title> <procedure xml:id="nova_cli_suspend_resume">
<title>To suspend and resume a server</title>
<para>Administrative users might want to suspend an infrequently used
instance or to perform system maintenance. </para>
<step><para>When you suspend an instance, its VM state is stored on disk,
all memory is written to disk, and the virtual machine is
stopped. Suspending an instance is similar to placing a device
in hibernation; memory and vCPUs become available. </para><para>To initiate a hypervisor-level suspend operation,
run the following command:</para><screen><prompt>$</prompt> <userinput>nova suspend</userinput> <replaceable>SERVER</replaceable></screen>
</step>
<step><para>To resume a suspended server:</para>
<screen><prompt>$</prompt> <userinput>nova resume</userinput> <replaceable>SERVER</replaceable></screen>
</step>
</procedure></section>
</section>

58
doc/src/docbkx/common/nova_cli_terminate.xml
View File

@ -5,32 +5,34 @@
xmlns:xlink="http://www.w3.org/1999/xlink"
version="5.0"
xml:id="terminating">
<title>Terminate an Instance</title>
<para>When you no longer need an instance, use the <command>nova
delete</command> command to terminate it. You can use the instance
name or the ID string. You will not receive a notification
indicating that the instance has been deleted, but if you run the
<command>nova list</command> command, the instance will no longer
appear in the list.</para>
<para>In this example, we will delete the instance
<literal>tinyimage</literal>, which is experiencing an
error
condition.<screen>
<prompt>$</prompt> <userinput>nova list</userinput>
+--------------------------------------+------------+--------+-------------------------------------------+
| ID | Name | Status | Networks |
+--------------------------------------+------------+--------+-------------------------------------------+
| 30ed8924-f1a5-49c1-8944-b881446a6a51 | tinyimage | ERROR | public=10.4.113.11; private=172.16.101.11 |
| 4bb825ea-ea43-4771-a574-ca86ab429dcb | tinyimage2 | ACTIVE | public=10.4.113.6; private=172.16.101.6 |
| 542235df-8ba4-4d08-90c9-b79f5a77c04f | smallimage | ACTIVE | public=10.4.113.9; private=172.16.101.9 |
+--------------------------------------+------------+--------+-------------------------------------------+
<prompt>$</prompt> <userinput>nova delete tinyimage</userinput>
<prompt>$</prompt> <userinput>nova list</userinput>
+--------------------------------------+------------+--------+-------------------------------------------+
| ID | Name | Status | Networks |
+--------------------------------------+------------+--------+-------------------------------------------+
| 4bb825ea-ea43-4771-a574-ca86ab429dcb | tinyimage2 | ACTIVE | public=10.4.113.6; private=172.16.101.6 |
| 542235df-8ba4-4d08-90c9-b79f5a77c04f | smallimage | ACTIVE | public=10.4.113.9; private=172.16.101.9 |
+--------------------------------------+------------+--------+-------------------------------------------+
</screen></para>
<title>Delete an instance</title>
<para>When you no longer need an instance, you can delete it. </para>
<procedure><title>To delete an instance</title><step>
<para>List all instances:</para>
<screen><prompt>$</prompt> <userinput>nova list</userinput></screen>
<screen><computeroutput>+--------------------------------------+----------------------+--------+------------+-------------+------------------+
| ID | Name | Status | Task State | Power State | Networks |
+--------------------------------------+----------------------+--------+------------+-------------+------------------+
| 84c6e57d-a6b1-44b6-81eb-fcb36afd31b5 | myCirrosServer | ACTIVE | None | Running | private=10.0.0.3 |
| 8a99547e-7385-4ad1-ae50-4ecfaaad5f42 | myInstanceFromVolume | ACTIVE | None | Running | private=10.0.0.4 |
| d7efd3e4-d375-46d1-9d57-372b6e4bdb7f | newServer | ERROR | None | NOSTATE | |
+--------------------------------------+----------------------+--------+------------+-------------+------------------+</computeroutput></screen>
</step><step>
<para>Use the following command to delete the
<literal>newServer</literal> instance, which is in
<literal>ERROR</literal> state:</para>
<screen><prompt>$</prompt> <userinput>nova delete newServer</userinput></screen>
</step><step><para>The command does not notify that your server was deleted. </para>
<para>Instead, run the <command>nova list</command>
command:</para>
<screen><prompt>$</prompt> <userinput>nova list</userinput></screen>
<screen><computeroutput>+--------------------------------------+----------------------+--------+------------+-------------+------------------+
| ID | Name | Status | Task State | Power State | Networks |
+--------------------------------------+----------------------+--------+------------+-------------+------------------+
| 84c6e57d-a6b1-44b6-81eb-fcb36afd31b5 | myCirrosServer | ACTIVE | None | Running | private=10.0.0.3 |
| 8a99547e-7385-4ad1-ae50-4ecfaaad5f42 | myInstanceFromVolume | ACTIVE | None | Running | private=10.0.0.4 |
+--------------------------------------+----------------------+--------+------------+-------------+------------------+</computeroutput> </screen>
<para>The deleted instance does not appear in the list.</para>
</step>
</procedure>
</section>

167
doc/src/docbkx/common/nova_cli_usage_statistics.xml
View File

@ -1,87 +1,96 @@
<?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="usage_statistics">
<title>Usage statistics</title><para xlink:href="http://graphite.wikidot.com">The nova command-line tool can provide some basic
<title>Show usage statistics for hosts and instances</title><para xlink:href="http://graphite.wikidot.com">You can show basic
statistics on resource usage for hosts and instances.</para>
<para xlink:href="http://graphite.wikidot.com">For more sophisticated monitoring, see the <link
xlink:href="https://launchpad.net/ceilometer">Ceilometer</link> project, which is
currently under development. You may also wish to consider installing tools such as <link
xlink:href="http://ganglia.info/">Ganglia</link> or <link
xlink:href="http://graphite.wikidot.com/">Graphite</link> if you require access to more
detailed data.</para><section xml:id="host_usage_statistics">
<title>Host usage statistics</title>
<para>Use the <command>nova host-list</command> command to list the hosts and the
nova-related services that are running on
them:<screen><prompt>$</prompt> <userinput>nova host-list</userinput>
<computeroutput>+------------------+-------------+
| host_name | service |
+------------------+-------------+
| c2-compute-01 | compute |
| c2-compute-01 | network |
| c2-compute-02 | compute |
| c2-compute-02 | network |
| c2-compute-03 | compute |
| c2-compute-03 | network |
| c2-compute-04 | compute |
| c2-compute-04 | network |
| c2-controller-01 | cert |
| c2-controller-01 | consoleauth |
| c2-controller-01 | scheduler |
+------------------+-------------+</computeroutput></screen></para>
<para>Use the <command>nova host-describe</command> command to retrieve a summary of
resource usage of all of the instances running on the host. The "cpu" column is the sum
of the virtual CPUs of all of the instances running on the host, the "memory_mb" column
is the sum of the memory (in MB) allocated to the instances running on the hosts, and
the "disk_gb" column is the sum of the root and ephemeral disk sizes (in GB) of the
instances running on the hosts.</para>
<para>Note that these values are computed using only information about the flavors of the
instances running on the hosts. This command does not query the CPU usage, memory usage,
or hard disk usage of the physical
host.<screen><prompt>$</prompt> <userinput>nova host-describe <replaceable>c2-compute-01</replaceable></userinput>
<computeroutput>+---------------+----------------------------------+-----+-----------+---------+
| HOST | PROJECT | cpu | memory_mb | disk_gb |
+---------------+----------------------------------+-----+-----------+---------+
| c2-compute-01 | (total) | 24 | 96677 | 492 |
| c2-compute-01 | (used_max) | 2 | 2560 | 0 |
| c2-compute-01 | (used_now) | 4 | 7168 | 0 |
| c2-compute-01 | f34d8f7170034280a42f6318d1a4af34 | 2 | 2560 | 0 |
+---------------+----------------------------------+-----+-----------+---------+</computeroutput></screen></para>
</section>
<section xml:id="instance_usage_statistics">
<title>Instance usage statistics</title>
<para>Use the <command>nova diagnostics</command> command to retrieve CPU, memory, I/O and
network statistics from an
instance:<screen><prompt>$</prompt> <userinput>nova diagnostics <replaceable>ubuntu</replaceable></userinput>
<computeroutput>+------------------+---------------+
| Property | Value |
+------------------+---------------+
| cpu0_time | 1138410000000 |
| memory | 524288 |
| memory-actual | 524288 |
| memory-rss | 591664 |
| vda_errors | -1 |
| vda_read | 334864384 |
| vda_read_req | 13851 |
| vda_write | 2985382912 |
| vda_write_req | 177180 |
| vnet4_rx | 45381339 |
| vnet4_rx_drop | 0 |
| vnet4_rx_errors | 0 |
| vnet4_rx_packets | 106426 |
| vnet4_tx | 37513574 |
| vnet4_tx_drop | 0 |
| vnet4_tx_errors | 0 |
| vnet4_tx_packets | 162200 |
+------------------+---------------+</computeroutput></screen></para>
<para>Use the <command>nova usage-list</command> command to get summary statistics for each
tenant:<screen><prompt>$</prompt> <userinput>nova usage-list</userinput>
<computeroutput>Usage from 2012-10-10 to 2012-11-08:
<note> <para xlink:href="http://graphite.wikidot.com">For more sophisticated
monitoring, see the <link
xlink:href="https://launchpad.net/ceilometer"
>Ceilometer</link> project, which is under
development. You can also use tools, such as <link
xlink:href="http://ganglia.info/">Ganglia</link> or
<link xlink:href="http://graphite.wikidot.com/"
>Graphite</link>, to gather more detailed data.</para></note>
<procedure xml:id="host_usage_statistics">
<title>To show host usage statistics</title>
<step><para>List the hosts and the nova-related services that run on
them:</para><screen><prompt>$</prompt> <userinput>nova host-list</userinput></screen>
<screen><computeroutput>+------------------+-------------+----------+
| host_name | service | zone |
+------------------+-------------+----------+
| devstack-grizzly | conductor | internal |
| devstack-grizzly | compute | nova |
| devstack-grizzly | cert | internal |
| devstack-grizzly | network | internal |
| devstack-grizzly | scheduler | internal |
| devstack-grizzly | consoleauth | internal |
+------------------+-------------+----------+</computeroutput></screen></step>
<step><para>Get a summary of resource usage of all of the instances running
on the host.</para><screen><prompt>$</prompt> <userinput>nova host-describe <replaceable>devstack-grizzly</replaceable></userinput></screen>
<screen><computeroutput>+------------------+----------------------------------+-----+-----------+---------+
| HOST | PROJECT | cpu | memory_mb | disk_gb |
+------------------+----------------------------------+-----+-----------+---------+
| devstack-grizzly | (total) | 2 | 4003 | 157 |
| devstack-grizzly | (used_now) | 3 | 5120 | 40 |
| devstack-grizzly | (used_max) | 3 | 4608 | 40 |
| devstack-grizzly | b70d90d65e464582b6b2161cf3603ced | 1 | 512 | 0 |
| devstack-grizzly | 66265572db174a7aa66eba661f58eb9e | 2 | 4096 | 40 |
+------------------+----------------------------------+-----+-----------+---------+</computeroutput></screen>
<para>The <literal>cpu</literal> column shows the sum of
the virtual CPUs for instances running on the host. </para>
<para>The <literal>memory_mb</literal> column shows the
sum of the memory (in MB) allocated to the instances
that run on the hosts. </para>
<para>The <literal>disk_gb</literal> column shows the sum
of the root and ephemeral disk sizes (in GB) of the
instances that run on the hosts.</para>
<note> <para>These values are computed by using only information
about the flavors of the instances that run on the
hosts. This command does not query the CPU usage,
memory usage, or hard disk usage of the physical
host.</para> </note> </step> </procedure>
<procedure xml:id="instance_usage_statistics">
<title>To show instance usage statistics</title>
<step>
<para>Get CPU, memory, I/O, and network statistics for an
instance. </para>
<para>First, list instances:</para>
<screen><prompt>$</prompt> <userinput>nova list</userinput></screen>
<screen><computeroutput>+--------------------------------------+----------------------+--------+------------+-------------+------------------+
| ID | Name | Status | Task State | Power State | Networks |
+--------------------------------------+----------------------+--------+------------+-------------+------------------+
| 84c6e57d-a6b1-44b6-81eb-fcb36afd31b5 | myCirrosServer | ACTIVE | None | Running | private=10.0.0.3 |
| 8a99547e-7385-4ad1-ae50-4ecfaaad5f42 | myInstanceFromVolume | ACTIVE | None | Running | private=10.0.0.4 |
+--------------------------------------+----------------------+--------+------------+-------------+------------------+</computeroutput></screen>
<para>Then, get diagnostic statistics:</para>
<screen><prompt>$</prompt> <userinput> nova diagnostics myCirrosServer</userinput></screen>
<screen><computeroutput>+------------------+----------------+
| Property | Value |
+------------------+----------------+
| vnet1_rx | 1210744 |
| cpu0_time | 19624610000000 |
| vda_read | 0 |
| vda_write | 0 |
| vda_write_req | 0 |
| vnet1_tx | 863734 |
| vnet1_tx_errors | 0 |
| vnet1_rx_drop | 0 |
| vnet1_tx_packets | 3855 |
| vnet1_tx_drop | 0 |
| vnet1_rx_errors | 0 |
| memory | 2097152 |
| vnet1_rx_packets | 5485 |
| vda_read_req | 0 |
| vda_errors | -1 |
+------------------+----------------+</computeroutput></screen>
</step>
<step> <para>Get summary statistics for each tenant:</para><screen><prompt>$</prompt> <userinput>nova usage-list</userinput></screen>
<screen><computeroutput>Usage from 2013-06-25 to 2013-07-24:
+----------------------------------+-----------+--------------+-----------+---------------+
| Tenant ID | Instances | RAM MB-Hours | CPU Hours | Disk GB-Hours |
+----------------------------------+-----------+--------------+-----------+---------------+
| 0eec5c34a7a24a7a8ddad27cb81d2706 | 8 | 240031.10 | 468.81 | 0.00 |
| 92a5d9c313424537b78ae3e42858fd4e | 5 | 483568.64 | 236.12 | 0.00 |
| f34d8f7170034280a42f6318d1a4af34 | 106 | 16888511.58 | 9182.88 | 0.00 |
+----------------------------------+-----------+--------------+-----------+---------------+</computeroutput></screen></para>
</section>
| b70d90d65e464582b6b2161cf3603ced | 1 | 344064.44 | 672.00 | 0.00 |
| 66265572db174a7aa66eba661f58eb9e | 3 | 671626.76 | 327.94 | 6558.86 |
+----------------------------------+-----------+--------------+-----------+---------------+</computeroutput></screen>
</step> </procedure>
</section>

1
doc/src/docbkx/common/nova_cli_userdata.xml
View File

@ -1,4 +1,5 @@
<?xml version="1.0" encoding="UTF-8"?>
<!-- moved to launch instances file -->
<section
xmlns="http://docbook.org/ns/docbook"
xmlns:xi="http://www.w3.org/2001/XInclude"

122
doc/src/docbkx/common/section_cli_baremetal.xml Normal file
View File

@ -0,0 +1,122 @@
<?xml version="1.0" encoding="UTF-8"?>
<section xml:id="baremetal" 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>Manage bare metal nodes</title>
<para>If you use the bare metal driver, you must create a bare
metal node and add a network interface to it. You then launch an
instance from a bare metal image. You can list and delete bare
metal nodes. When you delete a node, any associated network
interfaces are removed. You can list and remove network interfaces
that are associated with a bare metal node.</para>
<itemizedlist><title>Commands</title><listitem>
<para><command>baremetal-interface-add</command></para>
<para>Adds a network interface to a bare metal node.</para>
</listitem>
<listitem>
<para><command>baremetal-interface-list</command></para>
<para> Lists network interfaces associated with a bare metal
node.</para>
</listitem>
<listitem>
<para>
<command>baremetal-interface-remove</command></para>
<para> Removes a network interface from a bare metal
node.</para>
</listitem>
<listitem>
<para>
<command>baremetal-node-create</command></para>
<para> Creates a bare metal node.</para>
</listitem>
<listitem>
<para>
<command>baremetal-node-delete</command></para>
<para> Removes a bare metal node and any associated
interfaces.</para>
</listitem>
<listitem>
<para><command>baremetal-node-list</command></para>
<para>Lists available bare metal nodes.</para>
</listitem>
<listitem>
<para><command>baremetal-node-show</command></para>
<para> Shows information about a bare metal node.</para>
</listitem></itemizedlist>
<procedure><title>To manage bare metal nodes</title><step><para>Create a bare metal node.</para>
<screen><prompt>$</prompt> <userinput>nova baremetal-node-create --pm_address=1.2.3.4 --pm_user=ipmi --pm_password=ipmi $(hostname -f) 1 512 10 aa:bb:cc:dd:ee:ff</userinput></screen>
<screen><computeroutput>+------------------+-------------------+
| Property | Value |
+------------------+-------------------+
| instance_uuid | None |
| pm_address | 1.2.3.4 |
| interfaces | [] |
| prov_vlan_id | None |
| cpus | 1 |
| memory_mb | 512 |
| prov_mac_address | aa:bb:cc:dd:ee:ff |
| service_host | ubuntu |
| local_gb | 10 |
| id | 1 |
| pm_user | ipmi |
| terminal_port | None |
+------------------+-------------------+</computeroutput></screen>
</step>
<step><para>Add network interface information to the node:</para>
<screen><prompt>$</prompt> <userinput>nova baremetal-interface-add 1 aa:bb:cc:dd:ee:ff</userinput></screen>
<screen><computeroutput>+-------------+-------------------+
| Property | Value |
+-------------+-------------------+
| datapath_id | 0 |
| id | 1 |
| port_no | 0 |
| address | aa:bb:cc:dd:ee:ff |
+-------------+-------------------+</computeroutput> </screen>
</step>
<step><para>Launch an instance from a bare metal image:</para>
<screen><prompt>$</prompt> <userinput>nova boot --image my-baremetal-image --flavor my-baremetal-flavor test</userinput> </screen>
<screen>+-----------------------------+--------------------------------------+
| Property | Value |
+-----------------------------+--------------------------------------+
| status | BUILD |
| id | cc302a8f-cd81-484b-89a8-b75eb3911b1b |
... wait for instance to become active ... </screen>
</step>
<step><para>You can list bare metal nodes and interfaces. When a node is in
use, its status includes the UUID of the instance that runs on
it:</para>
<screen><prompt>$</prompt> <userinput>nova baremetal-node-list</userinput></screen>
<screen><computeroutput>+----+--------+------+-----------+---------+-------------------
+------+------------+-------------+-------------+---------------+
| ID | Host | CPUs | Memory_MB | Disk_GB | MAC Address
| VLAN | PM Address | PM Username | PM Password | Terminal Port |
+----+--------+------+-----------+---------+-------------------
+------+------------+-------------+-------------+---------------+
| 1 | ubuntu | 1 | 512 | 10 | aa:bb:cc:dd:ee:ff
| None | 1.2.3.4 | ipmi | | None |
+----+--------+------+-----------+---------+-------------------
+------+------------+-------------+-------------+---------------+</computeroutput></screen>
</step>
<step><para>Show details about a bare metal node:</para>
<screen><prompt>$</prompt> <userinput>nova baremetal-node-show 1</userinput> </screen>
<screen><computeroutput>+------------------+--------------------------------------+
| Property | Value |
+------------------+--------------------------------------+
| instance_uuid | cc302a8f-cd81-484b-89a8-b75eb3911b1b |
| pm_address | 1.2.3.4 |
| interfaces |
[{u'datapath_id': u'0', u'id': 1, u'port_no': 0, u'address': u'aa:bb:cc:dd:ee:ff'}] |
| prov_vlan_id | None |
| cpus | 1 |
| memory_mb | 512 |
| prov_mac_address | aa:bb:cc:dd:ee:ff |
| service_host | ubuntu |
| local_gb | 10 |
| id | 1 |
| pm_user | ipmi |
| terminal_port | None |
+------------------+--------------------------------------+</computeroutput></screen></step></procedure>
</section>

17
doc/src/docbkx/common/section_cli_get_console.xml Normal file
View File

@ -0,0 +1,17 @@
<?xml version="1.0" encoding="UTF-8"?>
<section xml:id="instance_console" xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:svg="http://www.w3.org/2000/svg"
xmlns:html="http://www.w3.org/1999/xhtml" version="5.0">
<title>Get a console to an instance</title>
<procedure><title>To get a console to an instance</title> <step><para>To get a VNC console to an instance, run the following
command:</para> <screen><userinput><prompt>$</prompt> nova get-vnc-console myCirrosServer xvpvnc</userinput></screen>
<para>The command returns a URL from which you can access your instance:</para>
<screen><computeroutput>+--------+------------------------------------------------------------------------------+
| Type | Url |
+--------+------------------------------------------------------------------------------+
| xvpvnc | http://166.78.190.96:6081/console?token=c83ae3a3-15c4-4890-8d45-aefb494a8d6c |
+--------+------------------------------------------------------------------------------+</computeroutput></screen>
<note><para>To get a non-VNC console, specify the <parameter>novnc</parameter> parameter instead of the <parameter>xvpvnc</parameter> parameter.</para></note></step></procedure>
</section>

12
doc/src/docbkx/common/section_cli_reboot.xml Normal file
View File

@ -0,0 +1,12 @@
<?xml version="1.0" encoding="UTF-8"?>
<section xml:id="reboot" 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>Reboot an instance</title>
<para>You can perform a soft or hard reboot of a running instance. A
soft reboot attempts a graceful shutdown and restart of the
instance. A hard reboot power cycles the instance.</para>
<procedure><title>To reboot a server</title> <step><para>By default, when you reboot a server, it is a soft reboot. </para>
<screen><prompt>$</prompt> <userinput>nova reboot <replaceable>SERVER</replaceable></userinput></screen></step></procedure>
<para>To perform a hard reboot, pass the <parameter>--hard</parameter>
parameter, as follows:</para><screen><prompt>$</prompt> <userinput>nova reboot --hard <replaceable>SERVER</replaceable></userinput></screen></section>

10
doc/src/docbkx/openstack-compute-admin/aboutcompute.xml
View File

@ -1,7 +1,10 @@
<?xml version="1.0" encoding="UTF-8"?>
<chapter xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
xmlns:svg="http://www.w3.org/2000/svg"
xmlns:html="http://www.w3.org/1999/xhtml"
version="5.0"
xml:id="ch_introduction-to-openstack-compute">
<title>Introduction to OpenStack Compute</title>
<para>OpenStack Compute gives you a tool to orchestrate a cloud, including running instances,
@ -324,9 +327,8 @@
but the root filesystem (and possibly others) will be
on the persistent volume and thus state will be
maintained even if the instance it shutdown. Details
of this configuration are discussed in <xref
linkend="boot_from_volume"/>.</para>
<para>Volumes do not provide concurrent access from multiple
of this configuration are discussed in the <link xlink:href="http://docs.openstack.org/cli/quick-start/content/"><citetitle>OpenStack Clients Guide</citetitle></link>.</para>
<para>Volumes do not provide concurrent access from multiple
instances. For that you need either a traditional network
filesystem like NFS or CIFS or a cluster filesystem such as
GlusterFS. These may be built within an OpenStack cluster or

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

@ -49,6 +49,16 @@
<revhistory>
<!-- ... continue adding more revisions here as you change this document using the markup shown below... -->
<revision>
<date>2013-07-23</date>
<revdescription>
<itemizedlist spacing="compact">
<listitem>
<para>Moved information about launching instances to the <citetitle>OpenStack Clients Guide</citetitle>.</para>
</listitem>
</itemizedlist>
</revdescription>
</revision>
<revision>
<date>2013-05-09</date>
<revdescription>
<itemizedlist spacing="compact">

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

@ -7,14 +7,13 @@
<para>Instances are the running virtual machines within an
OpenStack cloud. </para>
<para><!--<phrase>The <link linkend="images-and-instances"
>Images and Instances</link> section</phrase>-->See <xref
<!--<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>
a high level overview of instances and their life cycle.</para>-->
<para>This chapter describes how to manage that
life cycle.</para>
<para>Learn how to manage that life cycle.</para>
<section xml:id="instance-mgmt-interfaces">
<?dbhtml stop-chunking?>
@ -78,13 +77,12 @@
</listitem>
</itemizedlist>
<para>For example if you have your <link
linkend="ch-identity-mgmt-config">Keytone</link>
identity management service running on the default
port (5000) on host keystone.example.com and want to
use the <application>nova</application> cli as the
user "demouser" with the password "demopassword" in
the "demoproject" tenant you can export the following
<para>For example if you have your Identity Service
running on the default port (5000) on host
keystone.example.com and want to use the
<application>nova</application> cli as the user
"demouser" with the password "demopassword" in the
"demoproject" tenant you can export the following
values in your shell environment or pass the
equivalent command line args (presuming these
identities already exist):</para>
@ -140,9 +138,7 @@ header: Date: Thu, 13 Sep 2012 20:27:36 GMT
+----+------+--------+----------+
| ID | Name | Status | Networks |
+----+------+--------+----------+
+----+------+--------+----------+
</computeroutput>
</screen></para>
+----+------+--------+----------+</computeroutput></screen></para>
</simplesect>
<simplesect xml:id="instance-mgmt-ec2compat">
@ -253,8 +249,7 @@ header: Date: Thu, 13 Sep 2012 20:27:36 GMT
<simplesect xml:id="instance-building-blocks-images">
<title>Images</title>
<para>In OpenStack the base operating system is usually
copied from an <link linkend="ch_image_mgmt"
>"image"</link> stored in the Glance image
copied from an image stored in the Glance image
service. This is the most common case and results in
an ephemeral instance which starts from a know
templated state and lose all accumulated state on
@ -276,31 +271,28 @@ header: Date: Thu, 13 Sep 2012 20:27:36 GMT
</computeroutput>
</screen>
</para>
<para> The displayed image attributes are <itemizedlist>
<listitem>
<para>ID: the automatically generate UUID of
the image</para>
</listitem>
<listitem>
<para>Name: a free form human readable name
given to the image</para>
</listitem>
<listitem>
<para>Status: shows the status of the image
ACTIVE images are available for
use.</para>
</listitem>
<listitem>
<para>Server: for images that are created as
snapshots of running instance this is the
UUID of the instance the snapshot derives
from, for uploaded images it is
blank</para>
</listitem>
</itemizedlist>
</para>
<para>The displayed image attributes are:</para>
<itemizedlist>
<listitem>
<para>ID: the automatically generate UUID of the
image</para>
</listitem>
<listitem>
<para>Name: a free form human readable name given
to the image</para>
</listitem>
<listitem>
<para>Status: shows the status of the image ACTIVE
images are available for use.</para>
</listitem>
<listitem>
<para>Server: for images that are created as
snapshots of running instance this is the UUID
of the instance the snapshot derives from, for
uploaded images it is blank</para>
</listitem>
</itemizedlist>
</simplesect>
<simplesect xml:id="instance-building-blocks-flavors">
<title>Flavors</title>
<para>Virtual hardware templates are called "flavors" in
@ -311,8 +303,8 @@ header: Date: Thu, 13 Sep 2012 20:27:36 GMT
"compute_extension:flavormanage" in
<filename>/etc/nova/policy.json</filename> on the
compute-api server) . To get a list of available
flavors on your system run:
<screen><prompt>$</prompt> <userinput>nova flavor-list</userinput>
flavors on your system run:</para>
<screen><prompt>$</prompt> <userinput>nova flavor-list</userinput>
<computeroutput>
+----+-----------+-----------+------+-----------+------+-------+-------------+
| ID | Name | Memory_MB | Disk | Ephemeral | Swap | VCPUs | RXTX_Factor |
@ -323,10 +315,7 @@ header: Date: Thu, 13 Sep 2012 20:27:36 GMT
| 4 | m1.large | 8192 | 80 | N/A | 0 | 4 | |
| 5 | m1.xlarge | 16384 | 160 | N/A | 0 | 8 | |
+----+-----------+-----------+------+-----------+------+-------+-------------+
</computeroutput>
</screen>
</para>
</computeroutput></screen>
<para> The <command>nova flavor-create</command> command
allows authorized users to create new flavors.
Additional flavor manipulation commands can be shown
@ -349,13 +338,12 @@ header: Date: Thu, 13 Sep 2012 20:27:36 GMT
</listitem>
<listitem>
<para>Disk: virtual root disk size in
gigabytes. This is an ephemeral disk the
base <link linkend="ch_image_mgmt"
>image</link> is copied into. When
booting from a persistent volume it is not used. The "0"
size is a special case which uses the
native base image size as the size of the
ephemeral root volume. </para>
gigabytes. This is an ephemeral disk that
the base image is copied into. When
booting from a persistent volume it is not
used. The "0" size is a special case which
uses the native base image size as the
size of the ephemeral root volume. </para>
</listitem>
<listitem>
<para>Ephemeral: specifies the size of a
@ -401,23 +389,28 @@ header: Date: Thu, 13 Sep 2012 20:27:36 GMT
</para>
</simplesect>
</section>
<section xml:id="instance-creation">
<?dbhtml stop-chunking?>
<title>Creating instances</title>
<xi:include href="../common/nova_cli_boot.xml"/>
<xi:include href="../common/boot_from_volume.xml"/>
<para>For information about launching instances through the
nova command-line client, see the <link
xlink:href="http://docs.openstack.org/cli/quick-start/content/"
><citetitle>OpenStack Clients
Guide</citetitle></link>.</para>
<!--moved the following to the OpenStack Clients Guide -->
<!-- once OpenStack End User Guide is signed off, move to there -->
<!--<xi:include href="../openstack-user/src/section_cli_openrc.xml"/>
<xi:include href="../common/nova_cli_boot.xml"/> -->
</section>
<section xml:id="instance-scheduling-constraints">
<title>Controlling where instances run</title>
<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
nodes for service resiliency or on the <link
linkend="samehostfilter">same</link> node for high
performance inter-instance communications</para>
<title>Control where instances run</title>
<para>The <!--<xref linkend="ch_scheduling"/>-->
<citetitle>OpenStack Configuration Reference</citetitle>
provides detailed information on controlling where your
instances run, including ensuring a set of instances run
on different compute nodes for service resiliency or on
the same node for high performance inter-instance
communications</para>
<para> Additionally admin users can specify and exact compute
node to run on by specifying <literal>--availability-zone
&lt;availability-zone&gt;:&lt;compute-host&gt;</literal>
@ -426,63 +419,71 @@ header: Date: Thu, 13 Sep 2012 20:27:36 GMT
the default <literal>nova</literal> availability zone:
<screen><prompt>#</prompt> <userinput>nova boot --image aee1d242-730f-431f-88c1-87630c0f07ba --flavor 1 --availability-zone nova:nova-1 testhost</userinput></screen></para>
</section>
<section xml:id="instance-data">
<?dbhtml stop-chunking?>
<title>Instance specific data</title>
<para>For each instance, you can specify certain data
including authorized_keys key injection, user-data,
metadata service, and file injection.</para>
<xi:include href="../common/nova_cli_sshkeys.xml"/>
<para>For information, see the <link
xlink:href="http://docs.openstack.org/cli/quick-start/content/"
><citetitle>OpenStack Clients
Guide</citetitle></link>.</para>
<!--<xi:include href="../common/nova_cli_sshkeys.xml"/>
<xi:include href="../common/nova_cli_metadata.xml"/>
<xi:include href="../common/nova_cli_userdata.xml"/>
<xi:include href="../common/nova_cli_fileinjection.xml"/>
</section>
<xi:include href="../common/user-data.xml" />
<xi:include href="../common/config-drive.xml"/>
<xi:include href="../common/config-drive.xml"/>-->
</section>
<section xml:id="instance-networking">
<?dbhtml stop-chunking?>
<title>Managing instance networking</title>
<xi:include href="../common/nova_cli_floatingip.xml"/>
<xi:include href="../common/nova_cli_secgroups.xml"/>
<para>For information, see <link
xlink:href="http://docs.openstack.org/cli/quick-start/content/"
><citetitle>OpenStack Clients
Guide</citetitle></link>.</para>
<!--<xi:include href="../common/nova_cli_floatingip.xml"/>
<xi:include href="../common/nova_cli_secgroups.xml"/> -->
</section>
<!-- maybe this should not be shared with nova-cli so we can talk about cinder? -->
<xi:include href="../common/nova_cli_volumes.xml"/>
<section xml:id="instance-access">
<?dbhtml stop-chunking?>
<title>Accessing running instances</title>
<title>Access running instances</title>
<para>The most common access method for running instances is
probably ssh, but this requires you have setup your
instance with <link linkend="inserting_sshkeys">ssh
keys</link> and you have arranged for it to be running
ssh with a <link linkend="floating_ip_addresses">public
ip</link> and opened the ssh port in your <link
linkend="nova_cli_security_groups">security
group</link> configuration. If you haven't done this
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. </para><!--<para>See the <link
instance with ssh keys and you have arranged for it to be
running ssh with a public ip and opened the ssh port in
your security group configuration. If you haven't done
this 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
xlink:href="http://docs.openstack.org/cli/quick-start/content/"
><citetitle>OpenStack Clients
Guide</citetitle></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> -->
</section>
<xi:include href="../common/nova_cli_startstop.xml"/>
<section xml:id="manage_instances">
<title>Manage running instances</title>
<para>For information about how to start and stop, resize,
evacuate, and delete instances, see the <link
xlink:href="http://docs.openstack.org/cli/quick-start/content/"
><citetitle>OpenStack Clients
Guide</citetitle></link>.</para>
</section>
<!--<xi:include href="../common/nova_cli_startstop.xml"/>
<xi:include href="../common/nova_cli_resizerebuild.xml"/>
<xi:include href="../common/nova_cli_evacuate.xml"/>
<xi:include href="../common/nova_cli_evacuate.xml"/>-->
<!-- future work
<section xml:id="instance-migration">
<?dbhtml stop-chunking?>
<title>Migrating running instances</title>
<para>live, stop &amp; copy</para>
</section>
-->
<xi:include href="../common/nova_cli_terminate.xml"/>
<xi:include href="../common/nova_cli_terminate.xml"/>-->
</chapter>

2
doc/src/docbkx/openstack-compute-admin/computescheduler.xml
View File

@ -126,7 +126,7 @@ scheduler_default_filters=AvailabilityZoneFilter,RamFilter,ComputeFilter
<title>AggregateRamFilter </title>
<para>Implements blueprint <literal>per-aggregate-resource-ratio</literal>. Supports per-aggregate
<literal>ram_allocation_ratio</literal>. If per-aggregate value is not found, it falls back to the
<link linkend="compute-scheduler-config-ref">default setting</link>.</para>
default setting.</para>
</section>
<section xml:id="allhostsfilter">

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

@ -41,7 +41,7 @@
appendix toc
article/appendix nop
article toc,title
book toc,title,figure,table,example,equation
book toc,title,figure,example,equation
chapter toc
section toc
part toc

14
doc/src/docbkx/openstack-user/src/app_command_reference.xml
View File

@ -19,18 +19,18 @@
<xi:include href="section_cli_keystone.xml"/>
<xi:include href="section_cli_swift.xml"/> -->
<xi:include
href="../../cli-guide/src/keystone_cli_commands.xml"/>
href="keystone_cli_commands.xml"/>
<?hard page-break?>
<xi:include href="../../cli-guide/src/glance_cli_commands.xml"/>
<xi:include href="glance_cli_commands.xml"/>
<?hard page-break?>
<xi:include
href="../../cli-guide/src/neutron_cli_commands.xml"/>
href="neutron_cli_commands.xml"/>
<?hard page-break?>
<xi:include href="../../cli-guide/src/nova_cli_commands.xml"/>
<xi:include href="nova_cli_commands.xml"/>
<?hard page-break?>
<xi:include href="../../cli-guide/src/cinder_cli_commands.xml"/>
<xi:include href="cinder_cli_commands.xml"/>
<?hard page-break?>
<xi:include href="../../cli-guide/src/swift_cli_commands.xml"/>
<xi:include href="swift_cli_commands.xml"/>
<?hard page-break?>
<xi:include href="../../cli-guide/src/heat_cli_commands.xml"/>
<xi:include href="heat_cli_commands.xml"/>
</appendix>

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

@ -9,19 +9,21 @@
<info>
<title>OpenStack command-line clients</title>
</info>
<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. 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
<para>The OpenStack command-line clients let you run simple
commands to make OpenStack API calls and automate tasks
by using scripts. These open-source Python
clients run on Linux or Mac OS X systems and are easy to learn and use. Each OpenStack service has
its own command-line client. </para>
<para>The OpenStack APIs are RESTful APIs that use the HTTP
protocol, including methods, URIs, media types, and response
codes. Internally, each client command runs cURL commands that
embed API requests. </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
parameter on some client commands 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
@ -30,12 +32,93 @@
OpenStack APIs work.</para>
<para>You can modify these examples to create other types and
sizes of servers.</para>
<xi:include href="section_cli_overview.xml"/>
<para>To install an OpenStack client, see <xref
linkend="install_clients"/>.</para>
<para>To request OpenStack services through either the clients or
the APIs directly, you must source an
<filename>openrc</filename> file to set required
environment variables.</para>
<note>
<para>An OpenStack common client is in development.</para>
</note>
<para>The following command-line clients are available for the
respective services' APIs:</para>
<table rules="all" width="100%">
<caption>OpenStack clients</caption>
<thead>
<tr>
<th>Client</th>
<th>Associated service API</th>
<th>Description</th>
<th>Client name</th>
</tr>
</thead>
<tbody>
<tr>
<td><para>cinder</para></td>
<td><para>Block storage service</para></td>
<td><para>Create and manage volumes.</para></td>
<td><para>python-cinderclient</para></td>
</tr>
<tr>
<td><para>glance</para></td>
<td><para>Image service</para></td>
<td><para>Create and manage images.</para></td>
<td><para>python-glanceclient</para></td>
</tr>
<tr>
<td><para>keystone</para></td>
<td><para>Identity service</para></td>
<td><para>Create and manage users, tenants, roles,
endpoints, and credentials.</para></td>
<td><para>python-keystoneclient</para></td>
</tr>
<tr>
<td><para>nova</para></td>
<td><para>Compute, Compute extensions</para></td>
<td><para>Create and manage instances and flavors.
</para></td>
<td><para>python-novaclient</para></td>
</tr>
<tr>
<td><para>neutron</para></td>
<td><para>Networking</para></td>
<td><para>Configure networks for guest servers. <note>
<para> The <literal>neutron</literal>
client was previously known as
<literal>quantum</literal>. </para>
</note></para></td>
<td><para>python-neutronclient</para></td>
</tr>
<tr>
<td><para>swift</para></td>
<td><para>Object storage</para></td>
<td><para>Gather statistics, list items, update
metadata, upload, download and delete files
stored by the object storage service. Provides
access to a swift installation for ad hoc
processing.</para></td>
<td><para>python-swiftclient</para></td>
</tr>
<tr>
<td><para>heat</para></td>
<td><para>Orchestration</para></td>
<td><para>Launch stacks from templates, view details
of running stacks (including events and
resources), update and delete
stacks.</para></td>
<td><para>python-heatclient</para></td>
</tr>
</tbody>
</table>
<!--<xi:include href="cli_overview.xml"/> -->
<xi:include href="cli_install.xml"/>
<xi:include href="section_cli_openrc.xml"/>
<xi:include href="section_cli_manage_images.xml"/>
<xi:include href="section_cli_launch_instances.xml"/>
<!-- <xi:include href="section_cli_launch_instances.xml"/> -->
<xi:include href="section_cli_configure_instances.xml"/>
<xi:include href="../../cli-guide/src/section_cli_heat.xml"/>
<!--<xi:include href="section_cli_manage_instances.xml"/>
<xi:include href="section_cli_manage_volumes.xml"/>-->
<xi:include href="../../common/nova_cli_boot.xml"/>
<xi:include href="../../common/nova_cli_manage_instances.xml"/>
<xi:include href="section_cli_heat.xml"/>
<xi:include href="section_cli_manage_volumes.xml"/>
</chapter>

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

@ -38,4 +38,13 @@
<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>
<section xml:id="concepts"><title>OpenStack concepts</title>
<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 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>
</preface>

0
doc/src/docbkx/cli-guide/src/cinder_cli_commands.xml → doc/src/docbkx/openstack-user/src/cinder_cli_commands.xml
View File

57
doc/src/docbkx/cli-guide/src/cli_credentials.xml → doc/src/docbkx/openstack-user/src/cli_credentials.xml
View File

@ -1,5 +1,5 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter [
<!DOCTYPE section [
<!-- Some useful entities borrowed from HTML -->
<!ENTITY ndash "&#x2013;">
<!ENTITY mdash "&#x2014;">
@ -26,28 +26,24 @@ format="SVG" scale="60"/>
</imageobject>
</inlinemediaobject>'>
]>
<chapter xmlns="http://docbook.org/ns/docbook"
<section xmlns="http://docbook.org/ns/docbook"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
xml:id="authenticate">
<title>Authenticate</title>
<title>Authentication</title>
<para>To authenticate a tenant to run commands for the OpenStack
clients, you issue an authentication request to the OpenStack
Identity Service v2.0. To issue this request, you must first
set and source environment variables and install the nova
client. Then, you issue an authentication request through the
nova <command>credentials</command> command. </para>
<procedure>
<title>To authenticate:</title>
Identity Service v2.0. To issue this request, you download and
source the <filename>openrc.sh</filename> file to set and
source environment variables. </para>
<xi:include href="../../openstack-user/src/section_cli_openrc.xml"/>
<!--<section xml:id="auth_proc"><title>nova credentials</title>
<procedure>
<title>To authenticate</title>
<step>
<title>Set environment variables</title>
<para>Before you can issue client commands, you must set
environment variables to authenticate. </para>
<para>You can either edit your bash profile to add and set
environment variables or use an
<filename>openrc</filename> file downloaded from
@ -67,7 +63,7 @@ export NOVACLIENT_DEBUG=1
export NOVA_VERSION=2</programlisting>
<para>Or download an <filename>openrc</filename> file from
the OpenStack Dashboard:</para>
<programlisting><?db-font-size 75%?>#!/bin/bash
<screen><computeroutput><?db-font-size 75%?>#!/bin/bash
# With the addition of Keystone, to use an openstack cloud you should
# authenticate against keystone, which returns a **Token** and **Service
@ -90,12 +86,12 @@ export OS_USERNAME=<varname>username</varname>
# With Keystone you pass the keystone password.
echo "Please enter your OpenStack Password: "
read -s OS_PASSWORD_INPUT
export OS_PASSWORD=$OS_PASSWORD_INPUT </programlisting>
export OS_PASSWORD=$OS_PASSWORD_INPUT</computeroutput></screen>
<para>Source the file:</para>
<programlisting><prompt>$</prompt> source openrc.sh </programlisting>
<programlisting><prompt>$</prompt> source openrc.sh</programlisting>
<para>Enter your OpenStack password when prompted.</para>
<para>The following table describes the environment
variables:<table rules="all" width="85%">
variables:<table rules="all" width="85%">
<caption>OpenStack Clients Environment
Variables</caption>
<col width="25%"/>
@ -111,14 +107,14 @@ export OS_PASSWORD=$OS_PASSWORD_INPUT </programlisting>
<td>OS_USERNAME</td>
<td>Your OpenStack username.</td>
</tr>
<!--<tr>
<td>NOVA_RAX_AUTH</td>
<td>Set to <literal>1</literal> to enter
<tr>
<td>NOVA_RAX_AUTH</td>
<td>Set to <literal>1</literal> to enter
your API key instead of your password
in the <command>OS_PASSWORD</command>
variable. </td>
</tr>-->
<tr>
<!-- <tr>
<td>OS_PASSWORD</td>
<td>Your OpenStack user password.</td>
</tr>
@ -148,7 +144,7 @@ export OS_PASSWORD=$OS_PASSWORD_INPUT </programlisting>
error.</para>
</td>
</tr>
<!--<tr>
<tr>
<td>NOVA_SERVICE_NAME</td>
<td>The Cloud service name that you want
the nova client to access. Set to
@ -156,7 +152,7 @@ export OS_PASSWORD=$OS_PASSWORD_INPUT </programlisting>
to access the Cloud Servers
service.</td>
</tr>-->
<tr>
<!-- <tr>
<td>NOVACLIENT_DEBUG</td>
<td>Set to <literal>1</literal> to show
the underlying cURL commands with
@ -184,9 +180,8 @@ export OS_PASSWORD=$OS_PASSWORD_INPUT </programlisting>
your current shell, run the following command:</para>
<programlisting language="bash" role="gutter: false"><prompt>$</prompt> source ~/.bash_profile </programlisting>
</step>
<procedure><title>To authenticate</title>
<step>
<title>Authenticate</title>
<para>To authenticate, you must install the nova client.
To install the nova client, see <xref
linkend="install_clients"/>.</para>
@ -196,7 +191,7 @@ export OS_PASSWORD=$OS_PASSWORD_INPUT </programlisting>
<prompt>$</prompt> nova image-list </programlisting></para>
<para condition="cn">Then, list networks:
<programlisting language="bash" role="gutter: false"><prompt>$</prompt> nova network-list </programlisting></para>
</step>
</step></procedure>-->
<!--<step>
<title>Get help for client commands</title>
<para>To get help for client commands, run the
@ -213,7 +208,7 @@ export OS_PASSWORD=$OS_PASSWORD_INPUT </programlisting>
in the Rackspace Cloud.</para>
</step> -->
<step>
<!-- <procedure><title>To troubleshoot authentication</title> <step>
<title>Troubleshooting</title>
<itemizedlist>
<listitem>
@ -236,12 +231,12 @@ export OS_PASSWORD=$OS_PASSWORD_INPUT </programlisting>
<literal>OS_PASSWORD</literal> setting in
the bash profile by specifying a password on a
nova command, as follows: </para>
<programlisting language="bash" role="gutter: false"><prompt>$</prompt> nova --password &lt;password> image-list </programlisting>
<programlisting language="bash" role="gutter: false"><prompt>$</prompt> nova password &lt;password> image-list </programlisting>
<para>Where <parameter>password</parameter> is
your password.</para>
</listitem>
</itemizedlist>
</step>
</procedure>
</chapter>
</section>-->
</section>

4
doc/src/docbkx/cli-guide/src/cli_help.xml → doc/src/docbkx/openstack-user/src/cli_help.xml
View File

@ -1,5 +1,5 @@
<?xml version="1.0" encoding="UTF-8"?>
<chapter xmlns="http://docbook.org/ns/docbook"
<section xmlns="http://docbook.org/ns/docbook"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
xml:id="cli_help">
@ -39,4 +39,4 @@ Positional arguments:
Optional arguments:
--human-readable Print image size in a human-friendly format.</screen>
</para>
</chapter>
</section>

251
doc/src/docbkx/openstack-user/src/cli_install.xml Normal file
View File

@ -0,0 +1,251 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE section [
<!-- Some useful entities borrowed from HTML -->
<!ENTITY ndash "&#x2013;">
<!ENTITY mdash "&#x2014;">
<!ENTITY hellip "&#x2026;">
<!ENTITY plusmn "&#xB1;">
<!-- Useful for describing APIs -->
<!ENTITY GET '<command xmlns="http://docbook.org/ns/docbook">GET</command>'>
<!ENTITY PUT '<command xmlns="http://docbook.org/ns/docbook">PUT</command>'>
<!ENTITY POST '<command xmlns="http://docbook.org/ns/docbook">POST</command>'>
<!ENTITY DELETE '<command xmlns="http://docbook.org/ns/docbook">DELETE</command>'>
<!ENTITY CHECK '<inlinemediaobject xmlns="http://docbook.org/ns/docbook">
<imageobject>
<imagedata fileref="figures/Check_mark_23x20_02.svg"
format="SVG" scale="60"/>
</imageobject>
</inlinemediaobject>'>
<!ENTITY ARROW '<inlinemediaobject xmlns="http://docbook.org/ns/docbook">
<imageobject>
<imagedata fileref="figures/Arrow_east.svg"
format="SVG" scale="60"/>
</imageobject>
</inlinemediaobject>'>
]>
<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="install_clients">
<title>Install the command-line clients</title>
<para>To manage your servers, images, volumes, isolated networks,
and other cloud resources from the command line, install and
use the OpenStack clients. </para>
<para>To install the clients, install prerequisite software and
the Python package for each OpenStack client. </para>
<!-- <xi:include href="../../openstack-user/src/cli_overview.xml"/> -->
<section xml:id="prereq_software">
<title>Before you begin</title>
<para>Before you begin, install the following prerequisite
software:</para>
<table rules="all" width="85%">
<caption>OpenStack Clients prerequisite software</caption>
<thead>
<tr>
<th>Prerequisite</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td valign="top">
<para>Python 2.6 or later</para>
</td>
<td>
<para>Currently, the clients do not support
Python 3. </para>
</td>
</tr>
<tr>
<td valign="top">
<para><command>setuptools</command> package
</para>
</td>
<td>
<para>Installed by default on Mac OS X. </para>
<para>Many Linux distributions provide
packages to make
<command>setuptools</command> easy to
install.</para>
<para>Search your package manager for
<command>setuptools</command> to find
an installation package. If you cannot
find one, download the
<command>setuptools</command> package
directly from <link
xlink:href="http://pypi.python.org/pypi/setuptools"
>http://pypi.python.org/pypi/setuptools</link>.
</para>
</td>
</tr>
<tr>
<td valign="top"><command>pip</command>
package</td>
<td>
<para>To install the clients on a Mac OS X or
Linux system, use <command>pip</command>.
It is easy to use and ensures that you get
the latest version of the clients from the
<link
xlink:href="http://pypi.python.org/pypi/python-novaclient/"
>Python Package Index</link>. Also, it
lets you update or remove the packages
later on.</para>
<para>Install <command>pip</command> through
the package manager for your
system:</para><itemizedlist>
<listitem>
<para>Mac OS X
<screen><prompt>$</prompt> <userinput>sudo easy_install pip</userinput></screen></para>
</listitem>
<listitem>
<para>Ubuntu 12.04</para>
<para>A packaged version enables you
to use <command>dpkg</command> or
<command>aptitude</command> to
install the
python-novaclient.</para>
<screen><prompt>#</prompt> aptitude install python-novaclient</screen>
</listitem>
<listitem>
<para>Ubuntu
<screen><prompt>#</prompt> aptitude install python-pip</screen></para>
</listitem>
<listitem>
<para>RHEL, CentOS, or Fedora</para>
<para> A packaged version available in
<link
xlink:href="http://openstack.redhat.com/"
>RDO</link> enables you to use
<command>yum</command> to install
the clients:
<screen><prompt>#</prompt> yum install python-<replaceable>PROJECT</replaceable>client</screen>
Replace
<replaceable>PROJECT</replaceable>
with the lower case name of the
client to install, such as
<literal>nova</literal>. Repeat
this step for each desired client. </para>
<para> Alternatively install
<command>pip</command> and use it
to manage client installation:
<screen><prompt>#</prompt> yum install python-pip</screen>
</para>
</listitem>
<listitem>
<para>openSUSE 12.2 and earlier</para>
<para>A <link
xlink:href="https://build.opensuse.org/package/show?package=python-novaclient&amp;project=Cloud:OpenStack:Master"
>packaged version available in the
Open Build Service</link> enables
you to use <command>rpm</command>
or <command>zypper</command> to
install the the python-novaclient.
<screen><prompt>#</prompt> zypper install python-<replaceable>PROJECT</replaceable></screen>
Replace
<replaceable>PROJECT</replaceable>
with the lower case name of the
client to install, such as
<literal>nova</literal>. Repeat
this step for each desired client. </para>
<para> Alternatively install
<command>pip</command> and use it
to manage client installation:
<screen><prompt>#</prompt> zypper install python-pip </screen></para>
</listitem>
<listitem>
<para>openSUSE 12.3</para>
<para>A packaged version enables you
to use <command>rpm</command> or
<command>zypper</command> to
install the clients:
<screen><prompt>#</prompt> zypper install python-<replaceable>PROJECT</replaceable>client</screen>
Replace
<replaceable>PROJECT</replaceable>
with the lower case name of the
client to install, such as
<literal>nova</literal>. Repeat
this step for each desired client.
</para>
</listitem>
</itemizedlist>
</td>
</tr>
</tbody>
</table>
</section>
<section xml:id="install-clients">
<title>Install the clients</title>
<para>Use <command>pip</command> to install the OpenStack
clients on a Mac OS X or Linux system. It is easy and
ensures that you get the latest version of the client from
the <link xlink:href="http://pypi.python.org/pypi">Python
Package Index</link>. Also, <command>pip</command>
lets you update or remove a package. </para>
<note>
<para>If you already installed the OpenStack client
packages using the package management tools provided
by your distribution, these steps are not required.
</para>
</note>
<procedure>
<title>To install the OpenStack clients</title>
<step>
<para>You must install each client separately.</para>
<para>Run the following command to install or update a
client package:</para>
<screen><prompt>$</prompt> <userinput>sudo pip install [--update] python-&lt;project&gt;client</userinput></screen>
<para>Where &lt;project&gt; is the project name and has
one of the following values:</para>
<itemizedlist>
<listitem>
<para><literal>nova</literal>. Compute
API and extensions.</para>
</listitem>
<listitem>
<para><literal>neutron</literal>. Networking
API.</para>
</listitem>
<listitem>
<para><literal>keystone</literal>. Identity
Service API.</para>
</listitem>
<listitem>
<para><literal>glance</literal>. Image Service
API.</para>
</listitem>
<listitem>
<para><literal>swift</literal>. Object Storage
API.</para>
</listitem>
<listitem>
<para><literal>cinder</literal>. Block Storage Service
API.</para>
</listitem>
<listitem>
<para><literal>heat</literal>. Orchestration
API.</para>
</listitem>
</itemizedlist>
<para>For example, to install the nova client, run the
following command:</para>
<screen><prompt>$</prompt> <userinput>sudo pip install python-novaclient</userinput></screen>
<para>To update the nova client, run the following
command:</para>
<screen><prompt>$</prompt> <userinput>sudo pip install --upgrade python-novaclient</userinput></screen>
<para>To remove the nova client, run the following
command:</para>
<screen><prompt>$</prompt> <userinput>sudo pip uninstall python-novaclient</userinput></screen>
</step>
<step>
<para>Before you can issue client commands, you must
source the <filename>openrc</filename> file to set
environment variables. See <xref linkend="cli_openrc"/>.</para>
</step>
</procedure>
</section>
</section>

121
doc/src/docbkx/openstack-user/src/cli_overview.xml Normal file
View File

@ -0,0 +1,121 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE section [
<!-- Some useful entities borrowed from HTML -->
<!ENTITY ndash "&#x2013;">
<!ENTITY mdash "&#x2014;">
<!ENTITY hellip "&#x2026;">
<!ENTITY plusmn "&#xB1;">
<!-- Useful for describing APIs -->
<!ENTITY GET '<command xmlns="http://docbook.org/ns/docbook">GET</command>'>
<!ENTITY PUT '<command xmlns="http://docbook.org/ns/docbook">PUT</command>'>
<!ENTITY POST '<command xmlns="http://docbook.org/ns/docbook">POST</command>'>
<!ENTITY DELETE '<command xmlns="http://docbook.org/ns/docbook">DELETE</command>'>
<!ENTITY CHECK '<inlinemediaobject xmlns="http://docbook.org/ns/docbook">
<imageobject>
<imagedata fileref="figures/Check_mark_23x20_02.svg"
format="SVG" scale="60"/>
</imageobject>
</inlinemediaobject>'>
<!ENTITY CLIall 'command-line interface (CLI)'>
<!ENTITY CLIallp 'command-line interfaces (CLIs)'>
<!ENTITY ARROW '<inlinemediaobject xmlns="http://docbook.org/ns/docbook">
<imageobject>
<imagedata fileref="figures/Arrow_east.svg"
format="SVG" scale="60"/>
</imageobject>
</inlinemediaobject>'>
]>
<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="client_overview">
<title>Overview</title>
<para>The OpenStack command-line clients let you run simple
commands to make OpenStack API calls. These open-source Python
clients are easy to learn and use. </para>
<para>The OpenStack APIs are RESTful APIs that use the HTTP
protocol, including methods, URIs, media types, and response
codes. Internally, each client command runs cURL commands that
embed API requests. </para>
<para>To install an OpenStack client, see <xref
linkend="install_clients"/>.</para>
<para>To request OpenStack services through either the clients or
the APIs directly, you must source an
<filename>openrc</filename> file to set required
environment variables.</para>
<note>
<para>An OpenStack common client is in development.</para>
</note>
<para>The following command-line clients are available for the
respective services' APIs:</para>
<table rules="all" width="100%">
<caption>OpenStack clients</caption>
<thead>
<tr>
<th>Client</th>
<th>Associated service API</th>
<th>Description</th>
<th>Client name</th>
</tr>
</thead>
<tbody>
<tr>
<td><para>cinder</para></td>
<td><para>Block storage service</para></td>
<td><para>Create and manage volumes.</para></td>
<td><para>python-cinderclient</para></td>
</tr>
<tr>
<td><para>glance</para></td>
<td><para>Image service</para></td>
<td><para>Create and manage images.</para></td>
<td><para>python-glanceclient</para></td>
</tr>
<tr>
<td><para>keystone</para></td>
<td><para>Identity service</para></td>
<td><para>Create and manage users, tenants, roles,
endpoints, and credentials.</para></td>
<td><para>python-keystoneclient</para></td>
</tr>
<tr>
<td><para>nova</para></td>
<td><para>Compute, Compute extensions</para></td>
<td><para>Create and manage instances and flavors.
</para></td>
<td><para>python-novaclient</para></td>
</tr>
<tr>
<td><para>neutron</para></td>
<td><para>Networking</para></td>
<td><para>Configure networks for guest servers. <note>
<para> The <literal>neutron</literal>
client was previously known as
<literal>quantum</literal>. </para>
</note></para></td>
<td><para>python-neutronclient</para></td>
</tr>
<tr>
<td><para>swift</para></td>
<td><para>Object storage</para></td>
<td><para>Gather statistics, list items, update
metadata, upload, download and delete files
stored by the object storage service. Provides
access to a swift installation for ad hoc
processing.</para></td>
<td><para>python-swiftclient</para></td>
</tr>
<tr>
<td><para>heat</para></td>
<td><para>Orchestration</para></td>
<td><para>Launch stacks from templates, view details
of running stacks (including events and
resources), update and delete
stacks.</para></td>
<td><para>python-heatclient</para></td>
</tr>
</tbody>
</table>
</section>

4
doc/src/docbkx/cli-guide/src/cli_version.xml → doc/src/docbkx/openstack-user/src/cli_version.xml
View File

@ -1,5 +1,5 @@
<?xml version="1.0" encoding="UTF-8"?>
<chapter xmlns="http://docbook.org/ns/docbook"
<section xmlns="http://docbook.org/ns/docbook"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
xml:id="checking_version_cli">
@ -17,4 +17,4 @@ python-swiftclient==1.1.1</programlisting>
<programlisting language="bash" role="gutter: false"><prompt>$</prompt>yolk -l | grep python-novaclient</programlisting>
<programlisting language="bash" role="gutter: false">python-novaclient - 2.6.10.27 - active development (/Users/your.name/src/cloud-servers/src/src/python-novaclient)
python-novaclient - 2012.1 - non-active </programlisting>
</chapter>
</section>

0
doc/src/docbkx/cli-guide/src/glance_cli_commands.xml → doc/src/docbkx/openstack-user/src/glance_cli_commands.xml
View File

0
doc/src/docbkx/cli-guide/src/heat_cli_commands.xml → doc/src/docbkx/openstack-user/src/heat_cli_commands.xml
View File

0
doc/src/docbkx/cli-guide/src/keystone_cli_commands.xml → doc/src/docbkx/openstack-user/src/keystone_cli_commands.xml
View File

59
doc/src/docbkx/cli-guide/src/neutron_cli_commands.xml → doc/src/docbkx/openstack-user/src/neutron_cli_commands.xml Normal file → Executable file
View File

@ -1,11 +1,55 @@
<?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="neutron_client_commands">
<title>neutron commands</title>
<literallayout class="monospaced">
agent-delete Delete a given agent.
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
xml:id="neutron_client_commands">
<title>neutron commands</title>
<para>Describes the commands for neutron, which is the command-line
interface for the OpenStack Networking API.</para>
<para>For help on a specific neutron command, enter:</para>
<screen><userinput><command>neutron</command> <option>help</option> <replaceable>COMMAND</replaceable></userinput></screen>
<example>
<title>Usage</title>
<screen><computeroutput>neutron [--version] [-v] [-q] [-h] [--debug]
[--os-auth-strategy &lt;auth-strategy>] [--os-auth-url &lt;auth-url>]
[--os-tenant-name &lt;auth-tenant-name>]
[--os-username &lt;auth-username>] [--os-password &lt;auth-password>]
[--os-region-name &lt;auth-region-name>] [--os-token &lt;token>]
[--endpoint-type &lt;endpoint-type>] [--os-url &lt;url>] [--insecure]</computeroutput></screen>
</example>
<example>
<title>Optional arguments</title>
<screen><computeroutput> --version show program's version number and exit
-v, --verbose Increase verbosity of output. Can be repeated.
-q, --quiet suppress output except warnings and errors
-h, --help show this help message and exit
--debug show tracebacks on errors
--os-auth-strategy &lt;auth-strategy>
Authentication strategy (Env: OS_AUTH_STRATEGY,
default keystone). For now, any other value will
disable the authentication
--os-auth-url &lt;auth-url>
Authentication URL (Env: OS_AUTH_URL)
--os-tenant-name &lt;auth-tenant-name>
Authentication tenant name (Env: OS_TENANT_NAME)
--os-username &lt;auth-username>
Authentication username (Env: OS_USERNAME)
--os-password &lt;auth-password>
Authentication password (Env: OS_PASSWORD)
--os-region-name &lt;auth-region-name>
Authentication region name (Env: OS_REGION_NAME)
--os-token &lt;token> Defaults to env[OS_TOKEN]
--endpoint-type &lt;endpoint-type>
Defaults to env[OS_ENDPOINT_TYPE] or publicURL.
--os-url &lt;url> Defaults to env[OS_URL]
--insecure Explicitly allow quantumclient to perform "insecure"
SSL (https) requests. The server's certificate will
not be verified against any certificate authorities.
This option should be used with caution.</computeroutput></screen>
</example>
<example>
<title>Commands</title>
<screen><computeroutput> agent-delete Delete a given agent.
agent-list List agents.
agent-show Show information of a given agent.
agent-update Update a given agent.
@ -98,5 +142,6 @@
subnet-delete Delete a given subnet.
subnet-list List networks that belong to a given tenant.
subnet-show Show information of a given subnet.
subnet-update Update subnet's information.</literallayout>
subnet-update Update subnet's information.</computeroutput></screen>
</example>
</section>

0
doc/src/docbkx/cli-guide/src/nova_cli_commands.xml → doc/src/docbkx/openstack-user/src/nova_cli_commands.xml
View File

450
doc/src/docbkx/openstack-user/src/section_cli_configure_instances.xml
View File

@ -1,145 +1,120 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE section [
<!-- Some useful entities borrowed from HTML -->
<!ENTITY ndash "&#x2013;">
<!ENTITY mdash "&#x2014;">
<!ENTITY hellip "&#x2026;">
<!-- Useful for describing APIs -->
<!ENTITY GET '<command xmlns="http://docbook.org/ns/docbook">GET</command>'>
<!ENTITY PUT '<command xmlns="http://docbook.org/ns/docbook">PUT</command>'>
<!ENTITY POST '<command xmlns="http://docbook.org/ns/docbook">POST</command>'>
<!ENTITY DELETE '<command xmlns="http://docbook.org/ns/docbook">DELETE</command>'>
]>
<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="cli_configure_instances">
<title>Configure access to instances</title>
<para>The following parameters influence access to an
instance:</para>
<itemizedlist>
<listitem>
<para><emphasis role="bold">Keypairs</emphasis>. 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. For SSH access to
an instance, you usually provide a keypair at launch
time. </para>
<para>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. In case an image uses a static root
password or a static key set (neither is recommended),
you do not must provide a keypair on starting of the
instance. </para>
</listitem>
<listitem>
<para><emphasis role="bold">Security group</emphasis>.
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>. The security rules need
adjustment, because the default rules block access to
SSH ports and prevent pinging an instance. You manage
security groups with the <command>nova
secgroup-*</command> commands, provided by the
<literal>python-novaclient</literal>
package.</para>
</listitem>
<listitem>
<para>Security Group Rules. You can adjust rules of the
default security group as well as rules of any other
security group that has been created. </para>
<para>As soon as the rules for a group are modified, the
new rules are automatically applied to all running
instances belonging to that security group. </para>
<para>Adjust the rules in a security group to allow access
to instances via different ports and protocols. This
is necessary to be able to access instances via SSH,
to ping them, or to allow UDP traffic (for example,
for a DNS server running on an instance). </para>
<para>Rules in security groups are specified by the
following parameters: </para>
<para>
<itemizedlist>
<listitem>
<para><emphasis role="bold">Source of
traffic</emphasis> Decide whether to
allow traffic to instances only from IP
addresses inside the cloud (from other
group members) or from all IP addresses.
</para>
</listitem>
<listitem>
<para><emphasis role="bold"
>Protocol</emphasis> Choose between
TCP (for SSH), ICMP (for pings), and UDP.
</para>
</listitem>
<listitem>
<para><emphasis role="bold">Destination Port
on Virtual Machine</emphasis> Define a
port range. To open a single port only,
enter the same value twice. ICMP does not
support ports. In that case, enter values
that define the codes and types of ICMP
traffic to be allowed. </para>
</listitem>
</itemizedlist>
</para>
<para>If no further security groups have been created, any
instances are automatically assigned to the default
security group (if not specified otherwise). </para>
<para>Unless you change the rules for the default group,
those instances cannot be accessed from any IP
addresses outside the cloud. </para>
</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. For details, see
Section 1.5.3, Managing IP Addresses and Section 1.7,
Managing Volumes.</para>
</listitem>
</itemizedlist>
<title>Set up access and security for instances</title>
<para>When you launch a virtual machine, you can inject a
<emphasis role="italic">keypair</emphasis>, which provides
SSH access to your instance. For this to work, the image must
contain the <literal>cloud-init</literal> package. Create at
least one keypair for each project. If you generate 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. In case an image uses a static root password or a
static key set &ndash; neither is recommended &ndash; you must
not provide a keypair when you launch the instance. </para>
<para>A <emphasis role="italic">security group</emphasis> is a
named collection of network access rules that you use to limit
the types of traffic that have access to instances. When you
launch an instance, you can assign one or more security groups
to it. If you do not create security groups, new instances are
automatically assigned to the default security group, unless
you explicitly specify a different security group. The
associated <emphasis role="italic">rules</emphasis> in each
security group control the traffic to instances in the group.
Any incoming traffic that is not matched by a rule is denied
access by default. You can add rules to or remove rules from a
security group. You can modify rules for the default and any
other security group. </para>
<para>You must modify the rules for the default security group
because users cannot access instances that use the default
group from any IP address outside the cloud. </para>
<para>You can modify the rules in a security group to allow access
to instances through different ports and protocols. For
example, you can modify rules to allow access to instances
through SSH, to ping them, or to allow UDP traffic &ndash; for
example, for a DNS server running on an instance. You specify
the following parameters for rules: </para>
<itemizedlist>
<listitem>
<para><emphasis role="bold">Floating IP
address</emphasis>. To make the instance also
accessible from outside the cloud, assign a floating
(public) IP address.</para>
<para><emphasis role="bold">Source of traffic</emphasis>.
Enable traffic to instances from either IP addresses
inside the cloud from other group members or from all
IP addresses. </para>
</listitem>
<listitem>
<para><emphasis role="bold">Protocol</emphasis>. Choose
TCP for SSH, ICMP for pings, or UDP. </para>
</listitem>
<listitem>
<para><emphasis role="bold">Destination port on virtual
machine</emphasis>. Defines a port range. To open
a single port only, enter the same value twice. ICMP
does not support ports: Enter values to define the
codes and types of ICMP traffic to be allowed. </para>
</listitem>
</itemizedlist>
<para>Rules are automatically enforced as soon as you create or
modify them.</para>
<para>You can also assign a floating IP address to a running
instance to make it accessible from outside the cloud. You
assign a floating IP address to an instance and attach a block
storage device, or volume, for persistent storage. See <xref
linkend="manage_ip_addresses"/>.</para>
<section xml:id="create_import_keys">
<title>Create or import keys</title>
<title>Add or import keypairs</title>
<procedure>
<title>To create or import keys:</title>
<para>Use the <command>nova keypair-add</command> command
to generate a keypair or upload an existing public
key. </para>
<title>To add or import keys</title>
<para>You can generate a keypair or upload an existing
public key. </para>
<step>
<para>To generate a keypair, run the following
command:</para>
<programlisting language="bash" role="gutter: false"><prompt>$</prompt> nova keypair-add KEY_NAME > MY_KEY.pem</programlisting>
<para>The command generates a keypair named KEY_NAME,
writing the private key to the file MY_KEY.pem and
registering the public key at the Nova database. </para>
<para>To set the permissions of the
<filename>MY_KEY.pem</filename> file, run the
following command:</para>
<programlisting language="bash" role="gutter: false"><prompt>$</prompt> chmod 600 MY_KEY.pem</programlisting>
<para>The command changes the permissions of the
<filename>MY_KEY.pem</filename> file so that
only you can read and write to it.</para>
<screen><prompt>$</prompt> <userinput>nova keypair-add KEY_NAME > MY_KEY.pem</userinput></screen>
<para>The command generates a keypair named
<replaceable>KEY_NAME</replaceable>, writes
the private key to the
<filename><replaceable>MY_KEY</replaceable>.pem</filename>
file, and registers the public key at the Nova
database. </para>
</step>
<step>
<para>If you have already generated a keypair, with
the public key located at
<filename>~/.ssh/id_rsa.pub</filename>, you
can upload the public key with the following
command:</para>
<programlisting language="bash" role="gutter: false"><prompt>$</prompt> nova keypair-add --pub_key ~/.ssh/id_rsa.pub KEY_NAME</programlisting>
<para>To set the permissions of the
<filename><replaceable>MY_KEY</replaceable>.pem</filename>
file, run the following command:</para>
<screen><prompt>$</prompt> <userinput>chmod 600 MY_KEY.pem</userinput></screen>
<para>The command changes the permissions of the
<filename><replaceable>MY_KEY</replaceable>.pem</filename>
file so that only you can read and write to
it.</para>
</step>
<step>
<para>If you have already generated a keypair with the
public key located at
<filename>~/.ssh/id_rsa.pub</filename>, run
the following command to upload the public
key:</para>
<screen><prompt>$</prompt> <userinput>nova keypair-add --pub_key ~/.ssh/id_rsa.pub KEY_NAME</userinput></screen>
<para>The command registers the public key at the Nova
database and names the keypair
<literal>KEY_NAME</literal>.</para>
<literal><replaceable>KEY_NAME</replaceable></literal>.</para>
</step>
<step>
<para>Check if the uploaded keypair appears in the
list of available keypairs:</para>
<programlisting language="bash" role="gutter: false"><prompt>$</prompt> nova keypair-list</programlisting>
<para>List keypairs to make sure that the uploaded
keypair appears in the list:</para>
<screen><prompt>$</prompt> <userinput>nova keypair-list</userinput></screen>
</step>
</procedure>
@ -148,80 +123,82 @@
</section>
<section xml:id="configure_security_groups_rules">
<title>Configure security groups and rules</title>
<procedure>
<title>To list security groups:</title>
<title>To list security groups</title>
<step>
<programlisting language="bash" role="gutter: false"><prompt>$</prompt> nova secgroup-list</programlisting>
<para>Lists all security groups for the current
project, including the groups'
descriptions.</para>
</step>
</procedure>
<procedure>
<title>To create a security group:</title>
<step>
<programlisting language="bash" role="gutter: false"><prompt>$</prompt> nova secgroup-create SEC_GROUP_NAME GROUP_DESCRIPTION</programlisting>
<para>Creates a new security group with the specified
name and description. </para>
<para>To list all security groups for the current
project, including descriptions, enter the
following command:</para>
<screen><prompt>$</prompt> <userinput>nova secgroup-list</userinput></screen>
</step>
</procedure>
<procedure>
<title>To delete a security group:</title>
<title>To create a security group</title>
<step>
<programlisting language="bash" role="gutter: false"><prompt>$</prompt> nova secgroup-delete SEC_GROUP_NAME </programlisting>
<para>Deletes the specified group.</para>
<para>To create a security group with a specified name
and description, enter the following
command:</para>
<screen><prompt>$</prompt> <userinput>nova secgroup-create SEC_GROUP_NAME GROUP_DESCRIPTION</userinput></screen>
</step>
</procedure>
<procedure>
<title>To delete a security group</title>
<step>
<para>To delete a specified group, enter the following
command:</para>
<screen><prompt>$</prompt> <userinput>nova secgroup-delete SEC_GROUP_NAME </userinput></screen>
<note>
<title>Deleting Security Groups</title>
<para>The default security group for a project
cannot be deleted. If another group cannot be
deleted, it is because it is still assigned to
a running instance.</para>
<para>You cannot delete the default security group
for a project. Also, you cannot delete a
security group that is assigned to a running
instance. </para>
</note>
</step>
</procedure>
<procedure>
<title>To configure security group rules:</title>
<para>Modify security group rules with the nova
secgroup-*-rule commands. Proceed as follows: </para>
<title>To configure security group rules</title>
<para>Modify security group rules with the <command>nova
secgroup-*-rule</command> commands. </para>
<step>
<para>On a shell, source the OpenStack RC file. For
details, see <xref linkend="cli_openrc"/>.</para>
</step>
<step>
<para>Look up the existing rules for a security group:
<programlisting language="bash" role="gutter: false"><prompt>$</prompt> nova secgroup-list-rules SEC_GROUP_NAME</programlisting></para>
<para>List the existing rules for a security group:
<screen><prompt>$</prompt> <userinput>nova secgroup-list-rules SEC_GROUP_NAME</userinput></screen></para>
</step>
<step>
<para>To allow SSH access to the instances:</para>
<para>To allow SSH access to the instances, choose one
of the following sub-steps:</para>
<substeps>
<step>
<step xml:id="sec_group_rule_add">
<title>Add rule for all IP addresses</title>
<para>Either from all IP addresses (specified
as IP subnet in CIDR notation as
0.0.0.0/0):</para>
<programlisting language="bash" role="gutter: false"><prompt>$</prompt> nova secgroup-add-rule SEC_GROUP_NAME tcp 22 22 0.0.0.0/0</programlisting>
<screen><prompt>$</prompt> <userinput>nova secgroup-add-rule SEC_GROUP_NAME tcp 22 22 0.0.0.0/0</userinput></screen>
</step>
<step>
<step xml:id="sec_group_rule_add_alt">
<title>Add rule for other security
groups</title>
<para>Alternatively, you can allow only IP
addresses from other security groups
(source groups) to access the specified
port: </para>
<programlisting language="bash" role="gutter: false"><prompt>$</prompt> nova secgroup-add-group-rule --ip_proto tcp --from_port 22 \
--to_port 22 SEC_GROUP_NAME SOURCE_GROUP_NAME</programlisting>
<screen><prompt>$</prompt> <userinput>nova secgroup-add-group-rule --ip_proto tcp --from_port 22 \
--to_port 22 SEC_GROUP_NAME SOURCE_GROUP_NAME</userinput></screen>
</step>
</substeps>
</step>
<step>
<para>To allow pinging the instances:</para>
<para>To allow pinging the instances, choose from one
of the following sub-steps:</para>
<substeps>
<step>
<para>Either from all IP addresses (specified
as IP subnet in CIDR notation as
0.0.0.0/0):</para>
<programlisting language="bash" role="gutter: false"><prompt>$</prompt> nova secgroup-add-rule SEC_GROUP_NAME icmp -1 -1 0.0.0.0/0</programlisting>
<screen><prompt>$</prompt> <userinput>nova secgroup-add-rule SEC_GROUP_NAME icmp -1 -1 0.0.0.0/0</userinput></screen>
<para>This command allows access to all codes
and all types of ICMP traffic,
respectively.</para>
@ -230,165 +207,46 @@
<para>Alternatively, you can allow only
members of other security groups (source
groups) to ping instances:</para>
<programlisting language="bash" role="gutter: false"><prompt>$</prompt> nova secgroup-add-group-rule --ip_proto icmp --from_port -1 \
--to_port -1 SEC_GROUP_NAME SOURCE_GROUP_NAME</programlisting>
<screen><prompt>$</prompt> <userinput>nova secgroup-add-group-rule --ip_proto icmp --from_port -1 \
--to_port -1 SEC_GROUP_NAME SOURCE_GROUP_NAME</userinput></screen>
</step>
</substeps>
</step>
<step>
<para>To allow access through UDP port (for example,
for a DNS server running on a VM):</para>
<para>To allow access through UDP port, such as
allowing access to a DNS server that runs on a VM,
complete one of the following sub-steps:</para>
<substeps>
<step>
<para>Either from all IP addresses (specified
as IP subnet in CIDR notation as
0.0.0.0/0):
<programlisting language="bash" role="gutter: false"><prompt>$</prompt> nova secgroup-add-rule SEC_GROUP_NAME udp 53 53 0.0.0.0/0</programlisting></para>
<screen><prompt>$</prompt> <userinput>nova secgroup-add-rule SEC_GROUP_NAME udp 53 53 0.0.0.0/0</userinput></screen></para>
</step>
<step>
<para>Alternatively, you can allow only IP
addresses from other security groups
(source groups) to access the specified
port:
<programlisting language="bash" role="gutter: false"><prompt>$</prompt> nova secgroup-add-group-rule --ip_proto udp --from_port 53 \
--to_port 53 SEC_GROUP_NAME SOURCE_GROUP_NAME</programlisting></para>
<screen><prompt>$</prompt> <userinput>nova secgroup-add-group-rule --ip_proto udp --from_port 53 \
--to_port 53 SEC_GROUP_NAME SOURCE_GROUP_NAME</userinput></screen></para>
</step>
</substeps>
</step>
<step>
<para>To delete security group rules, you must specify
the same arguments that you used to create the
rule. For example: To delete the security rule
that you created in Step 3.a: </para>
<programlisting language="bash" role="gutter: false"><prompt>$</prompt> nova secgroup-delete-rule SEC_GROUP_NAME tcp 22 22 0.0.0.0/0</programlisting>
rule.</para>
<para>To delete the security rule that you created in
Step 3.b:</para>
<programlisting language="bash" role="gutter: false"><prompt>$</prompt> nova secgroup-delete-group-rule --ip_proto tcp --from_port 22 \
--to_port 22 SEC_GROUP_NAME SOURCE_GROUP_NAME</programlisting>
</step>
</procedure>
</section>
<section xml:id="manage_ip_addresses">
<title>Manage IP addresses</title>
<para>Each instance can have two IP addresses: a private
(fixed) IP address and a public (floating) one. </para>
<para>Private IP addresses are used for communication between
instances, and public ones are used for communication with
the outside world. </para>
<para>When an instance is launched, it is automatically
assigned a private IP address, which stays the same until
the instance is explicitly terminated. (Rebooting the
instance does not have an effect on the private IP
address.) </para>
<para>A pool of floating IPs is available in OpenStack Nova,
as configured by the cloud operator. </para>
<para>You can allocate a certain number of these to a
project—the maximum number of floating IP addresses per
project is defined by the quota. </para>
<para>From this set, you can then add a floating IP address to
an instance of the project. Floating IP addresses can be
dynamically disassociated and associated with other
instances of the same project at any time. </para>
<para>Before you can assign a floating IP address to an
instance, you first must allocate floating IPs to a
project. After floating IP addresses have been allocated
to the current project, you can assign them to running
instances. </para>
<para>One floating IP address can be assigned to only one
instance at a time. Floating IP addresses can be managed
with the <command>nova *floating-ip-*</command> commands,
provided by the python-novaclient package.</para>
<procedure>
<title>To list pools with floating IP addresses:</title>
<step>
<programlisting language="bash" role="gutter: false"><prompt>$</prompt> nova floating-ip-pool-list</programlisting>
<para>Lists the name of all pools that provide
floating IP addresses. </para>
</step>
</procedure>
<procedure>
<title>To allocate a floating IP address to the current
project:</title>
<step>
<programlisting language="bash" role="gutter: false"><prompt>$</prompt> nova floating-ip-pool-list</programlisting>
<para>The output of the command shows the freshly
allocated IP address. If there is more than one
pool of IP addresses available, you can also
specify the pool from which to allocate the IP
address (optional):</para>
<programlisting language="bash" role="gutter: false"><prompt>$</prompt> floating-ip-create POOL_NAME</programlisting>
</step>
</procedure>
<procedure>
<title>To list floating IP addresses allocated to the
current project:</title>
<step>
<programlisting language="bash" role="gutter: false"><prompt>$</prompt> nova floating-ip-list</programlisting>
<para>Lists all floating IP addresses that have been
allocated to the current project. If an IP is
already associated with an instance, the output
also shows the instance's IP, the instance's fixed
IP address and the name of the pool that provides
the floating IP address.</para>
</step>
</procedure>
<procedure>
<title>To release a floating IP address from the current
project:</title>
<step>
<programlisting language="bash" role="gutter: false"><prompt>$</prompt> nova floating-ip-delete FLOATING_IP </programlisting>
<para>The IP address is put back into the pool of IP
addresses that are available for all projects. If
an IP address is currently assigned to a running
instance, it will automatically be disassociated
from the instance.</para>
</step>
</procedure>
<procedure>
<title>To assign a floating IP address to an
instance:</title>
<step>
<programlisting language="bash" role="gutter: false"><prompt>$</prompt> nova add-floating-ip INSTANCE_NAME_OR_ID FLOATING_IP </programlisting>
<para>To associate an IP address with an instance, one
or multiple floating IP addresses must be
allocated to the current project. Check this
with:<programlisting language="bash" role="gutter: false"><prompt>$</prompt> nova floating-ip-list</programlisting>In
addition, you must know the instance's name (or
ID). To look up the instances that belong to the
current project, use the <code>nova list</code>
command. </para>
<para>After you assign the IP with <command>nova
add-floating-ip</command>, the instance is now
publicly available under the respective floating
IP address (provided you have also configured the
security group rules for the instance
accordingly). For details, see <xref
linkend="configure_security_groups_rules"
/>.</para>
</step>
</procedure>
<procedure>
<title>To remove a floating IP address from an
instance:</title>
<step>
<programlisting language="bash" role="gutter: false"><prompt>$</prompt> nova remove-floating-ip INSTANCE_NAME_OR_ID FLOATING_IP </programlisting>
<para>To remove a floating IP address from an
instance, you must specify the same arguments that
you used to assign the IP.</para>
<xref linkend="sec_group_rule_add"/>: </para>
<screen><prompt>$</prompt> <userinput>nova secgroup-delete-rule SEC_GROUP_NAME tcp 22 22 0.0.0.0/0</userinput></screen>
<para>To delete the security rule that you created in
<xref linkend="sec_group_rule_add_alt"
/>:</para>
<screen><prompt>$</prompt> <userinput>nova secgroup-delete-group-rule --ip_proto tcp --from_port 22 \
--to_port 22 SEC_GROUP_NAME SOURCE_GROUP_NAME</userinput></screen>
</step>
</procedure>
</section>
</section>

106
doc/src/docbkx/openstack-user/src/section_cli_floating_ips.xml Normal file
View File

@ -0,0 +1,106 @@
<?xml version="1.0" encoding="UTF-8"?>
<section xml:id="manage_ip_addresses"
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>Manage IP addresses</title>
<para>Each instance can have a private, or fixed, IP address and a
public, or floating, one. </para>
<para>Private IP addresses are used for communication between
instances, and public ones are used for communication with the
outside world. </para>
<para>When you launch an instance, it is automatically assigned a
private IP address that stays the same until you explicitly
terminate the instance. Rebooting an instance has no effect on
the private IP address.</para>
<para>A pool of floating IPs, configured by the cloud operator, is
available in OpenStack Compute. </para>
<para>You can allocate a certain number of these to a project: The
maximum number of floating IP addresses per project is defined
by the quota. </para>
<para>You can add a floating IP address from this set to an
instance of the project. Floating IP addresses can be
dynamically disassociated and associated with other instances
of the same project at any time. </para>
<para>Before you can assign a floating IP address to an instance,
you first must allocate floating IPs to a project. After
floating IP addresses have been allocated to the current
project, you can assign them to running instances. </para>
<para>One floating IP address can be assigned to only one instance
at a time. Floating IP addresses can be managed with the
<command>nova *floating-ip-*</command> commands, provided
by the python-novaclient package.</para>
<procedure>
<title>To list pools with floating IP addresses</title>
<step>
<para>To list all pools that provide floating IP
addresses: </para>
<screen><prompt>$</prompt> <userinput>nova floating-ip-pool-list</userinput></screen>
</step>
</procedure>
<procedure>
<title>To allocate a floating IP address to the current
project</title>
<step>
<para>The output of the following command shows the
freshly allocated IP address:</para>
<screen><prompt>$</prompt> <userinput>nova floating-ip-pool-list</userinput></screen>
<para>If more than one pool of IP addresses is available,
you can also specify the pool from which to allocate
the IP address:</para>
<screen><prompt>$</prompt> <userinput>floating-ip-create POOL_NAME</userinput></screen>
</step>
</procedure>
<procedure>
<title>To list floating IP addresses allocated to the current
project</title>
<step>
<para>If an IP is already associated with an instance, the
output also shows the IP for the instance, thefixed IP
address for the instance, and the name of the pool
that provides the floating IP address.</para>
<screen><prompt>$</prompt> <userinput>nova floating-ip-list</userinput></screen>
</step>
</procedure>
<procedure>
<title>To release a floating IP address from the current
project</title>
<step>
<para>The IP address is returned to the pool of IP
addresses that are available for all projects. If an
IP address is currently assigned to a running
instance, it is automatically disassociated from the
instance.</para>
<screen><prompt>$</prompt> <userinput>nova floating-ip-delete FLOATING_IP</userinput></screen>
</step>
</procedure>
<procedure>
<title>To assign a floating IP address to an instance</title>
<step>
<para>To associate an IP address with an instance, one or
multiple floating IP addresses must be allocated to
the current project. Check this
with:<screen><prompt>$</prompt> <userinput>nova floating-ip-list</userinput></screen>In
addition, you must know the instance's name (or ID).
To look up the instances that belong to the current
project, use the <code>nova list</code> command. </para>
<screen><prompt>$</prompt> <userinput>nova add-floating-ip INSTANCE_NAME_OR_ID FLOATING_IP </userinput></screen>
<para>After you assign the IP with <command>nova
add-floating-ip</command> and configure security group rules for the instance, the instance is
publicly available at the floating IP
address.
</para>
</step>
</procedure>
<procedure>
<title>To remove a floating IP address from an
instance</title>
<step>
<para>To remove a floating IP address from an instance,
you must specify the same arguments that you used to
assign the IP.</para>
<screen><prompt>$</prompt> <userinput> nova remove-floating-ip INSTANCE_NAME_OR_ID FLOATING_IP </userinput></screen>
</step>
</procedure>
</section>

0
doc/src/docbkx/cli-guide/src/section_cli_heat.xml → doc/src/docbkx/openstack-user/src/section_cli_heat.xml
View File

237
doc/src/docbkx/openstack-user/src/section_cli_launch_instances.xml
View File

@ -4,7 +4,6 @@
xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
xml:id="cli_launch_instances">
<title>Launch instances</title>
<para>Instances are virtual machines that run inside the
cloud.</para>
<para>You can launch an instance directly from one of the
@ -12,129 +11,178 @@
copied to a persistent volume. The OpenStack Image Service
provides a pool of images that are accessible to members of
different projects.</para>
<para>To launch an instance, you must 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. For more details and a list of default
flavors available, see Section 1.5, "Managing
Flavors," (↑ User Guide for Administrators ). </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. For details, refer to Section 1.5.1,
Creating or Importing Keys. </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>. For details, see xx.
</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. For details, see
Section 1.5.3, Managing IP Addresses and Section 1.7,
Managing Volumes.</para>
</listitem>
</itemizedlist>
<procedure>
<title>To launch an instance:</title>
<para>After you gather the parameters you need to launch an
instance, you can launch it.</para>
<para>After you gather the <link
xlink:href="instance_parameters">parameters you need
to launch an instance</link>, you can launch
it.</para>
<section xml:id="launch_from_image"><title>Launch instance from an image</title><para>Use this procedure to launch an instance from an image.</para> <procedure>
<title>To gather the parameters you need to launch an instance</title>
<step>
<para>On a shell, source the OpenStack RC file. See <xref
linkend="cli_openrc"/>. </para>
</step>
<step>
<para>List the available flavors:</para>
<programlisting language="bash"><prompt>$</prompt> nova flavor-list</programlisting>
<screen><prompt>$</prompt> nova flavor-list</screen>
<screen><computeroutput>+----+-----------+-----------+------+-----------+------+-------+-------------+-----------+
| ID | Name | Memory_MB | Disk | Ephemeral | Swap | VCPUs | RXTX_Factor | Is_Public |
+----+-----------+-----------+------+-----------+------+-------+-------------+-----------+
| 1 | m1.tiny | 512 | 0 | 0 | | 1 | 1.0 | True |
| 2 | m1.small | 2048 | 20 | 0 | | 1 | 1.0 | True |
| 3 | m1.medium | 4096 | 40 | 0 | | 2 | 1.0 | True |
| 4 | m1.large | 8192 | 80 | 0 | | 4 | 1.0 | True |
| 42 | m1.nano | 64 | 0 | 0 | | 1 | 1.0 | True |
| 5 | m1.xlarge | 16384 | 160 | 0 | | 8 | 1.0 | True |
| 84 | m1.micro | 128 | 0 | 0 | | 1 | 1.0 | True |
+----+-----------+-----------+------+-----------+------+-------+-------------+-----------+</computeroutput></screen>
<para>Note the ID of the flavor that you want to use for
your instance. </para>
</step>
<step>
<para>List the available images:</para>
<programlisting language="bash"><prompt>$</prompt> nova image-list</programlisting>
<screen><prompt>$</prompt> <userinput>nova image-list</userinput></screen>
<screen><computeroutput>+--------------------------------------+---------------------------------+--------+--------+
| ID | Name | Status | Server |
+--------------------------------------+---------------------------------+--------+--------+
| 397e713c-b95b-4186-ad46-6126863ea0a9 | cirros-0.3.1-x86_64-uec | ACTIVE | |
| df430cc2-3406-4061-b635-a51c16e488ac | cirros-0.3.1-x86_64-uec-kernel | ACTIVE | |
| 3cf852bd-2332-48f4-9ae4-7d926d50945e | cirros-0.3.1-x86_64-uec-ramdisk | ACTIVE | |
+--------------------------------------+---------------------------------+--------+--------+</computeroutput></screen>
<para>You can also filter the image list by using grep to
find a specific image, like this: </para>
<screen><prompt>$</prompt> <userinput>nova image-list | grep 'kernel'</userinput></screen>
<screen><computeroutput>| df430cc2-3406-4061-b635-a51c16e488ac | cirros-0.3.1-x86_64-uec-kernel | ACTIVE | |</computeroutput></screen>
<para>Note the ID of the image that you want to boot your
instance from. </para>
</step>
<step>
<para>List the available security groups:</para>
<programlisting language="bash"><prompt>$</prompt> nova secgroup-list</programlisting>
<note>
<para>If you are an admin user, specify the
<literal>--all-tenants</literal> parameter to
list groups for all tenants. </para>
</note>
<screen><prompt>$</prompt> <userinput>nova secgroup-list --all-tenants</userinput></screen>
<screen><computeroutput>+----+---------+-------------+
| Id | Name | Description |
+----+---------+-------------+
| 2 | default | default |
+----+---------+-------------+</computeroutput></screen>
<para>If you have not created any security groups, you can
assign the instance to only the default security
group. </para>
<para>You can also list rules for a specified security
group:</para>
<screen><prompt>$</prompt> <userinput>nova secgroup-list-rules default</userinput> </screen>
<screen><computeroutput>+-------------+-----------+---------+----------+--------------+
| IP Protocol | From Port | To Port | IP Range | Source Group |
+-------------+-----------+---------+----------+--------------+
+-------------+-----------+---------+----------+--------------+</computeroutput></screen>
<para>In this example, the default security group has been
modified to allow HTTP traffic on the instance by
permitting TCP traffic on Port 80.</para>
</step>
<step>
<para>List the keypairs. </para>
<programlisting><prompt>$</prompt> nova keypair-list</programlisting>
<para>List the available keypairs. </para>
<screen><prompt>$</prompt> <userinput>nova keypair-list</userinput></screen>
<screen><computeroutput>+------+-------------+
| Name | Fingerprint |
+------+-------------+
+------+-------------+</computeroutput></screen>
<para>Note the name of the keypair that you use for SSH
access.</para>
</step>
<step>
<para>Now you have all the parameters required to launch
an instance, run the following command:</para>
<programlisting language="bash"><prompt>$</prompt> nova boot --flavor FLAVOR_ID --imageIMAGE_ID --key_name KEY_NAME \
--security_group NAME_OF_SEC_GROUP NAME_FOR_INSTANCE </programlisting>
<para>The command returns a list of instance properties,
including the status of the instance. </para>
<para>The status BUILD indicates that the instance has
started, but is not yet online. </para>
</step>
<step>
<para>Check if the instance is online:</para>
<programlisting language="bash"><prompt>$</prompt> nova list</programlisting>
</procedure>
<procedure><title>To launch an instance from an image</title>
<step>
<para>Now you have all the parameters required to launch
an instance, run the following command. Specify the
server name, flavor ID, and image ID. Optionally, you
can provide a key name for access control and security
group for security. You can also include metadata key
and value pairs. For example you can add a description
for your server by providing the <parameter>--meta
description="My Server"</parameter>
parameter.</para>
<screen><prompt>$</prompt> <userinput>nova boot --flavor FLAVOR_ID --image IMAGE_ID --key_name KEY_NAME \
--security_group NAME_OF_SEC_GROUP NAME_FOR_INSTANCE --meta KEY=VALUE --meta KEY=VALUE</userinput></screen>
<para>The command returns a list of server properties. </para>
<para>A status of <literal>BUILD</literal> indicates that the
instance has started, but is not yet online. </para>
<para>A status of <literal>ACTIVE</literal> indicates that
your server is active. </para>
<informalexample>
<screen><computeroutput><?db-font-size 70%?>+-------------------------------------+--------------------------------------+
| Property | Value |
+-------------------------------------+--------------------------------------+
| OS-EXT-STS:task_state | scheduling |
| image | cirros-0.3.1-x86_64-uec |
| OS-EXT-STS:vm_state | building |
| OS-EXT-SRV-ATTR:instance_name | instance-00000002 |
| flavor | m1.small |
| id | b3cdc6c0-85a7-4904-ae85-71918f734048 |
| security_groups | [{u'name': u'default'}] |
| user_id | 376744b5910b4b4da7d8e6cb483b06a8 |
| OS-DCF:diskConfig | MANUAL |
| accessIPv4 | |
| accessIPv6 | |
| progress | 0 |
| OS-EXT-STS:power_state | 0 |
| OS-EXT-AZ:availability_zone | nova |
| config_drive | |
| status | BUILD |
| updated | 2013-07-16T16:25:34Z |
| hostId | |
| OS-EXT-SRV-ATTR:host | None |
| key_name | None |
| OS-EXT-SRV-ATTR:hypervisor_hostname | None |
| name | myCirrosServer |
| adminPass | tVs5pL8HcPGw |
| tenant_id | 66265572db174a7aa66eba661f58eb9e |
| created | 2013-07-16T16:25:34Z |
| metadata | {} |
+-------------------------------------+--------------------------------------</computeroutput></screen>
</informalexample>
<para>Copy the server ID value from the
<literal>id</literal> field in the output. You use
this ID to get details for or delete your server. </para>
<para>Copy the administrative password value from the
<literal>adminPass</literal> field. You use this
value to log into your server.</para>
<note> <para>Arbitrary local files can also be placed into
the instance file system at creation time using
the <literal>--file
&lt;dst-path=src-path&gt;</literal> option.
You may store up to 5 files. For example if you
have a special authorized_keys file named
<filename>special_authorized_keysfile</filename>
that you want to put on the instance rather than
using the regular <link
linkend="nova_cli_associatekey">ssh key
injection</link> for some reason you can use
the following
command:<screen> <prompt>$</prompt><userinput>nova boot --image ubuntu-cloudimage --flavor 1 --file /root/.ssh/authorized_keys=special_authorized_keysfile</userinput></screen></para></note>
</step>
<step>
<para>Check if the instance is online:</para>
<screen><prompt>$</prompt> <userinput>nova list</userinput></screen>
<screen><computeroutput>+--------------------------------------+----------------------+--------+------------+-------------+------------------+
| ID | Name | Status | Task State | Power State | Networks |
+--------------------------------------+----------------------+--------+------------+-------------+------------------+
| 84c6e57d-a6b1-44b6-81eb-fcb36afd31b5 | myCirrosServer | ACTIVE | None | Running | private=10.0.0.3 |
| 8a99547e-7385-4ad1-ae50-4ecfaaad5f42 | myInstanceFromVolume | ACTIVE | None | Running | private=10.0.0.4 |
+--------------------------------------+----------------------+--------+------------+-------------+------------------+</computeroutput></screen>
<para>This command lists all instances of the project you
belong to, including their ID, their name, their
status, and their private (and if assigned, their
public) IP addresses. </para>
<para>If your instance's status is ACTIVE, the instance is
online. </para>
<para>If the status for the instance is ACTIVE, the
instance is online. </para>
<para>To view the available options for the <command>nova
list</command> command, run the following
command:</para>
<programlisting language="bash"><prompt>$</prompt> nova help list</programlisting>
<screen><prompt>$</prompt> <userinput>nova help list</userinput></screen>
</step>
<step>
<para>If you did not provide a keypair, security groups,
@ -144,5 +192,6 @@
<para>To change this, proceed to <xref
linkend="cli_configure_instances"/>.</para>
</step>
</procedure>
</procedure></section>
<xi:include href="../../common/boot_from_volume.xml"/>
</section>

180
doc/src/docbkx/openstack-user/src/section_cli_manage_networks.xml Executable file
View File

@ -0,0 +1,180 @@
<?xml version="1.0" encoding="UTF-8"?>
<section xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:svg="http://www.w3.org/2000/svg"
xmlns:html="http://www.w3.org/1999/xhtml" version="5.0"
xml:id="neutron_client_sample_commands">
<title>Create and manage networks</title>
<para>Before you run commands, set the following environment
variables:</para>
<screen><computeroutput>export OS_USERNAME=admin
export OS_PASSWORD=password
export OS_TENANT_NAME=admin
export OS_AUTH_URL=http://localhost:5000/v2.0</computeroutput></screen>
<procedure>
<title>To create and manage networks</title>
<step>
<para>List the extensions of the system:</para>
<screen><prompt>$</prompt> <userinput> neutron ext-list -c alias -c name</userinput></screen>
<screen><computeroutput>+-----------------+--------------------------+
| alias | name |
+-----------------+--------------------------+
| agent_scheduler | Agent Schedulers |
| binding | Port Binding |
| quotas | Quota management support |
| agent | agent |
| provider | Provider Network |
| router | Neutron L3 Router |
| lbaas | LoadBalancing service |
| extraroute | Neutron Extra Route |
+-----------------+--------------------------+ </computeroutput></screen>
</step>
<step>
<para>Create a network:</para>
<screen><prompt>$</prompt> <userinput> neutron net-create net1</userinput></screen>
<screen><computeroutput>Created a new network:
+---------------------------+--------------------------------------+
| Field | Value |
+---------------------------+--------------------------------------+
| admin_state_up | True |
| id | 2d627131-c841-4e3a-ace6-f2dd75773b6d |
| name | net1 |
| provider:network_type | vlan |
| provider:physical_network | physnet1 |
| provider:segmentation_id | 1001 |
| router:external | False |
| shared | False |
| status | ACTIVE |
| subnets | |
| tenant_id | 3671f46ec35e4bbca6ef92ab7975e463 |
+---------------------------+--------------------------------------+</computeroutput></screen>
<note>
<para>Some fields of the created network are invisible
to non-admin users.</para>
</note>
</step>
<step>
<para>Create a network with specified provider network
type:</para>
<screen><prompt>$</prompt> <userinput> neutron net-create net2 --provider:network-type local</userinput></screen>
<screen><computeroutput>Created a new network:
+---------------------------+--------------------------------------+
| Field | Value |
+---------------------------+--------------------------------------+
| admin_state_up | True |
| id | 524e26ea-fad4-4bb0-b504-1ad0dc770e7a |
| name | net2 |
| provider:network_type | local |
| provider:physical_network | |
| provider:segmentation_id | |
| router:external | False |
| shared | False |
| status | ACTIVE |
| subnets | |
| tenant_id | 3671f46ec35e4bbca6ef92ab7975e463 |
+---------------------------+--------------------------------------+ </computeroutput></screen>
<para>Just as shown previous, the unknown option
<literal>--provider:network-type</literal> is used
to create a <literal>local</literal> provider
network.</para>
</step>
<step>
<para>Create a subnet:</para>
<screen><prompt>$</prompt> <userinput> neutron subnet-create net1 192.168.2.0/24 --name subnet1</userinput></screen>
<screen><computeroutput>Created a new subnet:
+------------------+--------------------------------------------------+
| Field | Value |
+------------------+--------------------------------------------------+
| allocation_pools | {"start": "192.168.2.2", "end": "192.168.2.254"} |
| cidr | 192.168.2.0/24 |
| dns_nameservers | |
| enable_dhcp | True |
| gateway_ip | 192.168.2.1 |
| host_routes | |
| id | 15a09f6c-87a5-4d14-b2cf-03d97cd4b456 |
| ip_version | 4 |
| name | subnet1 |
| network_id | 2d627131-c841-4e3a-ace6-f2dd75773b6d |
| tenant_id | 3671f46ec35e4bbca6ef92ab7975e463 |
+------------------+--------------------------------------------------+</computeroutput></screen>
<para>In the previous command, <literal>net1</literal> is
the network name, <literal>192.168.2.0/24</literal> is
the subnet's CIDR. They are positional arguments.
<literal>--name subnet1</literal> is an unknown
option, which specifies the subnet's name.</para>
</step>
<step>
<para>Create a port with specified IP address:</para>
<screen><prompt>$</prompt> <userinput> neutron port-create net1 --fixed-ip ip_address=192.168.2.40</userinput></screen>
<screen><computeroutput>Created a new port:
+----------------------+-------------------------------------------------------------------------------------+
| Field | Value |
+----------------------+-------------------------------------------------------------------------------------+
| admin_state_up | True |
| binding:capabilities | {"port_filter": false} |
| binding:vif_type | ovs |
| device_id | |
| device_owner | |
| fixed_ips | {"subnet_id": "15a09f6c-87a5-4d14-b2cf-03d97cd4b456", "ip_address": "192.168.2.40"} |
| id | f7a08fe4-e79e-4b67-bbb8-a5002455a493 |
| mac_address | fa:16:3e:97:e0:fc |
| name | |
| network_id | 2d627131-c841-4e3a-ace6-f2dd75773b6d |
| status | DOWN |
| tenant_id | 3671f46ec35e4bbca6ef92ab7975e463 |
+----------------------+-------------------------------------------------------------------------------------+ </computeroutput></screen>
<para>In the previous command, <literal>net1</literal> is
the network name, which is a positional argument.
<literal>--fixed-ip
ip_address=192.168.2.40</literal> is an option,
which specifies the port's fixed IP address we
wanted.</para>
</step>
<step>
<para>Create a port without specified IP address:</para>
<screen><prompt>$</prompt> <userinput> neutron port-create net1</userinput></screen>
<screen><computeroutput>Created a new port:
+----------------------+------------------------------------------------------------------------------------+
| Field | Value |
+----------------------+------------------------------------------------------------------------------------+
| admin_state_up | True |
| binding:capabilities | {"port_filter": false} |
| binding:vif_type | ovs |
| device_id | |
| device_owner | |
| fixed_ips | {"subnet_id": "15a09f6c-87a5-4d14-b2cf-03d97cd4b456", "ip_address": "192.168.2.2"} |
| id | baf13412-2641-4183-9533-de8f5b91444c |
| mac_address | fa:16:3e:f6:ec:c7 |
| name | |
| network_id | 2d627131-c841-4e3a-ace6-f2dd75773b6d |
| status | DOWN |
| tenant_id | 3671f46ec35e4bbca6ef92ab7975e463 |
+----------------------+------------------------------------------------------------------------------------+ </computeroutput></screen>
<para>We can see that the system will allocate one IP
address if we don't specify the IP address in command
line.</para>
</step>
<step>
<para>Query ports with specified fixed IP
addresses:</para>
<screen><prompt>$</prompt> <userinput> neutron port-list --fixed-ips ip_address=192.168.2.2 ip_address=192.168.2.40</userinput></screen>
<screen><computeroutput>+--------------------------------------+------+-------------------+-------------------------------------------------------------------------------------+
| id | name | mac_address | fixed_ips |
+--------------------------------------+------+-------------------+-------------------------------------------------------------------------------------+
| baf13412-2641-4183-9533-de8f5b91444c | | fa:16:3e:f6:ec:c7 | {"subnet_id": "15a09f6c-87a5-4d14-b2cf-03d97cd4b456", "ip_address": "192.168.2.2"} |
| f7a08fe4-e79e-4b67-bbb8-a5002455a493 | | fa:16:3e:97:e0:fc | {"subnet_id": "15a09f6c-87a5-4d14-b2cf-03d97cd4b456", "ip_address": "192.168.2.40"} |
+--------------------------------------+------+-------------------+-------------------------------------------------------------------------------------+ </computeroutput></screen>
<para><literal>--fixed-ips ip_address=192.168.2.2
ip_address=192.168.2.40</literal> is one unknown
option.</para>
<para><emphasis role="bold">How to find unknown
options?</emphasis> The unknown options can be
easily found by watching the output of
<literal>create_xxx</literal> or
<literal>show_xxx</literal> command. For example,
in the port creation command, we see the fixed_ips
fields, which can be used as an unknown option.</para>
</step>
</procedure>
</section>

15
doc/src/docbkx/openstack-user/src/section_cli_openrc.xml
View File

@ -16,7 +16,7 @@
<para>You can download the file from the OpenStack dashboard as an
administrative user or any other user.</para>
<procedure>
<title>To download the OpenStack RC file:</title>
<title>To download the OpenStack RC file</title>
<step>
<para>Log in to the OpenStack dashboard. </para>
</step>
@ -45,13 +45,22 @@
<para>In this example, we source the
<filename>demo-openrc.sh</filename> file for the
demo project:</para>
<programlisting language="bash" linenumbering="unnumbered"><prompt>$</prompt> source demo-openrc.sh</programlisting>
<screen><prompt>$</prompt> <userinput>source demo-openrc.sh</userinput></screen>
</step>
<step>
<para>When you are prompted for an OpenStack password,
enter the OpenStack password for the user who
downloaded the <filename>openrc.sh</filename>
file.</para>
file.</para> </step> <step><para>When you run OpenStack client commands, you can override some
environment variable settings by using the options
that are listed at the end of the <command>nova
help</command> output. For example, you can
override the <literal>OS_PASSWORD</literal> setting in
the <filename>openrc.sh</filename> file by specifying
a password on a nova command, as follows: </para>
<screen><prompt>$</prompt> <userinput>nova --password &lt;password> image-list</userinput></screen>
<para>Where <parameter>password</parameter> is
your password.</para>
</step>
</procedure>
</section>

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

@ -1,78 +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="cli_overview">
<title>Command-line clients overview</title>
<para>The following command-line clients are available for the
respective services' APIs:</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>Compute, Compute extensions</para>
<para>Manage instances and flavors.</para>
<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>Block Storage Service</para>
<para>Manage volumes.</para>
<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>Object Storage</para>
<para>Manage the object store. </para>
<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>
</variablelist>
<para>All clients have tab completion. </para>
<para>Help and detailed information about the individual commands
and their arguments are available with</para>
<programlisting language="bash">COMMAND help</programlisting>
<para>For help on subcommands, use </para>
<programlisting language="bash">COMMAND help SUBCOMMAND</programlisting>
<para>For example: </para>
<programlisting language="bash">glance help </programlisting>
<para>or </para>
<programlisting language="bash">glance help image-create </programlisting>
</section>

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

@ -12,7 +12,7 @@
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="instance_parameters">
<!-- <section xml:id="instance_parameters">
<title>Parameters</title>
<para>To launch an instance, you must specify the following
parameters:</para>
@ -84,7 +84,7 @@
1.7, Managing Volumes.</para></listitem>
</itemizedlist>
</section>
</section> -->
<section xml:id="launch_instance">
<title>Launch an instance</title>
<para>You can launch an instance directly from one of the

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

@ -36,7 +36,7 @@
<literal>xvda</literal> for Xen images.</para>
</listitem>
</itemizedlist></para>
<section xml:id="instance_parameters-iv">
<!-- <section xml:id="instance_parameters-iv">
<title>Parameters</title>
<para>To launch an instance, you must specify the following
parameters:</para>
@ -101,7 +101,7 @@
(volume) for persistent storage. For details, see Section
1.5.3, Managing IP Addresses and Section 1.7, Managing
Volumes.</para>
</section>
</section>-->
<section xml:id="dashboard_boot_instance_from_volume">
<title>Boot an instance from a volume</title>
<para>You can start an instance directly from one of the

0
doc/src/docbkx/cli-guide/src/swift_cli_commands.xml → doc/src/docbkx/openstack-user/src/swift_cli_commands.xml
View File