openstack/openstack-manuals
Code Issues Proposed changes

bk and ch fixes: edits up to cli_nova_boot, removed excess info

Browse Source 
- excess removed from cli_version
- removed redundant section from ch_cli

Change-Id: I31b5c49e007ec2ff5e58b964c8b32dbcfa7cab32
This commit is contained in:
Karin Levenstein 2014-04-19 09:22:53 -05:00
parent 4bb27a9906
commit b2c7f2864c
10 changed files with 703 additions and 758 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

276
doc/common/section_cli_glance_manage_images.xml
View File

@ -9,19 +9,19 @@
who can upload and manage images. The operator might restrict who can upload and manage images. The operator might restrict
image upload and management to only cloud administrators or image upload and management to only cloud administrators or
operators.</para> operators.</para>
<para>You can upload images through the glance client or the Image Service API. You can also use <para>You can upload images through the <command>glance</command> client or the Image Service
the nova client to list images, set, and delete image metadata, delete images, and take a API. You can also use the <command>nova</command> client to list images, set and delete
snapshot of a running instance to create an image. After you upload an image, you cannot image metadata, delete images, and take a snapshot of a running instance to create an image.
change it.</para> After you upload an image, you cannot change it.</para>
<para>For details about image creation, see the <link <para>For details about image creation, see the <link
xlink:href="http://docs.openstack.org/image-guide/content/" xlink:href="http://docs.openstack.org/image-guide/content/"
><citetitle>Virtual Machine Image ><citetitle>Virtual Machine Image
Guide</citetitle></link>.</para> Guide</citetitle></link>.</para>
<section xml:id="glance-image-list"> <section xml:id="glance-image-list">
<title>List or get details for images (glance)</title> <title>List or get details for images (glance)</title>
<procedure> <para>To get a list of images and to then get further details about a single image,
<step> use <command>glance image-list</command> and <command>glance
<para>To list the available images:</para> image-show</command>.</para>
<screen><prompt>$</prompt> <userinput>glance image-list</userinput> <screen><prompt>$</prompt> <userinput>glance image-list</userinput>
<computeroutput>+--------------------------------------+---------------------------------+-------------+------------------+----------+--------+ <computeroutput>+--------------------------------------+---------------------------------+-------------+------------------+----------+--------+
| ID | Name | Disk Format | Container Format | Size | Status | | ID | Name | Disk Format | Container Format | Size | Status |
@ -31,17 +31,9 @@
| 3cf852bd-2332-48f4-9ae4-7d926d50945e | cirros-0.3.2-x86_64-uec-ramdisk | ari | ari | 3714968 | active | | 3cf852bd-2332-48f4-9ae4-7d926d50945e | cirros-0.3.2-x86_64-uec-ramdisk | ari | ari | 3714968 | active |
| 7e5142af-1253-4634-bcc6-89482c5f2e8a | myCirrosImage | ami | ami | 14221312 | active | | 7e5142af-1253-4634-bcc6-89482c5f2e8a | myCirrosImage | ami | ami | 14221312 | active |
+--------------------------------------+---------------------------------+-------------+------------------+----------+--------+</computeroutput></screen> +--------------------------------------+---------------------------------+-------------+------------------+----------+--------+</computeroutput></screen>
<para>You can use grep to filter the list, as
follows:</para>
<screen><prompt>$</prompt> <userinput>glance image-list | grep 'cirros'</userinput>
<computeroutput>| 397e713c-b95b-4186-ad46-6126863ea0a9 | cirros-0.3.2-x86_64-uec | ami | ami | 25165824 | active |
| df430cc2-3406-4061-b635-a51c16e488ac | cirros-0.3.2-x86_64-uec-kernel | aki | aki | 4955792 | active |
| 3cf852bd-2332-48f4-9ae4-7d926d50945e | cirros-0.3.2-x86_64-uec-ramdisk | ari | ari | 3714968 | active |</computeroutput></screen>
</step>
<step>
<para>To get image details, by name or ID:</para>
<screen><prompt>$</prompt> <userinput>glance image-show myCirrosImage</userinput> <screen><prompt>$</prompt> <userinput>glance image-show myCirrosImage</userinput>
<?db-font-size 45%?><computeroutput>+---------------------------------------+--------------------------------------+ <?db-font-size 45%?>
<computeroutput>+---------------------------------------+--------------------------------------+
| Property | Value | | Property | Value |
+---------------------------------------+--------------------------------------+ +---------------------------------------+--------------------------------------+
| Property 'base_image_ref' | 397e713c-b95b-4186-ad46-6126863ea0a9 | | Property 'base_image_ref' | 397e713c-b95b-4186-ad46-6126863ea0a9 |
@ -79,6 +71,12 @@
| status | active | | status | active |
| updated_at | 2013-07-22T19:46:42 | | updated_at | 2013-07-22T19:46:42 |
+---------------------------------------+--------------------------------------+</computeroutput></screen> +---------------------------------------+--------------------------------------+</computeroutput></screen>
<para>When viewing a list of images, you can also use <command>grep</command> to filter the
list, as follows:</para>
<screen><prompt>$</prompt> <userinput>glance image-list | grep 'cirros'</userinput>
<computeroutput>| 397e713c-b95b-4186-ad46-6126863ea0a9 | cirros-0.3.2-x86_64-uec | ami | ami | 25165824 | active |
| df430cc2-3406-4061-b635-a51c16e488ac | cirros-0.3.2-x86_64-uec-kernel | aki | aki | 4955792 | active |
| 3cf852bd-2332-48f4-9ae4-7d926d50945e | cirros-0.3.2-x86_64-uec-ramdisk | ari | ari | 3714968 | active |</computeroutput></screen>
<note><para>To store location metadata for images, which enables direct file <note><para>To store location metadata for images, which enables direct file
access for a client, update the access for a client, update the
<filename>/etc/glance/glance.conf</filename> <filename>/etc/glance/glance.conf</filename>
@ -89,17 +87,13 @@
<para><code>show_multiple_locations = True</code></para> <para><code>show_multiple_locations = True</code></para>
</listitem> </listitem>
<listitem> <listitem>
<para><code>filesystem_store_metadata_file <para><code>filesystem_store_metadata_file =
= <replaceable>filePath</replaceable></code>, where
<replaceable>filePath</replaceable></code>, <replaceable>filePath</replaceable> points to a JSON file
where that defines the mount point for OpenStack images on your system
<replaceable>filePath</replaceable> and a unique ID. For example:
points to a JSON file that defines
the mount point for OpenStack
images on your system and a unique
ID. For example:
<programlisting language="json">[{ <programlisting language="json">[{
"id": "b9d69795-5951-4cb0-bb5c-29491e1e2daf", "id": "2d9bb53f-70ea-4066-a68b-67960eaae673",
"mountpoint": "/var/lib/glance/images/" "mountpoint": "/var/lib/glance/images/"
}]</programlisting></para> }]</programlisting></para>
</listitem> </listitem>
@ -107,178 +101,188 @@
</para> </para>
<para>After you restart the Image Service, you can use the following syntax to view the image's location information:</para> <para>After you restart the Image Service, you can use the following syntax to view the image's location information:</para>
<screen><prompt>$</prompt> <userinput>glance --os-image-api-version=2 image-show <replaceable>imageID</replaceable></userinput></screen> <screen><prompt>$</prompt> <userinput>glance --os-image-api-version=2 image-show <replaceable>imageID</replaceable></userinput></screen>
<para>For example:</para> <para>For example, using the image ID shown above, you would issue the command
as follows:</para>
<screen><prompt>$</prompt> <userinput>glance --os-image-api-version=2 image-show 2d9bb53f-70ea-4066-a68b-67960eaae673</userinput></screen></note> <screen><prompt>$</prompt> <userinput>glance --os-image-api-version=2 image-show 2d9bb53f-70ea-4066-a68b-67960eaae673</userinput></screen></note>
</step>
</procedure>
</section> </section>
<section xml:id="glance_add_image"> <section xml:id="glance_add_image">
<title>Create or update an image (glance)</title> <title>Create or update an image (glance)</title>
<procedure> <para>To create an image, use <command>glance image-create</command>:</para>
<step> <screen><prompt>$</prompt> <userinput>glance image-create <replaceable>imageName</replaceable></userinput></screen>
<para>To upload a CentOS 6.3 image in qcow2 format and <para>To update an image by name or ID, use <command>glance image-update</command>:</para>
configure it for public access:</para> <para>
<screen><prompt>$</prompt> <userinput>glance image-create --name centos63-image --disk-format=qcow2 \ <screen><prompt>$</prompt> <userinput>glance image-update <replaceable>imageName</replaceable></userinput></screen>
--container-format=bare --is-public=True --file=./centos63.qcow2</userinput></screen> </para>
</step> <para>The following table lists the optional arguments that you can use with the
<step> <command>create</command> and <command>update</command> commands to modify image
<para>To update an image by name or ID:</para> properties. For more information, refer to Image Service chapter in the <link
<para><screen><prompt>$</prompt> <userinput>glance image-update <replaceable>IMAGE</replaceable></userinput></screen></para> xlink:href="http://docs.openstack.org/cli-reference/content/index.html">OpenStack
<para>To modify image properties, use the following Command-Line Interface Reference</link>.</para>
optional arguments:</para>
<informaltable> <informaltable>
<col width="40%"/> <col width="40%"/>
<col width="60%"/> <col width="60%"/>
<tr> <tr>
<td><para><parameter>--name <td>
<replaceable>NAME</replaceable></parameter></para></td> <para><parameter>--name NAME</parameter></para>
<td><para>The name of the image.</para> </td>
<td>
<para>The name of the image.</para>
</td> </td>
</tr> </tr>
<tr> <tr>
<td><para><parameter>--disk-format <td>
<replaceable>DISK_FORMAT</replaceable></parameter></para></td> <para><parameter>--disk-format DISK_FORMAT</parameter></para>
<td><para>The disk format of the image. </td>
Acceptable formats are ami, ari, aki, <td>
vhd, vmdk, raw, qcow2, vdi, and <para>The disk format of the image. Acceptable formats are ami, ari, aki, vhd,
iso.</para> vmdk, raw, qcow2, vdi, and iso.</para>
</td> </td>
</tr> </tr>
<tr> <tr>
<td><para><parameter>--container-format <td>
<replaceable>CONTAINER_FORMAT</replaceable></parameter></para></td> <para><parameter>--container-format CONTAINER_FORMAT</parameter></para>
<td><para>The container format of the image. </td>
Acceptable formats are ami, ari, aki, <td>
<para>The container format of the image. Acceptable formats are ami, ari, aki,
bare, and ovf.</para> bare, and ovf.</para>
</td> </td>
</tr> </tr>
<tr> <tr>
<td><para><parameter>--owner <td>
<replaceable>TENANT_ID</replaceable></parameter></para></td> <para><parameter>--owner TENANT_ID</parameter></para>
<td><para>The tenant who should own the </td>
image.</para> <td>
<para>The tenant who should own the image.</para>
</td> </td>
</tr> </tr>
<tr> <tr>
<td><para><parameter>--size <td>
<replaceable>SIZE</replaceable></parameter></para></td> <para><parameter>--size SIZE</parameter></para>
<td><para>The size of image data, in </td>
bytes.</para> <td>
<para>The size of image data, in bytes.</para>
</td> </td>
</tr> </tr>
<tr> <tr>
<td><para><parameter>--min-disk <td>
<replaceable>DISK_GB</replaceable></parameter></para></td> <para><parameter>--min-disk DISK_GB</parameter></para>
<td><para>The minimum size of disk needed to </td>
boot image, in gigabytes.</para> <td>
<para>The minimum size of the disk needed to boot the image, in
gigabytes.</para>
</td> </td>
</tr> </tr>
<tr> <tr>
<td><para><parameter>--min-ram <td>
<replaceable>DISK_RAM</replaceable></parameter></para></td> <para><parameter>--min-ram DISK_RAM</parameter></para>
<td><para>The minimum amount of ram needed to </td>
boot image, in megabytes.</para> <td>
<para>The minimum amount of RAM needed to boot the image, in megabytes.</para>
</td> </td>
</tr> </tr>
<tr> <tr>
<td><para><parameter>--location <td>
<replaceable>IMAGE_URL</replaceable></parameter></para></td> <para><parameter>--location IMAGE_URL</parameter></para>
<td><para>The URL where the data for this </td>
image resides. For example, if the <td>
image data is stored in swift, you <para>The URL where the data for this image resides. For example, if the image
could specify data is stored in swift, you could specify
<literal>swift://account:key@example.com/container/obj</literal>.</para> <literal>swift://account:key@example.com/container/obj</literal>.</para>
</td> </td>
</tr> </tr>
<tr> <tr>
<td><para><parameter>--file <td>
<replaceable>FILE</replaceable></parameter></para></td> <para><parameter>--file FILE</parameter></para>
<td><para>Local file that contains disk image </td>
to be uploaded during update. <td>
Alternatively, you can pass images to <para>Local file that contains the disk image to be uploaded during the update.
the client through stdin.</para> Alternatively, you can pass images to the client through stdin.</para>
</td> </td>
</tr> </tr>
<tr> <tr>
<td><para><parameter>--checksum <td>
<replaceable>CHECKSUM</replaceable></parameter></para></td> <para><parameter>--checksum CHECKSUM</parameter></para>
<td><para>Hash of image data to use for </td>
verification.</para> <td>
<para>Hash of image data to use for verification.</para>
</td> </td>
</tr> </tr>
<tr> <tr>
<td><para><parameter>--copy-from <td>
<replaceable>IMAGE_URL</replaceable></parameter></para></td> <para><parameter>--copy-from IMAGE_URL</parameter></para>
<td><para>Similar to </td>
<parameter>--location</parameter> <td>
in usage, but indicates that the <para>Similar to <parameter>--location</parameter> in usage, but indicates that
Image server should immediately copy the image server should immediately copy the data and store it in its
the data and store it in its
configured image store.</para> configured image store.</para>
</td> </td>
</tr> </tr>
<tr> <tr>
<td><para><parameter>--is-public <td>
[True|False]</parameter></para></td> <para><parameter>--is-public [True|False]</parameter></para>
<td><para>Makes an image accessible to the </td>
public.</para> <td>
<para>Makes an image accessible for all the tenants.</para>
</td> </td>
</tr> </tr>
<tr> <tr>
<td><para><parameter>--is-protected <td>
[True|False]</parameter></para></td> <para><parameter>--is-protected [True|False]</parameter></para>
<td><para>Prevents an image from being </td>
deleted.</para> <td>
<para>Prevents an image from being deleted.</para>
</td> </td>
</tr> </tr>
<tr> <tr>
<td><para><parameter>--property <td>
<replaceable>KEY</replaceable>=<replaceable>VALUE</replaceable></parameter></para></td> <para><parameter>--property KEY=VALUE</parameter></para>
<td><para>Arbitrary property to associate with </td>
image. Can be used multiple <td>
times.</para> <para>Arbitrary property to associate with image. This option can be used
multiple times.</para>
</td> </td>
</tr> </tr>
<tr> <tr>
<td><para><parameter>--purge-props</parameter></para></td> <td>
<td><para>Deletes all image properties that <para><parameter>--purge-props</parameter></para>
are not explicitly set in the update </td>
request. Otherwise, those properties <td>
not referenced are preserved.</para> <para>Deletes all image properties that are not explicitly set in the update
request. Otherwise, those properties not referenced are preserved.</para>
</td> </td>
</tr> </tr>
<tr> <tr>
<td><para><parameter>--human-readable</parameter></para></td> <td>
<td><para>Prints image size in a <para><parameter>--human-readable</parameter></para>
human-friendly format.</para> </td>
<td>
<para>Prints the image size in a human-friendly format.</para>
</td> </td>
</tr> </tr>
</informaltable> </informaltable>
</step> <para>The following example shows the command that you would use to upload a CentOS
<step> 6.3 image in qcow2 format and configure it for public access:</para>
<para>To annotate an image with a property that describes the <literal>disk_bus</literal>, <literal>cdrom_bus</literal>, <screen><prompt>$</prompt> <userinput>glance image-create --name centos63-image --disk-format=qcow2 \
and <literal>vif_model</literal>:</para> --container-format=bare --is-public=True --file=./centos63.qcow2</userinput></screen>
<para>The following example shows how to update an existing image with a properties
that describe the disk bus, the CD-ROM bus, and the VIF model:</para>
<screen><prompt>$</prompt> <userinput>glance image-update \ <screen><prompt>$</prompt> <userinput>glance image-update \
--property hw_disk_bus=scsi \ --property hw_disk_bus=scsi \
--property hw_cdrom_bus=ide \ --property hw_cdrom_bus=ide \
--property hw_vif_model=e1000 \ --property hw_vif_model=e1000 \
f16-x86_64-openstack-sda</userinput></screen> f16-x86_64-openstack-sda</userinput></screen>
<para>Currently libvirt will determine the disk/cdrom/vif device models based on the <para>Currently the libvirt virtualization tool determines the disk, CD-ROM, and VIF
configured hypervisor type (<literal>libvirt_type</literal> in device models based on the configured hypervisor type (<literal>libvirt_type</literal>
<literal>/etc/nova/nova.conf</literal>). For the sake of optimal in <filename>/etc/nova/nova.conf</filename>). For the sake of optimal performance, libvirt
performance, it will default to using virtio for both disk and VIF (NIC) models. defaults to using virtio for both disk and VIF (NIC) models. The disadvantage of this
The downside of this approach is that it is not possible to run operating approach is that it is not possible to run operating systems that lack virtio drivers,
systems that lack virtio drivers, for example, BSD, Solaris, old Linux, and old for example, BSD, Solaris, and older versions of Linux and Windows.</para>
Windows.</para>
<para>If you specify a disk or CD-ROM bus model that is not supported, see <xref <para>If you specify a disk or CD-ROM bus model that is not supported, see <xref
linkend="bus_models"/>. If you specify a VIF model that is not supported, linkend="bus_models"/>. If you specify a VIF model that is not supported,
the instance fails to launch. See <xref linkend="vif_models"/>.</para> the instance fails to launch. See <xref linkend="vif_models"/>.</para>
</step>
</procedure>
<?hard-pagebreak?> <?hard-pagebreak?>
<para>The valid model values depend on the <para>The valid model values depend on the <literal>libvirt_type</literal> setting, as shown
<literal>libvirt_type</literal> setting, as shown in in the following tables.</para>
the following tables:</para>
<table xml:id="bus_models" rules="all" width="50%"> <table xml:id="bus_models" rules="all" width="50%">
<caption>Disk and CD-ROM bus model values</caption> <caption>Disk and CD-ROM bus model values</caption>
<col width="40%"/> <col width="40%"/>
@ -407,6 +411,8 @@
<xi:include href="section_cli_nova_manage_images.xml"/> <xi:include href="section_cli_nova_manage_images.xml"/>
<section xml:id="troubleshoot"> <section xml:id="troubleshoot">
<title>Troubleshoot image creation</title> <title>Troubleshoot image creation</title>
<para>If you encounter problems in creating an image in Image Service or Compute, the
following information may help you troubleshoot the creation process.</para>
<itemizedlist> <itemizedlist>
<listitem> <listitem>
<para>You cannot create a snapshot from an instance <para>You cannot create a snapshot from an instance
@ -414,11 +420,9 @@
create the image, and re-mount the volume.</para> create the image, and re-mount the volume.</para>
</listitem> </listitem>
<listitem> <listitem>
<para>Make sure the version of qemu you are using is <para>Ensure that the version of qemu you are using is version 0.14 or later.
version 0.14 or greater. Older versions of qemu Earlier versions of qemu result in an <literal>unknown option -s</literal> error
result in an "<literal>unknown option message in the <filename>nova-compute.log</filename> file.</para>
-s</literal>" error message in the
<filename>nova-compute.log</filename>.</para>
</listitem> </listitem>
<listitem> <listitem>
<para>Examine the <para>Examine the

265
doc/common/section_cli_install.xml
View File

@ -5,7 +5,6 @@
<!ENTITY mdash "&#x2014;"> <!ENTITY mdash "&#x2014;">
<!ENTITY hellip "&#x2026;"> <!ENTITY hellip "&#x2026;">
<!ENTITY plusmn "&#xB1;"> <!ENTITY plusmn "&#xB1;">
]> ]>
<section xmlns="http://docbook.org/ns/docbook" <section xmlns="http://docbook.org/ns/docbook"
xmlns:xi="http://www.w3.org/2001/XInclude" xmlns:xi="http://www.w3.org/2001/XInclude"
@ -15,13 +14,11 @@
<title>Install the OpenStack command-line clients</title> <title>Install the OpenStack command-line clients</title>
<para>Install the prerequisite software and the Python package for <para>Install the prerequisite software and the Python package for
each OpenStack client.</para> each OpenStack client.</para>
<note> <section xml:id="install_prereq_software">
<para>For each command, replace <title>Install the prerequisite software</title>
<replaceable>PROJECT</replaceable> with the lower case <para>The following table lists the software that you need to
name of the client to install, such as have to run the command-line clients, and provides
<literal>nova</literal>. Repeat for each installation instructions as needed.</para>
client.</para>
</note>
<table rules="all" width="75%"> <table rules="all" width="75%">
<caption>Prerequisite software</caption> <caption>Prerequisite software</caption>
<col width="15%"/> <col width="15%"/>
@ -35,7 +32,7 @@
<tbody> <tbody>
<tr> <tr>
<td valign="top"> <td valign="top">
<para>Python 2.6 or newer</para> <para>Python 2.6 or later</para>
</td> </td>
<td> <td>
<para>Currently, the clients do not support Python <para>Currently, the clients do not support Python
@ -71,168 +68,186 @@
<tr> <tr>
<td valign="top"><package>pip</package> package</td> <td valign="top"><package>pip</package> package</td>
<td> <td>
<para>To install the clients on a Linux, Mac OS X or Microsoft <para>To install the clients on a Linux, Mac OS X,
Windows system, use <package>pip</package>. It or Microsoft Windows system, use
is easy to use, ensures that you get the <package>pip</package>. It is easy to
latest version of the clients from the <link use, ensures that you get the latest
version of the clients from the <link
xlink:href="http://pypi.python.org/pypi/python-novaclient/" xlink:href="http://pypi.python.org/pypi/python-novaclient/"
>Python Package Index</link>, and lets you >Python Package Index</link>, and lets
update or remove the packages later on.</para> you update or remove the packages later
on.</para>
<para>Install <package>pip</package> through the <para>Install <package>pip</package> through the
package manager for your system:</para> package manager for your system:</para>
<formalpara> <formalpara>
<title>Mac OS X</title> <title>MacOS</title>
<para> <para><screen><prompt>#</prompt> <userinput>easy_install pip</userinput></screen></para>
<screen><prompt>#</prompt> <userinput>easy_install pip</userinput></screen></para>
</formalpara> </formalpara>
<formalpara> <formalpara>
<title>Microsoft Windows</title> <title>Microsoft Windows</title>
<para>Make sure that the <para>Ensure that the
<filename>C:\Python27\Scripts</filename> directory <filename>C:\Python27\Scripts</filename>
is defined in the <literal>PATH</literal> directory is defined in the
environment variable, and use the <literal>PATH</literal> environment
<command>easy_install</command> command from the variable, and use the
<package>setuptools</package> package: <command>easy_install</command>
<screen><prompt>C:\></prompt><userinput>easy_install pip</userinput></screen> command from the
Another option is to use the unofficial binary <package>setuptools</package>
installer provided by Christoph Gohlke (<link package:
<screen><prompt>C:\></prompt><userinput>easy_install pip</userinput></screen>Another
option is to use the unofficial binary
installer provided by Christoph Gohlke
(<link
xlink:href="http://www.lfd.uci.edu/~gohlke/pythonlibs/#pip" xlink:href="http://www.lfd.uci.edu/~gohlke/pythonlibs/#pip"
>http://www.lfd.uci.edu/~gohlke/pythonlibs/#pip</link>).</para> >http://www.lfd.uci.edu/~gohlke/pythonlibs/#pip</link>).</para>
</formalpara> </formalpara>
<formalpara> <formalpara>
<title>Ubuntu 12.04</title> <title>Ubuntu 12.04/14.04</title>
<para>A packaged version enables you to use <para>A packaged version enables you to use
<package>dpkg</package> or <package>dpkg</package> or
<package>aptitude</package> to install <package>aptitude</package> to
the install the
<package>python-novaclient</package>:<screen><prompt>#</prompt> <userinput>aptitude install python-novaclient</userinput></screen></para> <package>python-novaclient</package>:
<screen><prompt>#</prompt> <userinput>aptitude install python-novaclient</userinput> </screen></para>
</formalpara> </formalpara>
<formalpara> <formalpara>
<title>Ubuntu and Debian</title> <title>Ubuntu and Debian</title>
<para><screen><prompt>#</prompt> <userinput>aptitude install python-pip</userinput></screen></para> <para><screen><prompt>#</prompt> <userinput>aptitude install python-pip</userinput></screen></para>
</formalpara> </formalpara>
<formalpara> <formalpara>
<title>RHEL, CentOS, or Fedora</title> <title>Red Hat Enterprise Linux, CentOS, or Fedora</title>
<para>A packaged version available in <link <para>A packaged version available in <link
xlink:href="http://openstack.redhat.com/" xlink:href="http://openstack.redhat.com/">RDO</link>
>RDO</link> enables you to use enables you to use <package>yum</package>
<package>yum</package> to install the to install the clients, or you can install
clients:
<screen><prompt>#</prompt> <userinput>yum install python-<replaceable>PROJECT</replaceable>client</userinput></screen></para>
</formalpara>
<para>Alternatively, install
<package>pip</package> and use it to <package>pip</package> and use it to
manage client installation:</para> manage client installation: <screen><prompt>#</prompt> <userinput>yum install python-pip</userinput></screen></para>
<screen><prompt>#</prompt> <userinput>yum install python-pip</userinput></screen> </formalpara>
<formalpara> <formalpara>
<title>openSUSE 12.2 and earlier</title> <title>openSUSE 12.2 and earlier</title>
<para>A <link <para>A <link
xlink:href="https://build.opensuse.org/package/show?package=python-novaclient&amp;project=Cloud:OpenStack:Master" xlink:href="https://build.opensuse.org/package/show?package=python-novaclient&amp;project=Cloud:OpenStack:Master">packaged
>packaged version available in the version available in the Open Build
Open Build Service</link> enables you Service</link> enables you to use
to use <package>rpm</package> or <package>rpm</package> or
<package>zypper</package> to install <package>zypper</package> to install the
the clients, or you can install
python-novaclient:<screen><prompt>#</prompt> <userinput>zypper install python-<replaceable>PROJECT</replaceable></userinput></screen></para> <package>pip</package> and use it to manage client installation:
</formalpara><para>Alternatively, install
<package>pip</package> and use it to
manage client installation:
<screen><prompt>#</prompt> <userinput>zypper install python-pip</userinput></screen></para> <screen><prompt>#</prompt> <userinput>zypper install python-pip</userinput></screen></para>
</formalpara>
<formalpara> <formalpara>
<title>openSUSE 12.3 and newer</title> <title>openSUSE 12.3 and later</title>
<para>A packaged version enables you to use <para>A packaged version enables you to use
<package>rpm</package> or <package>rpm</package> or
<package>zypper</package> to install <package>zypper</package> to install the
the clients: clients. See <xref linkend="cli_clients_install"/></para>
<screen><prompt>#</prompt> <userinput>zypper install python-<replaceable>PROJECT</replaceable>client</userinput></screen></para>
</formalpara> </formalpara>
</td> </td>
</tr> </tr>
</tbody> </tbody>
</table> </table>
</section>
<section xml:id="cli_clients_install"> <section xml:id="cli_clients_install">
<title>Install the clients</title> <title>Install the clients</title>
<para>When following the instructions in this section, replace
<replaceable>PROJECT</replaceable> with the lowercase
name of the client to install, such as
<command>nova</command>. Repeat for each client. The
following values are valid:</para>
<itemizedlist>
<listitem>
<para><literal>ceilometer</literal> - Telemetry
API</para>
</listitem>
<listitem>
<para><literal>cinder</literal> - Block Storage API
and extensions</para>
</listitem>
<listitem>
<para><literal>glance</literal> - Image Service
API</para>
</listitem>
<listitem>
<para><literal>heat</literal> - Orchestration
API</para>
</listitem>
<listitem>
<para><literal>keystone</literal> - Identity service
API and extensions</para>
</listitem>
<listitem>
<para><literal>neutron</literal> - Networking
API</para>
</listitem>
<listitem>
<para><literal>nova</literal> - Compute API and
extensions</para>
</listitem>
<listitem>
<para><literal>swift</literal> - Object Storage
API</para>
</listitem>
<listitem>
<para><literal>trove</literal> - Database Service
API</para>
</listitem>
</itemizedlist>
<para>The following example shows the command for installing
the nova client with
<replaceable>pip</replaceable>.</para>
<screen><prompt>#</prompt> <userinput>pip install python-novaclient</userinput></screen>
<section xml:id="cli_clients_install_pip">
<title>Installing with pip</title>
<para>Use <package>pip</package> to install the OpenStack <para>Use <package>pip</package> to install the OpenStack
clients on a Linux, Mac OS X or Microsoft Windows system. It is clients on a Linux, Mac OS X, or Microsoft Windows
easy and ensures that you get the latest version of the client system. It is easy to use and ensures that you get the
from the <link xlink:href="http://pypi.python.org/pypi">Python latest version of the client from the <link
xlink:href="http://pypi.python.org/pypi">Python
Package Index</link>. Also, <package>pip</package> Package Index</link>. Also, <package>pip</package>
lets you update or remove a package. After you install the enables you to update or remove a package.</para>
clients, you must source an <filename <para>Install each client separately by using the
xmlns:raxm="http://docs.rackspace.com/api/metadata" following command:</para>
><replaceable>PROJECT</replaceable>-openrc.sh</filename>
file to set required environment
variables before you can request OpenStack services
through the clients or the APIs.</para>
<procedure>
<step>
<para>Install each client separately using:</para>
<itemizedlist> <itemizedlist>
<listitem><para>For Mac OS X or Linux:</para> <listitem><para>For Mac OS X or Linux:</para>
<screen><prompt>#</prompt> <userinput>pip install python-<replaceable>PROJECT</replaceable>client</userinput></screen></listitem> <screen><prompt>#</prompt> <userinput>pip install python-<replaceable>PROJECT</replaceable>client</userinput></screen></listitem>
<listitem><para>For Microsoft Windows:</para> <listitem><para>For Microsoft Windows:</para>
<screen><prompt>C:\></prompt><userinput>pip install python-<replaceable>PROJECT</replaceable>client</userinput></screen></listitem> <screen><prompt>C:\></prompt><userinput>pip install python-<replaceable>PROJECT</replaceable>client</userinput></screen></listitem>
</itemizedlist> </itemizedlist>
<para>Where <replaceable>PROJECT</replaceable> is the </section>
project name and has one of the following <section xml:id="cli_clients_install_packages">
values:</para> <title>Installing from packages</title>
<itemizedlist> <para>RDO and openSUSE have client packages that can be
<listitem> installed without <filename>pip</filename>.</para>
<para><literal>ceilometer</literal> - Telemetry API.</para> <para>On Red Hat Enterprise Linux, CentOS, or Fedora, use
</listitem> <command>yum</command> to install the clients from
<listitem> the packaged versions available in <link
<para><literal>cinder</literal> - Block Storage xlink:href="http://openstack.redhat.com/"
API and extensions.</para> >RDO</link>:
</listitem> <screen><prompt>#</prompt> <userinput>yum install python-<replaceable>PROJECT</replaceable>client</userinput></screen></para>
<listitem> <para>For openSUSE, use <package>rpm</package> or
<para><literal>glance</literal> - Image Service <package>zypper</package> to install the clients
API.</para> from the packaged versions available in <link
</listitem> xlink:href="https://build.opensuse.org/package/show?package=python-novaclient&amp;project=Cloud:OpenStack:Master"
<listitem> >the Open Build
<para><literal>heat</literal> - Orchestration Service</link>:<screen><prompt>#</prompt> <userinput>zypper install python-<replaceable>PROJECT</replaceable></userinput></screen></para>
API.</para> </section>
</listitem> </section>
<listitem> <section xml:id="cli_clients_remove_upgrade">
<para><literal>keystone</literal> - Identity <title>Upgrade or remove clients</title>
service API and extensions.</para> <para>To upgrade a client, add the
</listitem>
<listitem>
<para><literal>neutron</literal> - Networking
API.</para>
</listitem>
<listitem>
<para><literal>nova</literal> - Compute API and
extensions.</para>
</listitem>
<listitem>
<para><literal>swift</literal> - Object Storage
API.</para>
</listitem>
<listitem>
<para><literal>trove</literal> - Database Service
API.</para>
</listitem>
</itemizedlist>
<para>For example, to install the nova client, run
this command:</para>
<screen><prompt>#</prompt> <userinput>pip install python-novaclient</userinput></screen>
<para>To remove the nova client, run this
command:</para>
<screen><prompt>#</prompt> <userinput>pip uninstall python-novaclient</userinput></screen>
<note> <para>To upgrade a package, add the
<literal>--upgrade</literal> option to the <literal>--upgrade</literal> option to the
<command>pip</command> command.</para> <command>pip install</command> command:</para>
<para>For example, to update the <systemitem>nova</systemitem> client, run this <screen><prompt>#</prompt> <userinput>pip install --upgrade python-<replaceable>PROJECT</replaceable>client</userinput></screen>
command:</para> <para>To remove the a client, run the <command>pip
<screen><prompt>#</prompt> <userinput>pip install --upgrade python-novaclient</userinput></screen></note> uninstall</command> command:</para>
</step> <screen><prompt>#</prompt> <userinput>pip uninstall python-<replaceable>PROJECT</replaceable>client</userinput></screen>
<step audience="enduser"> </section>
<para>Before you can run client commands, you must <section xml:id="cli_clients_install_nextsteps" audience="enduser">
create and source the <title>What's next</title>
<para>Before you can run client commands, you must create
and source the
<filename><replaceable>PROJECT</replaceable>-openrc.sh</filename> <filename><replaceable>PROJECT</replaceable>-openrc.sh</filename>
file to set environment variables. See <xref file to set environment variables. See <xref
linkend="cli_openrc"/>.</para> linkend="cli_openrc"/>.</para>
</step>
</procedure>
</section> </section>
</section> </section>

215
doc/common/section_cli_nova_boot.xml
View File

@ -10,57 +10,46 @@
parameters:</para> parameters:</para>
<itemizedlist xml:id="instance_parameters"> <itemizedlist xml:id="instance_parameters">
<listitem> <listitem>
<para>The <guilabel>instance source</guilabel>, which is <para>The <guilabel>instance source</guilabel>. This can be an
an image or snapshot. Alternatively, you can boot from image, a snapshot, or a block storage volume that contains an
a volume, which is block storage, to which you've image or snapshot.</para>
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>
<listitem> <listitem>
<para>A <guilabel>name</guilabel> for your instance. <para>A <guilabel>name</guilabel> for your instance.
</para> </para>
</listitem> </listitem>
<listitem> <listitem>
<para>The <emphasis role="bold">flavor</emphasis> for your <para>The <emphasis role="bold">flavor</emphasis> for your instance,
instance, which defines the compute, memory, and which defines the compute, memory, and storage capacity of nova
storage capacity of nova computing instances. A flavor computing instances. A flavor is an available hardware
is an available hardware configuration for a server. configuration for a server. It defines the "size" of a virtual
It defines the "size" of a virtual server that can be server that can be launched.</para>
launched.</para>
</listitem> </listitem>
<listitem> <listitem>
<para><literal>User Data</literal> is a special key in the <para>Any <emphasis role="bold">user data</emphasis> files: A user
metadata service that holds a file that cloud-aware data file is a special key in the metadata service that holds a
applications in the guest instance can access. For file that cloud-aware applications in the guest instance can
example, the <link access. For example, one application that uses user data is the
<link
xlink:href="https://help.ubuntu.com/community/CloudInit" xlink:href="https://help.ubuntu.com/community/CloudInit"
>cloudinit</link> system is an open-source package >cloud-init</link> system, which is an open-source package
from Ubuntu that is available on various Linux from Ubuntu that is available on various Linux distributions and
distributions including Ubuntu, Fedora, and openSUSE which handles early initialization of a cloud instance.</para>
and that handles early initialization of a cloud
instance that uses <literal>user
data</literal>.</para>
</listitem> </listitem>
<listitem> <listitem>
<para>Access and security credentials, which include one <para>Access and security credentials, which include one
or both of the following credentials:</para> or both of the following credentials:</para>
<itemizedlist> <itemizedlist>
<listitem> <listitem>
<para>A <emphasis role="bold">keypair</emphasis> <para>A <emphasis role="bold">key pair</emphasis> for your
for your instance, which are SSH credentials instance, which are SSH credentials that are injected
that are injected into images when they are into images when they are launched. For the key pair to
launched. For this to work, the image must be successfully injected, the image must contain the
contain the <literal>cloud-init</literal> <literal>cloud-init</literal> package. Create at
package. Create at least one keypair for each least one key pair for each project. If you already have
project. If you already have generated a generated a key pair with an external tool, you can
keypair with an external tool, you can import import it into OpenStack. You can use the key pair for
it into OpenStack. You can use the keypair for multiple instances that belong to that project.</para>
multiple instances that belong to that
project.</para>
</listitem> </listitem>
<listitem> <listitem>
<para>A <emphasis role="bold">security <para>A <emphasis role="bold">security
@ -74,32 +63,42 @@
</itemizedlist> </itemizedlist>
</listitem> </listitem>
<listitem> <listitem>
<para>If needed, you can assign a <emphasis role="bold" <para>If needed, you can assign a <emphasis role="bold">floating
>floating (public) IP address</emphasis> to a (public) IP address</emphasis> to a running instance.
running instance and attach a block storage device, or </para>
volume, for persistent storage.</para>
</listitem> </listitem>
</itemizedlist> <listitem>
<para>After you gather the parameters you need to launch an <para>You can also attach a block storage device, or <emphasis
instance, you can launch it from an role="bold">volume</emphasis>, for persistent
<link linkend="launch_from_image">image</link> or a storage.</para>
<link linkend="boot_from_volume">volume</link>.</para> </listitem>
<para>You can launch an instance directly from one of the </itemizedlist><note>
available OpenStack images or from an image that you have <para>Instances that use the default security group cannot,
copied to a persistent volume. The OpenStack Image Service by default, be accessed from any IP address outside of
provides a pool of images that are accessible to members of the cloud. If you want those IP addresses to access the
instances, you must modify the rules for the default
security group.</para>
<para>You can also assign a floating IP address to a running
instance to make it accessible from outside the cloud.
See <xref linkend="manage_ip_addresses"/>.</para>
</note>
<para>After you gather the parameters that you need to launch an instance,
you can launch it from an <link linkend="launch_from_image">image</link>
or a <link linkend="boot_from_volume">volume</link>. 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> different projects.</para>
<?hard-pagebreak?> <?hard-pagebreak?>
<section xml:id="gather_parms"> <section xml:id="gather_parms">
<title wordsize="20">Gather parameters to launch an <title wordsize="20">Gather parameters to launch an
instance</title> instance</title>
<para>
Before you begin, source the OpenStack RC file.</para>
<procedure> <procedure>
<step> <step>
<para>On a shell, source the OpenStack RC file. See <para>List the available flavors and note the ID of the flavor
<xref linkend="cli_openrc"/>.</para> that you want to use for your instance.</para>
</step>
<step>
<para>List the available flavors:</para>
<screen><prompt>$</prompt> <userinput>nova flavor-list</userinput></screen> <screen><prompt>$</prompt> <userinput>nova flavor-list</userinput></screen>
<screen><?db-font-size 55%?><computeroutput>+----+-----------+-----------+------+-----------+------+-------+-------------+-----------+ <screen><?db-font-size 55%?><computeroutput>+----+-----------+-----------+------+-----------+------+-------+-------------+-----------+
| ID | Name | Memory_MB | Disk | Ephemeral | Swap | VCPUs | RXTX_Factor | Is_Public | | ID | Name | Memory_MB | Disk | Ephemeral | Swap | VCPUs | RXTX_Factor | Is_Public |
@ -110,11 +109,10 @@
| 4 | m1.large | 8192 | 80 | 0 | | 4 | 1.0 | True | | 4 | m1.large | 8192 | 80 | 0 | | 4 | 1.0 | True |
| 5 | m1.xlarge | 16384 | 160 | 0 | | 8 | 1.0 | True | | 5 | m1.xlarge | 16384 | 160 | 0 | | 8 | 1.0 | True |
+----+-----------+-----------+------+-----------+------+-------+-------------+-----------+</computeroutput></screen> +----+-----------+-----------+------+-----------+------+-------+-------------+-----------+</computeroutput></screen>
<para>Note the ID of the flavor that you want to use
for your instance.</para>
</step> </step>
<step> <step>
<para>List the available images:</para> <para>List the available images and note the ID of the image
from which you want to boot your instance.</para>
<screen><prompt>$</prompt> <userinput>nova image-list</userinput></screen> <screen><prompt>$</prompt> <userinput>nova image-list</userinput></screen>
<screen><?db-font-size 55%?><computeroutput>+--------------------------------------+---------------------------------+--------+--------+ <screen><?db-font-size 55%?><computeroutput>+--------------------------------------+---------------------------------+--------+--------+
| ID | Name | Status | Server | | ID | Name | Status | Server |
@ -123,18 +121,19 @@
| df430cc2-3406-4061-b635-a51c16e488ac | cirros-0.3.2-x86_64-uec-kernel | ACTIVE | | | df430cc2-3406-4061-b635-a51c16e488ac | cirros-0.3.2-x86_64-uec-kernel | ACTIVE | |
| 3cf852bd-2332-48f4-9ae4-7d926d50945e | cirros-0.3.2-x86_64-uec-ramdisk | ACTIVE | | | 3cf852bd-2332-48f4-9ae4-7d926d50945e | cirros-0.3.2-x86_64-uec-ramdisk | ACTIVE | |
+--------------------------------------+---------------------------------+--------+--------+</computeroutput></screen> +--------------------------------------+---------------------------------+--------+--------+</computeroutput></screen>
<para>You can also filter the image list by using grep <para>You can also filter the image list by using
to find a specific image, like this:</para> <command>grep</command> to find a specific image, as
follows:</para>
<screen><prompt>$</prompt> <userinput>nova image-list | grep 'kernel'</userinput></screen> <screen><prompt>$</prompt> <userinput>nova image-list | grep 'kernel'</userinput></screen>
<screen><?db-font-size 55%?><computeroutput>| df430cc2-3406-4061-b635-a51c16e488ac | cirros-0.3.2-x86_64-uec-kernel | ACTIVE | |</computeroutput></screen> <screen><?db-font-size 55%?><computeroutput>| df430cc2-3406-4061-b635-a51c16e488ac | cirros-0.3.2-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>
<step> <step>
<para>List the available security groups:</para> <para>List the available security groups and note the ID of the
security group that you want to use for your
instance.</para>
<note> <note>
<para>If you are an admin user, specify the <para>If you are an admin user, specify the
<literal>--all-tenants</literal> parameter <option>--all-tenants</option> parameter
to list groups for all tenants.</para> to list groups for all tenants.</para>
</note> </note>
<screen><prompt>$</prompt> <userinput>nova secgroup-list --all-tenants</userinput></screen> <screen><prompt>$</prompt> <userinput>nova secgroup-list --all-tenants</userinput></screen>
@ -147,18 +146,13 @@
<para>If you have not created any security groups, you <para>If you have not created any security groups, you
can assign the instance to only the default can assign the instance to only the default
security group.</para> security group.</para>
<para>You can also list rules for a specified security <para>You can view rules for a specified security group:</para>
group:</para>
<screen><prompt>$</prompt> <userinput>nova secgroup-list-rules default</userinput> </screen> <screen><prompt>$</prompt> <userinput>nova secgroup-list-rules default</userinput> </screen>
<para>This example modifies the default security group
to allow HTTP traffic on the instance by
permitting TCP traffic on Port 80.</para>
</step> </step>
<step> <step>
<para>List the available keypairs.</para> <para>List the available key pairs and note the name of the key
pair that you use for SSH access.</para>
<screen><prompt>$</prompt> <userinput>nova keypair-list</userinput></screen> <screen><prompt>$</prompt> <userinput>nova keypair-list</userinput></screen>
<para>Note the name of the keypair that you use for
SSH access.</para>
</step> </step>
</procedure> </procedure>
</section> </section>
@ -167,22 +161,33 @@
<title wordsize="20">Launch an instance from an image</title> <title wordsize="20">Launch an instance from an image</title>
<procedure> <procedure>
<step> <step>
<para>Now you have all parameters required to launch <para>After you have all the parameters required to launch an
an instance, run the following command and specify instance, run the following command and specify the server
the server name, flavor ID, and image ID. name, flavor ID, and image ID. Optionally, you can provide a
Optionally, you can provide a key name for access key name for access control and a security group for
control and security group for security. You can security. You can also include metadata key and value pairs.
also include metadata key and value pairs. For For example, you can add a description for your server by
example, you can add a description for your server providing the <parameter>--meta description="My
by providing the <parameter>--meta description="My
Server"</parameter> parameter.</para> Server"</parameter> parameter.</para>
<para>You can pass user data in a local file at <para>You can pass user data in a local file at instance launch
instance launch by using the flag by using the <parameter>--user-data
<parameter>--user-data
<replaceable>USER-DATA-FILE</replaceable></parameter> <replaceable>USER-DATA-FILE</replaceable></parameter>
parameter.</para> parameter.</para>
<screen><prompt>$</prompt> <userinput>nova boot --flavor <replaceable>FLAVOR_ID</replaceable> --image <replaceable>IMAGE_ID</replaceable> --key-name <replaceable>KEY_NAME</replaceable> \ <screen><prompt>$</prompt> <userinput>nova boot --flavor <replaceable>FLAVOR_ID</replaceable> --image <replaceable>IMAGE_ID</replaceable> --key-name <replaceable>KEY_NAME</replaceable> \
--user-data mydata.file --security-groups <replaceable>SEC_GROUP</replaceable> --meta <replaceable>KEY=VALUE</replaceable> \ --user-data <replaceable>USER_DATA_FILE</replaceable> --security-groups <replaceable>SEC_GROUP</replaceable> --meta <replaceable>KEY=VALUE</replaceable> \
<replaceable>INSTANCE_NAME</replaceable></userinput></screen>
<para>The following example shows a the command for launching an
instance called <literal>MyCirrosServer</literal> with the
<literal>m1.small</literal> flavor (ID of
<literal>1</literal>),
<literal>cirros-0.3.2-x86_64-uec</literal> image (ID
of
<literal>397e713c-b95b-4186-ad46-6126863ea0a9</literal>),
the <literal>default</literal> security group, the
<literal>KeyPair01</literal> key, and a user data file
called <filename>cloudinit.file</filename>.</para>
<screen><prompt>$</prompt> <userinput>nova boot --flavor 1 --image 397e713c-b95b-4186-ad46-6126863ea0a9 \
--security-groups default --key-name KeyPair01 --user-data cloudinit.file \
<replaceable>myCirrosServer</replaceable></userinput></screen> <replaceable>myCirrosServer</replaceable></userinput></screen>
<para>Depending on the parameters that you provide, <para>Depending on the parameters that you provide,
the command returns a list of server the command returns a list of server
@ -227,31 +232,29 @@
use this ID to get details for or delete your use this ID to get details for or delete your
server.</para> server.</para>
<para>Copy the administrative password value from the <para>Copy the administrative password value from the
<literal>adminPass</literal> field. You use <literal>adminPass</literal> field. You use this value
this value to log into your server.</para> to log in to your server.</para>
<note> <note>
<para>Arbitrary local files can also be placed <para>You can also place arbitrary local files into the
into the instance file system at creation time instance file system at creation time by using the
using the <literal>--file <option>--file &lt;dst-path=src-path&gt;</option>
&lt;dst-path=src-path&gt;</literal> option. You can store up to five files. For example, if
option. You may store up to 5 files. For you have a special authorized keys file named
example, if you have a special authorized_keys
file named
<filename>special_authorized_keysfile</filename> <filename>special_authorized_keysfile</filename>
that you want to put on the instance rather that you want to put on the instance rather than using
than using the regular ssh key injection, you the regular SSH key injection, you can use the
can use the following <option>--file</option> option as shown in the
command:<screen><prompt>$</prompt> <userinput><?db-font-size 75%?>nova boot --image ubuntu-cloudimage --flavor 1 vm-name \ following
example:<screen><prompt>$</prompt> <userinput><?db-font-size 75%?>nova boot --image ubuntu-cloudimage --flavor 1 vm-name \
--file /root/.ssh/authorized_keys=special_authorized_keysfile</userinput></screen></para> --file /root/.ssh/authorized_keys=special_authorized_keysfile</userinput></screen></para>
</note> </note>
</step> </step>
<step> <step>
<para>Check if the instance is online:</para> <para>Check if the instance is online:</para>
<screen><prompt>$</prompt> <userinput><?db-font-size 75%?>nova list</userinput></screen> <screen><prompt>$</prompt> <userinput><?db-font-size 75%?>nova list</userinput></screen>
<para>The list shows the ID, name, status, and private <para>The list shows the ID, name, status, and private (and if
(and if assigned, public) IP addresses for all assigned, public) IP addresses for all instances in the
instances in the project that you belong project to which you belong:</para>
to:</para>
<screen><?db-font-size 50%?><computeroutput>+--------------------------------------+----------------------+--------+------------+-------------+------------------+ <screen><?db-font-size 50%?><computeroutput>+--------------------------------------+----------------------+--------+------------+-------------+------------------+
| ID | Name | Status | Task State | Power State | Networks | | ID | Name | Status | Task State | Power State | Networks |
+--------------------------------------+----------------------+--------+------------+-------------+------------------+ +--------------------------------------+----------------------+--------+------------+-------------+------------------+
@ -265,14 +268,10 @@
following command:</para> following command:</para>
<screen><prompt>$</prompt> <userinput><?db-font-size 75%?>nova help list</userinput></screen> <screen><prompt>$</prompt> <userinput><?db-font-size 75%?>nova help list</userinput></screen>
</step> </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>
</step>
</procedure> </procedure>
</section> <note><para>If you did not provide a key pair, security groups, or rules, you can
<?hard-pagebreak?> access the instance only from inside the cloud through VNC. Even
pinging the instance is not possible.</para></note>
</section><?hard-pagebreak?>
<xi:include href="section_cli_nova_boot_from_volume.xml"/> <xi:include href="section_cli_nova_boot_from_volume.xml"/>
</section> </section>

45
doc/common/section_cli_nova_manage_images.xml
View File

@ -3,27 +3,25 @@
xmlns:xi="http://www.w3.org/2001/XInclude" xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
xml:id="nova_manage_images"> xml:id="nova_manage_images">
<title>Create image (nova)</title> <title>Create an image (nova)</title>
<para>You can use the nova client to list images, set and delete <para>You can use the <command>nova</command> client to take a snapshot of a
image metadata, delete images, and take a snapshot of a
running instance to create an image.</para> running instance to create an image.</para>
<para>The safest approach is to shut down the instance before you <para>To minimize the potential for data loss and ensure that you create an
take a snapshot.</para> accurate image, you should shut down the instance before you take a
<para>You cannot create a snapshot from an instance that has an snapshot.</para>
attached volume. Detach the volume, create the image, and <para>You cannot create a snapshot from an instance that has an attached
re-mount the volume.</para> volume. Detach the volume, create the image, and remount the
volume.</para>
<procedure> <procedure>
<step> <step>
<para>Write any buffered data to disk.</para> <para>Write any buffered data to disk.</para>
<para>For more information, see <link <para>For more information, see <link xlink:href="http://docs.openstack.org/trunk/openstack-ops/content/snapshots.html"
xlink:href="http://docs.openstack.org/trunk/openstack-ops/content/snapshots.html"
>Taking Snapshots</link> in the >Taking Snapshots</link> in the
<citetitle>OpenStack Operations <citetitle>OpenStack Operations
Guide</citetitle>.</para> Guide</citetitle>.</para>
</step> </step>
<step> <step>
<para>To create the image, list instances to get the <para>List instances to get the server name:</para>
server ID:</para>
<screen><prompt>$</prompt> <userinput>nova list</userinput> <screen><prompt>$</prompt> <userinput>nova list</userinput>
<?db-font-size 50%?><computeroutput>+--------------------------------------+----------------------+--------+------------+-------------+------------------+ <?db-font-size 50%?><computeroutput>+--------------------------------------+----------------------+--------+------------+-------------+------------------+
| ID | Name | Status | Task State | Power State | Networks | | ID | Name | Status | Task State | Power State | Networks |
@ -31,17 +29,16 @@
| 84c6e57d-a6b1-44b6-81eb-fcb36afd31b5 | myCirrosServer | ACTIVE | None | Running | private=10.0.0.3 | | 84c6e57d-a6b1-44b6-81eb-fcb36afd31b5 | myCirrosServer | ACTIVE | None | Running | private=10.0.0.3 |
+--------------------------------------+----------------------+--------+------------+-------------+------------------+</computeroutput></screen> +--------------------------------------+----------------------+--------+------------+-------------+------------------+</computeroutput></screen>
<para>In this example, the server is named <para>In this example, the server is named
<literal>myCirrosServer</literal>. Use this server <literal>myCirrosServer</literal>.</para></step>
to create a snapshot, as follows: <step><para>Use this server to create a snapshot:
<screen><prompt>$</prompt> <userinput>nova image-create myCirrosServer myCirrosImage</userinput></screen>The <screen><prompt>$</prompt> <userinput>nova image-create myCirrosServer myCirrosImage</userinput></screen>The
command creates a qemu snapshot and automatically command creates a qemu snapshot and automatically uploads the
uploads the image to your repository. Only the tenant image to your repository. Only the tenant that creates the image
that creates the image has access to it.</para> has access to it.</para>
</step> </step>
<step> <step>
<para>Get details for your image to check its <para>Get details for your image to check its status:</para>
status:</para> <screen><prompt>$</prompt> <userinput>nova image-show myCirrosImage</userinput>
<screen><prompt>$</prompt> <userinput>nova image-show <replaceable>IMAGE</replaceable></userinput>
<?db-font-size 50%?><computeroutput>+-------------------------------------+--------------------------------------+ <?db-font-size 50%?><computeroutput>+-------------------------------------+--------------------------------------+
| Property | Value | | Property | Value |
+-------------------------------------+--------------------------------------+ +-------------------------------------+--------------------------------------+
@ -80,9 +77,9 @@
<literal>ACTIVE</literal>. Only the tenant who <literal>ACTIVE</literal>. Only the tenant who
creates the image has access to it.</para> creates the image has access to it.</para>
</step> </step>
<step> </procedure>
<para>To launch an instance from your image, include the <para>To launch an instance from your image, include the image ID
image ID and flavor ID, as follows:</para> and flavor ID, as in the following example:</para>
<screen><prompt>$</prompt> <userinput>nova boot newServer --image 7e5142af-1253-4634-bcc6-89482c5f2e8a \ <screen><prompt>$</prompt> <userinput>nova boot newServer --image 7e5142af-1253-4634-bcc6-89482c5f2e8a \
--flavor 3</userinput> --flavor 3</userinput>
<?db-font-size 50%?><computeroutput>+-------------------------------------+--------------------------------------+ <?db-font-size 50%?><computeroutput>+-------------------------------------+--------------------------------------+
@ -115,6 +112,4 @@
| created | 2013-07-22T19:58:33Z | | created | 2013-07-22T19:58:33Z |
| metadata | {} | | metadata | {} |
+-------------------------------------+--------------------------------------+</computeroutput></screen> +-------------------------------------+--------------------------------------+</computeroutput></screen>
</step>
</procedure>
</section> </section>

18
doc/common/section_cli_nova_userdata.xml
View File

@ -1,19 +1,17 @@
<?xml version="1.0" encoding="UTF-8"?> <?xml version="1.0" encoding="UTF-8"?>
<!-- moved to launch instances file -->
<section xmlns="http://docbook.org/ns/docbook" <section xmlns="http://docbook.org/ns/docbook"
xmlns:xi="http://www.w3.org/2001/XInclude" xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
xml:id="inserting_userdata"> xml:id="inserting_userdata">
<title>Provide user data to instances</title> <title>Provide user data to instances</title>
<para><glossterm baseform="user data">User data</glossterm> is a <para>A <glossterm baseform="user data">user data</glossterm> file is a special key in the metadata service that
special key in the holds a file that cloud-aware applications in the guest instance
metadata service that holds a file that cloud-aware applications can access. For example, one application that uses user data is
in the guest instance can access. For example the <link the <link xlink:href="https://help.ubuntu.com/community/CloudInit"
xlink:href="https://help.ubuntu.com/community/CloudInit" xmlns:raxm="http://docs.rackspace.com/api/metadata"
><package>cloudinit</package></link> system is a Ubuntu open >cloud-init</link> system, which is an open-source package from
source package that handles early initialization of a cloud Ubuntu that is available on various Linux distributions and which
instance and that makes use of <literal>user handles early initialization of a cloud instance.</para>
data</literal>.</para>
<para>You can place user data in a local file and pass it through <para>You can place user data in a local file and pass it through
the <parameter>--user-data &lt;user-data-file&gt;</parameter> the <parameter>--user-data &lt;user-data-file&gt;</parameter>
parameter at instance creation:</para> parameter at instance creation:</para>

98
doc/common/section_cli_openrc.xml
View File

@ -4,9 +4,11 @@
xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
xml:id="cli_openrc"> xml:id="cli_openrc">
<?dbhtml stop-chunking?> <?dbhtml stop-chunking?>
<title>The OpenStack RC file</title> <title>Set environment variables using the OpenStack RC
file</title>
<para>To set the required environment variables for the OpenStack <para>To set the required environment variables for the OpenStack
command-line clients, you must create an environment command-line clients, you must create an environment file
called an OpenStack rc file, or <filename>openrc.sh</filename>
file.<phrase audience="enduser"> If your OpenStack file.<phrase audience="enduser"> If your OpenStack
installation provides it, you can download the file from installation provides it, you can download the file from
the OpenStack dashboard as an administrative user or any the OpenStack dashboard as an administrative user or any
@ -18,11 +20,10 @@
commands to communicate with the OpenStack services that run commands to communicate with the OpenStack services that run
in the cloud.</para> in the cloud.</para>
<note> <note>
<title>Environment variables on Microsoft Windows</title>
<para>Defining environment variables using an environment file is not a <para>Defining environment variables using an environment file is not a
common practice on Microsoft Windows. Environment variables are usually common practice on Microsoft Windows. Environment variables are usually
defined in the <literal>Advanced</literal> tab of the <literal>System defined in the <guilabel>Advanced</guilabel> tab of the System
Properties</literal> dialog.</para> Properties dialog box.</para>
</note> </note>
<section xml:id="openrc-dashboard" audience="enduser"> <section xml:id="openrc-dashboard" audience="enduser">
<title>Download and source the OpenStack RC file</title> <title>Download and source the OpenStack RC file</title>
@ -34,32 +35,32 @@
&amp; Security</guibutton>.</para> &amp; Security</guibutton>.</para>
</step> </step>
<step> <step>
<para> <para>On the API Access tab, click <guibutton>Download
Click on the API Access tab. Click OpenStack RC File</guibutton> and save the
<guibutton>Download OpenStack RC File</guibutton> file. The filename will be of the form
and save the file. The filename will be of the form
<filename><replaceable>PROJECT</replaceable>-openrc.sh</filename> <filename><replaceable>PROJECT</replaceable>-openrc.sh</filename>
where <replaceable>PROJECT</replaceable> is the name where <replaceable>PROJECT</replaceable> is the
of the project for which you downloaded the file. name of the project for which you downloaded the
</para> file.</para>
</step> </step>
<step> <step>
<para>Copy the <para>Copy the
<filename><replaceable>PROJECT</replaceable>-openrc.sh</filename> <filename><replaceable>PROJECT</replaceable>-openrc.sh</filename>
file to the machine from where you want to run file to the computer from which you want to run
OpenStack commands.</para> OpenStack commands.</para>
<para>For example, copy the file to the machine from <para>For example, copy the file to the computer from
where you want to upload an image with a glance which you want to upload an image with a
client command.</para> <command>glance</command> client
command.</para>
</step> </step>
<step> <step>
<para>On any shell from where you want to run <para>On any shell from which you want to run
OpenStack commands, source the OpenStack commands, source the
<filename><replaceable>PROJECT</replaceable>-openrc.sh</filename> <filename><replaceable>PROJECT</replaceable>-openrc.sh</filename>
file for the respective project.</para> file for the respective project.</para>
<para>In this example, you source the <para>In the following example, the
<filename>demo-openrc.sh</filename> file for <filename>demo-openrc.sh</filename> file is
the demo project:</para> sourced for the demo project:</para>
<screen><prompt>$</prompt> <userinput>source demo-openrc.sh</userinput></screen> <screen><prompt>$</prompt> <userinput>source demo-openrc.sh</userinput></screen>
</step> </step>
<step> <step>
@ -73,32 +74,41 @@
<section xml:id="openrc-create"> <section xml:id="openrc-create">
<title>Create and source the OpenStack RC file</title> <title>Create and source the OpenStack RC file</title>
<para audience="enduser">Alternatively, you can create the <para audience="enduser">Alternatively, you can create the
<filename><replaceable>PROJECT</replaceable>-openrc.sh</filename> file from <filename><replaceable>PROJECT</replaceable>-openrc.sh</filename>
scratch.</para> file from scratch, if for some reason you cannot download
the file from the dashboard.</para>
<procedure> <procedure>
<step> <step>
<para>Create the <filename><replaceable>PROJECT</replaceable>-openrc.sh</filename> file <para>In a text editor, create a file named
and add the authentication information:</para> <filename><replaceable>PROJECT</replaceable>-openrc.sh</filename>
<programlisting language="bash" audience="enduser">export OS_USERNAME=<replaceable>USERNAME</replaceable> file and add the following authentication
export OS_PASSWORD=<replaceable>PASSWORD</replaceable> information:</para>
export OS_TENANT_NAME=<replaceable>PROJECT_NAME</replaceable> <programlisting language="bash" audience="enduser">export OS_USERNAME=<replaceable>username</replaceable>
export OS_AUTH_URL=<replaceable>https://IDENTITY_HOST:PORT/v2.0</replaceable> export OS_PASSWORD=<replaceable>password</replaceable>
export OS_TENANT_NAME=<replaceable>projectName</replaceable>
export OS_AUTH_URL=<replaceable>https://identityHost:portNumber/v2.0</replaceable>
# The following lines can be omitted # The following lines can be omitted
export OS_TENANT_ID=<replaceable>9d792532ffce494583138c495801d164</replaceable> export OS_TENANT_ID=<replaceable>tenantIDString</replaceable>
export OS_REGION_NAME=<replaceable>RegionOne</replaceable></programlisting> export OS_REGION_NAME=<replaceable>regionName</replaceable></programlisting>
<para>The following example shows the information for
a project called <literal>admin</literal>, where
the OS username is also <literal>admin</literal>,
and the identity host is located at
<literal>controller</literal>.</para>
<programlisting language="bash" audience="installer">export OS_USERNAME=admin <programlisting language="bash" audience="installer">export OS_USERNAME=admin
export OS_PASSWORD=<replaceable>ADMIN_PASS</replaceable> export OS_PASSWORD=<replaceable>ADMIN_PASS</replaceable>
export OS_TENANT_NAME=admin export OS_TENANT_NAME=admin
export OS_AUTH_URL=http://<replaceable>controller</replaceable>:35357/v2.0</programlisting> export OS_AUTH_URL=http://controller:35357/v2.0</programlisting>
</step> </step>
<step> <step>
<para>On any shell from where you want to run <para>On any shell from which you want to run
OpenStack commands, source the OpenStack commands, source the
<filename><replaceable>PROJECT</replaceable>-openrc.sh</filename> <filename><replaceable>PROJECT</replaceable>-openrc.sh</filename>
file for the file for the respective project. In this example,
respective project. In this example, you source the you source the
<filename>admin-openrc.sh</filename> file for <filename>admin-openrc.sh</filename> file for
the <replaceable>admin</replaceable> project:</para> the <replaceable>admin</replaceable>
project:</para>
<screen><prompt>$</prompt> <userinput>source admin-openrc.sh</userinput></screen> <screen><prompt>$</prompt> <userinput>source admin-openrc.sh</userinput></screen>
</step> </step>
</procedure> </procedure>
@ -106,12 +116,12 @@ export OS_AUTH_URL=http://<replaceable>controller</replaceable>:35357/v2.0</prog
<para>You are not prompted for the password with this <para>You are not prompted for the password with this
method. The password lives in clear text format in the method. The password lives in clear text format in the
<filename><replaceable>PROJECT</replaceable>-openrc.sh</filename> <filename><replaceable>PROJECT</replaceable>-openrc.sh</filename>
file. Restrict the file. Restrict the permissions on this file to avoid
permissions on this file to avoid security problems. security problems. You can also remove the
You can also remove the <literal>OS_PASSWORD</literal> <literal>OS_PASSWORD</literal> variable from the
variable from the file, and use the file, and use the <parameter>--password</parameter>
<parameter>--password</parameter> parameter with parameter with OpenStack client commands
OpenStack client commands.</para> instead.</para>
</note> </note>
</section> </section>
<section xml:id="override-variables"> <section xml:id="override-variables">
@ -122,11 +132,9 @@ export OS_AUTH_URL=http://<replaceable>controller</replaceable>:35357/v2.0</prog
of the various client commands. For example, you can override of the various client commands. For example, you can override
the <option>OS_PASSWORD</option> setting in the the <option>OS_PASSWORD</option> setting in the
<filename><replaceable>PROJECT</replaceable>-openrc.sh</filename> <filename><replaceable>PROJECT</replaceable>-openrc.sh</filename>
file by specifying a file by specifying a password on a <command>keystone</command> command, as
password on a <command>keystone</command> command, as
follows:</para> follows:</para>
<screen><prompt>$</prompt> <userinput>keystone --os-password <replaceable>PASSWORD</replaceable> service-list</userinput></screen> <screen><prompt>$</prompt> <userinput>keystone --os-password <replaceable>PASSWORD</replaceable> service-list</userinput></screen>
<para>Where <replaceable>PASSWORD</replaceable> is your <para>Where <replaceable>PASSWORD</replaceable> is your password.</para>
password.</para>
</section> </section>
</section> </section>

24
doc/common/section_cli_overview.xml
View File

@ -12,11 +12,10 @@
xmlns:raxm="http://docs.rackspace.com/api/metadata" version="5.0" xmlns:raxm="http://docs.rackspace.com/api/metadata" version="5.0"
xml:id="section_cli_overview"> xml:id="section_cli_overview">
<title>Overview</title> <title>Overview</title>
<para>You can use the OpenStack command-line clients to run simple <para>You can use the OpenStack command-line clients to run simple commands
commands that make API calls. You can run these commands from that make API calls. You can run these commands from the command line or
the command line or in scripts to automate tasks. As long as in scripts to automate tasks. If you provide OpenStack credentials, you
you provide OpenStack credentials, you can run these commands can run these commands on any computer.</para>
on any machine.</para>
<para>Internally, each client command runs cURL commands that <para>Internally, each client command runs cURL commands that
embed API requests. The OpenStack APIs are RESTful APIs that embed API requests. The OpenStack APIs are RESTful APIs that
use the HTTP protocol, including methods, URIs, media types, use the HTTP protocol, including methods, URIs, media types,
@ -24,17 +23,12 @@
<para>These open-source Python clients run on Linux or Mac OS X <para>These open-source Python clients run on Linux or Mac OS X
systems and are easy to learn and use. Each OpenStack service systems and are easy to learn and use. Each OpenStack service
has its own command-line client. On some client commands, you has its own command-line client. On some client commands, you
can specify a <parameter can specify a <command>debug</command>
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 to show the underlying API request for the command. parameter to show the underlying API request for the command.
This is a good way to become familiar with the OpenStack API This is a good way to become familiar with the OpenStack API
calls.</para> calls.</para>
<para>The following table lists the command-line client for each <para>The following table lists the command-line client for each OpenStack
OpenStack service, together with its service with its package name and description.</para>
package name and description.</para>
<table rules="all"> <table rules="all">
<caption>OpenStack services and clients</caption> <caption>OpenStack services and clients</caption>
<col width="15%"/> <col width="15%"/>
@ -84,8 +78,8 @@
<td>Networking</td> <td>Networking</td>
<td><command>neutron</command></td> <td><command>neutron</command></td>
<td><package>python-neutronclient</package></td> <td><package>python-neutronclient</package></td>
<td>Configure networks for guest servers. This client was previously known as <td>Configure networks for guest servers. This client was
<command>quantum</command>.</td> previously called <command>quantum</command>.</td>
</tr> </tr>
<tr> <tr>
<td>Object Storage</td> <td>Object Storage</td>

59
doc/common/section_cli_version.xml
View File

@ -3,57 +3,14 @@
xmlns:xi="http://www.w3.org/2001/XInclude" xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
xml:id="checking_version_cli"> xml:id="checking_version_cli">
<title>Get the version for a client</title> <title>Discover the version number for a client</title>
<para>Run this command get the version number for a <para>Run the following command to discover the version number
client:</para> for a client:</para>
<screen><prompt>$</prompt> <userinput><replaceable>PROJECT</replaceable> --version</userinput></screen> <screen><prompt>$</prompt> <userinput><replaceable>PROJECT</replaceable> --version</userinput></screen>
<para>Where <replaceable>PROJECT</replaceable> is a project
name:</para>
<itemizedlist>
<listitem>
<para><literal>ceilometer</literal> - Telemetry API.</para>
</listitem>
<listitem>
<para><literal>cinder</literal> - Block Storage
API and extensions.</para>
</listitem>
<listitem>
<para><literal>glance</literal> - Image Service
API.</para>
</listitem>
<listitem>
<para><literal>heat</literal> - Orchestration
API.</para>
</listitem>
<listitem>
<para><literal>keystone</literal> - Identity
service API and extensions.</para>
</listitem>
<listitem>
<para><literal>neutron</literal> - Networking
API.</para>
</listitem>
<listitem>
<para><literal>nova</literal> - Compute API and
extensions.</para>
</listitem>
<listitem>
<para><literal>swift</literal> - Object Storage
API.</para>
</listitem>
<listitem>
<para><literal>trove</literal> - Database Service
API.</para>
</listitem>
</itemizedlist>
<para>For example, to see the version number for the <para>For example, to see the version number for the
<command>nova</command> client, run this <command>nova</command> client, run the
command:</para> following command:</para>
<screen><prompt>$</prompt> <userinput>nova --version</userinput> <screen><prompt>$</prompt> <userinput>nova --version</userinput></screen>
<computeroutput>2.15.0</computeroutput></screen> <para>The version number (2.15.0 in the example) is returned.</para>
<para>To see the version number for the <screen><computeroutput>2.15.0</computeroutput></screen>
<command>keystone</command> client, run this
command:</para>
<screen><prompt>$</prompt> <userinput>keystone --version</userinput>
<computeroutput>0.4.0</computeroutput></screen>
</section> </section>

22
doc/user-guide/bk-user-guide.xml
View File

@ -35,12 +35,13 @@
</annotation> </annotation>
</legalnotice> </legalnotice>
<abstract> <abstract>
<para>OpenStack is an open-source cloud computing platform for <para>OpenStack is an open-source cloud computing platform
public and private clouds. A series of interrelated projects for public and private clouds. A series of
deliver a cloud infrastructure solution. This guide shows interrelated projects deliver a cloud infrastructure
OpenStack end users how to create and manage resources in an solution. This guide shows OpenStack end users how to
OpenStack cloud with the OpenStack dashboard and OpenStack create and manage resources in an OpenStack cloud with
client commands.</para> the OpenStack dashboard and OpenStack client
commands.</para>
</abstract> </abstract>
<revhistory> <revhistory>
<revision> <revision>
@ -52,8 +53,7 @@
information is now in the <link information is now in the <link
xlink:href="http://docs.openstack.org/cli-reference/content/" xlink:href="http://docs.openstack.org/cli-reference/content/"
><citetitle>OpenStack Command-Line ><citetitle>OpenStack Command-Line
Interface Interface Reference</citetitle></link>.</para>
Reference</citetitle></link>.</para>
</listitem> </listitem>
</itemizedlist> </itemizedlist>
</revdescription> </revdescription>
@ -63,7 +63,8 @@
<revdescription> <revdescription>
<itemizedlist> <itemizedlist>
<listitem> <listitem>
<para>Added the OpenStack Python SDK chapter.</para> <para>Added the OpenStack Python SDK
chapter.</para>
</listitem> </listitem>
</itemizedlist> </itemizedlist>
</revdescription> </revdescription>
@ -93,7 +94,8 @@
<revdescription> <revdescription>
<itemizedlist> <itemizedlist>
<listitem> <listitem>
<para>First edition of this document.</para> <para>First edition of this
document.</para>
</listitem> </listitem>
</itemizedlist> </itemizedlist>
</revdescription> </revdescription>

273
doc/user-guide/section_cli_nova_configure_instances.xml
View File

@ -16,38 +16,35 @@
xml:id="cli_configure_instances"> xml:id="cli_configure_instances">
<title>Configure access and security for instances</title> <title>Configure access and security for instances</title>
<?dbhtml stop-chunking?> <?dbhtml stop-chunking?>
<para>When you launch a virtual machine, you can inject a <para>When you launch a virtual machine, you can inject a <emphasis
<emphasis role="italic">keypair</emphasis>, which provides role="italic">key pair</emphasis>, which provides SSH access to your
SSH access to your instance. For this to work, the image must instance. For this to work, the image must contain the
contain the <literal>cloud-init</literal> package. Create at <literal>cloud-init</literal> package.</para>
least one keypair for each project. If you generate a keypair <para>You create at least one key pair for each project. You can use the key
with an external tool, you can import it into OpenStack. You pair for multiple instances that belong to that project. If you generate
can use the keypair for multiple instances that belong to that a key pair with an external tool, you can import it into OpenStack.</para>
project. In case an image uses a static root password or a <para>If an image uses a static root password or a static key set &ndash;
static key set &ndash; neither is recommended &ndash; you must neither is recommended &ndash; you must not provide a key pair when you
not provide a keypair when you launch the instance.</para> launch the instance.</para>
<para>A <emphasis role="italic">security group</emphasis> is a <para>A <emphasis role="italic">security group</emphasis> is a named
named collection of network access rules that you use to limit collection of network access rules that you use to limit the types of
the types of traffic that have access to instances. When you traffic that have access to instances. When you launch an instance, you
launch an instance, you can assign one or more security groups can assign one or more security groups to it. If you do not create
to it. If you do not create security groups, new instances are security groups, new instances are automatically assigned to the default
automatically assigned to the default security group, unless security group, unless you explicitly specify a different security
you explicitly specify a different security group. The group.</para>
associated <emphasis role="italic">rules</emphasis> in each <para>The associated <emphasis role="italic">rules</emphasis> in each
security group control the traffic to instances in the group. security group control the traffic to instances in the group. Any
Any incoming traffic that is not matched by a rule is denied incoming traffic that is not matched by a rule is denied access by
access by default. You can add rules to or remove rules from a default. You can add rules to or remove rules from a security group, and
security group. You can modify rules for the default and any you can modify rules for the default and any other security
other security group.</para> group.</para>
<para>You must modify the rules for the default security group <para>You can modify the rules in a security group to allow access to
because users cannot access instances that use the default instances through different ports and protocols. For example, you can
group from any IP address outside the cloud.</para> modify rules to allow access to instances through SSH, to ping
<para>You can modify the rules in a security group to allow access instances, or to allow UDP traffic; for example, for a DNS server
to instances through different ports and protocols. For running on an instance. You specify the following parameters for
example, you can modify rules to allow access to instances rules:</para>
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> <itemizedlist>
<listitem> <listitem>
<para><emphasis role="bold">Source of traffic</emphasis>. <para><emphasis role="bold">Source of traffic</emphasis>.
@ -61,45 +58,42 @@
</listitem> </listitem>
<listitem> <listitem>
<para><emphasis role="bold">Destination port on virtual <para><emphasis role="bold">Destination port on virtual
machine</emphasis>. Defines a port range. To open machine</emphasis>. Define a port range. To open a single
a single port only, enter the same value twice. ICMP port only, enter the same value twice. ICMP does not support
does not support ports: Enter values to define the ports; instead, you enter values to define the codes and types
codes and types of ICMP traffic to be allowed.</para> of ICMP traffic to be allowed.</para>
</listitem> </listitem>
</itemizedlist> </itemizedlist>
<para>Rules are automatically enforced as soon as you create or <para>Rules are automatically enforced as soon as you create or
modify them.</para> modify them.</para>
<para>You can also assign a floating IP address to a running <note>
instance to make it accessible from outside the cloud. You <para>Instances that use the default security group cannot, by default, be
assign a floating IP address to an instance and attach a block accessed from any IP address outside of the cloud. If you want those IP
storage device, or volume, for persistent storage. See <xref addresses to access the instances, you must modify the rules for the
linkend="manage_ip_addresses"/>.</para> default security group.</para>
<para>You can also assign a floating IP address to a running instance to
make it accessible from outside the cloud. See <xref
linkend="manage_ip_addresses"/>.</para></note>
<?hard-pagebreak?> <?hard-pagebreak?>
<section xml:id="create_import_keys"> <section xml:id="create_import_keys">
<title>Add a key pair</title> <title>Add a key pair</title>
<procedure> <procedure>
<para>You can generate a keypair or upload an existing <para>You can generate a key pair or upload an existing public
public key.</para> key.</para>
<step> <step>
<para>To generate a keypair, run the following <para>To generate a key pair, run the following command:</para>
command:</para>
<screen><prompt>$</prompt> <userinput>nova keypair-add <replaceable>KEY_NAME</replaceable> > <replaceable>MY_KEY</replaceable>.pem</userinput></screen> <screen><prompt>$</prompt> <userinput>nova keypair-add <replaceable>KEY_NAME</replaceable> > <replaceable>MY_KEY</replaceable>.pem</userinput></screen>
<para>The command generates a keypair named <para>The command generates a key pair with the name that you
<replaceable>KEY_NAME</replaceable>, writes specify fir <replaceable>KEY_NAME</replaceable>, writes the
the private key to the private key to the <filename>.pem</filename> file that you
<filename><replaceable>MY_KEY</replaceable>.pem</filename> specify, and registers the public key at the Nova
file, and registers the public key at the Nova
database.</para> database.</para>
</step> </step>
<step> <step>
<para>To set the permissions of the <para>To set the permissions of the <filename>.pem</filename>
<filename><replaceable>MY_KEY</replaceable>.pem</filename> file so that only you can read and write to it, run the
file, run the following command:</para> following command:</para>
<screen><prompt>$</prompt> <userinput>chmod 600 <replaceable>MY_KEY</replaceable>.pem</userinput></screen> <screen><prompt>$</prompt> <userinput>chmod 600 <replaceable>MY_KEY</replaceable>.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>
</procedure> </procedure>
</section> </section>
@ -107,19 +101,17 @@
<title>Import a key pair</title> <title>Import a key pair</title>
<procedure> <procedure>
<step> <step>
<para>If you have already generated a keypair with the <para>If you have already generated a key pair and the public
public key located at key is located at <filename>~/.ssh/id_rsa.pub</filename>,
<filename>~/.ssh/id_rsa.pub</filename>, run run the following command to upload the public key:</para>
the following command to upload the public
key:</para>
<screen><prompt>$</prompt> <userinput>nova keypair-add --pub_key ~/.ssh/id_rsa.pub <replaceable>KEY_NAME</replaceable></userinput></screen> <screen><prompt>$</prompt> <userinput>nova keypair-add --pub_key ~/.ssh/id_rsa.pub <replaceable>KEY_NAME</replaceable></userinput></screen>
<para>The command registers the public key at the Nova <para>The command registers the public key at the Nova database
database and names the keypair and names the key pair the name that you specify for
<literal><replaceable>KEY_NAME</replaceable></literal>.</para> <literal><replaceable>KEY_NAME</replaceable></literal>.</para>
</step> </step>
<step> <step>
<para>List keypairs to make sure that the uploaded <para>To ensure that the key pair has been successfully
keypair appears in the list:</para> imported, list key pairs as follows:</para>
<screen><prompt>$</prompt> <userinput>nova keypair-list</userinput></screen> <screen><prompt>$</prompt> <userinput>nova keypair-list</userinput></screen>
</step> </step>
</procedure> </procedure>
@ -128,21 +120,20 @@
<title>Create and manage security groups</title> <title>Create and manage security groups</title>
<procedure> <procedure>
<step> <step>
<para>To list security groups for the current project, <para>To list the security groups for the current project,
including descriptions, enter the following including descriptions, enter the following command:</para>
command:</para>
<screen><prompt>$</prompt> <userinput>nova secgroup-list</userinput></screen> <screen><prompt>$</prompt> <userinput>nova secgroup-list</userinput></screen>
</step> </step>
<step> <step>
<para>To create a security group with a specified name <para>To create a security group with a specified name
and description, enter the following and description, enter the following
command:</para> command:</para>
<screen><prompt>$</prompt> <userinput>nova secgroup-create <replaceable>SEC_GROUP_NAME</replaceable> <replaceable>GROUP_DESCRIPTION</replaceable></userinput></screen> <screen><prompt>$</prompt> <userinput>nova secgroup-create <replaceable>SECURITY_GROUP_NAME</replaceable> <replaceable>GROUP_DESCRIPTION</replaceable></userinput></screen>
</step> </step>
<step> <step>
<para>To delete a specified group, enter the following <para>To delete a specified group, enter the following
command:</para> command:</para>
<screen><prompt>$</prompt> <userinput>nova secgroup-delete <replaceable>SEC_GROUP_NAME</replaceable> </userinput></screen> <screen><prompt>$</prompt> <userinput>nova secgroup-delete <replaceable>SECURITY_GROUP_NAME</replaceable> </userinput></screen>
<note> <note>
<para>You cannot delete the default security group <para>You cannot delete the default security group
for a project. Also, you cannot delete a for a project. Also, you cannot delete a
@ -156,98 +147,80 @@
<title>Create and manage security group rules</title> <title>Create and manage security group rules</title>
<procedure> <procedure>
<para>Modify security group rules with the <command>nova <para>Modify security group rules with the <command>nova
secgroup-*-rule</command> commands.</para> secgroup-*-rule</command> commands. Before you begin, source
the OpenStack RC file. For details, see <xref
linkend="cli_openrc"/>.</para>
<step> <step>
<para>On a shell, source the OpenStack RC file. For <para>To list the rules for a security group, run the following
details, see <xref linkend="cli_openrc"/>.</para> command:</para>
<screen><prompt>$</prompt> <userinput>nova secgroup-list-rules <replaceable>SECURITY_GROUP_NAME</replaceable></userinput></screen>
</step> </step>
<step> <step>
<para>To list the rules for a security group</para> <para>To allow SSH access to the instances, choose one of the
<screen><prompt>$</prompt> <userinput>nova secgroup-list-rules <replaceable>SEC_GROUP_NAME</replaceable></userinput></screen> following options:</para>
</step> <itemizedlist>
<step> <listitem xml:id="sec_group_rule_add">
<para>To allow SSH access to the instances, choose one <para>Allow access from all IP addresses, specified as
of the following sub-steps:</para> IP subnet <filename>0.0.0.0/0</filename> in CIDR
<substeps> notation:</para>
<step xml:id="sec_group_rule_add"> <screen><prompt>$</prompt> <userinput>nova secgroup-add-rule <replaceable>SECURITY_GROUP_NAME</replaceable> tcp 22 22 0.0.0.0/0</userinput></screen>
<title wordsize="20">Add rule for all </listitem>
IPs</title> <listitem xml:id="sec_group_rule_add_alt">
<para>Either from all IP addresses (specified <para>Allow access only from IP addresses from other
as IP subnet in CIDR notation as security groups (source groups) to access the
0.0.0.0/0):</para> specified port:</para>
<screen><prompt>$</prompt> <userinput>nova secgroup-add-rule <replaceable>SEC_GROUP_NAME</replaceable> tcp 22 22 0.0.0.0/0</userinput></screen>
</step>
<step xml:id="sec_group_rule_add_alt">
<title wordsize="20">Add rule for security
groups</title>
<para>Alternatively, you can allow only IP
addresses from other security groups
(source groups) to access the specified
port:</para>
<screen><prompt>$</prompt> <userinput>nova secgroup-add-group-rule --ip_proto tcp --from_port 22 \ <screen><prompt>$</prompt> <userinput>nova secgroup-add-group-rule --ip_proto tcp --from_port 22 \
--to_port 22 <replaceable>SEC_GROUP_NAME</replaceable> <replaceable>SOURCE_GROUP_NAME</replaceable></userinput></screen> --to_port 22 <replaceable>SECURITY_GROUP_NAME</replaceable> <replaceable>SOURCE_GROUP_NAME</replaceable></userinput></screen>
</step> </listitem>
</substeps> </itemizedlist>
</step> </step>
<step> <step>
<para>To allow pinging the instances, choose one of <para>To allow pinging of the instances, choose one of the
the following sub-steps:</para> following options:</para>
<substeps> <itemizedlist>
<step> <listitem>
<title wordsize="20">To allow pinging from <para>Allow pinging from all IP addresses, specified as
IPs</title> IP subnet <filename>0.0.0.0/0</filename> in CIDR
<para>Specify all IP addresses as IP subnet in notation:</para>
CIDR notation: <screen><prompt>$</prompt> <userinput>nova
<literal>0.0.0.0/0</literal>. This secgroup-add-rule <replaceable>SECURITY_GROUP_NAME</replaceable> icmp -1 -1 0.0.0.0/0</userinput></screen><para>This allows access to all codes and all
command allows access to all codes and all types of ICMP traffic.</para>
types of ICMP traffic, </listitem>
respectively:</para> <listitem>
<screen><prompt>$</prompt> <userinput>nova secgroup-add-rule <replaceable>SEC_GROUP_NAME</replaceable> icmp -1 -1 0.0.0.0/0</userinput></screen> <para>Allow only members of other security groups
</step> (source groups) to ping instances:</para>
<step>
<title wordsize="20">To allow pinging from
other security groups</title>
<para>To allow only members of other security
groups (source groups) to ping
instances:</para>
<screen><prompt>$</prompt> <userinput>nova secgroup-add-group-rule --ip_proto icmp --from_port -1 \ <screen><prompt>$</prompt> <userinput>nova secgroup-add-group-rule --ip_proto icmp --from_port -1 \
--to_port -1 <replaceable>SEC_GROUP_NAME</replaceable> <replaceable>SOURCE_GROUP_NAME</replaceable></userinput></screen> --to_port -1 <replaceable>SECURITY_GROUP_NAME</replaceable> <replaceable>SOURCE_GROUP_NAME</replaceable></userinput></screen>
</step> </listitem>
</substeps> </itemizedlist>
</step> </step>
<step> <step>
<para>To allow access through a UDP port, such as <para>To allow access through a UDP port, such as allowing
allowing access to a DNS server that runs on a VM, access to a DNS server that runs on a VM, choose one of the
complete one of the following sub-steps:</para> following options:</para>
<substeps> <itemizedlist>
<step> <listitem>
<para>To allow UDP access from IPs, specify <para>Allow UDP access from IP addresses, specified as
all IP addresses as IP subnet in CIDR IP subnet <filename>0.0.0.0/0</filename> in CIDR
notation: notation:<screen><prompt>$</prompt> <userinput>nova secgroup-add-rule SECURITY_GROUP_NAME udp 53 53 0.0.0.0/0</userinput></screen></para>
<literal>0.0.0.0/0</literal>.<screen><prompt>$</prompt> <userinput>nova secgroup-add-rule SEC_GROUP_NAME udp 53 53 0.0.0.0/0</userinput></screen></para> </listitem>
</step> <listitem>
<step> <para>Allow only IP addresses from other security groups
<para>To allow only IP addresses from other (source groups) to access the specified port:</para>
security groups (source groups) to access
the specified port:</para>
<screen><prompt>$</prompt> <userinput>nova secgroup-add-group-rule --ip_proto udp --from_port 53 \ <screen><prompt>$</prompt> <userinput>nova secgroup-add-group-rule --ip_proto udp --from_port 53 \
--to_port 53 <replaceable>SEC_GROUP_NAME</replaceable> <replaceable>SOURCE_GROUP_NAME</replaceable></userinput></screen> --to_port 53 <replaceable>SECURITY_GROUP_NAME</replaceable> <replaceable>SOURCE_GROUP_NAME</replaceable></userinput></screen>
</listitem>
</itemizedlist>
</step> </step>
</substeps> </procedure>
</step> <section xml:id="security_grp_rules_cli_delete">
<step> <title>Delete a security group</title>
<para>To delete a security group rule, specify the <para>To delete a security group rule, specify the
same arguments that you used to create the same arguments that you used to create the
rule.</para> rule.</para>
<para>To delete the security rule that you created in <para>For example, to delete the security group rule that permits SSH
<xref linkend="sec_group_rule_add"/>:</para> access from all IP addresses, run the following command.</para>
<screen><prompt>$</prompt> <userinput>nova secgroup-delete-rule <replaceable>SEC_GROUP_NAME</replaceable> tcp 22 22 0.0.0.0/0</userinput></screen> <screen><prompt>$</prompt> <userinput>nova secgroup-delete-rule <replaceable>SECURITY_GROUP_NAME</replaceable> tcp 22 22 0.0.0.0/0</userinput></screen>
<para>To delete the security rule that you created in </section>
<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 <replaceable>SEC_GROUP_NAME</replaceable> <replaceable>SOURCE_GROUP_NAME</replaceable></userinput></screen>
</step>
</procedure>
</section> </section>
</section> </section>