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