From b2c7f2864c999785c68b4a461606bfb572c7d5ba Mon Sep 17 00:00:00 2001 From: Karin Levenstein Date: Sat, 19 Apr 2014 09:22:53 -0500 Subject: [PATCH] bk and ch fixes: edits up to cli_nova_boot, removed excess info - excess removed from cli_version - removed redundant section from ch_cli Change-Id: I31b5c49e007ec2ff5e58b964c8b32dbcfa7cab32 --- .../section_cli_glance_manage_images.xml | 386 +++++++++--------- doc/common/section_cli_install.xml | 301 +++++++------- doc/common/section_cli_nova_boot.xml | 215 +++++----- doc/common/section_cli_nova_manage_images.xml | 45 +- doc/common/section_cli_nova_userdata.xml | 18 +- doc/common/section_cli_openrc.xml | 110 ++--- doc/common/section_cli_overview.xml | 24 +- doc/common/section_cli_version.xml | 59 +-- doc/user-guide/bk-user-guide.xml | 22 +- .../section_cli_nova_configure_instances.xml | 281 ++++++------- 10 files changed, 703 insertions(+), 758 deletions(-) diff --git a/doc/common/section_cli_glance_manage_images.xml b/doc/common/section_cli_glance_manage_images.xml index d8856b2442..ca2e836720 100644 --- a/doc/common/section_cli_glance_manage_images.xml +++ b/doc/common/section_cli_glance_manage_images.xml @@ -9,19 +9,19 @@ who can upload and manage images. The operator might restrict image upload and management to only cloud administrators or operators. - 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. + 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. For details about image creation, see the Virtual Machine Image Guide.
List or get details for images (glance) - - - To list the available images: + To get a list of images and to then get further details about a single image, + use glance image-list and glance + image-show. $ glance image-list +--------------------------------------+---------------------------------+-------------+------------------+----------+--------+ | 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 | +--------------------------------------+---------------------------------+-------------+------------------+----------+--------+ - You can use grep to filter the list, as - follows: - $ glance image-list | grep 'cirros' -| 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 | - - - To get image details, by name or ID: - $ glance image-show myCirrosImage -+---------------------------------------+--------------------------------------+ + $ glance image-show myCirrosImage + ++---------------------------------------+--------------------------------------+ | Property | Value | +---------------------------------------+--------------------------------------+ | Property 'base_image_ref' | 397e713c-b95b-4186-ad46-6126863ea0a9 | @@ -79,6 +71,12 @@ | status | active | | updated_at | 2013-07-22T19:46:42 | +---------------------------------------+--------------------------------------+ + When viewing a list of images, you can also use grep to filter the + list, as follows: + $ glance image-list | grep 'cirros' +| 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 | To store location metadata for images, which enables direct file access for a client, update the /etc/glance/glance.conf @@ -89,17 +87,13 @@ show_multiple_locations = True - filesystem_store_metadata_file - = - filePath, - where - filePath - points to a JSON file that defines - the mount point for OpenStack - images on your system and a unique - ID. For example: - [{ - "id": "b9d69795-5951-4cb0-bb5c-29491e1e2daf", + filesystem_store_metadata_file = + filePath, where + filePath points to a JSON file + that defines the mount point for OpenStack images on your system + and a unique ID. For example: + [{ + "id": "2d9bb53f-70ea-4066-a68b-67960eaae673", "mountpoint": "/var/lib/glance/images/" }] @@ -107,178 +101,188 @@ After you restart the Image Service, you can use the following syntax to view the image's location information: $ glance --os-image-api-version=2 image-show imageID - For example: + For example, using the image ID shown above, you would issue the command + as follows: $ glance --os-image-api-version=2 image-show 2d9bb53f-70ea-4066-a68b-67960eaae673 - -
Create or update an image (glance) - - - To upload a CentOS 6.3 image in qcow2 format and - configure it for public access: + To create an image, use glance image-create: + $ glance image-create imageName + To update an image by name or ID, use glance image-update: + + $ glance image-update imageName + + The following table lists the optional arguments that you can use with the + create and update commands to modify image + properties. For more information, refer to Image Service chapter in the OpenStack + Command-Line Interface Reference. + + + + + + --name NAME + + + The name of the image. + + + + + --disk-format DISK_FORMAT + + + The disk format of the image. Acceptable formats are ami, ari, aki, vhd, + vmdk, raw, qcow2, vdi, and iso. + + + + + --container-format CONTAINER_FORMAT + + + The container format of the image. Acceptable formats are ami, ari, aki, + bare, and ovf. + + + + + --owner TENANT_ID + + + The tenant who should own the image. + + + + + --size SIZE + + + The size of image data, in bytes. + + + + + --min-disk DISK_GB + + + The minimum size of the disk needed to boot the image, in + gigabytes. + + + + + --min-ram DISK_RAM + + + The minimum amount of RAM needed to boot the image, in megabytes. + + + + + --location IMAGE_URL + + + The URL where the data for this image resides. For example, if the image + data is stored in swift, you could specify + swift://account:key@example.com/container/obj. + + + + + --file FILE + + + Local file that contains the disk image to be uploaded during the update. + Alternatively, you can pass images to the client through stdin. + + + + + --checksum CHECKSUM + + + Hash of image data to use for verification. + + + + + --copy-from IMAGE_URL + + + Similar to --location in usage, but indicates that + the image server should immediately copy the data and store it in its + configured image store. + + + + + --is-public [True|False] + + + Makes an image accessible for all the tenants. + + + + + --is-protected [True|False] + + + Prevents an image from being deleted. + + + + + --property KEY=VALUE + + + Arbitrary property to associate with image. This option can be used + multiple times. + + + + + --purge-props + + + Deletes all image properties that are not explicitly set in the update + request. Otherwise, those properties not referenced are preserved. + + + + + --human-readable + + + Prints the image size in a human-friendly format. + + + + 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: $ glance image-create --name centos63-image --disk-format=qcow2 \ --container-format=bare --is-public=True --file=./centos63.qcow2 - - - To update an image by name or ID: - $ glance image-update IMAGE - To modify image properties, use the following - optional arguments: - - - - - --name - NAME - The name of the image. - - - - --disk-format - DISK_FORMAT - The disk format of the image. - Acceptable formats are ami, ari, aki, - vhd, vmdk, raw, qcow2, vdi, and - iso. - - - - --container-format - CONTAINER_FORMAT - The container format of the image. - Acceptable formats are ami, ari, aki, - bare, and ovf. - - - - --owner - TENANT_ID - The tenant who should own the - image. - - - - --size - SIZE - The size of image data, in - bytes. - - - - --min-disk - DISK_GB - The minimum size of disk needed to - boot image, in gigabytes. - - - - --min-ram - DISK_RAM - The minimum amount of ram needed to - boot image, in megabytes. - - - - --location - IMAGE_URL - The URL where the data for this - image resides. For example, if the - image data is stored in swift, you - could specify - swift://account:key@example.com/container/obj. - - - - --file - FILE - Local file that contains disk image - to be uploaded during update. - Alternatively, you can pass images to - the client through stdin. - - - - --checksum - CHECKSUM - Hash of image data to use for - verification. - - - - --copy-from - IMAGE_URL - Similar to - --location - in usage, but indicates that the - Image server should immediately copy - the data and store it in its - configured image store. - - - - --is-public - [True|False] - Makes an image accessible to the - public. - - - - --is-protected - [True|False] - Prevents an image from being - deleted. - - - - --property - KEY=VALUE - Arbitrary property to associate with - image. Can be used multiple - times. - - - - --purge-props - Deletes all image properties that - are not explicitly set in the update - request. Otherwise, those properties - not referenced are preserved. - - - - --human-readable - Prints image size in a - human-friendly format. - - - - - - To annotate an image with a property that describes the disk_bus, cdrom_bus, - and vif_model: + 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: $ glance image-update \ --property hw_disk_bus=scsi \ --property hw_cdrom_bus=ide \ --property hw_vif_model=e1000 \ f16-x86_64-openstack-sda - Currently libvirt will determine the disk/cdrom/vif device models based on the - configured hypervisor type (libvirt_type in - /etc/nova/nova.conf). 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. + Currently the libvirt virtualization tool determines the disk, CD-ROM, and VIF + device models based on the configured hypervisor type (libvirt_type + in /etc/nova/nova.conf). 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. If you specify a disk or CD-ROM bus model that is not supported, see . If you specify a VIF model that is not supported, the instance fails to launch. See . - - - The valid model values depend on the - libvirt_type setting, as shown in - the following tables: + The valid model values depend on the libvirt_type setting, as shown + in the following tables. @@ -407,6 +411,8 @@
Troubleshoot image creation + If you encounter problems in creating an image in Image Service or Compute, the + following information may help you troubleshoot the creation process. You cannot create a snapshot from an instance @@ -414,11 +420,9 @@ create the image, and re-mount the volume. - Make sure the version of qemu you are using is - version 0.14 or greater. Older versions of qemu - result in an "unknown option - -s" error message in the - nova-compute.log. + Ensure that the version of qemu you are using is version 0.14 or later. + Earlier versions of qemu result in an unknown option -s error + message in the nova-compute.log file. Examine the diff --git a/doc/common/section_cli_install.xml b/doc/common/section_cli_install.xml index 47668a18bd..67fbf7c9fa 100644 --- a/doc/common/section_cli_install.xml +++ b/doc/common/section_cli_install.xml @@ -5,7 +5,6 @@ - ]>
Install the OpenStack command-line clients Install the prerequisite software and the Python package for each OpenStack client. - - For each command, replace - PROJECT with the lower case - name of the client to install, such as - nova. Repeat for each - client. - +
+ Install the prerequisite software + The following table lists the software that you need to + have to run the command-line clients, and provides + installation instructions as needed.
Disk and CD-ROM bus model values
@@ -35,7 +32,7 @@
Prerequisite software
- Python 2.6 or newer + Python 2.6 or later Currently, the clients do not support Python @@ -71,168 +68,186 @@
pip package - To install the clients on a Linux, Mac OS X or Microsoft - Windows system, use pip. It - is easy to use, ensures that you get the - latest version of the clients from the Python Package Index, and lets you - update or remove the packages later on. + To install the clients on a Linux, Mac OS X, + or Microsoft Windows system, use + pip. It is easy to + use, ensures that you get the latest + version of the clients from the Python Package Index, and lets + you update or remove the packages later + on. Install pip through the package manager for your system: - Mac OS X - - # easy_install pip + MacOS + # easy_install pip Microsoft Windows - Make sure that the - C:\Python27\Scripts directory - is defined in the PATH - environment variable, and use the - easy_install command from the - setuptools package: - C:\>easy_install pip - Another option is to use the unofficial binary - installer provided by Christoph Gohlke (http://www.lfd.uci.edu/~gohlke/pythonlibs/#pip). + Ensure that the + C:\Python27\Scripts + directory is defined in the + PATH environment + variable, and use the + easy_install + command from the + setuptools + package: + C:\>easy_install pipAnother + option is to use the unofficial binary + installer provided by Christoph Gohlke + (http://www.lfd.uci.edu/~gohlke/pythonlibs/#pip). - Ubuntu 12.04 + Ubuntu 12.04/14.04 A packaged version enables you to use - dpkg or - aptitude to install - the - python-novaclient:# aptitude install python-novaclient + dpkg or + aptitude to + install the + python-novaclient: + # aptitude install python-novaclient Ubuntu and Debian # aptitude install python-pip - + - RHEL, CentOS, or Fedora + Red Hat Enterprise Linux, CentOS, or Fedora A packaged version available in RDO enables you to use - yum to install the - clients: - # yum install python-PROJECTclient - - Alternatively, install + xlink:href="http://openstack.redhat.com/">RDO + enables you to use yum + to install the clients, or you can install pip and use it to - manage client installation: - # yum install python-pip + manage client installation: # yum install python-pip + openSUSE 12.2 and earlier A packaged version available in the - Open Build Service enables you - to use rpm or - zypper to install - the - python-novaclient:# zypper install python-PROJECT - Alternatively, install - pip and use it to - manage client installation: - # zypper install python-pip + xlink:href="https://build.opensuse.org/package/show?package=python-novaclient&project=Cloud:OpenStack:Master">packaged + version available in the Open Build + Service enables you to use + rpm or + zypper to install the + clients, or you can install + pip and use it to manage client installation: + # zypper install python-pip + - openSUSE 12.3 and newer + openSUSE 12.3 and later A packaged version enables you to use - rpm or - zypper to install - the clients: - # zypper install python-PROJECTclient + rpm or + zypper to install the + clients. See
+
Install the clients - Use pip 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 Python - Package Index. Also, pip - lets you update or remove a package. After you install the - clients, you must source an PROJECT-openrc.sh - file to set required environment - variables before you can request OpenStack services - through the clients or the APIs. - - - Install each client separately using: - - For Mac OS X or Linux: - # pip install python-PROJECTclient - For Microsoft Windows: - C:\>pip install python-PROJECTclient - - Where PROJECT is the - project name and has one of the following - values: - - - ceilometer - Telemetry API. - - - cinder - Block Storage - API and extensions. - - - glance - Image Service - API. - - - heat - Orchestration - API. - - - keystone - Identity - service API and extensions. - - - neutron - Networking - API. - - - nova - Compute API and - extensions. - - - swift - Object Storage - API. - - - trove - Database Service - API. - - - For example, to install the nova client, run - this command: - # pip install python-novaclient - To remove the nova client, run this - command: - # pip uninstall python-novaclient - To upgrade a package, add the + When following the instructions in this section, replace + PROJECT with the lowercase + name of the client to install, such as + nova. Repeat for each client. The + following values are valid: + + + ceilometer - Telemetry + API + + + cinder - Block Storage API + and extensions + + + glance - Image Service + API + + + heat - Orchestration + API + + + keystone - Identity service + API and extensions + + + neutron - Networking + API + + + nova - Compute API and + extensions + + + swift - Object Storage + API + + + trove - Database Service + API + + + The following example shows the command for installing + the nova client with + pip. + # pip install python-novaclient +
+ Installing with pip + Use pip 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 Python + Package Index. Also, pip + enables you to update or remove a package. + Install each client separately by using the + following command: + + For Mac OS X or Linux: + # pip install python-PROJECTclient + For Microsoft Windows: + C:\>pip install python-PROJECTclient + +
+
+ Installing from packages + RDO and openSUSE have client packages that can be + installed without pip. + On Red Hat Enterprise Linux, CentOS, or Fedora, use + yum to install the clients from + the packaged versions available in RDO: + # yum install python-PROJECTclient + For openSUSE, use rpm or + zypper to install the clients + from the packaged versions available in the Open Build + Service:# zypper install python-PROJECT +
+
+
+ Upgrade or remove clients + To upgrade a client, add the --upgrade option to the - pip command. - For example, to update the nova client, run this - command: - # pip install --upgrade python-novaclient - - - Before you can run client commands, you must - create and source the - PROJECT-openrc.sh - file to set environment variables. See . - - + pip install command: + # pip install --upgrade python-PROJECTclient + To remove the a client, run the pip + uninstall command: + # pip uninstall python-PROJECTclient +
+
+ What's next + Before you can run client commands, you must create + and source the + PROJECT-openrc.sh + file to set environment variables. See .
diff --git a/doc/common/section_cli_nova_boot.xml b/doc/common/section_cli_nova_boot.xml index f39e4b1dc5..de1749b389 100644 --- a/doc/common/section_cli_nova_boot.xml +++ b/doc/common/section_cli_nova_boot.xml @@ -10,57 +10,46 @@ parameters: - The instance source, 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. - - - The image or - snapshot, which represents - the operating system. + The instance source. This can be an + image, a snapshot, or a block storage volume that contains an + image or snapshot. A name for your instance. - The flavor 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. + The flavor 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. - User Data 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 Any user data 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 + cloudinit 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 user - data. + >cloud-init 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. Access and security credentials, which include one or both of the following credentials: - A keypair - 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 cloud-init - 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. + A key pair 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 + cloud-init 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. A security @@ -74,32 +63,42 @@ - If needed, you can assign a floating (public) IP address to a - running instance and attach a block storage device, or - volume, for persistent storage. + If needed, you can assign a floating + (public) IP address to a running instance. + - - After you gather the parameters you need to launch an - instance, you can launch it from an - image or a - volume. - 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 + + You can also attach a block storage device, or volume, for persistent + storage. + + + 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. + You can also assign a floating IP address to a running + instance to make it accessible from outside the cloud. + See . + + After you gather the parameters that you need to launch an instance, + you can launch it from an image + or a volume. 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.
Gather parameters to launch an instance + + Before you begin, source the OpenStack RC file. - On a shell, source the OpenStack RC file. See - . - - - List the available flavors: + List the available flavors and note the ID of the flavor + that you want to use for your instance. $ nova flavor-list +----+-----------+-----------+------+-----------+------+-------+-------------+-----------+ | 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 | +----+-----------+-----------+------+-----------+------+-------+-------------+-----------+ - Note the ID of the flavor that you want to use - for your instance. - List the available images: + List the available images and note the ID of the image + from which you want to boot your instance. $ nova image-list +--------------------------------------+---------------------------------+--------+--------+ | 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 | | +--------------------------------------+---------------------------------+--------+--------+ - You can also filter the image list by using grep - to find a specific image, like this: + You can also filter the image list by using + grep to find a specific image, as + follows: $ nova image-list | grep 'kernel' | df430cc2-3406-4061-b635-a51c16e488ac | cirros-0.3.2-x86_64-uec-kernel | ACTIVE | | - Note the ID of the image that you want to boot - your instance from. - List the available security groups: + List the available security groups and note the ID of the + security group that you want to use for your + instance. If you are an admin user, specify the - --all-tenants parameter + parameter to list groups for all tenants. $ nova secgroup-list --all-tenants @@ -147,18 +146,13 @@ If you have not created any security groups, you can assign the instance to only the default security group. - You can also list rules for a specified security - group: + You can view rules for a specified security group: $ nova secgroup-list-rules default - This example modifies the default security group - to allow HTTP traffic on the instance by - permitting TCP traffic on Port 80. - List the available keypairs. + List the available key pairs and note the name of the key + pair that you use for SSH access. $ nova keypair-list - Note the name of the keypair that you use for - SSH access.
@@ -167,22 +161,33 @@ Launch an instance from an image - 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 --meta description="My + 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 --meta description="My Server" parameter. - You can pass user data in a local file at - instance launch by using the flag - --user-data + You can pass user data in a local file at instance launch + by using the --user-data USER-DATA-FILE parameter. $ nova boot --flavor FLAVOR_ID --image IMAGE_ID --key-name KEY_NAME \ - --user-data mydata.file --security-groups SEC_GROUP --meta KEY=VALUE \ + --user-data USER_DATA_FILE --security-groups SEC_GROUP --meta KEY=VALUE \ + INSTANCE_NAME + The following example shows a the command for launching an + instance called MyCirrosServer with the + m1.small flavor (ID of + 1), + cirros-0.3.2-x86_64-uec image (ID + of + 397e713c-b95b-4186-ad46-6126863ea0a9), + the default security group, the + KeyPair01 key, and a user data file + called cloudinit.file. + $ nova boot --flavor 1 --image 397e713c-b95b-4186-ad46-6126863ea0a9 \ + --security-groups default --key-name KeyPair01 --user-data cloudinit.file \ myCirrosServer 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. Copy the administrative password value from the - adminPass field. You use - this value to log into your server. + adminPass field. You use this value + to log in to your server. - Arbitrary local files can also be placed - into the instance file system at creation time - using the --file - <dst-path=src-path> - option. You may store up to 5 files. For - example, if you have a special authorized_keys - file named + You can also place arbitrary local files into the + instance file system at creation time by using the + + option. You can store up to five files. For example, if + you have a special authorized keys file named special_authorized_keysfile - that you want to put on the instance rather - than using the regular ssh key injection, you - can use the following - command:$ 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 as shown in the + following + example:$ nova boot --image ubuntu-cloudimage --flavor 1 vm-name \ --file /root/.ssh/authorized_keys=special_authorized_keysfile Check if the instance is online: $ nova list - 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: + 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: +--------------------------------------+----------------------+--------+------------+-------------+------------------+ | ID | Name | Status | Task State | Power State | Networks | +--------------------------------------+----------------------+--------+------------+-------------+------------------+ @@ -265,14 +268,10 @@ following command: $ nova help list - - 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. - - - + 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. + diff --git a/doc/common/section_cli_nova_manage_images.xml b/doc/common/section_cli_nova_manage_images.xml index 45d5522e44..aa7191b1d1 100644 --- a/doc/common/section_cli_nova_manage_images.xml +++ b/doc/common/section_cli_nova_manage_images.xml @@ -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"> - Create image (nova) - You can use the nova client to list images, set and delete - image metadata, delete images, and take a snapshot of a + Create an image (nova) + You can use the nova client to take a snapshot of a running instance to create an image. - The safest approach is to shut down the instance before you - take a snapshot. - You cannot create a snapshot from an instance that has an - attached volume. Detach the volume, create the image, and - re-mount the volume. + 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. + You cannot create a snapshot from an instance that has an attached + volume. Detach the volume, create the image, and remount the + volume. Write any buffered data to disk. - For more information, see For more information, see Taking Snapshots in the OpenStack Operations Guide. - To create the image, list instances to get the - server ID: + List instances to get the server name: $ nova list +--------------------------------------+----------------------+--------+------------+-------------+------------------+ | 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 | +--------------------------------------+----------------------+--------+------------+-------------+------------------+ In this example, the server is named - myCirrosServer. Use this server - to create a snapshot, as follows: + myCirrosServer. + Use this server to create a snapshot: $ nova image-create myCirrosServer myCirrosImageThe - command creates a qemu snapshot and automatically - uploads the image to your repository. Only the tenant - that creates the image has access to it. + command creates a qemu snapshot and automatically uploads the + image to your repository. Only the tenant that creates the image + has access to it. - Get details for your image to check its - status: - $ nova image-show IMAGE + Get details for your image to check its status: + $ nova image-show myCirrosImage +-------------------------------------+--------------------------------------+ | Property | Value | +-------------------------------------+--------------------------------------+ @@ -80,9 +77,9 @@ ACTIVE. Only the tenant who creates the image has access to it. - - To launch an instance from your image, include the - image ID and flavor ID, as follows: + + To launch an instance from your image, include the image ID + and flavor ID, as in the following example: $ nova boot newServer --image 7e5142af-1253-4634-bcc6-89482c5f2e8a \ --flavor 3 +-------------------------------------+--------------------------------------+ @@ -115,6 +112,4 @@ | created | 2013-07-22T19:58:33Z | | metadata | {} | +-------------------------------------+--------------------------------------+ - - diff --git a/doc/common/section_cli_nova_userdata.xml b/doc/common/section_cli_nova_userdata.xml index e313d325a8..d16005f942 100644 --- a/doc/common/section_cli_nova_userdata.xml +++ b/doc/common/section_cli_nova_userdata.xml @@ -1,19 +1,17 @@ -
Provide user data to instances - User data 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 cloudinit system is a Ubuntu open - source package that handles early initialization of a cloud - instance and that makes use of user - data. + 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 cloud-init 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. You can place user data in a local file and pass it through the --user-data <user-data-file> parameter at instance creation: diff --git a/doc/common/section_cli_openrc.xml b/doc/common/section_cli_openrc.xml index 76225f1075..5f2b802228 100644 --- a/doc/common/section_cli_openrc.xml +++ b/doc/common/section_cli_openrc.xml @@ -4,9 +4,11 @@ xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="cli_openrc"> - The OpenStack RC file + Set environment variables using the OpenStack RC + file 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 openrc.sh file. 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. - Environment variables on Microsoft Windows Defining environment variables using an environment file is not a common practice on Microsoft Windows. Environment variables are usually - defined in the Advanced tab of the System - Properties dialog. + defined in the Advanced tab of the System + Properties dialog box.
Download and source the OpenStack RC file @@ -34,32 +35,32 @@ & Security. - - Click on the API Access tab. Click - Download OpenStack RC File - and save the file. The filename will be of the form - PROJECT-openrc.sh - where PROJECT is the name - of the project for which you downloaded the file. - + On the API Access tab, click Download + OpenStack RC File and save the + file. The filename will be of the form + PROJECT-openrc.sh + where PROJECT is the + name of the project for which you downloaded the + file. Copy the - PROJECT-openrc.sh - file to the machine from where you want to run - OpenStack commands. - For example, copy the file to the machine from - where you want to upload an image with a glance - client command. + PROJECT-openrc.sh + file to the computer from which you want to run + OpenStack commands. + For example, copy the file to the computer from + which you want to upload an image with a + glance client + command. - On any shell from where you want to run + On any shell from which you want to run OpenStack commands, source the - PROJECT-openrc.sh + PROJECT-openrc.sh file for the respective project. - In this example, you source the - demo-openrc.sh file for - the demo project: + In the following example, the + demo-openrc.sh file is + sourced for the demo project: $ source demo-openrc.sh @@ -73,45 +74,54 @@
Create and source the OpenStack RC file Alternatively, you can create the - PROJECT-openrc.sh file from - scratch. + PROJECT-openrc.sh + file from scratch, if for some reason you cannot download + the file from the dashboard. - Create the PROJECT-openrc.sh file - and add the authentication information: - export OS_USERNAME=USERNAME -export OS_PASSWORD=PASSWORD -export OS_TENANT_NAME=PROJECT_NAME -export OS_AUTH_URL=https://IDENTITY_HOST:PORT/v2.0 + In a text editor, create a file named + PROJECT-openrc.sh + file and add the following authentication + information: + export OS_USERNAME=username +export OS_PASSWORD=password +export OS_TENANT_NAME=projectName +export OS_AUTH_URL=https://identityHost:portNumber/v2.0 # The following lines can be omitted -export OS_TENANT_ID=9d792532ffce494583138c495801d164 -export OS_REGION_NAME=RegionOne +export OS_TENANT_ID=tenantIDString +export OS_REGION_NAME=regionName + The following example shows the information for + a project called admin, where + the OS username is also admin, + and the identity host is located at + controller. export OS_USERNAME=admin export OS_PASSWORD=ADMIN_PASS export OS_TENANT_NAME=admin -export OS_AUTH_URL=http://controller:35357/v2.0 +export OS_AUTH_URL=http://controller:35357/v2.0 - On any shell from where you want to run + On any shell from which you want to run OpenStack commands, source the - PROJECT-openrc.sh - file for the - respective project. In this example, you source the + PROJECT-openrc.sh + file for the respective project. In this example, + you source the admin-openrc.sh file for - the admin project: + the admin + project: $ source admin-openrc.sh You are not prompted for the password with this method. The password lives in clear text format in the - PROJECT-openrc.sh - file. Restrict the - permissions on this file to avoid security problems. - You can also remove the OS_PASSWORD - variable from the file, and use the - --password parameter with - OpenStack client commands. + PROJECT-openrc.sh + file. Restrict the permissions on this file to avoid + security problems. You can also remove the + OS_PASSWORD variable from the + file, and use the --password + parameter with OpenStack client commands + instead.
@@ -122,11 +132,9 @@ export OS_AUTH_URL=http://controller:35357/v2.0OS_PASSWORD setting in the PROJECT-openrc.sh - file by specifying a - password on a keystone command, as + file by specifying a password on a keystone command, as follows: $ keystone --os-password PASSWORD service-list - Where PASSWORD is your - password. + Where PASSWORD is your password.
diff --git a/doc/common/section_cli_overview.xml b/doc/common/section_cli_overview.xml index c9b2091bb3..8c43d9bdaa 100644 --- a/doc/common/section_cli_overview.xml +++ b/doc/common/section_cli_overview.xml @@ -12,11 +12,10 @@ xmlns:raxm="http://docs.rackspace.com/api/metadata" version="5.0" xml:id="section_cli_overview"> Overview - 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. + 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. 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 @@ 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 debug + can specify a debug parameter to show the underlying API request for the command. This is a good way to become familiar with the OpenStack API calls. - The following table lists the command-line client for each - OpenStack service, together with its - package name and description. + The following table lists the command-line client for each OpenStack + service with its package name and description. @@ -84,8 +78,8 @@ - + diff --git a/doc/common/section_cli_version.xml b/doc/common/section_cli_version.xml index d28f5834e7..1440ba24c7 100644 --- a/doc/common/section_cli_version.xml +++ b/doc/common/section_cli_version.xml @@ -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"> - Get the version for a client - Run this command get the version number for a - client: + Discover the version number for a client + Run the following command to discover the version number + for a client:$ PROJECT --version - Where PROJECT is a project - name: - - - ceilometer - Telemetry API. - - - cinder - Block Storage - API and extensions. - - - glance - Image Service - API. - - - heat - Orchestration - API. - - - keystone - Identity - service API and extensions. - - - neutron - Networking - API. - - - nova - Compute API and - extensions. - - - swift - Object Storage - API. - - - trove - Database Service - API. - - For example, to see the version number for the - nova client, run this - command: - $ nova --version -2.15.0 - To see the version number for the - keystone client, run this - command: - $ keystone --version -0.4.0 + nova client, run the + following command: + $ nova --version + The version number (2.15.0 in the example) is returned. + 2.15.0 diff --git a/doc/user-guide/bk-user-guide.xml b/doc/user-guide/bk-user-guide.xml index 49c24973f9..4b6bbcd4ee 100644 --- a/doc/user-guide/bk-user-guide.xml +++ b/doc/user-guide/bk-user-guide.xml @@ -35,12 +35,13 @@ - 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. + 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. @@ -52,8 +53,7 @@ information is now in the OpenStack Command-Line - Interface - Reference. + Interface Reference. @@ -63,7 +63,8 @@ - Added the OpenStack Python SDK chapter. + Added the OpenStack Python SDK + chapter. @@ -93,7 +94,8 @@ - First edition of this document. + First edition of this + document. diff --git a/doc/user-guide/section_cli_nova_configure_instances.xml b/doc/user-guide/section_cli_nova_configure_instances.xml index b733905e8f..66ad9fba30 100644 --- a/doc/user-guide/section_cli_nova_configure_instances.xml +++ b/doc/user-guide/section_cli_nova_configure_instances.xml @@ -16,38 +16,35 @@ xml:id="cli_configure_instances"> Configure access and security for instances - When you launch a virtual machine, you can inject a - keypair, which provides - SSH access to your instance. For this to work, the image must - contain the cloud-init 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 – neither is recommended – you must - not provide a keypair when you launch the instance. - A security group is a - named collection of network access rules that you use to limit - the types of traffic that have access to instances. When you - launch an instance, you can assign 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 rules in each - security group control the traffic to instances in the group. - Any incoming traffic that is not matched by a rule is denied - access by default. You can add rules to or remove rules from a - security group. You can modify rules for the default and any - other security group. - 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. - 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 – for - example, for a DNS server running on an instance. You specify - the following parameters for rules: + When you launch a virtual machine, you can inject a key pair, which provides SSH access to your + instance. For this to work, the image must contain the + cloud-init package. + 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. + If an image uses a static root password or a static key set – + neither is recommended – you must not provide a key pair when you + launch the instance. + A security group is a named + collection of network access rules that you use to limit the types of + traffic that have access to instances. When you launch an instance, you + can assign 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 rules in each + security group control the traffic to instances in the group. Any + incoming traffic that is not matched by a rule is denied access by + default. You can add rules to or remove rules from a security group, and + you can modify rules for the default and any other security + group. + 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: Source of traffic. @@ -61,65 +58,60 @@ Destination port on virtual - machine. 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. + machine. 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. Rules are automatically enforced as soon as you create or modify them. - 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 . + + 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. + You can also assign a floating IP address to a running instance to + make it accessible from outside the cloud. See .
- Add a keypair + Add a key pair - You can generate a keypair or upload an existing - public key. + You can generate a key pair or upload an existing public + key. - To generate a keypair, run the following - command: + To generate a key pair, run the following command: $ nova keypair-add KEY_NAME > MY_KEY.pem - The command generates a keypair named - KEY_NAME, writes - the private key to the - MY_KEY.pem - file, and registers the public key at the Nova + The command generates a key pair with the name that you + specify fir KEY_NAME, writes the + private key to the .pem file that you + specify, and registers the public key at the Nova database. - To set the permissions of the - MY_KEY.pem - file, run the following command: + To set the permissions of the .pem + file so that only you can read and write to it, run the + following command: $ chmod 600 MY_KEY.pem - The command changes the permissions of the - MY_KEY.pem - file so that only you can read and write to - it.
- Import a keypair + Import a key pair - If you have already generated a keypair with the - public key located at - ~/.ssh/id_rsa.pub, run - the following command to upload the public - key: + If you have already generated a key pair and the public + key is located at ~/.ssh/id_rsa.pub, + run the following command to upload the public key: $ nova keypair-add --pub_key ~/.ssh/id_rsa.pub KEY_NAME - The command registers the public key at the Nova - database and names the keypair + The command registers the public key at the Nova database + and names the key pair the name that you specify for KEY_NAME. - List keypairs to make sure that the uploaded - keypair appears in the list: + To ensure that the key pair has been successfully + imported, list key pairs as follows: $ nova keypair-list @@ -128,21 +120,20 @@ Create and manage security groups - To list security groups for the current project, - including descriptions, enter the following - command: + To list the security groups for the current project, + including descriptions, enter the following command: $ nova secgroup-list To create a security group with a specified name and description, enter the following command: - $ nova secgroup-create SEC_GROUP_NAME GROUP_DESCRIPTION + $ nova secgroup-create SECURITY_GROUP_NAME GROUP_DESCRIPTION To delete a specified group, enter the following command: - $ nova secgroup-delete SEC_GROUP_NAME + $ nova secgroup-delete SECURITY_GROUP_NAME You cannot delete the default security group for a project. Also, you cannot delete a @@ -156,98 +147,80 @@ Create and manage security group rules Modify security group rules with the nova - secgroup-*-rule commands. + secgroup-*-rule commands. Before you begin, source + the OpenStack RC file. For details, see . - On a shell, source the OpenStack RC file. For - details, see . + To list the rules for a security group, run the following + command: + $ nova secgroup-list-rules SECURITY_GROUP_NAME - To list the rules for a security group - $ nova secgroup-list-rules SEC_GROUP_NAME - - - To allow SSH access to the instances, choose one - of the following sub-steps: - - - Add rule for all - IPs - Either from all IP addresses (specified - as IP subnet in CIDR notation as - 0.0.0.0/0): - $ nova secgroup-add-rule SEC_GROUP_NAME tcp 22 22 0.0.0.0/0 - - - Add rule for security - groups - Alternatively, you can allow only IP - addresses from other security groups - (source groups) to access the specified - port: + To allow SSH access to the instances, choose one of the + following options: + + + Allow access from all IP addresses, specified as + IP subnet 0.0.0.0/0 in CIDR + notation: + $ nova secgroup-add-rule SECURITY_GROUP_NAME tcp 22 22 0.0.0.0/0 + + + Allow access only from IP addresses from other + security groups (source groups) to access the + specified port: $ nova secgroup-add-group-rule --ip_proto tcp --from_port 22 \ - --to_port 22 SEC_GROUP_NAME SOURCE_GROUP_NAME - - + --to_port 22 SECURITY_GROUP_NAME SOURCE_GROUP_NAME + + - To allow pinging the instances, choose one of - the following sub-steps: - - - To allow pinging from - IPs - Specify all IP addresses as IP subnet in - CIDR notation: - 0.0.0.0/0. This - command allows access to all codes and all - types of ICMP traffic, - respectively: - $ nova secgroup-add-rule SEC_GROUP_NAME icmp -1 -1 0.0.0.0/0 - - - To allow pinging from - other security groups - To allow only members of other security - groups (source groups) to ping - instances: + To allow pinging of the instances, choose one of the + following options: + + + Allow pinging from all IP addresses, specified as + IP subnet 0.0.0.0/0 in CIDR + notation: + $ nova + secgroup-add-rule SECURITY_GROUP_NAME icmp -1 -1 0.0.0.0/0This allows access to all codes and all + types of ICMP traffic. + + + Allow only members of other security groups + (source groups) to ping instances: $ nova secgroup-add-group-rule --ip_proto icmp --from_port -1 \ - --to_port -1 SEC_GROUP_NAME SOURCE_GROUP_NAME - - + --to_port -1 SECURITY_GROUP_NAME SOURCE_GROUP_NAME + + - 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: - - - To allow UDP access from IPs, specify - all IP addresses as IP subnet in CIDR - notation: - 0.0.0.0/0.$ nova secgroup-add-rule SEC_GROUP_NAME udp 53 53 0.0.0.0/0 - - - To allow only IP addresses from other - security groups (source groups) to access - the specified port: + 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: + + + Allow UDP access from IP addresses, specified as + IP subnet 0.0.0.0/0 in CIDR + notation:$ nova secgroup-add-rule SECURITY_GROUP_NAME udp 53 53 0.0.0.0/0 + + + Allow only IP addresses from other security groups + (source groups) to access the specified port: $ nova secgroup-add-group-rule --ip_proto udp --from_port 53 \ - --to_port 53 SEC_GROUP_NAME SOURCE_GROUP_NAME - - - - - To delete a security group rule, specify the - same arguments that you used to create the - rule. - To delete the security rule that you created in - : - $ nova secgroup-delete-rule SEC_GROUP_NAME tcp 22 22 0.0.0.0/0 - To delete the security rule that you created in - : - $ nova secgroup-delete-group-rule --ip_proto tcp --from_port 22 \ - --to_port 22 SEC_GROUP_NAME SOURCE_GROUP_NAME + --to_port 53 SECURITY_GROUP_NAME SOURCE_GROUP_NAME + + +
+ Delete a security group + To delete a security group rule, specify the + same arguments that you used to create the + rule. + For example, to delete the security group rule that permits SSH + access from all IP addresses, run the following command. + $ nova secgroup-delete-rule SECURITY_GROUP_NAME tcp 22 22 0.0.0.0/0 +
OpenStack services and clients
Networking neutron python-neutronclientConfigure networks for guest servers. This client was previously known as - quantum.Configure networks for guest servers. This client was + previously called quantum.
Object Storage