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

386
doc/common/section_cli_glance_manage_images.xml
View File

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

301
doc/common/section_cli_install.xml
View File

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

215
doc/common/section_cli_nova_boot.xml
View File

@ -10,57 +10,46 @@
parameters:</para>
<itemizedlist xml:id="instance_parameters">
<listitem>
<para>The <guilabel>instance source</guilabel>, which is
an image or snapshot. Alternatively, you can boot from
a volume, which is block storage, to which you've
copied an image or snapshot.</para>
</listitem>
<listitem>
<para>The <guilabel>image</guilabel> or
<guilabel>snapshot</guilabel>, which represents
the operating system.</para>
<para>The <guilabel>instance source</guilabel>. This can be an
image, a snapshot, or a block storage volume that contains an
image or snapshot.</para>
</listitem>
<listitem>
<para>A <guilabel>name</guilabel> for your instance.
</para>
</listitem>
<listitem>
<para>The <emphasis role="bold">flavor</emphasis> for your
instance, which defines the compute, memory, and
storage capacity of nova computing instances. A flavor
is an available hardware configuration for a server.
It defines the "size" of a virtual server that can be
launched.</para>
<para>The <emphasis role="bold">flavor</emphasis> for your instance,
which defines the compute, memory, and storage capacity of nova
computing instances. A flavor is an available hardware
configuration for a server. It defines the "size" of a virtual
server that can be launched.</para>
</listitem>
<listitem>
<para><literal>User Data</literal> is a special key in the
metadata service that holds a file that cloud-aware
applications in the guest instance can access. For
example, the <link
<para>Any <emphasis role="bold">user data</emphasis> files: A user
data file is a special key in the metadata service that holds a
file that cloud-aware applications in the guest instance can
access. For example, one application that uses user data is the
<link
xlink:href="https://help.ubuntu.com/community/CloudInit"
>cloudinit</link> system is an open-source package
from Ubuntu that is available on various Linux
distributions including Ubuntu, Fedora, and openSUSE
and that handles early initialization of a cloud
instance that uses <literal>user
data</literal>.</para>
>cloud-init</link> system, which is an open-source package
from Ubuntu that is available on various Linux distributions and
which handles early initialization of a cloud instance.</para>
</listitem>
<listitem>
<para>Access and security credentials, which include one
or both of the following credentials:</para>
<itemizedlist>
<listitem>
<para>A <emphasis role="bold">keypair</emphasis>
for your instance, which are SSH credentials
that are injected into images when they are
launched. For this to work, the image must
contain the <literal>cloud-init</literal>
package. Create at least one keypair for each
project. If you already have generated a
keypair with an external tool, you can import
it into OpenStack. You can use the keypair for
multiple instances that belong to that
project.</para>
<para>A <emphasis role="bold">key pair</emphasis> for your
instance, which are SSH credentials that are injected
into images when they are launched. For the key pair to
be successfully injected, the image must contain the
<literal>cloud-init</literal> package. Create at
least one key pair for each project. If you already have
generated a key pair with an external tool, you can
import it into OpenStack. You can use the key pair for
multiple instances that belong to that project.</para>
</listitem>
<listitem>
<para>A <emphasis role="bold">security
@ -74,32 +63,42 @@
</itemizedlist>
</listitem>
<listitem>
<para>If needed, you can assign a <emphasis role="bold"
>floating (public) IP address</emphasis> to a
running instance and attach a block storage device, or
volume, for persistent storage.</para>
<para>If needed, you can assign a <emphasis role="bold">floating
(public) IP address</emphasis> to a running instance.
</para>
</listitem>
</itemizedlist>
<para>After you gather the parameters 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>.</para>
<para>You can launch an instance directly from one of the
available OpenStack images or from an image that you have
copied to a persistent volume. The OpenStack Image Service
provides a pool of images that are accessible to members of
<listitem>
<para>You can also attach a block storage device, or <emphasis
role="bold">volume</emphasis>, for persistent
storage.</para>
</listitem>
</itemizedlist><note>
<para>Instances that use the default security group cannot,
by default, be accessed from any IP address outside 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>
<?hard-pagebreak?>
<section xml:id="gather_parms">
<title wordsize="20">Gather parameters to launch an
instance</title>
<para>
Before you begin, source the OpenStack RC file.</para>
<procedure>
<step>
<para>On a shell, source the OpenStack RC file. See
<xref linkend="cli_openrc"/>.</para>
</step>
<step>
<para>List the available flavors:</para>
<para>List the available flavors and note the ID of the flavor
that you want to use for your instance.</para>
<screen><prompt>$</prompt> <userinput>nova flavor-list</userinput></screen>
<screen><?db-font-size 55%?><computeroutput>+----+-----------+-----------+------+-----------+------+-------+-------------+-----------+
| 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 |
| 5 | m1.xlarge | 16384 | 160 | 0 | | 8 | 1.0 | True |
+----+-----------+-----------+------+-----------+------+-------+-------------+-----------+</computeroutput></screen>
<para>Note the ID of the flavor that you want to use
for your instance.</para>
</step>
<step>
<para>List the available images:</para>
<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><?db-font-size 55%?><computeroutput>+--------------------------------------+---------------------------------+--------+--------+
| ID | Name | Status | Server |
@ -123,18 +121,19 @@
| 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 | |
+--------------------------------------+---------------------------------+--------+--------+</computeroutput></screen>
<para>You can also filter the image list by using grep
to find a specific image, like this:</para>
<para>You can also filter the image list by using
<command>grep</command> to find a specific image, as
follows:</para>
<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>
<para>Note the ID of the image that you want to boot
your instance from.</para>
</step>
<step>
<para>List the available security groups:</para>
<para>List the available security groups and note the ID of the
security group that you want to use for your
instance.</para>
<note>
<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>
</note>
<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
can assign the instance to only the default
security group.</para>
<para>You can also list rules for a specified security
group:</para>
<para>You can view rules for a specified security group:</para>
<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>
<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>
<para>Note the name of the keypair that you use for
SSH access.</para>
</step>
</procedure>
</section>
@ -167,22 +161,33 @@
<title wordsize="20">Launch an instance from an image</title>
<procedure>
<step>
<para>Now you have all parameters required to launch
an instance, run the following command and specify
the server name, flavor ID, and image ID.
Optionally, you can provide a key name for access
control and security group for security. You can
also include metadata key and value pairs. For
example, you can add a description for your server
by providing the <parameter>--meta description="My
<para>After you have all the parameters required to launch an
instance, run the following command and specify the server
name, flavor ID, and image ID. Optionally, you can provide a
key name for access control and a security group for
security. You can also include metadata key and value pairs.
For example, you can add a description for your server by
providing the <parameter>--meta description="My
Server"</parameter> parameter.</para>
<para>You can pass user data in a local file at
instance launch by using the flag
<parameter>--user-data
<para>You can pass user data in a local file at instance launch
by using the <parameter>--user-data
<replaceable>USER-DATA-FILE</replaceable></parameter>
parameter.</para>
<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>
<para>Depending on the parameters that you provide,
the command returns a list of server
@ -227,31 +232,29 @@
use this ID to get details for or delete your
server.</para>
<para>Copy the administrative password value from the
<literal>adminPass</literal> field. You use
this value to log into your server.</para>
<literal>adminPass</literal> field. You use this value
to log in to your server.</para>
<note>
<para>Arbitrary local files can also be placed
into the instance file system at creation time
using the <literal>--file
&lt;dst-path=src-path&gt;</literal>
option. You may store up to 5 files. For
example, if you have a special authorized_keys
file named
<para>You can also place arbitrary local files into the
instance file system at creation time by using the
<option>--file &lt;dst-path=src-path&gt;</option>
option. You can store up to five files. For example, if
you have a special authorized keys file named
<filename>special_authorized_keysfile</filename>
that you want to put on the instance rather
than using the regular ssh key injection, you
can use the following
command:<screen><prompt>$</prompt> <userinput><?db-font-size 75%?>nova boot --image ubuntu-cloudimage --flavor 1 vm-name \
that you want to put on the instance rather than using
the regular SSH key injection, you can use the
<option>--file</option> option as shown in the
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>
</note>
</step>
<step>
<para>Check if the instance is online:</para>
<screen><prompt>$</prompt> <userinput><?db-font-size 75%?>nova list</userinput></screen>
<para>The list shows the ID, name, status, and private
(and if assigned, public) IP addresses for all
instances in the project that you belong
to:</para>
<para>The list shows the ID, name, status, and private (and if
assigned, public) IP addresses for all instances in the
project to which you belong:</para>
<screen><?db-font-size 50%?><computeroutput>+--------------------------------------+----------------------+--------+------------+-------------+------------------+
| ID | Name | Status | Task State | Power State | Networks |
+--------------------------------------+----------------------+--------+------------+-------------+------------------+
@ -265,14 +268,10 @@
following command:</para>
<screen><prompt>$</prompt> <userinput><?db-font-size 75%?>nova help list</userinput></screen>
</step>
<step>
<para>If you did not provide a keypair, security
groups, or rules, you can only access the instance
from inside the cloud through VNC. Even pinging
the instance is not possible.</para>
</step>
</procedure>
</section>
<?hard-pagebreak?>
<note><para>If you did not provide a key pair, security groups, or rules, you can
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"/>
</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:xlink="http://www.w3.org/1999/xlink" version="5.0"
xml:id="nova_manage_images">
<title>Create image (nova)</title>
<para>You can use the nova client to list images, set and delete
image metadata, delete images, and take a snapshot of a
<title>Create an image (nova)</title>
<para>You can use the <command>nova</command> client to take a snapshot of a
running instance to create an image.</para>
<para>The safest approach is to shut down the instance before you
take a snapshot.</para>
<para>You cannot create a snapshot from an instance that has an
attached volume. Detach the volume, create the image, and
re-mount the volume.</para>
<para>To minimize the potential for data loss and ensure that you create an
accurate image, you should shut down the instance before you take a
snapshot.</para>
<para>You cannot create a snapshot from an instance that has an attached
volume. Detach the volume, create the image, and remount the
volume.</para>
<procedure>
<step>
<para>Write any buffered data to disk.</para>
<para>For more information, see <link
xlink:href="http://docs.openstack.org/trunk/openstack-ops/content/snapshots.html"
<para>For more information, see <link xlink:href="http://docs.openstack.org/trunk/openstack-ops/content/snapshots.html"
>Taking Snapshots</link> in the
<citetitle>OpenStack Operations
Guide</citetitle>.</para>
</step>
<step>
<para>To create the image, list instances to get the
server ID:</para>
<para>List instances to get the server name:</para>
<screen><prompt>$</prompt> <userinput>nova list</userinput>
<?db-font-size 50%?><computeroutput>+--------------------------------------+----------------------+--------+------------+-------------+------------------+
| 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 |
+--------------------------------------+----------------------+--------+------------+-------------+------------------+</computeroutput></screen>
<para>In this example, the server is named
<literal>myCirrosServer</literal>. Use this server
to create a snapshot, as follows:
<literal>myCirrosServer</literal>.</para></step>
<step><para>Use this server to create a snapshot:
<screen><prompt>$</prompt> <userinput>nova image-create myCirrosServer myCirrosImage</userinput></screen>The
command creates a qemu snapshot and automatically
uploads the image to your repository. Only the tenant
that creates the image has access to it.</para>
command creates a qemu snapshot and automatically uploads the
image to your repository. Only the tenant that creates the image
has access to it.</para>
</step>
<step>
<para>Get details for your image to check its
status:</para>
<screen><prompt>$</prompt> <userinput>nova image-show <replaceable>IMAGE</replaceable></userinput>
<para>Get details for your image to check its status:</para>
<screen><prompt>$</prompt> <userinput>nova image-show myCirrosImage</userinput>
<?db-font-size 50%?><computeroutput>+-------------------------------------+--------------------------------------+
| Property | Value |
+-------------------------------------+--------------------------------------+
@ -80,9 +77,9 @@
<literal>ACTIVE</literal>. Only the tenant who
creates the image has access to it.</para>
</step>
<step>
<para>To launch an instance from your image, include the
image ID and flavor ID, as follows:</para>
</procedure>
<para>To launch an instance from your image, include the image ID
and flavor ID, as in the following example:</para>
<screen><prompt>$</prompt> <userinput>nova boot newServer --image 7e5142af-1253-4634-bcc6-89482c5f2e8a \
--flavor 3</userinput>
<?db-font-size 50%?><computeroutput>+-------------------------------------+--------------------------------------+
@ -115,6 +112,4 @@
| created | 2013-07-22T19:58:33Z |
| metadata | {} |
+-------------------------------------+--------------------------------------+</computeroutput></screen>
</step>
</procedure>
</section>

18
doc/common/section_cli_nova_userdata.xml
View File

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

110
doc/common/section_cli_openrc.xml
View File

@ -4,9 +4,11 @@
xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
xml:id="cli_openrc">
<?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
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
installation provides it, you can download the file from
the OpenStack dashboard as an administrative user or any
@ -18,11 +20,10 @@
commands to communicate with the OpenStack services that run
in the cloud.</para>
<note>
<title>Environment variables on Microsoft Windows</title>
<para>Defining environment variables using an environment file is not a
common practice on Microsoft Windows. Environment variables are usually
defined in the <literal>Advanced</literal> tab of the <literal>System
Properties</literal> dialog.</para>
defined in the <guilabel>Advanced</guilabel> tab of the System
Properties dialog box.</para>
</note>
<section xml:id="openrc-dashboard" audience="enduser">
<title>Download and source the OpenStack RC file</title>
@ -34,32 +35,32 @@
&amp; Security</guibutton>.</para>
</step>
<step>
<para>
Click on the API Access tab. Click
<guibutton>Download OpenStack RC File</guibutton>
and save the file. The filename will be of the form
<filename><replaceable>PROJECT</replaceable>-openrc.sh</filename>
where <replaceable>PROJECT</replaceable> is the name
of the project for which you downloaded the file.
</para>
<para>On the API Access tab, click <guibutton>Download
OpenStack RC File</guibutton> and save the
file. The filename will be of the form
<filename><replaceable>PROJECT</replaceable>-openrc.sh</filename>
where <replaceable>PROJECT</replaceable> is the
name of the project for which you downloaded the
file.</para>
</step>
<step>
<para>Copy the
<filename><replaceable>PROJECT</replaceable>-openrc.sh</filename>
file to the machine from where you want to run
OpenStack commands.</para>
<para>For example, copy the file to the machine from
where you want to upload an image with a glance
client command.</para>
<filename><replaceable>PROJECT</replaceable>-openrc.sh</filename>
file to the computer from which you want to run
OpenStack commands.</para>
<para>For example, copy the file to the computer from
which you want to upload an image with a
<command>glance</command> client
command.</para>
</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
<filename><replaceable>PROJECT</replaceable>-openrc.sh</filename>
<filename><replaceable>PROJECT</replaceable>-openrc.sh</filename>
file for the respective project.</para>
<para>In this example, you source the
<filename>demo-openrc.sh</filename> file for
the demo project:</para>
<para>In the following example, the
<filename>demo-openrc.sh</filename> file is
sourced for the demo project:</para>
<screen><prompt>$</prompt> <userinput>source demo-openrc.sh</userinput></screen>
</step>
<step>
@ -73,45 +74,54 @@
<section xml:id="openrc-create">
<title>Create and source the OpenStack RC file</title>
<para audience="enduser">Alternatively, you can create the
<filename><replaceable>PROJECT</replaceable>-openrc.sh</filename> file from
scratch.</para>
<filename><replaceable>PROJECT</replaceable>-openrc.sh</filename>
file from scratch, if for some reason you cannot download
the file from the dashboard.</para>
<procedure>
<step>
<para>Create the <filename><replaceable>PROJECT</replaceable>-openrc.sh</filename> file
and add the authentication information:</para>
<programlisting language="bash" audience="enduser">export OS_USERNAME=<replaceable>USERNAME</replaceable>
export OS_PASSWORD=<replaceable>PASSWORD</replaceable>
export OS_TENANT_NAME=<replaceable>PROJECT_NAME</replaceable>
export OS_AUTH_URL=<replaceable>https://IDENTITY_HOST:PORT/v2.0</replaceable>
<para>In a text editor, create a file named
<filename><replaceable>PROJECT</replaceable>-openrc.sh</filename>
file and add the following authentication
information:</para>
<programlisting language="bash" audience="enduser">export OS_USERNAME=<replaceable>username</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
export OS_TENANT_ID=<replaceable>9d792532ffce494583138c495801d164</replaceable>
export OS_REGION_NAME=<replaceable>RegionOne</replaceable></programlisting>
export OS_TENANT_ID=<replaceable>tenantIDString</replaceable>
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
export OS_PASSWORD=<replaceable>ADMIN_PASS</replaceable>
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>
<para>On any shell from where you want to run
<para>On any shell from which you want to run
OpenStack commands, source the
<filename><replaceable>PROJECT</replaceable>-openrc.sh</filename>
file for the
respective project. In this example, you source the
<filename><replaceable>PROJECT</replaceable>-openrc.sh</filename>
file for the respective project. In this example,
you source the
<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>
</step>
</procedure>
<note audience="enduser">
<para>You are not prompted for the password with this
method. The password lives in clear text format in the
<filename><replaceable>PROJECT</replaceable>-openrc.sh</filename>
file. Restrict the
permissions on this file to avoid security problems.
You can also remove the <literal>OS_PASSWORD</literal>
variable from the file, and use the
<parameter>--password</parameter> parameter with
OpenStack client commands.</para>
<filename><replaceable>PROJECT</replaceable>-openrc.sh</filename>
file. Restrict the permissions on this file to avoid
security problems. You can also remove the
<literal>OS_PASSWORD</literal> variable from the
file, and use the <parameter>--password</parameter>
parameter with OpenStack client commands
instead.</para>
</note>
</section>
<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
the <option>OS_PASSWORD</option> setting in the
<filename><replaceable>PROJECT</replaceable>-openrc.sh</filename>
file by specifying a
password on a <command>keystone</command> command, as
file by specifying a password on a <command>keystone</command> command, as
follows:</para>
<screen><prompt>$</prompt> <userinput>keystone --os-password <replaceable>PASSWORD</replaceable> service-list</userinput></screen>
<para>Where <replaceable>PASSWORD</replaceable> is your
password.</para>
<para>Where <replaceable>PASSWORD</replaceable> is your password.</para>
</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"
xml:id="section_cli_overview">
<title>Overview</title>
<para>You can use the OpenStack command-line clients to run simple
commands that make API calls. You can run these commands from
the command line or in scripts to automate tasks. As long as
you provide OpenStack credentials, you can run these commands
on any machine.</para>
<para>You can use the OpenStack command-line clients to run simple commands
that make API calls. You can run these commands from the command line or
in scripts to automate tasks. If you provide OpenStack credentials, you
can run these commands on any computer.</para>
<para>Internally, each client command runs cURL commands that
embed API requests. The OpenStack APIs are RESTful APIs that
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
systems and are easy to learn and use. Each OpenStack service
has its own command-line client. On some client commands, you
can specify a <parameter
xmlns:svg="http://www.w3.org/2000/svg"
xmlns:m="http://www.w3.org/1998/Math/MathML"
xmlns:html="http://www.w3.org/1999/xhtml"
xmlns:db="http://docbook.org/ns/docbook">debug</parameter>
can specify a <command>debug</command>
parameter to show the underlying API request for the command.
This is a good way to become familiar with the OpenStack API
calls.</para>
<para>The following table lists the command-line client for each
OpenStack service, together with its
package name and description.</para>
<para>The following table lists the command-line client for each OpenStack
service with its package name and description.</para>
<table rules="all">
<caption>OpenStack services and clients</caption>
<col width="15%"/>
@ -84,8 +78,8 @@
<td>Networking</td>
<td><command>neutron</command></td>
<td><package>python-neutronclient</package></td>
<td>Configure networks for guest servers. This client was previously known as
<command>quantum</command>.</td>
<td>Configure networks for guest servers. This client was
previously called <command>quantum</command>.</td>
</tr>
<tr>
<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:xlink="http://www.w3.org/1999/xlink" version="5.0"
xml:id="checking_version_cli">
<title>Get the version for a client</title>
<para>Run this command get the version number for a
client:</para>
<title>Discover the version number for a client</title>
<para>Run the following command to discover the version number
for a client:</para>
<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
<command>nova</command> client, run this
command:</para>
<screen><prompt>$</prompt> <userinput>nova --version</userinput>
<computeroutput>2.15.0</computeroutput></screen>
<para>To see the version number for the
<command>keystone</command> client, run this
command:</para>
<screen><prompt>$</prompt> <userinput>keystone --version</userinput>
<computeroutput>0.4.0</computeroutput></screen>
<command>nova</command> client, run the
following command:</para>
<screen><prompt>$</prompt> <userinput>nova --version</userinput></screen>
<para>The version number (2.15.0 in the example) is returned.</para>
<screen><computeroutput>2.15.0</computeroutput></screen>
</section>

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

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

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

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