openstack/operations-guide
Code Issues Proposed changes

Merge "Edits and markup for user facing operations"

Browse Source
This commit is contained in:
Jenkins 2014-03-03 15:58:09 +00:00 committed by Gerrit Code Review
commit 481e646f42
1 changed files with 121 additions and 111 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

232
doc/openstack-ops/ch_ops_user_facing.xml
View File

@ -28,15 +28,16 @@
<para>Several pre-made images exist and can easily be imported into the Image Service. A <para>Several pre-made images exist and can easily be imported into the Image Service. A
common image to add is the CirrOS image, which is very small and used for testing common image to add is the CirrOS image, which is very small and used for testing
purposes. To add this image, simply do:</para> purposes. To add this image, simply do:</para>
<programlisting><?db-font-size 65%?>$ wget http://download.cirros-cloud.net/0.3.1/cirros-0.3.1-x86_64-disk.img <screen><prompt>$</prompt> <userinput>wget http://download.cirros-cloud.net/0.3.1/cirros-0.3.1-x86_64-disk.img</userinput>
$ glance image-create --name='cirros image' --is-public=true --container-format=bare --disk-format=qcow2 &lt; cirros-0.3.1-x86_64-disk.img</programlisting> <prompt>$</prompt> <userinput>glance image-create --name='cirros image' --is-public=true \
--container-format=bare --disk-format=qcow2 &lt; cirros-0.3.1-x86_64-disk.img</userinput></screen>
<para>The <code>glance image-create</code> command <para>The <code>glance image-create</code> command
provides a large set of options to give your image. provides a large set of options to give your image.
For example, the <code>min-disk</code> option is For example, the <code>min-disk</code> option is
useful for images that require root disks of a certain useful for images that require root disks of a certain
size (for example, large Windows images). To view size (for example, large Windows images). To view
these options, do:</para> these options, do:</para>
<programlisting><?db-font-size 65%?>$ glance help image-create</programlisting> <screen><prompt>$</prompt> <userinput>glance help image-create</userinput></screen>
<para>The <code>location</code> option is important to <para>The <code>location</code> option is important to
note. It does not copy the entire image into Glance, note. It does not copy the entire image into Glance,
but reference an original location to where the image but reference an original location to where the image
@ -50,7 +51,7 @@ $ glance image-create --name='cirros image' --is-public=true --container-format=
such as shown in the example.</para> such as shown in the example.</para>
<para>Run the following command to view the properties of <para>Run the following command to view the properties of
existing images:</para> existing images:</para>
<programlisting><?db-font-size 65%?>$ glance details</programlisting> <screen><prompt>$</prompt> <userinput>glance details</userinput></screen>
</section> </section>
<section xml:id="sharing_images"> <section xml:id="sharing_images">
<title>Sharing Images Between Projects</title> <title>Sharing Images Between Projects</title>
@ -76,8 +77,7 @@ $ glance image-create --name='cirros image' --is-public=true --container-format=
<step> <step>
<para>Once you have both pieces of information, run the <para>Once you have both pieces of information, run the
glance command:</para> glance command:</para>
<screen><prompt>$</prompt> <userinput>glance member-create \ <screen><prompt>$</prompt> <userinput>glance member-create &lt;image-uuid&gt; &lt;project-uuid&gt;</userinput></screen>
&lt;image-uuid&gt; &lt;project-uuid&gt;</userinput></screen>
<para>For example:</para> <para>For example:</para>
<screen><prompt>$</prompt> <userinput>glance member-create 733d1c44-a2ea-414b-aca7-69decf20d810 \ <screen><prompt>$</prompt> <userinput>glance member-create 733d1c44-a2ea-414b-aca7-69decf20d810 \
771ed149ef7e4b2b88665cc1c98f77ca</userinput></screen> 771ed149ef7e4b2b88665cc1c98f77ca</userinput></screen>
@ -90,7 +90,8 @@ $ glance image-create --name='cirros image' --is-public=true --container-format=
<section xml:id="delete_images"> <section xml:id="delete_images">
<title>Deleting Images</title> <title>Deleting Images</title>
<para>To delete an image, just execute:</para> <para>To delete an image, just execute:</para>
<programlisting><?db-font-size 65%?>$ glance image-delete &lt;image uuid&gt;</programlisting> <screen><prompt>$</prompt> <userinput>glance
image-delete &lt;image uuid&gt;</userinput></screen>
<note> <note>
<para>Deleting an image does not affect instances or <para>Deleting an image does not affect instances or
snapshots that were based off the image.</para> snapshots that were based off the image.</para>
@ -99,7 +100,7 @@ $ glance image-create --name='cirros image' --is-public=true --container-format=
<section xml:id="other_cli"> <section xml:id="other_cli">
<title>Other CLI Options</title> <title>Other CLI Options</title>
<para>A full set of options can be found using:</para> <para>A full set of options can be found using:</para>
<programlisting><?db-font-size 65%?>$ glance help</programlisting> <screen><prompt>$</prompt> <userinput>glance help</userinput></screen>
<para>or the <link <para>or the <link
xlink:href="http://docs.openstack.org/cli/quick-start/content/glance-cli-reference.html" xlink:href="http://docs.openstack.org/cli/quick-start/content/glance-cli-reference.html"
>OpenStack Image Service</link> CLI Guide. >OpenStack Image Service</link> CLI Guide.
@ -131,25 +132,26 @@ $ glance image-create --name='cirros image' --is-public=true --container-format=
done if you simply display the unique ID of the owner, done if you simply display the unique ID of the owner,
this example goes one step further and displays the this example goes one step further and displays the
readable name of the owner:</para> readable name of the owner:</para>
<programlisting><?db-font-size 65%?>$ mysql&gt; select glance.images.id, glance.images.name, keystone.tenant.name, is_public from glance.images inner join keystone.tenant on glance.images.owner=keystone.tenant.id;</programlisting> <screen><prompt>$</prompt> <userinput>mysql&gt; select glance.images.id,
glance.images.name, keystone.tenant.name, is_public from
glance.images inner join keystone.tenant on
glance.images.owner=keystone.tenant.id;</userinput></screen>
<para>Another example is displaying all properties for a <para>Another example is displaying all properties for a
certain image:</para> certain image:</para>
<programlisting><?db-font-size 65%?>$ mysql&gt; select name, value from image_properties where id = &lt;image_id&gt;</programlisting> <screen><prompt>$</prompt> <userinput>mysql&gt; select name, value from
image_properties where id = &lt;image_id&gt;</userinput></screen>
</section> </section>
</section> </section>
<section xml:id="flavors"> <section xml:id="flavors">
<title>Flavors</title> <title>Flavors</title>
<para>Virtual hardware templates are called "flavors" in OpenStack, defining sizes for RAM, <para>Virtual hardware templates are called "flavors" in OpenStack, defining sizes for RAM,
disk, number of cores, and so on. The default install provides five flavors. These are disk, number of cores, and so on. The default install provides five flavors. These are
configurable by admin users (the rights may also be delegated to other users by configurable by admin users (the rights may also be delegated to other users by
redefining the access controls for <code>compute_extension:flavormanage</code> in redefining the access controls for <code>compute_extension:flavormanage</code> in
<code>/etc/nova/policy.json</code> on the <code>nova-api</code> server). To get the <code>/etc/nova/policy.json</code> on the <code>nova-api</code> server). To get the
list of available flavors on your system, run:</para> list of available flavors on your system, run:</para>
<programlisting><?db-font-size 65%?>$ nova flavor-list</programlisting> <screen><prompt>$</prompt> <userinput>nova flavor-list</userinput></screen>
<screen><computeroutput>+----+-----------+-----------+------+-----------+\+-------+-\+-------------+
<programlisting><?db-font-size 65%?>+----+-----------+-----------+------+-----------+\+-------+-\+-------------+
| ID | Name | Memory_MB | Disk | Ephemeral |/| VCPUs | /| extra_specs | | ID | Name | Memory_MB | Disk | Ephemeral |/| VCPUs | /| extra_specs |
+----+-----------+-----------+------+-----------+\+-------+-\+-------------+ +----+-----------+-----------+------+-----------+\+-------+-\+-------------+
| 1 | m1.tiny | 512 | 1 | 0 |/| 1 | /| {} | | 1 | m1.tiny | 512 | 1 | 0 |/| 1 | /| {} |
@ -157,12 +159,9 @@ $ glance image-create --name='cirros image' --is-public=true --container-format=
| 3 | m1.medium | 4096 | 10 | 40 |/| 2 | /| {} | | 3 | m1.medium | 4096 | 10 | 40 |/| 2 | /| {} |
| 4 | m1.large | 8192 | 10 | 80 |\| 4 | \| {} | | 4 | m1.large | 8192 | 10 | 80 |\| 4 | \| {} |
| 5 | m1.xlarge | 16384 | 10 | 160 |/| 8 | /| {} | | 5 | m1.xlarge | 16384 | 10 | 160 |/| 8 | /| {} |
+----+-----------+-----------+------+-----------+\+-------+-\+-------------+</programlisting> +----+-----------+-----------+------+-----------+\+-------+-\+-------------+</computeroutput></screen>
<para>The <code>nova flavor-create</code> command allows authorized users to create new <para>The <code>nova flavor-create</code> command allows authorized users to create new flavors. Additional flavor manipulation commands can be shown with the command: <screen><prompt>$</prompt> <userinput>nova help | grep flavor</userinput></screen>
flavors. Additional flavor manipulation commands can be shown with the command:
<programlisting language="bash"><?db-font-size 75%?><prompt>$</prompt> nova help | grep flavor</programlisting>
</para> </para>
<?hard-pagebreak?>
<para>Flavors define a number of parameters, resulting in the <para>Flavors define a number of parameters, resulting in the
user having a choice of what type of virtual machine to run - just user having a choice of what type of virtual machine to run - just
like they would have if they were purchasing a physical server. like they would have if they were purchasing a physical server.
@ -313,7 +312,7 @@ $ glance image-create --name='cirros image' --is-public=true --container-format=
</section> </section>
<simplesect> <simplesect>
<title>How do I modify an existing flavor?</title> <title>How do I modify an existing flavor?</title>
<para>The OpenStack Dashboard simulates the ability to modify a <para>The OpenStack dashboard simulates the ability to modify a
flavor by deleting an existing flavor and creating a new one flavor by deleting an existing flavor and creating a new one
with the same name.</para> with the same name.</para>
</simplesect> </simplesect>
@ -332,6 +331,8 @@ $ glance image-create --name='cirros image' --is-public=true --container-format=
a "default" security group which is applied to instances a "default" security group which is applied to instances
which have no other security group defined. Unless changed, which have no other security group defined. Unless changed,
this security group denies all incoming traffic.</para> this security group denies all incoming traffic.</para>
<section xml:id="general-security-group-config">
<title>General Security Groups Configuration</title>
<para>The <code>nova.conf</code> option <para>The <code>nova.conf</code> option
<code>allow_same_net_traffic</code> (which defaults to <code>allow_same_net_traffic</code> (which defaults to
true) globally controls whether the rules applies to hosts true) globally controls whether the rules applies to hosts
@ -347,8 +348,16 @@ $ glance image-create --name='cirros image' --is-public=true --container-format=
<code>allow_same_net_traffic</code> by configuring <code>allow_same_net_traffic</code> by configuring
their default security group to allow all traffic from their default security group to allow all traffic from
their subnet.</para> their subnet.</para>
<tip><para>As noted in the previous chapter the number of rules per
security group is controlled by the
<code>quota_security_group_rules</code> and the number of allowed
security groups per project is controlled by the
<code>quota_security_groups</code> quota.</para></tip>
</section>
<section xml:id="end-user-config-sec-group">
<title>End User Configuration of Security Groups</title>
<para>Security groups for the current project can be found on <para>Security groups for the current project can be found on
the Horizon dashboard under "Access &amp; Security". To see the OpenStack dashboard under "Access &amp; Security". To see
details of an existing group select the "edit" action for details of an existing group select the "edit" action for
that security group. Obviously modifying existing groups that security group. Obviously modifying existing groups
can be done from this "edit" interface. There is a "Create can be done from this "edit" interface. There is a "Create
@ -359,37 +368,26 @@ $ glance image-create --name='cirros image' --is-public=true --container-format=
<para>From the command line you can get a list of security <para>From the command line you can get a list of security
groups for the project you're acting in using the nova groups for the project you're acting in using the nova
command:</para> command:</para>
<screen><prompt>$</prompt> <userinput>nova secgroup-list</userinput><computeroutput>+---------+-------------+
<programlisting><prompt>$</prompt> nova secgroup-list</programlisting>
<programlisting><?db-font-size 65%?>+---------+-------------+
| Name | Description | | Name | Description |
+---------+-------------+ +---------+-------------+
| default | default | | default | default |
| open | all ports | | open | all ports |
+---------+-------------+</programlisting> +---------+-------------+</computeroutput></screen>
<para>To view the details of the "open" security group:</para> <para>To view the details of the "open" security group:</para>
<screen><prompt>$</prompt> <userinput>nova secgroup-list-rules open</userinput><computeroutput>+-------------+-----------+---------+-----------+--------------+
<programlisting><prompt>$</prompt> nova secgroup-list-rules open</programlisting>
<programlisting><?db-font-size 65%?>+-------------+-----------+---------+-----------+--------------+
| IP Protocol | From Port | To Port | IP Range | Source Group | | IP Protocol | From Port | To Port | IP Range | Source Group |
+-------------+-----------+---------+-----------+--------------+ +-------------+-----------+---------+-----------+--------------+
| icmp | -1 | 255 | 0.0.0.0/0 | | | icmp | -1 | 255 | 0.0.0.0/0 | |
| tcp | 1 | 65535 | 0.0.0.0/0 | | | tcp | 1 | 65535 | 0.0.0.0/0 | |
| udp | 1 | 65535 | 0.0.0.0/0 | | | udp | 1 | 65535 | 0.0.0.0/0 | |
+-------------+-----------+---------+-----------+--------------+ </programlisting> +-------------+-----------+---------+-----------+--------------+</computeroutput></screen>
<para>These rules are all "allow" type rules as the default is <para>These rules are all "allow" type rules as the default is
deny. The first column is the IP protocol (one of icmp, deny. The first column is the IP protocol (one of icmp,
tcp, or udp) the second and third columns specify the tcp, or udp) the second and third columns specify the
affected port range. The fourth column specifies the IP affected port range. The fourth column specifies the IP
range in CIDR format. This example shows the full port range in CIDR format. This example shows the full port
range for all protocols allowed from all IPs.</para> range for all protocols allowed from all IPs.</para>
<para>As noted in the previous chapter the number of rules per
security group is controlled by the
<code>quota_security_group_rules</code> and the number of allowed
security groups per project is controlled by the
<code>quota_security_groups</code> quota. </para>
<para>When adding a new security group you should pick a <para>When adding a new security group you should pick a
descriptive but brief name. This name shows up in brief descriptive but brief name. This name shows up in brief
descriptions of the instances that use it where the longer descriptions of the instances that use it where the longer
@ -401,24 +399,21 @@ $ glance image-create --name='cirros image' --is-public=true --container-format=
"global_http" which is clear and reasonably concise, "global_http" which is clear and reasonably concise,
encapsulating what is allowed and from where. From the encapsulating what is allowed and from where. From the
command line:</para> command line:</para>
<screen><prompt>$</prompt> <userinput>nova secgroup-create
<programlisting><?db-font-size 65%?><prompt>$</prompt> nova secgroup-create global_http "allow web traffic from the internet"</programlisting> global_http "allow web traffic from the internet"</userinput><computeroutput>+-------------+-------------------------------------+
<programlisting><?db-font-size 65%?>+-------------+-------------------------------------+
| Name | Description | | Name | Description |
+-------------+-------------------------------------+ +-------------+-------------------------------------+
| global_http | allow web traffic from the internet | | global_http | allow web traffic from the internet |
+-------------+-------------------------------------+</programlisting> +-------------+-------------------------------------+</computeroutput></screen>
<para>This creates the empty security group to make it do what <para>This creates the empty security group to make it do what
we want we need to add some rules.</para> we want we need to add some rules.</para>
<programlisting><?db-font-size 65%?>$ nova secgroup-add-rule &lt;secgroup&gt; &lt;ip-proto&gt; &lt;from-port&gt; &lt;to-port&gt; <screen><prompt>$</prompt> <userinput>nova secgroup-add-rule &lt;secgroup&gt; &lt;ip-proto&gt; &lt;from-port&gt; &lt;to-port&gt; &lt;cidr&gt;</userinput>
&lt;cidr&gt; <prompt>$</prompt> <userinput>nova secgroup-add-rule global_http tcp 80 80 0.0.0.0/0</userinput>
$ nova secgroup-add-rule global_http tcp 80 80 0.0.0.0/0 <computeroutput>+-------------+-----------+---------+-----------+--------------+
+-------------+-----------+---------+-----------+--------------+
| IP Protocol | From Port | To Port | IP Range | Source Group | | IP Protocol | From Port | To Port | IP Range | Source Group |
+-------------+-----------+---------+-----------+--------------+ +-------------+-----------+---------+-----------+--------------+
| tcp | 80 | 80 | 0.0.0.0/0 | | | tcp | 80 | 80 | 0.0.0.0/0 | |
+-------------+-----------+---------+-----------+--------------+</programlisting> +-------------+-----------+---------+-----------+--------------+</computeroutput></screen>
<para>Note that the arguments are positional and the <para>Note that the arguments are positional and the
"from-port" and "to-port" arguments specify the local port "from-port" and "to-port" arguments specify the local port
range connections are allowed to not source and range connections are allowed to not source and
@ -426,38 +421,35 @@ $ nova secgroup-add-rule global_http tcp 80 80 0.0.0.0/0
sets can be built up through multiple invocations of nova sets can be built up through multiple invocations of nova
secgroup-add-rule. For example if you want to pass both secgroup-add-rule. For example if you want to pass both
http and https traffic:</para> http and https traffic:</para>
<screen><prompt>$</prompt> <userinput>nova secgroup-add-rule global_http tcp 443 443 0.0.0.0/0</userinput><computeroutput>+-------------+-----------+---------+-----------+--------------+
<programlisting><?db-font-size 65%?><prompt>$</prompt> nova secgroup-add-rule global_http tcp 443 443 0.0.0.0/0</programlisting>
<programlisting><?db-font-size 65%?>+-------------+-----------+---------+-----------+--------------+
| IP Protocol | From Port | To Port | IP Range | Source Group | | IP Protocol | From Port | To Port | IP Range | Source Group |
+-------------+-----------+---------+-----------+--------------+ +-------------+-----------+---------+-----------+--------------+
| tcp | 443 | 443 | 0.0.0.0/0 | | | tcp | 443 | 443 | 0.0.0.0/0 | |
+-------------+-----------+---------+-----------+--------------+</programlisting> +-------------+-----------+---------+-----------+--------------+</computeroutput></screen>
<para>Despite only outputting the newly added rule this <para>Despite only outputting the newly added rule this
operation is additive:</para> operation is additive:</para>
<programlisting><?db-font-size 65%?>$ nova secgroup-list-rules global_http</programlisting> <screen><prompt>$</prompt> <userinput>nova secgroup-list-rules global_http</userinput><computeroutput>+-------------+-----------+---------+-----------+--------------+
<programlisting><?db-font-size 65%?>+-------------+-----------+---------+-----------+--------------+
| IP Protocol | From Port | To Port | IP Range | Source Group | | IP Protocol | From Port | To Port | IP Range | Source Group |
+-------------+-----------+---------+-----------+--------------+ +-------------+-----------+---------+-----------+--------------+
| tcp | 80 | 80 | 0.0.0.0/0 | | | tcp | 80 | 80 | 0.0.0.0/0 | |
| tcp | 443 | 443 | 0.0.0.0/0 | | | tcp | 443 | 443 | 0.0.0.0/0 | |
+-------------+-----------+---------+-----------+--------------+</programlisting> +-------------+-----------+---------+-----------+--------------+</computeroutput></screen>
<para>The inverse operation is called secgroup-delete-rule, <para>The inverse operation is called secgroup-delete-rule,
using the same format. Whole security groups can be using the same format. Whole security groups can be
removed with secgroup-delete.</para> removed with secgroup-delete.</para>
<para>To create security group rules for a cluster of <para>To create security group rules for a cluster of
instances:</para> instances, you want to use SourceGroups.</para>
<para>SourceGroups are a special dynamic way of defining the CIDR of allowed sources. The <para>SourceGroups are a special dynamic way of defining the CIDR of allowed sources. The
user specifies a SourceGroup (Security Group name), all the users' other Instances using user specifies a SourceGroup (Security Group name) and then all the users' other Instances using
the specified SourceGroup are selected dynamically. This alleviates the need for a the specified SourceGroup are selected dynamically. This dynamic
selection alleviates the need for
individual rules to allow each new member of the cluster.</para> individual rules to allow each new member of the cluster.</para>
<para>Example usage: <code>nova secgroup-add-group-rule &lt;secgroup&gt; &lt;source-group&gt; <para>Example usage: <code>nova secgroup-add-group-rule &lt;secgroup&gt; &lt;source-group&gt; &lt;ip-proto&gt; &lt;from-port&gt; &lt;to-port&gt;</code></para>
&lt;ip-proto&gt; &lt;from-port&gt; &lt;to-port&gt;</code></para> <screen><prompt>$</prompt> <userinput>nova secgroup-add-group-rule cluster global-http tcp 22 22</userinput></screen>
<programlisting><prompt>$</prompt> nova secgroup-add-group-rule cluster global-http tcp 22 22</programlisting>
<para>The "cluster" rule allows ssh access from any other <para>The "cluster" rule allows ssh access from any other
instance that uses the "global-http" group.</para> instance that uses the "global-http" group.</para>
</section> </section>
</section>
<?hard-pagebreak?> <?hard-pagebreak?>
<section xml:id="user_facing_block_storage"> <section xml:id="user_facing_block_storage">
<?dbhtml stop-chunking?> <?dbhtml stop-chunking?>
@ -486,21 +478,22 @@ $ nova secgroup-add-rule global_http tcp 80 80 0.0.0.0/0
them for first use and being cautious when removing them for first use and being cautious when removing
devices. What is specific is how to create new volumes and devices. What is specific is how to create new volumes and
attach and detach them from instances. These operations attach and detach them from instances. These operations
can all be done from the "Volumes" page of the Dashboard can all be done from the "Volumes" page of the dashboard
or using the cinder command line client.</para> or using the cinder command line client.</para>
<para>To add new volumes you only need a name and a volume <para>To add new volumes you only need a name and a volume
size in gigabytes, ether put these into the "create size in gigabytes, ether put these into the "create
volume" web form or using the command line:</para> volume" web form or using the command line:</para>
<programlisting><?db-font-size 65%?><prompt>$</prompt> cinder create --display-name test-volume 10</programlisting> <screen><prompt>$</prompt> <userinput>cinder create --display-name
test-volume 10</userinput></screen>
<para>This creates a 10 GB volume named "test-volume." To list <para>This creates a 10 GB volume named "test-volume." To list
existing volumes and the instances they are connected to existing volumes and the instances they are connected to
if any:</para> if any:</para>
<programlisting><?db-font-size 65%?><prompt>$</prompt> cinder list</programlisting> <screen><prompt>$</prompt> <userinput>cinder list</userinput></screen>
<programlisting><?db-font-size 65%?>+------------+---------+--------------------+------+-------------+-------------+ <screen><computeroutput>+------------+---------+--------------------+------+-------------+-------------+
| ID | Status | Display Name | Size | Volume Type | Attached to | | ID | Status | Display Name | Size | Volume Type | Attached to |
+------------+---------+--------------------+------+-------------+-------------+ +------------+---------+--------------------+------+-------------+-------------+
| 0821...19f | active | test-volume | 10 | None | | | 0821...19f | active | test-volume | 10 | None | |
+------------+---------+--------------------+------+-------------+-------------+</programlisting> +------------+---------+--------------------+------+-------------+-------------+</computeroutput></screen>
<para>The Block Storage service also allows for creating <para>The Block Storage service also allows for creating
snapshots of volumes. Remember this is a block level snapshots of volumes. Remember this is a block level
snapshot which is crash consistent so it is best if the snapshot which is crash consistent so it is best if the
@ -514,7 +507,7 @@ $ nova secgroup-add-rule global_http tcp 80 80 0.0.0.0/0
select "Create Snapshot" from the actions column next to select "Create Snapshot" from the actions column next to
the volume name in the dashboard volume page, or from the the volume name in the dashboard volume page, or from the
command line:</para> command line:</para>
<programlisting><?db-font-size 65%?>usage: cinder snapshot-create [--force &lt;True|False&gt;] <screen><computeroutput>usage: cinder snapshot-create [--force &lt;True|False&gt;]
[--display-name &lt;display-name&gt;] [--display-name &lt;display-name&gt;]
[--display-description &lt;display-description&gt;] [--display-description &lt;display-description&gt;]
&lt;volume-id&gt; &lt;volume-id&gt;
@ -522,7 +515,7 @@ Add a new snapshot.
Positional arguments: &lt;volume-id&gt; ID of the volume to snapshot Positional arguments: &lt;volume-id&gt; ID of the volume to snapshot
Optional arguments: --force &lt;True|False&gt; Optional flag to indicate whether to snapshot a volume even if its attached to an instance. (Default=False) --display-name &lt;display-name&gt; Optional snapshot name. (Default=None) Optional arguments: --force &lt;True|False&gt; Optional flag to indicate whether to snapshot a volume even if its attached to an instance. (Default=False) --display-name &lt;display-name&gt; Optional snapshot name. (Default=None)
--display-description &lt;display-description&gt; --display-description &lt;display-description&gt;
Optional snapshot description. (Default=None)</programlisting> Optional snapshot description. (Default=None)</computeroutput></screen>
<section xml:id="block_storage_creation_failures"> <section xml:id="block_storage_creation_failures">
<title>Block Storage Creation Failures</title> <title>Block Storage Creation Failures</title>
<para>If a user tries to create a volume and it <para>If a user tries to create a volume and it
@ -531,7 +524,7 @@ Optional snapshot description. (Default=None)</programlisting>
volume's UUID. First try the log files on the cloud volume's UUID. First try the log files on the cloud
controller and then try the storage node where they controller and then try the storage node where they
volume was attempted to be created:</para> volume was attempted to be created:</para>
<programlisting><?db-font-size 65%?><prompt>#</prompt> grep 903b85d0-bacc-4855-a261-10843fc2d65b /var/log/cinder/*.log</programlisting> <screen><prompt>#</prompt> <userinput>grep 903b85d0-bacc-4855-a261-10843fc2d65b /var/log/cinder/*.log</userinput></screen>
</section> </section>
</section> </section>
<section xml:id="instances"> <section xml:id="instances">
@ -553,7 +546,8 @@ Optional snapshot description. (Default=None)</programlisting>
image or snapshot on the "Images &amp; Snapshots" image or snapshot on the "Images &amp; Snapshots"
page.</para> page.</para>
<para>On the command line:</para> <para>On the command line:</para>
<programlisting><?db-font-size 65%?><prompt>$</prompt> nova boot --flavor &lt;flavor&gt; --image &lt;image&gt; &lt;name&gt;</programlisting> <screen><prompt>$</prompt> <userinput>nova boot --flavor
&lt;flavor&gt; --image &lt;image&gt; &lt;name&gt;</userinput></screen>
<para>There are a number of optional items that can be <para>There are a number of optional items that can be
specified. You should read the rest of this instances specified. You should read the rest of this instances
section before trying to start one, but this is the section before trying to start one, but this is the
@ -562,7 +556,8 @@ Optional snapshot description. (Default=None)</programlisting>
<para>To delete instances from the dashboard select the <para>To delete instances from the dashboard select the
"Terminate instance" action next to the instance on "Terminate instance" action next to the instance on
the "Instances" page, from the command line:</para> the "Instances" page, from the command line:</para>
<programlisting><?db-font-size 65%?><prompt>$</prompt> nova delete &lt;instance-uuid&gt;</programlisting> <screen><prompt>$</prompt> <userinput>nova delete
&lt;instance-uuid&gt;</userinput></screen>
<para>It is important to note that powering off an <para>It is important to note that powering off an
instance does not terminate it in the OpenStack instance does not terminate it in the OpenStack
sense.</para> sense.</para>
@ -580,11 +575,9 @@ Optional snapshot description. (Default=None)</programlisting>
In these cases the error is apparent doing a In these cases the error is apparent doing a
<code>nova show</code> on the faulted <code>nova show</code> on the faulted
instance.</para> instance.</para>
<screen><prompt>$</prompt> <userinput>nova show test-instance</userinput></screen>
<programlisting><prompt>$</prompt> nova show test-instance</programlisting> <screen><?db-font-size 55%?>
<computeroutput>+------------------------+-----------------------------------------------------\
<programlisting><?db-font-size 55%?>
+------------------------+-----------------------------------------------------\
| Property | Value / | Property | Value /
+------------------------+-----------------------------------------------------\ +------------------------+-----------------------------------------------------\
| OS-DCF:diskConfig | MANUAL / | OS-DCF:diskConfig | MANUAL /
@ -608,7 +601,8 @@ Optional snapshot description. (Default=None)</programlisting>
| tenant_id | 98333a1a28e746fa8c629c83a818ad57 / | tenant_id | 98333a1a28e746fa8c629c83a818ad57 /
| updated | 2013-03-01T19:28:26Z \ | updated | 2013-03-01T19:28:26Z \
| user_id | a1ef823458d24a68955fec6f3d390019 / | user_id | a1ef823458d24a68955fec6f3d390019 /
+------------------------+-----------------------------------------------------\ </programlisting> +------------------------+-----------------------------------------------------\</computeroutput>
</screen>
<para>In this case looking at the "fault" message shows <para>In this case looking at the "fault" message shows
NoValidHost indicating the scheduler was unable to NoValidHost indicating the scheduler was unable to
match the instance requirements.</para> match the instance requirements.</para>
@ -641,7 +635,8 @@ Optional snapshot description. (Default=None)</programlisting>
<para>As an example of instance metadata, users can <para>As an example of instance metadata, users can
generate and register ssh keys using the nova generate and register ssh keys using the nova
command:</para> command:</para>
<programlisting><?db-font-size 65%?><prompt>$</prompt> nova keypair-add mykey &gt; mykey.pem</programlisting> <screen><prompt>$</prompt> <userinput>nova keypair-add mykey
&gt; mykey.pem</userinput></screen>
<para>This creates a key named <userinput>mykey</userinput> which you can <para>This creates a key named <userinput>mykey</userinput> which you can
associate with instances. The file <filename>mykey.pem</filename> is the associate with instances. The file <filename>mykey.pem</filename> is the
private key which should be saved to a secure location private key which should be saved to a secure location
@ -649,13 +644,15 @@ Optional snapshot description. (Default=None)</programlisting>
associated with.</para> associated with.</para>
<para>Use this command to register an existing key <para>Use this command to register an existing key
with OpenStack:</para> with OpenStack:</para>
<programlisting><?db-font-size 65%?><prompt>$</prompt> nova keypair-add --pub-key mykey.pub mykey</programlisting> <screen><prompt>$</prompt> <userinput>nova keypair-add
--pub-key mykey.pub mykey</userinput></screen>
<note><para>You must have the matching private key to access <note><para>You must have the matching private key to access
instances associated with this key.</para></note> instances associated with this key.</para></note>
<para>To associate a key with an instance on boot add <para>To associate a key with an instance on boot add
<code>--key_name mykey</code> to your command line. <code>--key_name mykey</code> to your command line.
For example:</para> For example:</para>
<programlisting><?db-font-size 65%?><prompt>$</prompt> nova boot --image ubuntu-cloudimage --flavor 2 --key_name mykey myimage</programlisting> <screen><prompt>$</prompt> <userinput>nova
boot --image ubuntu-cloudimage --flavor 2 --key_name mykey myimage</userinput></screen>
<para>When booting a server, you can also add <para>When booting a server, you can also add
arbitrary metadata, so that you can more easily arbitrary metadata, so that you can more easily
identify it amongst other running instances. Use identify it amongst other running instances. Use
@ -664,11 +661,13 @@ Optional snapshot description. (Default=None)</programlisting>
the key and the value. For example, you could add the key and the value. For example, you could add
a description and also the creator of the a description and also the creator of the
server:</para> server:</para>
<programlisting><?db-font-size 65%?><prompt>$ </prompt>nova boot --image=test-image --flavor=1 --meta description='Small test image' smallimage</programlisting> <screen><prompt>$</prompt> <userinput>nova boot
--image=test-image --flavor=1 --meta description='Small test
image' smallimage</userinput></screen>
<para>When viewing the server information, you can see the <para>When viewing the server information, you can see the
metadata included on the metadata line:</para> metadata included on the metadata line:</para>
<programlisting><prompt>$</prompt> nova show smallimage</programlisting> <screen><prompt>$</prompt> <userinput>nova show smallimage</userinput></screen>
<programlisting><?db-font-size 65%?>+------------------------+-----------------------------------------+ <screen><computeroutput>+------------------------+-----------------------------------------+
| Property | Value | | Property | Value |
+------------------------+-----------------------------------------+ +------------------------+-----------------------------------------+
| OS-DCF:diskConfig | MANUAL | | OS-DCF:diskConfig | MANUAL |
@ -693,7 +692,7 @@ Optional snapshot description. (Default=None)</programlisting>
| tenant_id | e83...482 | | tenant_id | e83...482 |
| updated | 2012-05-16T20:48:35Z | | updated | 2012-05-16T20:48:35Z |
| user_id | de3...0a9 | | user_id | de3...0a9 |
+------------------------+-----------------------------------------+</programlisting> +------------------------+-----------------------------------------+</computeroutput></screen>
</section> </section>
<section xml:id="instance_user_data"> <section xml:id="instance_user_data">
<title>Instance User Data</title> <title>Instance User Data</title>
@ -711,7 +710,8 @@ Optional snapshot description. (Default=None)</programlisting>
system and then passed in at instance creation with system and then passed in at instance creation with
the flag <code>--user-data &lt;user-data-file&gt;</code>. the flag <code>--user-data &lt;user-data-file&gt;</code>.
For example:</para> For example:</para>
<programlisting><?db-font-size 65%?><prompt>$</prompt> nova boot --image ubuntu-cloudimage --flavor 1 --user-data mydata.file</programlisting> <screen><prompt>$</prompt> <userinput>nova boot --image
ubuntu-cloudimage --flavor 1 --user-data mydata.file</userinput></screen>
<para>To understand the difference between user data and <para>To understand the difference between user data and
metadata, realize that user data is created before an metadata, realize that user data is created before an
instance is started. User data is accessible instance is started. User data is accessible
@ -729,7 +729,9 @@ Optional snapshot description. (Default=None)</programlisting>
that you want to put on the instance rather than using that you want to put on the instance rather than using
the regular ssh key injection for some reason you can the regular ssh key injection for some reason you can
use the following command:</para> use the following command:</para>
<programlisting><?db-font-size 65%?><prompt>$</prompt> nova boot --image ubuntu-cloudimage --flavor 1 --file /root/.ssh/authorized_keys=special_authorized_keysfile</programlisting> <screen><prompt>$</prompt> <userinput>nova boot --image
ubuntu-cloudimage --flavor 1 --file
/root/.ssh/authorized_keys=special_authorized_keysfile</userinput></screen>
</section> </section>
</section> </section>
</section> </section>
@ -748,8 +750,10 @@ Optional snapshot description. (Default=None)</programlisting>
<para>It is also possible to add and remove security groups <para>It is also possible to add and remove security groups
when an instance is running. Currently this is only when an instance is running. Currently this is only
available through the command line tools.</para> available through the command line tools.</para>
<programlisting><?db-font-size 65%?><prompt>$</prompt> nova add-secgroup &lt;server&gt; &lt;securitygroup&gt;</programlisting> <screen><prompt>$</prompt> <userinput>nova add-secgroup
<programlisting><?db-font-size 65%?><prompt>$</prompt> nova remove-secgroup &lt;server&gt; &lt;securitygroup&gt;</programlisting> &lt;server&gt; &lt;securitygroup&gt;</userinput></screen>
<screen><prompt>$</prompt> <userinput>nova remove-secgroup
&lt;server&gt; &lt;securitygroup&gt;</userinput></screen>
</section> </section>
<section xml:id="floating_ips"> <section xml:id="floating_ips">
<title>Floating IPs</title> <title>Floating IPs</title>
@ -762,9 +766,9 @@ Optional snapshot description. (Default=None)</programlisting>
<guibutton>Allocate IP to Project</guibutton> button on the <guibutton>Allocate IP to Project</guibutton> button on the
"Access &amp; Security" page of the dashboard. The command "Access &amp; Security" page of the dashboard. The command
line can also be used:</para> line can also be used:</para>
<programlisting><prompt>$</prompt> nova floating-ip-create</programlisting> <screen><prompt>$</prompt> <userinput>nova floating-ip-create</userinput></screen>
<para>Once allocated, a Floating IP can be assigned to running <para>Once allocated, a Floating IP can be assigned to running
instances from the Dashboard either by selecting the instances from the dashboard either by selecting the
<guibutton>Associate Floating IP</guibutton> from the actions drop down next to <guibutton>Associate Floating IP</guibutton> from the actions drop down next to
the IP on the <guilabel>Access &amp; Security</guilabel> page or the same the IP on the <guilabel>Access &amp; Security</guilabel> page or the same
action next to the instance you wish to associate it with action next to the instance you wish to associate it with
@ -776,9 +780,8 @@ Optional snapshot description. (Default=None)</programlisting>
<para>To associate or disassociate a Floating IP to a server <para>To associate or disassociate a Floating IP to a server
from the command line, use the following commands: from the command line, use the following commands:
</para> </para>
<programlisting><prompt>$</prompt> nova add-floating-ip &lt;server&gt; &lt;address&gt;</programlisting> <screen><prompt>$</prompt> <userinput>nova add-floating-ip &lt;server&gt; &lt;address&gt;</userinput></screen>
<programlisting><prompt>$</prompt> nova remove-floating-ip &lt;server&gt; &lt;address&gt;</programlisting> <screen><prompt>$</prompt> <userinput>nova remove-floating-ip &lt;server&gt; &lt;address&gt;</userinput></screen>
</section> </section>
<section xml:id="attach_block_storage"> <section xml:id="attach_block_storage">
<title>Attaching Block Storage</title> <title>Attaching Block Storage</title>
@ -788,10 +791,10 @@ Optional snapshot description. (Default=None)</programlisting>
attach.</para> attach.</para>
<para>To perform this action from command line, run the following <para>To perform this action from command line, run the following
command:</para> command:</para>
<programlisting><prompt>$</prompt> nova volume-attach &lt;server&gt; &lt;volume&gt; &lt;device&gt;</programlisting> <screen><prompt>$</prompt> <userinput>nova volume-attach &lt;server&gt; &lt;volume&gt; &lt;device&gt;</userinput></screen>
<para>You can also specify block device mapping at instance boot time <para>You can also specify block device mapping at instance boot time
through the nova command line client, as follows:</para> through the nova command line client, as follows:</para>
<programlisting>--block-device-mapping &lt;dev-name=mapping&gt; </programlisting> <screen><userinput>--block-device-mapping &lt;dev-name=mapping&gt;</userinput></screen>
<para>The block device mapping format is <para>The block device mapping format is
<code>&lt;dev-name&gt;=&lt;id&gt;:&lt;type&gt;:&lt;size(GB)&gt;:&lt;delete-on-terminate&gt;</code>, <code>&lt;dev-name&gt;=&lt;id&gt;:&lt;type&gt;:&lt;size(GB)&gt;:&lt;delete-on-terminate&gt;</code>,
where:</para> where:</para>
@ -847,7 +850,8 @@ Optional snapshot description. (Default=None)</programlisting>
be attached as <code>/dev/vdc</code>, is not a snapshot, be attached as <code>/dev/vdc</code>, is not a snapshot,
does not specify a size, and will not be deleted when the does not specify a size, and will not be deleted when the
instance is terminated:</para> instance is terminated:</para>
<programlisting><?db-font-size 65%?><prompt>$</prompt> nova boot --image 4042220e-4f5e-4398-9054-39fbd75a5dd7 --flavor 2 --key-name mykey --block-device-mapping vdc=13:::0 boot-with-vol-test</programlisting> <screen><prompt>$</prompt> <userinput>nova boot --image 4042220e-4f5e-4398-9054-39fbd75a5dd7
--flavor 2 --key-name mykey --block-device-mapping vdc=13:::0 boot-with-vol-test</userinput></screen>
<para>If you have previously prepared the block storage with a <para>If you have previously prepared the block storage with a
bootable file system image it is even possible to boot bootable file system image it is even possible to boot
from persistent block storage. The following command from persistent block storage. The following command
@ -855,7 +859,8 @@ Optional snapshot description. (Default=None)</programlisting>
the similar to the previous command but the image is the similar to the previous command but the image is
omitted and the volume is now attached as omitted and the volume is now attached as
<code>/dev/vda</code>:</para> <code>/dev/vda</code>:</para>
<programlisting><?db-font-size 65%?><prompt>$</prompt> nova boot --flavor 2 --key-name mykey --block-device-mapping vda=13:::0 boot-from-vol-test</programlisting> <screen><prompt>$</prompt> <userinput>nova boot --flavor 2 --key-name mykey
--block-device-mapping vda=13:::0 boot-from-vol-test</userinput></screen>
<para>Read more detailed instructions for launching an instance from a <para>Read more detailed instructions for launching an instance from a
bootable volume in the <link bootable volume in the <link
xlink:href="http://docs.openstack.org/user-guide/content/boot_from_volume.html" xlink:href="http://docs.openstack.org/user-guide/content/boot_from_volume.html"
@ -868,13 +873,14 @@ Optional snapshot description. (Default=None)</programlisting>
<section xml:id="snapshots"> <section xml:id="snapshots">
<?dbhtml stop-chunking?> <?dbhtml stop-chunking?>
<title>Taking Snapshots</title> <title>Taking Snapshots</title>
<para>OpenStack's snapshot mechanism allows you to create new <para>The OpenStack snapshot mechanism allows you to create new
images from running instances. This is very convenient images from running instances. This is very convenient
for upgrading base images or taking a published image and for upgrading base images or taking a published image and
customizing for local use. To snapshot a running instance customizing for local use. To snapshot a running instance
to an image using the CLI:</para> to an image using the CLI:</para>
<programlisting><?db-font-size 65%?><prompt>$</prompt> nova image-create &lt;instance name or uuid&gt; &lt;name of new image&gt;</programlisting> <screen><prompt>$</prompt> <userinput>nova image-create &lt;instance
<para>The Dashboard interface for snapshots can be confusing name or uuid&gt; &lt;name of new image&gt;</userinput></screen>
<para>The dashboard interface for snapshots can be confusing
because the Images &amp; Snapshots page splits content up because the Images &amp; Snapshots page splits content up
into:</para> into:</para>
<itemizedlist role="compact"> <itemizedlist role="compact">
@ -963,7 +969,7 @@ Optional snapshot description. (Default=None)</programlisting>
running services normally.</para> running services normally.</para>
<para>To deal with the "dirty" buffer issue, we recommend <para>To deal with the "dirty" buffer issue, we recommend
using the sync command before snapshotting:</para> using the sync command before snapshotting:</para>
<programlisting><?db-font-size 65%?><prompt>#</prompt> sync</programlisting> <screen><prompt>#</prompt> <userinput>sync</userinput></screen>
<para>Running <code>sync</code> writes dirty buffer <para>Running <code>sync</code> writes dirty buffer
(buffered block that have been modified but not (buffered block that have been modified but not
written yet to the disk block) to disk.</para> written yet to the disk block) to disk.</para>
@ -976,7 +982,8 @@ Optional snapshot description. (Default=None)</programlisting>
and XFS. If your virtual machine instance is running and XFS. If your virtual machine instance is running
on Ubuntu, install the util-linux package to get on Ubuntu, install the util-linux package to get
fsfreeze:</para> fsfreeze:</para>
<programlisting><?db-font-size 65%?><prompt>#</prompt> apt-get install util-linux</programlisting> <screen><prompt>#</prompt> <userinput>apt-get install
util-linux</userinput></screen>
<para>If your operating system doesn't have a version of <para>If your operating system doesn't have a version of
fsfreeze available, you can use xfs_freeze instead, fsfreeze available, you can use xfs_freeze instead,
which is available on Ubuntu in the xfsprogs package. which is available on Ubuntu in the xfsprogs package.
@ -1002,7 +1009,8 @@ Optional snapshot description. (Default=None)</programlisting>
<para>To freeze the volume in preparation for <para>To freeze the volume in preparation for
snapshotting, you would do, as root, inside of the snapshotting, you would do, as root, inside of the
instance:</para> instance:</para>
<programlisting><?db-font-size 65%?><prompt>#</prompt> fsfreeze -f /mnt</programlisting> <screen><prompt>#</prompt> <userinput>fsfreeze -f
/mnt</userinput></screen>
<para>You <emphasis role="bold">must mount the file <para>You <emphasis role="bold">must mount the file
system</emphasis> before you run the system</emphasis> before you run the
<command>fsfreeze</command> command.</para> <command>fsfreeze</command> command.</para>
@ -1022,16 +1030,19 @@ Optional snapshot description. (Default=None)</programlisting>
instance was named mon-instance, and you wanted to instance was named mon-instance, and you wanted to
snapshot it to an image, named mon-snapshot, you could snapshot it to an image, named mon-snapshot, you could
now run the following:</para> now run the following:</para>
<programlisting><?db-font-size 65%?><prompt>$</prompt> nova image-create mon-instance mon-snapshot</programlisting> <screen><prompt>$</prompt> <userinput>nova image-create
mon-instance mon-snapshot</userinput></screen>
<para>When the snapshot is done, you can thaw the file <para>When the snapshot is done, you can thaw the file
system with the following command, as root, inside of system with the following command, as root, inside of
the instance:</para> the instance:</para>
<programlisting><?db-font-size 65%?><prompt>#</prompt> fsfreeze -u /mnt</programlisting> <screen><prompt>#</prompt> <userinput>fsfreeze -u
/mnt</userinput></screen>
<para>If you want to backup the root file system, you <para>If you want to backup the root file system, you
can't simply do the command above because it will can't simply do the command above because it will
freeze the prompt. Instead, run the following freeze the prompt. Instead, run the following
one-liner, as root, inside of the instance:</para> one-liner, as root, inside of the instance:</para>
<programlisting><?db-font-size 65%?><prompt>#</prompt> fsfreeze -f / &amp;&amp; sleep 30 &amp;&amp; fsfreeze -u /</programlisting> <screen><prompt>#</prompt> <userinput>fsfreeze -f / &amp;&amp;
sleep 30 &amp;&amp; fsfreeze -u /</userinput></screen>
</sidebar> </sidebar>
</section> </section>
</section> </section>
@ -1095,14 +1106,13 @@ Optional snapshot description. (Default=None)</programlisting>
<section xml:id="user-facing-outro"> <section xml:id="user-facing-outro">
<title>Good Luck!</title> <title>Good Luck!</title>
<para>This section was intended as a brief introduction to <para>This section was intended as a brief introduction to
some of the more useful of OpenStack's thousand commands. For some of the most useful of many OpenStack commands. For
an exhaustive list please refer to the <link an exhaustive list please refer to the <link
xlink:href="http://docs.openstack.org/user-guide-admin/content/">Admin User xlink:href="http://docs.openstack.org/user-guide-admin/content/">Admin User
Guide</link>, and for additional hints and tips please see Guide</link>, and for additional hints and tips please see
the <link xlink:href="http://docs.openstack.org/admin-guide-cloud/content/">Cloud Admin Guide</link>. the <link xlink:href="http://docs.openstack.org/admin-guide-cloud/content/">Cloud Admin Guide</link>.
We hope your users We hope your users remain happy and recognise your hard work!
remain happy and recognise your hard work! (For hard work, turn (For more hard work, turn the page to the next chapter where we discuss
the page to the next chapter where we discuss the system-facing the system-facing operations: Maintenance, Failures and Debugging.)</para>
operations: Maintenance, Failures and Debugging.)</para>
</section> </section>
</chapter> </chapter>