You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@cloudstack.apache.org by ke...@apache.org on 2014/01/28 03:23:24 UTC
[03/11] networking2.rst
http://git-wip-us.apache.org/repos/asf/cloudstack-docs-admin/blob/4bbce96f/source/service_offerings.rst
----------------------------------------------------------------------
diff --git a/source/service_offerings.rst b/source/service_offerings.rst
new file mode 100644
index 0000000..19b2296
--- /dev/null
+++ b/source/service_offerings.rst
@@ -0,0 +1,684 @@
+Service Offerings
+=================
+
+In this chapter we discuss compute, disk, and system service offerings.
+Network offerings are discussed in the section on setting up networking
+for users.
+
+Compute and Disk Service Offerings
+---------------------------------------
+
+A service offering is a set of virtual hardware features such as CPU
+core count and speed, memory, and disk size. The CloudStack
+administrator can set up various offerings, and then end users choose
+from the available offerings when they create a new VM. A service
+offering includes the following elements:
+
+-
+
+ CPU, memory, and network resource guarantees
+
+-
+
+ How resources are metered
+
+-
+
+ How the resource usage is charged
+
+-
+
+ How often the charges are generated
+
+For example, one service offering might allow users to create a virtual
+machine instance that is equivalent to a 1 GHz Intel® Core™ 2 CPU, with
+1 GB memory at $0.20/hour, with network traffic metered at $0.10/GB.
+Based on the user’s selected offering, CloudStack emits usage records
+that can be integrated with billing systems. CloudStack separates
+service offerings into compute offerings and disk offerings. The
+computing service offering specifies:
+
+-
+
+ Guest CPU
+
+-
+
+ Guest RAM
+
+-
+
+ Guest Networking type (virtual or direct)
+
+-
+
+ Tags on the root disk
+
+The disk offering specifies:
+
+-
+
+ Disk size (optional). An offering without a disk size will allow
+ users to pick their own
+
+-
+
+ Tags on the data disk
+
+Creating a New Compute Offering
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To create a new compute offering:
+
+#.
+
+ Log in with admin privileges to the CloudStack UI.
+
+#.
+
+ In the left navigation bar, click Service Offerings.
+
+#.
+
+ In Select Offering, choose Compute Offering.
+
+#.
+
+ Click Add Compute Offering.
+
+#.
+
+ In the dialog, make the following choices:
+
+ -
+
+ **Name**: Any desired name for the service offering.
+
+ -
+
+ **Description**: A short description of the offering that can be
+ displayed to users
+
+ -
+
+ **Storage type**: The type of disk that should be allocated. Local
+ allocates from storage attached directly to the host where the
+ system VM is running. Shared allocates from storage accessible via
+ NFS.
+
+ -
+
+ **Custom**: Custom compute offerings can be used in following
+ cases: deploying a VM, changing the compute offering of a stopped
+ VM and running VMs, which is nothing but scaling up.
+
+ If the Custom field is checked, the end-user must fill in the
+ desired values for number of CPU, CPU speed, and RAM Memory when
+ using a custom compute offering. When you check this box, those
+ three input fields are hidden in the dialog box.
+
+ -
+
+ **# of CPU cores**: The number of cores which should be allocated
+ to a system VM with this offering. If Custom is checked, this
+ field does not appear.
+
+ -
+
+ **CPU (in MHz)**: The CPU speed of the cores that the system VM is
+ allocated. For example, “2000” would provide for a 2 GHz clock. If
+ Custom is checked, this field does not appear.
+
+ -
+
+ **Memory (in MB)**: The amount of memory in megabytes that the
+ system VM should be allocated. For example, “2048” would provide
+ for a 2 GB RAM allocation. If Custom is checked, this field does
+ not appear.
+
+ -
+
+ **Network Rate**: Allowed data transfer rate in MB per second.
+
+ -
+
+ **Disk Read Rate**: Allowed disk read rate in bits per second.
+
+ -
+
+ **Disk Write Rate**: Allowed disk write rate in bits per second.
+
+ -
+
+ **Disk Read Rate**: Allowed disk read rate in IOPS (input/output
+ operations per second).
+
+ -
+
+ **Disk Write Rate**: Allowed disk write rate in IOPS (input/output
+ operations per second).
+
+ -
+
+ **Offer HA**: If yes, the administrator can choose to have the
+ system VM be monitored and as highly available as possible.
+
+ -
+
+ **Storage Tags**: The tags that should be associated with the
+ primary storage used by the system VM.
+
+ -
+
+ **Host Tags**: (Optional) Any tags that you use to organize your
+ hosts
+
+ -
+
+ **CPU cap**: Whether to limit the level of CPU usage even if spare
+ capacity is available.
+
+ -
+
+ **Public**: Indicate whether the service offering should be
+ available all domains or only some domains. Choose Yes to make it
+ available to all domains. Choose No to limit the scope to a
+ subdomain; CloudStack will then prompt for the subdomain's name.
+
+ -
+
+ **isVolatile**: If checked, VMs created from this service offering
+ will have their root disks reset upon reboot. This is useful for
+ secure environments that need a fresh start on every boot and for
+ desktops that should not retain state.
+
+ -
+
+ **Deployment Planner**: Choose the technique that you would like
+ CloudStack to use when deploying VMs based on this service
+ offering.
+
+ First Fit places new VMs on the first host that is found having
+ sufficient capacity to support the VM's requirements.
+
+ User Dispersing makes the best effort to evenly distribute VMs
+ belonging to the same account on different clusters or pods.
+
+ User Concentrated prefers to deploy VMs belonging to the same
+ account within a single pod.
+
+ Implicit Dedication will deploy VMs on private infrastructure that
+ is dedicated to a specific domain or account. If you choose this
+ planner, then you must also pick a value for Planner Mode. See
+ `Section 3.1.1, “Dedicating Resources to Accounts and
+ Domains” <#dedicated-host-cluster-pod>`__.
+
+ Bare Metal is used with bare metal hosts. See Bare Metal
+ Installation in the Installation Guide.
+
+ -
+
+ **Planner Mode**: Used when ImplicitDedicationPlanner is selected
+ in the previous field. The planner mode determines how VMs will be
+ deployed on private infrastructure that is dedicated to a single
+ domain or account.
+
+ Strict: A host will not be shared across multiple accounts. For
+ example, strict implicit dedication is useful for deployment of
+ certain types of applications, such as desktops, where no host can
+ be shared between different accounts without violating the desktop
+ software's terms of license.
+
+ Preferred: The VM will be deployed in dedicated infrastructure if
+ possible. Otherwise, the VM can be deployed in shared
+ infrastructure.
+
+#.
+
+ Click Add.
+
+Creating a New Disk Offering
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To create a new disk offering:
+
+#.
+
+ Log in with admin privileges to the CloudStack UI.
+
+#.
+
+ In the left navigation bar, click Service Offerings.
+
+#.
+
+ In Select Offering, choose Disk Offering.
+
+#.
+
+ Click Add Disk Offering.
+
+#.
+
+ In the dialog, make the following choices:
+
+ -
+
+ Name. Any desired name for the disk offering.
+
+ -
+
+ Description. A short description of the offering that can be
+ displayed to users
+
+ -
+
+ Custom Disk Size. If checked, the user can set their own disk
+ size. If not checked, the root administrator must define a value
+ in Disk Size.
+
+ -
+
+ Disk Size. Appears only if Custom Disk Size is not selected.
+ Define the volume size in GB.
+
+ -
+
+ QoS Type. Three options: Empty (no Quality of Service), hypervisor
+ (rate limiting enforced on the hypervisor side), and storage
+ (guaranteed minimum and maximum IOPS enforced on the storage
+ side). If leveraging QoS, make sure that the hypervisor or storage
+ system supports this feature.
+
+ -
+
+ Custom IOPS. If checked, the user can set their own IOPS. If not
+ checked, the root administrator can define values. If the root
+ admin does not set values when using storage QoS, default values
+ are used (the defauls can be overridden if the proper parameters
+ are passed into CloudStack when creating the primary storage in
+ question).
+
+ -
+
+ Min IOPS. Appears only if storage QoS is to be used. Set a
+ guaranteed minimum number of IOPS to be enforced on the storage
+ side.
+
+ -
+
+ Max IOPS. Appears only if storage QoS is to be used. Set a maximum
+ number of IOPS to be enforced on the storage side (the system may
+ go above this limit in certain circumstances for short intervals).
+
+ -
+
+ (Optional)Storage Tags. The tags that should be associated with
+ the primary storage for this disk. Tags are a comma separated list
+ of attributes of the storage. For example "ssd,blue". Tags are
+ also added on Primary Storage. CloudStack matches tags on a disk
+ offering to tags on the storage. If a tag is present on a disk
+ offering that tag (or tags) must also be present on Primary
+ Storage for the volume to be provisioned. If no such primary
+ storage exists, allocation from the disk offering will fail..
+
+ -
+
+ Public. Indicate whether the service offering should be available
+ all domains or only some domains. Choose Yes to make it available
+ to all domains. Choose No to limit the scope to a subdomain;
+ CloudStack will then prompt for the subdomain's name.
+
+#.
+
+ Click Add.
+
+Modifying or Deleting a Service Offering
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Service offerings cannot be changed once created. This applies to both
+compute offerings and disk offerings.
+
+A service offering can be deleted. If it is no longer in use, it is
+deleted immediately and permanently. If the service offering is still in
+use, it will remain in the database until all the virtual machines
+referencing it have been deleted. After deletion by the administrator, a
+service offering will not be available to end users that are creating
+new instances.
+
+System Service Offerings
+-----------------------------
+
+System service offerings provide a choice of CPU speed, number of CPUs,
+tags, and RAM size, just as other service offerings do. But rather than
+being used for virtual machine instances and exposed to users, system
+service offerings are used to change the default properties of virtual
+routers, console proxies, and other system VMs. System service offerings
+are visible only to the CloudStack root administrator. CloudStack
+provides default system service offerings. The CloudStack root
+administrator can create additional custom system service offerings.
+
+When CloudStack creates a virtual router for a guest network, it uses
+default settings which are defined in the system service offering
+associated with the network offering. You can upgrade the capabilities
+of the virtual router by applying a new network offering that contains a
+different system service offering. All virtual routers in that network
+will begin using the settings from the new service offering.
+
+Creating a New System Service Offering
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To create a system service offering:
+
+#.
+
+ Log in with admin privileges to the CloudStack UI.
+
+#.
+
+ In the left navigation bar, click Service Offerings.
+
+#.
+
+ In Select Offering, choose System Offering.
+
+#.
+
+ Click Add System Service Offering.
+
+#.
+
+ In the dialog, make the following choices:
+
+ -
+
+ Name. Any desired name for the system offering.
+
+ -
+
+ Description. A short description of the offering that can be
+ displayed to users
+
+ -
+
+ System VM Type. Select the type of system virtual machine that
+ this offering is intended to support.
+
+ -
+
+ Storage type. The type of disk that should be allocated. Local
+ allocates from storage attached directly to the host where the
+ system VM is running. Shared allocates from storage accessible via
+ NFS.
+
+ -
+
+ # of CPU cores. The number of cores which should be allocated to a
+ system VM with this offering
+
+ -
+
+ CPU (in MHz). The CPU speed of the cores that the system VM is
+ allocated. For example, "2000" would provide for a 2 GHz clock.
+
+ -
+
+ Memory (in MB). The amount of memory in megabytes that the system
+ VM should be allocated. For example, "2048" would provide for a 2
+ GB RAM allocation.
+
+ -
+
+ Network Rate. Allowed data transfer rate in MB per second.
+
+ -
+
+ Offer HA. If yes, the administrator can choose to have the system
+ VM be monitored and as highly available as possible.
+
+ -
+
+ Storage Tags. The tags that should be associated with the primary
+ storage used by the system VM.
+
+ -
+
+ Host Tags. (Optional) Any tags that you use to organize your hosts
+
+ -
+
+ CPU cap. Whether to limit the level of CPU usage even if spare
+ capacity is available.
+
+ -
+
+ Public. Indicate whether the service offering should be available
+ all domains or only some domains. Choose Yes to make it available
+ to all domains. Choose No to limit the scope to a subdomain;
+ CloudStack will then prompt for the subdomain's name.
+
+#.
+
+ Click Add.
+
+Network Throttling
+-----------------------
+
+Network throttling is the process of controlling the network access and
+bandwidth usage based on certain rules. CloudStack controls this
+behaviour of the guest networks in the cloud by using the network rate
+parameter. This parameter is defined as the default data transfer rate
+in Mbps (Megabits Per Second) allowed in a guest network. It defines the
+upper limits for network utilization. If the current utilization is
+below the allowed upper limits, access is granted, else revoked.
+
+You can throttle the network bandwidth either to control the usage above
+a certain limit for some accounts, or to control network congestion in a
+large cloud environment. The network rate for your cloud can be
+configured on the following:
+
+-
+
+ Network Offering
+
+-
+
+ Service Offering
+
+-
+
+ Global parameter
+
+If network rate is set to NULL in service offering, the value provided
+in the vm.network.throttling.rate global parameter is applied. If the
+value is set to NULL for network offering, the value provided in the
+network.throttling.rate global parameter is considered.
+
+For the default public, storage, and management networks, network rate
+is set to 0. This implies that the public, storage, and management
+networks will have unlimited bandwidth by default. For default guest
+networks, network rate is set to NULL. In this case, network rate is
+defaulted to the global parameter value.
+
+The following table gives you an overview of how network rate is applied
+on different types of networks in CloudStack.
+
+Networks
+
+Network Rate Is Taken from
+
+Guest network of Virtual Router
+
+Guest Network Offering
+
+Public network of Virtual Router
+
+Guest Network Offering
+
+Storage network of Secondary Storage VM
+
+System Network Offering
+
+Management network of Secondary Storage VM
+
+System Network Offering
+
+Storage network of Console Proxy VM
+
+System Network Offering
+
+Management network of Console Proxy VM
+
+System Network Offering
+
+Storage network of Virtual Router
+
+System Network Offering
+
+Management network of Virtual Router
+
+System Network Offering
+
+Public network of Secondary Storage VM
+
+System Network Offering
+
+Public network of Console Proxy VM
+
+System Network Offering
+
+Default network of a guest VM
+
+Compute Offering
+
+Additional networks of a guest VM
+
+Corresponding Network Offerings
+
+A guest VM must have a default network, and can also have many
+additional networks. Depending on various parameters, such as the host
+and virtual switch used, you can observe a difference in the network
+rate in your cloud. For example, on a VMware host the actual network
+rate varies based on where they are configured (compute offering,
+network offering, or both); the network type (shared or isolated); and
+traffic direction (ingress or egress).
+
+The network rate set for a network offering used by a particular network
+in CloudStack is used for the traffic shaping policy of a port group,
+for example: port group A, for that network: a particular subnet or VLAN
+on the actual network. The virtual routers for that network connects to
+the port group A, and by default instances in that network connects to
+this port group. However, if an instance is deployed with a compute
+offering with the network rate set, and if this rate is used for the
+traffic shaping policy of another port group for the network, for
+example port group B, then instances using this compute offering are
+connected to the port group B, instead of connecting to port group A.
+
+The traffic shaping policy on standard port groups in VMware only
+applies to the egress traffic, and the net effect depends on the type of
+network used in CloudStack. In shared networks, ingress traffic is
+unlimited for CloudStack, and egress traffic is limited to the rate that
+applies to the port group used by the instance if any. If the compute
+offering has a network rate configured, this rate applies to the egress
+traffic, otherwise the network rate set for the network offering
+applies. For isolated networks, the network rate set for the network
+offering, if any, effectively applies to the ingress traffic. This is
+mainly because the network rate set for the network offering applies to
+the egress traffic from the virtual router to the instance. The egress
+traffic is limited by the rate that applies to the port group used by
+the instance if any, similar to shared networks.
+
+For example:
+
+Network rate of network offering = 10 Mbps
+
+Network rate of compute offering = 200 Mbps
+
+In shared networks, ingress traffic will not be limited for CloudStack,
+while egress traffic will be limited to 200 Mbps. In an isolated
+network, ingress traffic will be limited to 10 Mbps and egress to 200
+Mbps.
+
+Changing the Default System Offering for System VMs
+--------------------------------------------------------
+
+You can manually change the system offering for a particular System VM.
+Additionally, as a CloudStack administrator, you can also change the
+default system offering used for System VMs.
+
+#.
+
+ Create a new system offering.
+
+ For more information, see Creating a New System Service Offering.
+
+#.
+
+ Back up the database:
+
+ .. code:: bash
+
+ mysqldump -u root -p cloud | bzip2 > cloud_backup.sql.bz2
+
+#.
+
+ Open an MySQL prompt:
+
+ .. code:: bash
+
+ mysql -u cloud -p cloud
+
+#.
+
+ Run the following queries on the cloud database.
+
+ #.
+
+ In the disk\_offering table, identify the original default
+ offering and the new offering you want to use by default.
+
+ Take a note of the ID of the new offering.
+
+ .. code:: bash
+
+ select id,name,unique_name,type from disk_offering;
+
+ #.
+
+ For the original default offering, set the value of unique\_name
+ to NULL.
+
+ .. code:: bash
+
+ # update disk_offering set unique_name = NULL where id = 10;
+
+ Ensure that you use the correct value for the ID.
+
+ #.
+
+ For the new offering that you want to use by default, set the
+ value of unique\_name as follows:
+
+ For the default Console Proxy VM (CPVM) offering,set unique\_name
+ to 'Cloud.com-ConsoleProxy'. For the default Secondary Storage VM
+ (SSVM) offering, set unique\_name to 'Cloud.com-SecondaryStorage'.
+ For example:
+
+ .. code:: bash
+
+ update disk_offering set unique_name = 'Cloud.com-ConsoleProxy' where id = 16;
+
+#.
+
+ Restart CloudStack Management Server. Restarting is required because
+ the default offerings are loaded into the memory at startup.
+
+ .. code:: bash
+
+ service cloudstack-management restart
+
+#.
+
+ Destroy the existing CPVM or SSVM offerings and wait for them to be
+ recreated. The new CPVM or SSVM are configured with the new offering.
+
http://git-wip-us.apache.org/repos/asf/cloudstack-docs-admin/blob/4bbce96f/source/storage.rst
----------------------------------------------------------------------
diff --git a/source/storage.rst b/source/storage.rst
new file mode 100644
index 0000000..9741998
--- /dev/null
+++ b/source/storage.rst
@@ -0,0 +1,955 @@
+Working with Storage
+====================
+
+13.1. Storage Overview
+----------------------
+
+CloudStack defines two types of storage: primary and secondary. Primary
+storage can be accessed by either iSCSI or NFS. Additionally, direct
+attached storage may be used for primary storage. Secondary storage is
+always accessed using NFS.
+
+There is no ephemeral storage in CloudStack. All volumes on all nodes
+are persistent.
+
+Primary Storage
+---------------------
+
+This section gives concepts and technical details about CloudStack
+primary storage. For information about how to install and configure
+primary storage through the CloudStack UI, see the Installation Guide.
+
+`Section 2.6, “About Primary Storage” <#about-primary-storage>`__
+
+Best Practices for Primary Storage
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+-
+
+ The speed of primary storage will impact guest performance. If
+ possible, choose smaller, higher RPM drives or SSDs for primary
+ storage.
+
+-
+
+ There are two ways CloudStack can leverage primary storage:
+
+ Static: This is CloudStack's traditional way of handling storage. In
+ this model, a preallocated amount of storage (ex. a volume from a
+ SAN) is given to CloudStack. CloudStack then permits many of its
+ volumes to be created on this storage (can be root and/or data
+ disks). If using this technique, ensure that nothing is stored on the
+ storage. Adding the storage to CloudStack will destroy any existing
+ data.
+
+ Dynamic: This is a newer way for CloudStack to manage storage. In
+ this model, a storage system (rather than a preallocated amount of
+ storage) is given to CloudStack. CloudStack, working in concert with
+ a storage plug-in, dynamically creates volumes on the storage system
+ and each volume on the storage system maps to a single CloudStack
+ volume. This is highly useful for features such as storage Quality of
+ Service. Currently this feature is supported for data disks (Disk
+ Offerings).
+
+Runtime Behavior of Primary Storage
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Root volumes are created automatically when a virtual machine is
+created. Root volumes are deleted when the VM is destroyed. Data volumes
+can be created and dynamically attached to VMs. Data volumes are not
+deleted when VMs are destroyed.
+
+Administrators should monitor the capacity of primary storage devices
+and add additional primary storage as needed. See the Advanced
+Installation Guide.
+
+Administrators add primary storage to the system by creating a
+CloudStack storage pool. Each storage pool is associated with a cluster
+or a zone.
+
+With regards to data disks, when a user executes a Disk Offering to
+create a data disk, the information is initially written to the
+CloudStack database only. Upon the first request that the data disk be
+attached to a VM, CloudStack determines what storage to place the volume
+on and space is taken from that storage (either from preallocated
+storage or from a storage system (ex. a SAN), depending on how the
+primary storage was added to CloudStack).
+
+Hypervisor Support for Primary Storage
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The following table shows storage options and parameters for different
+hypervisors.
+
+VMware vSphere
+
+Citrix XenServer
+
+KVM
+
+Hyper-V
+
+****Format for Disks, Templates, and Snapshots****
+
+VMDK
+
+VHD
+
+QCOW2
+
+VHD
+
+Snapshots are not supported.
+
+**iSCSI support**
+
+VMFS
+
+Clustered LVM
+
+Yes, via Shared Mountpoint
+
+No
+
+**Fiber Channel support**
+
+VMFS
+
+Yes, via Existing SR
+
+Yes, via Shared Mountpoint
+
+No
+
+**NFS support**
+
+Y
+
+Y
+
+Y
+
+No
+
+**Local storage support**
+
+Y
+
+Y
+
+Y
+
+Y
+
+**Storage over-provisioning**
+
+NFS and iSCSI
+
+NFS
+
+NFS
+
+No
+
+**SMB/CIFS**
+
+No
+
+No
+
+No
+
+Yes
+
+XenServer uses a clustered LVM system to store VM images on iSCSI and
+Fiber Channel volumes and does not support over-provisioning in the
+hypervisor. The storage server itself, however, can support
+thin-provisioning. As a result the CloudStack can still support storage
+over-provisioning by running on thin-provisioned storage volumes.
+
+KVM supports "Shared Mountpoint" storage. A shared mountpoint is a file
+system path local to each server in a given cluster. The path must be
+the same across all Hosts in the cluster, for example /mnt/primary1.
+This shared mountpoint is assumed to be a clustered filesystem such as
+OCFS2. In this case the CloudStack does not attempt to mount or unmount
+the storage as is done with NFS. The CloudStack requires that the
+administrator insure that the storage is available
+
+With NFS storage, CloudStack manages the overprovisioning. In this case
+the global configuration parameter storage.overprovisioning.factor
+controls the degree of overprovisioning. This is independent of
+hypervisor type.
+
+Local storage is an option for primary storage for vSphere, XenServer,
+and KVM. When the local disk option is enabled, a local disk storage
+pool is automatically created on each host. To use local storage for the
+System Virtual Machines (such as the Virtual Router), set
+system.vm.use.local.storage to true in global configuration.
+
+CloudStack supports multiple primary storage pools in a Cluster. For
+example, you could provision 2 NFS servers in primary storage. Or you
+could provision 1 iSCSI LUN initially and then add a second iSCSI LUN
+when the first approaches capacity.
+
+Storage Tags
+~~~~~~~~~~~~~~~~~~~~
+
+Storage may be "tagged". A tag is a text string attribute associated
+with primary storage, a Disk Offering, or a Service Offering. Tags allow
+administrators to provide additional information about the storage. For
+example, that is a "SSD" or it is "slow". Tags are not interpreted by
+CloudStack. They are matched against tags placed on service and disk
+offerings. CloudStack requires all tags on service and disk offerings to
+exist on the primary storage before it allocates root or data disks on
+the primary storage. Service and disk offering tags are used to identify
+the requirements of the storage that those offerings have. For example,
+the high end service offering may require "fast" for its root disk
+volume.
+
+The interaction between tags, allocation, and volume copying across
+clusters and pods can be complex. To simplify the situation, use the
+same set of tags on the primary storage for all clusters in a pod. Even
+if different devices are used to present those tags, the set of exposed
+tags can be the same.
+
+Maintenance Mode for Primary Storage
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Primary storage may be placed into maintenance mode. This is useful, for
+example, to replace faulty RAM in a storage device. Maintenance mode for
+a storage device will first stop any new guests from being provisioned
+on the storage device. Then it will stop all guests that have any volume
+on that storage device. When all such guests are stopped the storage
+device is in maintenance mode and may be shut down. When the storage
+device is online again you may cancel maintenance mode for the device.
+The CloudStack will bring the device back online and attempt to start
+all guests that were running at the time of the entry into maintenance
+mode.
+
+Secondary Storage
+-----------------------
+
+This section gives concepts and technical details about CloudStack
+secondary storage. For information about how to install and configure
+secondary storage through the CloudStack UI, see the Advanced
+Installation Guide.
+
+`Section 2.7, “About Secondary Storage” <#about-secondary-storage>`__
+
+Working With Volumes
+--------------------------
+
+A volume provides storage to a guest VM. The volume can provide for a
+root disk or an additional data disk. CloudStack supports additional
+volumes for guest VMs.
+
+Volumes are created for a specific hypervisor type. A volume that has
+been attached to guest using one hypervisor type (e.g, XenServer) may
+not be attached to a guest that is using another hypervisor type, for
+example:vSphere, KVM. This is because the different hypervisors use
+different disk image formats.
+
+CloudStack defines a volume as a unit of storage available to a guest
+VM. Volumes are either root disks or data disks. The root disk has "/"
+in the file system and is usually the boot device. Data disks provide
+for additional storage, for example: "/opt" or "D:". Every guest VM has
+a root disk, and VMs can also optionally have a data disk. End users can
+mount multiple data disks to guest VMs. Users choose data disks from the
+disk offerings created by administrators. The user can create a template
+from a volume as well; this is the standard procedure for private
+template creation. Volumes are hypervisor-specific: a volume from one
+hypervisor type may not be used on a guest of another hypervisor type.
+
+.. note:: CloudStack supports attaching up to 13 data disks to a VM on XenServer
+hypervisor versions 6.0 and above. For the VMs on other hypervisor
+types, the data disk limit is 6.
+
+Creating a New Volume
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You can add more data disk volumes to a guest VM at any time, up to the
+limits of your storage capacity. Both CloudStack administrators and
+users can add volumes to VM instances. When you create a new volume, it
+is stored as an entity in CloudStack, but the actual storage resources
+are not allocated on the physical storage device until you attach the
+volume. This optimization allows the CloudStack to provision the volume
+nearest to the guest that will use it when the first attachment is made.
+
+Using Local Storage for Data Volumes
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+You can create data volumes on local storage (supported with XenServer,
+KVM, and VMware). The data volume is placed on the same host as the VM
+instance that is attached to the data volume. These local data volumes
+can be attached to virtual machines, detached, re-attached, and deleted
+just as with the other types of data volume.
+
+Local storage is ideal for scenarios where persistence of data volumes
+and HA is not required. Some of the benefits include reduced disk I/O
+latency and cost reduction from using inexpensive local disks.
+
+In order for local volumes to be used, the feature must be enabled for
+the zone.
+
+You can create a data disk offering for local storage. When a user
+creates a new VM, they can select this disk offering in order to cause
+the data disk volume to be placed in local storage.
+
+You can not migrate a VM that has a volume in local storage to a
+different host, nor migrate the volume itself away to a different host.
+If you want to put a host into maintenance mode, you must first stop any
+VMs with local data volumes on that host.
+
+To Create a New Volume
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+#.
+
+ Log in to the CloudStack UI as a user or admin.
+
+#.
+
+ In the left navigation bar, click Storage.
+
+#.
+
+ In Select View, choose Volumes.
+
+#.
+
+ To create a new volume, click Add Volume, provide the following
+ details, and click OK.
+
+ -
+
+ Name. Give the volume a unique name so you can find it later.
+
+ -
+
+ Availability Zone. Where do you want the storage to reside? This
+ should be close to the VM that will use the volume.
+
+ -
+
+ Disk Offering. Choose the characteristics of the storage.
+
+ The new volume appears in the list of volumes with the state
+ “Allocated.” The volume data is stored in CloudStack, but the volume
+ is not yet ready for use
+
+#.
+
+ To start using the volume, continue to Attaching a Volume
+
+Uploading an Existing Volume to a Virtual Machine
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Existing data can be made accessible to a virtual machine. This is
+called uploading a volume to the VM. For example, this is useful to
+upload data from a local file system and attach it to a VM. Root
+administrators, domain administrators, and end users can all upload
+existing volumes to VMs.
+
+The upload is performed using HTTP. The uploaded volume is placed in the
+zone's secondary storage
+
+You cannot upload a volume if the preconfigured volume limit has already
+been reached. The default limit for the cloud is set in the global
+configuration parameter max.account.volumes, but administrators can also
+set per-domain limits that are different from the global default. See
+Setting Usage Limits
+
+To upload a volume:
+
+#.
+
+ (Optional) Create an MD5 hash (checksum) of the disk image file that
+ you are going to upload. After uploading the data disk, CloudStack
+ will use this value to verify that no data corruption has occurred.
+
+#.
+
+ Log in to the CloudStack UI as an administrator or user
+
+#.
+
+ In the left navigation bar, click Storage.
+
+#.
+
+ Click Upload Volume.
+
+#.
+
+ Provide the following:
+
+ -
+
+ Name and Description. Any desired name and a brief description
+ that can be shown in the UI.
+
+ -
+
+ Availability Zone. Choose the zone where you want to store the
+ volume. VMs running on hosts in this zone can attach the volume.
+
+ -
+
+ Format. Choose one of the following to indicate the disk image
+ format of the volume.
+
+ Hypervisor
+
+ Disk Image Format
+
+ XenServer
+
+ VHD
+
+ VMware
+
+ OVA
+
+ KVM
+
+ QCOW2
+
+ -
+
+ URL. The secure HTTP or HTTPS URL that CloudStack can use to
+ access your disk. The type of file at the URL must match the value
+ chosen in Format. For example, if Format is VHD, the URL might
+ look like the following:
+
+ http://yourFileServerIP/userdata/myDataDisk.vhd
+
+ -
+
+ MD5 checksum. (Optional) Use the hash that you created in step 1.
+
+#.
+
+ Wait until the status of the volume shows that the upload is
+ complete. Click Instances - Volumes, find the name you specified in
+ step 5, and make sure the status is Uploaded.
+
+Attaching a Volume
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You can attach a volume to a guest VM to provide extra disk storage.
+Attach a volume when you first create a new volume, when you are moving
+an existing volume from one VM to another, or after you have migrated a
+volume from one storage pool to another.
+
+#.
+
+ Log in to the CloudStack UI as a user or admin.
+
+#.
+
+ In the left navigation, click Storage.
+
+#.
+
+ In Select View, choose Volumes.
+
+#.
+
+ Click the volume name in the Volumes list, then click the Attach Disk
+ button |AttachDiskButton.png: button to attach a volume|
+
+#.
+
+ In the Instance popup, choose the VM to which you want to attach the
+ volume. You will only see instances to which you are allowed to
+ attach volumes; for example, a user will see only instances created
+ by that user, but the administrator will have more choices.
+
+#.
+
+ When the volume has been attached, you should be able to see it by
+ clicking Instances, the instance name, and View Volumes.
+
+Detaching and Moving Volumes
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. note:: This procedure is different from moving volumes from one storage pool to
+another as described in `Section 13.4.5, “VM Storage
+Migration” <#vm-storage-migration>`__.
+
+A volume can be detached from a guest VM and attached to another guest.
+Both CloudStack administrators and users can detach volumes from VMs and
+move them to other VMs.
+
+If the two VMs are in different clusters, and the volume is large, it
+may take several minutes for the volume to be moved to the new VM.
+
+#.
+
+ Log in to the CloudStack UI as a user or admin.
+
+#.
+
+ In the left navigation bar, click Storage, and choose Volumes in
+ Select View. Alternatively, if you know which VM the volume is
+ attached to, you can click Instances, click the VM name, and click
+ View Volumes.
+
+#.
+
+ Click the name of the volume you want to detach, then click the
+ Detach Disk button. |DetachDiskButton.png: button to detach a volume|
+
+#.
+
+ To move the volume to another VM, follow the steps in
+ `Section 13.4.3, “Attaching a Volume” <#attaching-volume>`__.
+
+VM Storage Migration
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Supported in XenServer, KVM, and VMware.
+
+.. note:: This procedure is different from moving disk volumes from one VM to
+another as described in `Section 13.4.4, “Detaching and Moving
+Volumes” <#detach-move-volumes>`__.
+
+You can migrate a virtual machine’s root disk volume or any additional
+data disk volume from one storage pool to another in the same zone.
+
+You can use the storage migration feature to achieve some commonly
+desired administration goals, such as balancing the load on storage
+pools and increasing the reliability of virtual machines by moving them
+away from any storage pool that is experiencing issues.
+
+On XenServer and VMware, live migration of VM storage is enabled through
+CloudStack support for XenMotion and vMotion. Live storage migration
+allows VMs to be moved from one host to another, where the VMs are not
+located on storage shared between the two hosts. It provides the option
+to live migrate a VM’s disks along with the VM itself. It is possible to
+migrate a VM from one XenServer resource pool / VMware cluster to
+another, or to migrate a VM whose disks are on local storage, or even to
+migrate a VM’s disks from one storage repository to another, all while
+the VM is running.
+
+.. note:: Because of a limitation in VMware, live migration of storage for a VM is
+allowed only if the source and target storage pool are accessible to the
+source host; that is, the host where the VM is running when the live
+migration operation is requested.
+
+Migrating a Data Volume to a New Storage Pool
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+There are two situations when you might want to migrate a disk:
+
+-
+
+ Move the disk to new storage, but leave it attached to the same
+ running VM.
+
+-
+
+ Detach the disk from its current VM, move it to new storage, and
+ attach it to a new VM.
+
+Migrating Storage For a Running VM
+''''''''''''''''''''''''''''''''''''''''''''''
+
+(Supported on XenServer and VMware)
+
+#.
+
+ Log in to the CloudStack UI as a user or admin.
+
+#.
+
+ In the left navigation bar, click Instances, click the VM name, and
+ click View Volumes.
+
+#.
+
+ Click the volume you want to migrate.
+
+#.
+
+ Detach the disk from the VM. See `Section 13.4.4, “Detaching and
+ Moving Volumes” <#detach-move-volumes>`__ but skip the “reattach”
+ step at the end. You will do that after migrating to new storage.
+
+#.
+
+ Click the Migrate Volume button |Migrateinstance.png: button to
+ migrate a volume| and choose the destination from the dropdown list.
+
+#.
+
+ Watch for the volume status to change to Migrating, then back to
+ Ready.
+
+Migrating Storage and Attaching to a Different VM
+'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
+
+#.
+
+ Log in to the CloudStack UI as a user or admin.
+
+#.
+
+ Detach the disk from the VM. See `Section 13.4.4, “Detaching and
+ Moving Volumes” <#detach-move-volumes>`__ but skip the “reattach”
+ step at the end. You will do that after migrating to new storage.
+
+#.
+
+ Click the Migrate Volume button |Migrateinstance.png: button to
+ migrate a volume| and choose the destination from the dropdown list.
+
+#.
+
+ Watch for the volume status to change to Migrating, then back to
+ Ready. You can find the volume by clicking Storage in the left
+ navigation bar. Make sure that Volumes is displayed at the top of the
+ window, in the Select View dropdown.
+
+#.
+
+ Attach the volume to any desired VM running in the same cluster as
+ the new storage server. See `Section 13.4.3, “Attaching a
+ Volume” <#attaching-volume>`__
+
+Migrating a VM Root Volume to a New Storage Pool
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+(XenServer, VMware) You can live migrate a VM's root disk from one
+storage pool to another, without stopping the VM first.
+
+(KVM) When migrating the root disk volume, the VM must first be stopped,
+and users can not access the VM. After migration is complete, the VM can
+be restarted.
+
+#.
+
+ Log in to the CloudStack UI as a user or admin.
+
+#.
+
+ In the left navigation bar, click Instances, and click the VM name.
+
+#.
+
+ (KVM only) Stop the VM.
+
+#.
+
+ Click the Migrate button |Migrateinstance.png: button to migrate a VM
+ or volume| and choose the destination from the dropdown list.
+
+ .. note:: If the VM's storage has to be migrated along with the VM, this will
+ be noted in the host list. CloudStack will take care of the storage
+ migration for you.
+
+#.
+
+ Watch for the volume status to change to Migrating, then back to
+ Running (or Stopped, in the case of KVM). This can take some time.
+
+#.
+
+ (KVM only) Restart the VM.
+
+Resizing Volumes
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+CloudStack provides the ability to resize data disks; CloudStack
+controls volume size by using disk offerings. This provides CloudStack
+administrators with the flexibility to choose how much space they want
+to make available to the end users. Volumes within the disk offerings
+with the same storage tag can be resized. For example, if you only want
+to offer 10, 50, and 100 GB offerings, the allowed resize should stay
+within those limits. That implies if you define a 10 GB, a 50 GB and a
+100 GB disk offerings, a user can upgrade from 10 GB to 50 GB, or 50 GB
+to 100 GB. If you create a custom-sized disk offering, then you have the
+option to resize the volume by specifying a new, larger size.
+
+Additionally, using the resizeVolume API, a data volume can be moved
+from a static disk offering to a custom disk offering with the size
+specified. This functionality allows those who might be billing by
+certain volume sizes or disk offerings to stick to that model, while
+providing the flexibility to migrate to whatever custom size necessary.
+
+This feature is supported on KVM, XenServer, and VMware hosts. However,
+shrinking volumes is not supported on VMware hosts.
+
+Before you try to resize a volume, consider the following:
+
+-
+
+ The VMs associated with the volume are stopped.
+
+-
+
+ The data disks associated with the volume are removed.
+
+-
+
+ When a volume is shrunk, the disk associated with it is simply
+ truncated, and doing so would put its content at risk of data loss.
+ Therefore, resize any partitions or file systems before you shrink a
+ data disk so that all the data is moved off from that disk.
+
+To resize a volume:
+
+#.
+
+ Log in to the CloudStack UI as a user or admin.
+
+#.
+
+ In the left navigation bar, click Storage.
+
+#.
+
+ In Select View, choose Volumes.
+
+#.
+
+ Select the volume name in the Volumes list, then click the Resize
+ Volume button |resize-volume-icon.png: button to display the resize
+ volume option.|
+
+#.
+
+ In the Resize Volume pop-up, choose desired characteristics for the
+ storage.
+
+ |resize-volume.png: option to resize a volume.|
+
+ #.
+
+ If you select Custom Disk, specify a custom size.
+
+ #.
+
+ Click Shrink OK to confirm that you are reducing the size of a
+ volume.
+
+ This parameter protects against inadvertent shrinking of a disk,
+ which might lead to the risk of data loss. You must sign off that
+ you know what you are doing.
+
+#.
+
+ Click OK.
+
+Reset VM to New Root Disk on Reboot
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You can specify that you want to discard the root disk and create a new
+one whenever a given VM is rebooted. This is useful for secure
+environments that need a fresh start on every boot and for desktops that
+should not retain state. The IP address of the VM will not change due to
+this operation.
+
+**To enable root disk reset on VM reboot:**
+
+When creating a new service offering, set the parameter isVolatile to
+True. VMs created from this service offering will have their disks reset
+upon reboot. See `Section 8.1.1, “Creating a New Compute
+Offering” <#creating-compute-offerings>`__.
+
+Volume Deletion and Garbage Collection
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The deletion of a volume does not delete the snapshots that have been
+created from the volume
+
+When a VM is destroyed, data disk volumes that are attached to the VM
+are not deleted.
+
+Volumes are permanently destroyed using a garbage collection process.
+The global configuration variables expunge.delay and expunge.interval
+determine when the physical deletion of volumes will occur.
+
+-
+
+ expunge.delay: determines how old the volume must be before it is
+ destroyed, in seconds
+
+-
+
+ expunge.interval: determines how often to run the garbage collection
+ check
+
+Administrators should adjust these values depending on site policies
+around data retention.
+
+Working with Volume Snapshots
+-----------------------------------
+
+(Supported for the following hypervisors: **XenServer**, **VMware
+vSphere**, and **KVM**)
+
+CloudStack supports snapshots of disk volumes. Snapshots are a
+point-in-time capture of virtual machine disks. Memory and CPU states
+are not captured. If you are using the Oracle VM hypervisor, you can not
+take snapshots, since OVM does not support them.
+
+Snapshots may be taken for volumes, including both root and data disks
+(except when the Oracle VM hypervisor is used, which does not support
+snapshots). The administrator places a limit on the number of stored
+snapshots per user. Users can create new volumes from the snapshot for
+recovery of particular files and they can create templates from
+snapshots to boot from a restored disk.
+
+Users can create snapshots manually or by setting up automatic recurring
+snapshot policies. Users can also create disk volumes from snapshots,
+which may be attached to a VM like any other disk volume. Snapshots of
+both root disks and data disks are supported. However, CloudStack does
+not currently support booting a VM from a recovered root disk. A disk
+recovered from snapshot of a root disk is treated as a regular data
+disk; the data on recovered disk can be accessed by attaching the disk
+to a VM.
+
+A completed snapshot is copied from primary storage to secondary
+storage, where it is stored until deleted or purged by newer snapshot.
+
+How to Snapshot a Volume
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+#.
+
+ Log in to the CloudStack UI as a user or administrator.
+
+#.
+
+ In the left navigation bar, click Storage.
+
+#.
+
+ In Select View, be sure Volumes is selected.
+
+#.
+
+ Click the name of the volume you want to snapshot.
+
+#.
+
+ Click the Snapshot button. |image43|
+
+Automatic Snapshot Creation and Retention
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+(Supported for the following hypervisors: **XenServer**, **VMware
+vSphere**, and **KVM**)
+
+Users can set up a recurring snapshot policy to automatically create
+multiple snapshots of a disk at regular intervals. Snapshots can be
+created on an hourly, daily, weekly, or monthly interval. One snapshot
+policy can be set up per disk volume. For example, a user can set up a
+daily snapshot at 02:30.
+
+With each snapshot schedule, users can also specify the number of
+scheduled snapshots to be retained. Older snapshots that exceed the
+retention limit are automatically deleted. This user-defined limit must
+be equal to or lower than the global limit set by the CloudStack
+administrator. See `Section 14.3, “Globally Configured
+Limits” <#globally-configured-limits>`__. The limit applies only to
+those snapshots that are taken as part of an automatic recurring
+snapshot policy. Additional manual snapshots can be created and
+retained.
+
+Incremental Snapshots and Backup
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Snapshots are created on primary storage where a disk resides. After a
+snapshot is created, it is immediately backed up to secondary storage
+and removed from primary storage for optimal utilization of space on
+primary storage.
+
+CloudStack does incremental backups for some hypervisors. When
+incremental backups are supported, every N backup is a full backup.
+
+VMware vSphere
+
+Citrix XenServer
+
+KVM
+
+Support incremental backup
+
+N
+
+Y
+
+N
+
+Volume Status
+~~~~~~~~~~~~~~~~~~~~~
+
+When a snapshot operation is triggered by means of a recurring snapshot
+policy, a snapshot is skipped if a volume has remained inactive since
+its last snapshot was taken. A volume is considered to be inactive if it
+is either detached or attached to a VM that is not running. CloudStack
+ensures that at least one snapshot is taken since the volume last became
+inactive.
+
+When a snapshot is taken manually, a snapshot is always created
+regardless of whether a volume has been active or not.
+
+Snapshot Restore
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+There are two paths to restoring snapshots. Users can create a volume
+from the snapshot. The volume can then be mounted to a VM and files
+recovered as needed. Alternatively, a template may be created from the
+snapshot of a root disk. The user can then boot a VM from this template
+to effect recovery of the root disk.
+
+Snapshot Job Throttling
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+When a snapshot of a virtual machine is requested, the snapshot job runs
+on the same host where the VM is running or, in the case of a stopped
+VM, the host where it ran last. If many snapshots are requested for VMs
+on a single host, this can lead to problems with too many snapshot jobs
+overwhelming the resources of the host.
+
+To address this situation, the cloud's root administrator can throttle
+how many snapshot jobs are executed simultaneously on the hosts in the
+cloud by using the global configuration setting
+concurrent.snapshots.threshold.perhost. By using this setting, the
+administrator can better ensure that snapshot jobs do not time out and
+hypervisor hosts do not experience performance issues due to hosts being
+overloaded with too many snapshot requests.
+
+Set concurrent.snapshots.threshold.perhost to a value that represents a
+best guess about how many snapshot jobs the hypervisor hosts can execute
+at one time, given the current resources of the hosts and the number of
+VMs running on the hosts. If a given host has more snapshot requests,
+the additional requests are placed in a waiting queue. No new snapshot
+jobs will start until the number of currently executing snapshot jobs
+falls below the configured limit.
+
+The admin can also set job.expire.minutes to place a maximum on how long
+a snapshot request will wait in the queue. If this limit is reached, the
+snapshot request fails and returns an error message.
+
+VMware Volume Snapshot Performance
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+When you take a snapshot of a data or root volume on VMware, CloudStack
+uses an efficient storage technique to improve performance.
+
+A snapshot is not immediately exported from vCenter to a mounted NFS
+share and packaged into an OVA file format. This operation would consume
+time and resources. Instead, the original file formats (e.g., VMDK)
+provided by vCenter are retained. An OVA file will only be created as
+needed, on demand. To generate the OVA, CloudStack uses information in a
+properties file (\*.ova.meta) which it stored along with the original
+snapshot data.
+
+.. note:: For upgrading customers: This process applies only to newly created
+snapshots after upgrade to CloudStack 4.2. Snapshots that have already
+been taken and stored in OVA format will continue to exist in that
+format, and will continue to work as expected.
+
http://git-wip-us.apache.org/repos/asf/cloudstack-docs-admin/blob/4bbce96f/source/systemvm.rst
----------------------------------------------------------------------
diff --git a/source/systemvm.rst b/source/systemvm.rst
new file mode 100644
index 0000000..2566b0d
--- /dev/null
+++ b/source/systemvm.rst
@@ -0,0 +1,620 @@
+Working with System Virtual Machines
+====================================
+
+CloudStack uses several types of system virtual machines to perform
+tasks in the cloud. In general CloudStack manages these system VMs and
+creates, starts, and stops them as needed based on scale and immediate
+needs. However, the administrator should be aware of them and their
+roles to assist in debugging issues.
+
+The System VM Template
+----------------------------
+
+The System VMs come from a single template. The System VM has the
+following characteristics:
+
+-
+
+ Debian 6.0 ("Squeeze"), 2.6.32 kernel with the latest security
+ patches from the Debian security APT repository
+
+-
+
+ Has a minimal set of packages installed thereby reducing the attack
+ surface
+
+-
+
+ 32-bit for enhanced performance on Xen/VMWare
+
+-
+
+ pvops kernel with Xen PV drivers, KVM virtio drivers, and VMware
+ tools for optimum performance on all hypervisors
+
+-
+
+ Xen tools inclusion allows performance monitoring
+
+-
+
+ Latest versions of HAProxy, iptables, IPsec, and Apache from debian
+ repository ensures improved security and speed
+
+-
+
+ Latest version of JRE from Sun/Oracle ensures improved security and
+ speed
+
+Changing the Default System VM Template
+---------------------------------------------
+
+CloudStack allows you to change the default 32-bit System VM template to
+64-bit one. Using the 64-bit template, upgrade the virtual router to
+manage larger number of connection in your network.
+
+#.
+
+ Based on the hypervisor you use, download the 64-bit template from
+ the following location:
+
+ Hypervisor
+
+ Download Location
+
+ XenServer
+
+ http://download.cloud.com/templates/4.2/64bit/systemvmtemplate64-2013-07-15-master-xen.vhd.bz2
+
+ KVM
+
+ http://download.cloud.com/templates/4.2/64bit/systemvmtemplate64-2013-07-15-master-kvm.qcow2.bz2
+
+#.
+
+ As an administrator, log in to the CloudStack UI
+
+#.
+
+ Register the 64 bit template.
+
+ For example: KVM64bitTemplate
+
+#.
+
+ While registering the template, select Routing.
+
+#.
+
+ Navigate to Infrastructure > Zone > Settings.
+
+#.
+
+ Set the name of the 64-bit template, KVM64bitTemplate, in the
+ *``router.template.kvm``* global parameter.
+
+ If you are using a XenServer 64-bit template, set the name in the
+ *``router.template.xen``* global parameter.
+
+ Any new virtual router created in this Zone automatically picks up
+ this template.
+
+#.
+
+ Restart the Management Server.
+
+16.3. Multiple System VM Support for VMware
+-------------------------------------------
+
+Every CloudStack zone has single System VM for template processing tasks
+such as downloading templates, uploading templates, and uploading ISOs.
+In a zone where VMware is being used, additional System VMs can be
+launched to process VMware-specific tasks such as taking snapshots and
+creating private templates. The CloudStack management server launches
+additional System VMs for VMware-specific tasks as the load increases.
+The management server monitors and weights all commands sent to these
+System VMs and performs dynamic load balancing and scaling-up of more
+System VMs.
+
+Console Proxy
+-------------------
+
+The Console Proxy is a type of System Virtual Machine that has a role in
+presenting a console view via the web UI. It connects the user’s browser
+to the VNC port made available via the hypervisor for the console of the
+guest. Both the administrator and end user web UIs offer a console
+connection.
+
+Clicking a console icon brings up a new window. The AJAX code downloaded
+into that window refers to the public IP address of a console proxy VM.
+There is exactly one public IP address allocated per console proxy VM.
+The AJAX application connects to this IP. The console proxy then proxies
+the connection to the VNC port for the requested VM on the Host hosting
+the guest.
+
+.. note:: The hypervisors will have many ports assigned to VNC usage so that
+multiple VNC sessions can occur simultaneously.
+
+There is never any traffic to the guest virtual IP, and there is no need
+to enable VNC within the guest.
+
+The console proxy VM will periodically report its active session count
+to the Management Server. The default reporting interval is five
+seconds. This can be changed through standard Management Server
+configuration with the parameter consoleproxy.loadscan.interval.
+
+Assignment of guest VM to console proxy is determined by first
+determining if the guest VM has a previous session associated with a
+console proxy. If it does, the Management Server will assign the guest
+VM to the target Console Proxy VM regardless of the load on the proxy
+VM. Failing that, the first available running Console Proxy VM that has
+the capacity to handle new sessions is used.
+
+Console proxies can be restarted by administrators but this will
+interrupt existing console sessions for users.
+
+Using a SSL Certificate for the Console Proxy
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The console viewing functionality uses a dynamic DNS service under the
+domain name realhostip.com to assist in providing SSL security to
+console sessions. The console proxy is assigned a public IP address. In
+order to avoid browser warnings for mismatched SSL certificates, the URL
+for the new console window is set to the form of
+https://aaa-bbb-ccc-ddd.realhostip.com. You will see this URL during
+console session creation. CloudStack includes the realhostip.com SSL
+certificate in the console proxy VM. Of course, CloudStack cannot know
+about the DNS A records for our customers' public IPs prior to shipping
+the software. CloudStack therefore runs a dynamic DNS server that is
+authoritative for the realhostip.com domain. It maps the aaa-bbb-ccc-ddd
+part of the DNS name to the IP address aaa.bbb.ccc.ddd on lookups. This
+allows the browser to correctly connect to the console proxy's public
+IP, where it then expects and receives a SSL certificate for
+realhostip.com, and SSL is set up without browser warnings.
+
+Changing the Console Proxy SSL Certificate and Domain
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If the administrator prefers, it is possible for the URL of the
+customer's console session to show a domain other than realhostip.com.
+The administrator can customize the displayed domain by selecting a
+different domain and uploading a new SSL certificate and private key.
+The domain must run a DNS service that is capable of resolving queries
+for addresses of the form aaa-bbb-ccc-ddd.your.domain to an IPv4 IP
+address in the form aaa.bbb.ccc.ddd, for example, 202.8.44.1. To change
+the console proxy domain, SSL certificate, and private key:
+
+#.
+
+ Set up dynamic name resolution or populate all possible DNS names in
+ your public IP range into your existing DNS server with the format
+ aaa-bbb-ccc-ddd.company.com -> aaa.bbb.ccc.ddd.
+
+#.
+
+ Generate the private key and certificate signing request (CSR). When
+ you are using openssl to generate private/public key pairs and CSRs,
+ for the private key that you are going to paste into the CloudStack
+ UI, be sure to convert it into PKCS#8 format.
+
+ #.
+
+ Generate a new 2048-bit private key
+
+ .. code:: bash
+
+ openssl genrsa -des3 -out yourprivate.key 2048
+
+ #.
+
+ Generate a new certificate CSR
+
+ .. code:: bash
+
+ openssl req -new -key yourprivate.key -out yourcertificate.csr
+
+ #.
+
+ Head to the website of your favorite trusted Certificate
+ Authority, purchase an SSL certificate, and submit the CSR. You
+ should receive a valid certificate in return
+
+ #.
+
+ Convert your private key format into PKCS#8 encrypted format.
+
+ .. code:: bash
+
+ openssl pkcs8 -topk8 -in yourprivate.key -out yourprivate.pkcs8.encrypted.key
+
+ #.
+
+ Convert your PKCS#8 encrypted private key into the PKCS#8 format
+ that is compliant with CloudStack
+
+ .. code:: bash
+
+ openssl pkcs8 -in yourprivate.pkcs8.encrypted.key -out yourprivate.pkcs8.key
+
+#.
+
+ In the Update SSL Certificate screen of the CloudStack UI, paste the
+ following:
+
+ -
+
+ The certificate you've just generated.
+
+ -
+
+ The private key you've just generated.
+
+ -
+
+ The desired new domain name; for example, company.com
+
+.. |updatessl.png: Updating Console Proxy SSL Certificate|
+
+#.
+
+ The desired new domain name; for example, company.com
+
+ This stops all currently running console proxy VMs, then restarts
+ them with the new certificate and key. Users might notice a brief
+ interruption in console availability.
+
+The Management Server generates URLs of the form
+"aaa-bbb-ccc-ddd.company.com" after this change is made. The new console
+requests will be served with the new DNS domain name, certificate, and
+key.
+
+Virtual Router
+--------------------
+
+The virtual router is a type of System Virtual Machine. The virtual
+router is one of the most frequently used service providers in
+CloudStack. The end user has no direct access to the virtual router.
+Users can ping the virtual router and take actions that affect it (such
+as setting up port forwarding), but users do not have SSH access into
+the virtual router.
+
+There is no mechanism for the administrator to log in to the virtual
+router. Virtual routers can be restarted by administrators, but this
+will interrupt public network access and other services for end users. A
+basic test in debugging networking issues is to attempt to ping the
+virtual router from a guest VM. Some of the characteristics of the
+virtual router are determined by its associated system service offering.
+
+Configuring the Virtual Router
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You can set the following:
+
+-
+
+ IP range
+
+-
+
+ Supported network services
+
+-
+
+ Default domain name for the network serviced by the virtual router
+
+-
+
+ Gateway IP address
+
+-
+
+ How often CloudStack fetches network usage statistics from CloudStack
+ virtual routers. If you want to collect traffic metering data from
+ the virtual router, set the global configuration parameter
+ router.stats.interval. If you are not using the virtual router to
+ gather network usage statistics, set it to 0.
+
+Upgrading a Virtual Router with System Service Offerings
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+When CloudStack creates a virtual router, it uses default settings which
+are defined in a default system service offering. See `Section 8.2,
+“System Service Offerings” <#system-service-offerings>`__. All the
+virtual routers in a single guest network use the same system service
+offering. You can upgrade the capabilities of the virtual router by
+creating and applying a custom system service offering.
+
+#.
+
+ Define your custom system service offering. See `Section 8.2.1,
+ “Creating a New System Service
+ Offering” <#creating-system-service-offerings>`__. In System VM Type,
+ choose Domain Router.
+
+#.
+
+ Associate the system service offering with a network offering. See
+ `Section 9.4.1, “Creating a New Network
+ Offering” <#creating-network-offerings>`__.
+
+#.
+
+ Apply the network offering to the network where you want the virtual
+ routers to use the new system service offering. If this is a new
+ network, follow the steps in Adding an Additional Guest Network on
+ page 66. To change the service offering for existing virtual routers,
+ follow the steps in `Section 15.6.3, “Changing the Network Offering
+ on a Guest Network” <#change-network-offering-on-guest-network>`__.
+
+Best Practices for Virtual Routers
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+-
+
+ WARNING: Restarting a virtual router from a hypervisor console
+ deletes all the iptables rules. To work around this issue, stop the
+ virtual router and start it from the CloudStack UI.
+
+-
+
+ WARNING: Do not use the destroyRouter API when only one router is
+ available in the network, because restartNetwork API with the
+ cleanup=false parameter can't recreate it later. If you want to
+ destroy and recreate the single router available in the network, use
+ the restartNetwork API with the cleanup=true parameter.
+
+16.5.4. Service Monitoring Tool for Virtual Router
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Various services running on the CloudStack virtual routers can be
+monitored by using a Service Monitoring tool. The tool ensures that
+services are successfully running until CloudStack deliberately disables
+them. If a service goes down, the tool automatically restarts the VR,
+and if that does not bring up the VR, an alert as well as an event is
+generated indicating the failure.
+
+Monitoring tool can help to start a VR service, which is crashed due to
+an unexpected reason. For example:
+
+-
+
+ The services crashed due to defects in the source code.
+
+-
+
+ The services that are terminated by the OS when memory or CPU is not
+ sufficiently available for the service.
+
+.. note:: Only those services with daemons are monitored. The services that are
+failed due to errors in the service/daemon configuration file cannot be
+restarted by the Monitoring tool.
+
+The following services are monitored in a VR:
+
+-
+
+ DNS
+
+-
+
+ HA Proxy
+
+-
+
+ SSH
+
+-
+
+ Apache Web Server
+
+The following networks are supported:
+
+-
+
+ Isolated Networks
+
+-
+
+ Shared Networks in both Advanced and Basic zone
+
+This feature is supported on the following hypervisors: XenServer,
+VMware, and KVM.
+
+Enhanced Upgrade for Virtual Routers
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Upgrading VR is made flexible. The CloudStack administrators will be
+able to control the sequence of the VR upgrades. The sequencing is based
+on Infrastructure hierarchy, such as by Cluster, Pod, or Zone, and
+Administrative (Account) hierarchy, such as by Tenant or Domain. As an
+administrator, you can also determine when a particular customer
+service, such as VR, is upgraded within a specified upgrade interval.
+Upgrade operation is enhanced to increase the upgrade speed by allowing
+as many upgrade operations in parallel as possible.
+
+During the entire duration of the upgrade, users cannot launch new
+services or make changes to an existing service.
+
+Additionally, using multiple versions of VRs in a single instance is
+supported. In the Details tab of a VR, you can view the version and
+whether it requires upgrade. During the Management Server upgrade,
+CloudStack checks whether VR is at the latest version before performing
+any operation on the VR. To support this, a new global parameter,
+*``router.version.check``*, has been added. This parameter is set to
+true by default, which implies minimum required version is checked
+before performing any operation. No operation is performed if the VR is
+not at the required version. Services of the older version VR continue
+to be available, but no further operations can be performed on the VR
+until it is upgraded to the latest version. This will be a transient
+state until the VR is upgraded. This will ensure that the availability
+of VR services and VR state is not impacted due to the Management Server
+upgrade.
+
+The following service will be available even if the VR is not upgraded.
+However, no changes for any of the services can be sent to the VR, until
+it is upgraded:
+
+-
+
+ SecurityGroup
+
+-
+
+ UserData
+
+-
+
+ DHCP
+
+-
+
+ DNS
+
+-
+
+ LB
+
+-
+
+ Port Forwarding
+
+-
+
+ VPN
+
+-
+
+ Static NAT
+
+-
+
+ Source NAT
+
+-
+
+ Firewall
+
+-
+
+ Gateway
+
+-
+
+ NetworkACL
+
+16.5.5.1. Supported Virtual Routers
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+-
+
+ VR
+
+-
+
+ VPC VR
+
+-
+
+ Redundant VR
+
+16.5.5.2. Upgrading Virtual Routers
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+#.
+
+ Download the latest System VM template.
+
+#.
+
+ Download the latest System VM to all the primary storage pools.
+
+#.
+
+ Upgrade the Management Server.
+
+#.
+
+ Upgrade CPVM and SSVM either from the UI or by using the following
+ script:
+
+ .. code:: bash
+
+ # cloudstack-sysvmadm -d <IP address> -u cloud -p -s
+
+ Even when the VRs are still on older versions, existing services will
+ continue to be available to the VMs. The Management Server cannot
+ perform any operations on the VRs until they are upgraded.
+
+#.
+
+ Selectively upgrade the VRs:
+
+ #.
+
+ Log in to the CloudStack UI as the root administrator.
+
+ #.
+
+ In the left navigation, choose Infrastructure.
+
+ #.
+
+ On Virtual Routers, click View More.
+
+ All the VRs are listed in the Virtual Routers page.
+
+ #.
+
+ In Select View drop-down, select desired grouping based on your
+ requirement.
+
+ You can use either of the following:
+
+ -
+
+ Group by zone
+
+ -
+
+ Group by pod
+
+ -
+
+ Group by cluster
+
+ -
+
+ Group by account
+
+ #.
+
+ Click the group which has the VRs to be upgraded.
+
+ For example, if you have selected Group by zone, select the name
+ of the desired zone.
+
+ #.
+
+ Click the Upgrade button to upgrade all the VRs. |vr-upgrade.png:
+ Button to upgrade VR to use the new template.|
+
+ #.
+
+ Click OK to confirm.
+
+16.6. Secondary Storage VM
+--------------------------
+
+In addition to the hosts, CloudStack’s Secondary Storage VM mounts and
+writes to secondary storage.
+
+Submissions to secondary storage go through the Secondary Storage VM.
+The Secondary Storage VM can retrieve templates and ISO images from URLs
+using a variety of protocols.
+
+The secondary storage VM provides a background task that takes care of a
+variety of secondary storage activities: downloading a new template to a
+Zone, copying templates between Zones, and snapshot backups.
+
+The administrator can log in to the secondary storage VM if needed.
+