This is an automated email from the ASF dual-hosted git repository.

dahn pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/cloudstack-documentation.git


The following commit(s) were added to refs/heads/master by this push:
     new 78c39ea  [WIP] Backup & Recovery Doc Guide (#85)
78c39ea is described below

commit 78c39eaf0bdc1ba85a72a76d4931d40078496ec5
Author: Rohit Yadav <rohit.ya...@shapeblue.com>
AuthorDate: Thu May 14 13:37:20 2020 +0530

    [WIP] Backup & Recovery Doc Guide (#85)
---
 source/_static/images/B&R-BackupSchedule.jpg       | Bin 0 -> 18106 bytes
 source/_static/images/B&R-BackupScheduleEntry.jpg  | Bin 0 -> 30672 bytes
 source/_static/images/B&R-assignOffering.jpg       | Bin 0 -> 18271 bytes
 source/_static/images/B&R-backup_offering.jpg      | Bin 0 -> 32300 bytes
 .../_static/images/B&R-backup_offering_policy.jpg  | Bin 0 -> 29798 bytes
 source/_static/images/B&R-createBackup.jpg         | Bin 0 -> 15940 bytes
 source/_static/images/BnR-CreateDummyTag.jpg       | Bin 0 -> 30197 bytes
 source/_static/images/BnR-DummyTagCategory.jpg     | Bin 0 -> 52030 bytes
 source/_static/images/BnR-VMsandTags.jpg           | Bin 0 -> 111407 bytes
 source/_static/images/BnR-backupschedule.jpg       | Bin 0 -> 118135 bytes
 source/adminguide/backup_and_recovery.rst          | 189 ++++
 source/adminguide/index.rst                        |   4 +-
 source/adminguide/templates.rst                    | 152 ++++
 source/adminguide/veeam_plugin.rst                 | 152 ++++
 source/adminguide/virtual_machines.rst             | 965 +++++++++------------
 15 files changed, 907 insertions(+), 555 deletions(-)

diff --git a/source/_static/images/B&R-BackupSchedule.jpg 
b/source/_static/images/B&R-BackupSchedule.jpg
new file mode 100644
index 0000000..931283c
Binary files /dev/null and b/source/_static/images/B&R-BackupSchedule.jpg differ
diff --git a/source/_static/images/B&R-BackupScheduleEntry.jpg 
b/source/_static/images/B&R-BackupScheduleEntry.jpg
new file mode 100644
index 0000000..b4b44ba
Binary files /dev/null and b/source/_static/images/B&R-BackupScheduleEntry.jpg 
differ
diff --git a/source/_static/images/B&R-assignOffering.jpg 
b/source/_static/images/B&R-assignOffering.jpg
new file mode 100644
index 0000000..9493847
Binary files /dev/null and b/source/_static/images/B&R-assignOffering.jpg differ
diff --git a/source/_static/images/B&R-backup_offering.jpg 
b/source/_static/images/B&R-backup_offering.jpg
new file mode 100644
index 0000000..8001a7c
Binary files /dev/null and b/source/_static/images/B&R-backup_offering.jpg 
differ
diff --git a/source/_static/images/B&R-backup_offering_policy.jpg 
b/source/_static/images/B&R-backup_offering_policy.jpg
new file mode 100644
index 0000000..f0b76c0
Binary files /dev/null and 
b/source/_static/images/B&R-backup_offering_policy.jpg differ
diff --git a/source/_static/images/B&R-createBackup.jpg 
b/source/_static/images/B&R-createBackup.jpg
new file mode 100644
index 0000000..756f99d
Binary files /dev/null and b/source/_static/images/B&R-createBackup.jpg differ
diff --git a/source/_static/images/BnR-CreateDummyTag.jpg 
b/source/_static/images/BnR-CreateDummyTag.jpg
new file mode 100644
index 0000000..98dd44b
Binary files /dev/null and b/source/_static/images/BnR-CreateDummyTag.jpg differ
diff --git a/source/_static/images/BnR-DummyTagCategory.jpg 
b/source/_static/images/BnR-DummyTagCategory.jpg
new file mode 100644
index 0000000..658ab6b
Binary files /dev/null and b/source/_static/images/BnR-DummyTagCategory.jpg 
differ
diff --git a/source/_static/images/BnR-VMsandTags.jpg 
b/source/_static/images/BnR-VMsandTags.jpg
new file mode 100644
index 0000000..aa9fc95
Binary files /dev/null and b/source/_static/images/BnR-VMsandTags.jpg differ
diff --git a/source/_static/images/BnR-backupschedule.jpg 
b/source/_static/images/BnR-backupschedule.jpg
new file mode 100644
index 0000000..af7259d
Binary files /dev/null and b/source/_static/images/BnR-backupschedule.jpg differ
diff --git a/source/adminguide/backup_and_recovery.rst 
b/source/adminguide/backup_and_recovery.rst
new file mode 100644
index 0000000..a85a2a1
--- /dev/null
+++ b/source/adminguide/backup_and_recovery.rst
@@ -0,0 +1,189 @@
+.. Licensed to the Apache Software Foundation (ASF) under one
+   or more contributor license agreements.  See the NOTICE file
+   distributed with this work for additional information#
+   regarding copyright ownership.  The ASF licenses this file
+   to you under the Apache License, Version 2.0 (the
+   "License"); you may not use this file except in compliance
+   with the License.  You may obtain a copy of the License at
+   http://www.apache.org/licenses/LICENSE-2.0
+   Unless required by applicable law or agreed to in writing,
+   software distributed under the License is distributed on an
+   "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+   KIND, either express or implied.  See the License for the
+   specific language governing permissions and limitations
+   under the License.
+ 
+About Backup And Recovery
+--------------------------
+
+CloudStack version 4.14 introduces a new Backup and Recovery (B&R) framework 
that
+provides CloudStack with users the ability to back up their guest VMs for 
recovery
+purposes via 3rd party backup solutions.  The framework abstracts the API 
commands
+required for common backup and recovery
+operations, from the vendor specific commmands needed to perform those actions 
and provides
+a plugin model to enable any solution which provides backup and recovery 'like'
+features to be integrated.
+
+The following providers are currently supported:
+
+- VMware with Veeam Backup and Recovery
+
+See the Veeam Backup and Recovery plugin documentation for plugin specific 
information.
+:ref:`Veeam Backup and Recovery Plugin`
+
+Backup and Recovery Concepts
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Backup and recovery has been designed to support two modes:
+
+- ‘SLA’ based backups
+
+- Adhoc and user scheduled backups
+
+'SLA' based backups are ones where the Cloud provider (ie the root admin) 
controls the time, and frequency of a backup scheme.
+A user signs up for a 'Gold' offering, which might give them a RPO of 12 hours 
and the last 14 backups kept; however the user would not be 
+allowed to perform additional backups nor set the exact time that these 
backups took place.  The user might be charged
+a fix rate for these backups regardless of the size of the backups.
+
+To use an SLA based backup policy the user adds their VMs to the 
offering/policy.  The job then runs at its predetermined times and 'includes' 
the
+VM when it runs.  A user can remove the VM from the offering/policy and it 
will no longer be included in the job when it runs.
+
+Adhoc and user scheduled backups follow the same idea as volume snapshots, 
however they leverage the backup solution
+rather than secondary storage.  These could likely be billed on backup storage 
consumed or protected capacity (the full virtual
+size of the VM(s) being backed up.
+
+Adhoc and user scheduled backups are created and managed in the same fashion 
as volume snapshots are.
+
+
+Configuring Backup and Recovery
+--------------------------------
+
+The cloud administrator can use global configuration variables to
+control the behavior of B&R feature. To set these variables, go through
+the Global Settings area of the CloudStack UI.
+
+.. cssclass:: table-striped table-bordered table-hover
+
+================================= ========================
+Configuration                     Description
+================================= ========================
+backup.framework.enabled          Setting to enable or disable the feature. 
Default: false.
+backup.framework.provider.plugin  The backup provider (plugin) name. For 
example: 'dummy' and 'veeam'. This is a zone specific setting. Default: dummy.
+backup.framework.sync.interval    Background sync task internal in seconds 
that performs metrics/usage stats collection, backup reconciliation and backup 
scheduling. Default: 300.
+================================= ========================
+
+Plugin specific settings
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Each backup and recovery plugin is likely to have settings specific to that 
plugin.  Refer to the CloudStack documentation
+for your plugin for details on how to configure those settings.
+
+
+Backup Offerings
+------------------
+
+Admins can import an external provider's backup offerings using UI or API for a
+particular zone, as well as manage a backup offering's lifecyle. Admins can 
also
+specify if a backup offering allows user-defined backup schedules and ad-hoc
+backups. Users can list and consume the imported backup offerings, only root 
admins can import or
+delete offerings.
+
+Supported APIs:
+~~~~~~~~~~~~~~~~ 
+
+- **listBackupProviders**: lists available backup provider plugins
+- **listBackupProviderOfferings**: lists external backup policy/offering from 
a provider
+- **importBackupProviderOfferings**: allows importing of an external backup 
policy/offering to CloudStack as a backup offering
+- **listBackupOfferings**: lists CloudStack's backup offerings (searching via 
keyword, and pagination supported)
+- **deleteBackupOffering**: deletes a backup offering by its ID
+
+Importing Backup Offerings
+-----------------------------
+
+See plugin specific documentation to create 'Backup provider offerings'
+
+To import a backup provider offering;
+
+#. (As root) navigate to Service Offerings, click on the 'select offering' 
dropdown box and select 'Backup Offerings'
+#. Click on Import Backup Offering
+#. Enter your user-friendly name and description and select the applicable 
zone.  The External ID will then be populated with the
+   template jobs which CloudStack retrieves from the connected provider.
+
+   |B&R-backup_offering_policy.jpg|  |B&R-backup_offering.jpg|
+
+Creating VM Backups
+---------------------
+
+SLA/Policy Based backups
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+With the backup and recovery feature enabled for a zone, users simply add and 
+remove a VM from a backup offering.
+
+|B&R-assignOffering.jpg|
+
+Adhoc and Scheduled Backups
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+For backup offerings that allow ad-hoc user backups and user-defined backup
+schedules, user will be allowed to define a backup schedule for a VM that is
+assigned to a backup offering using UI and API. A VM with backup will not be
+allowed to add/remove volumes similar to VM snapshots.
+
+To trigger an adhoc backup of a VM, navigate to the instance and click on the 
'Create Backup'
+icon.
+
+|B&R-createBackup.jpg|
+
+To setup a recurring backup schedule, navigate to the instance and click on 
the 'Backup Schedule'
+icon.
+
+|B&R-BackupSchedule.jpg|
+
+Then set the time and frequency of the backups, click 'Configure' and then 
'Close'
+
+|B&R-BackupScheduleEntry.jpg|
+
+Restoring VM Backups
+---------------------
+
+Users will need to stop a VM to restore to any existing VM backup, restoration
+of an expunged VM will not restore nics and recovery any network which may/may
+not exist. User may however restore a specific volume from a VM backup and 
attach
+that volume to a specified VM.
+
+Supported APIs:
+~~~~~~~~~~~~~~~~
+
+- **assignVirtualMachineToBackupOffering**: adds a VM to a backup offering.
+- **removeVirtualMachineFromBackupOffering**: removes a VM from a backup 
offering, if forced `true` parameter is passed this may also
+  remove any and all the backups of a VM associated with a backup offering.
+- **createBackupSchedule**: creates a backup schedule for a VM.
+- **updateBackupSchedule**: updates backup schedule.
+- **listBackupSchedule**: returns backup schedule of a VM if defined.
+- **deleteBackupSchedule**: deletes backup schedule of a VM.
+- **createBackup**: creates an adhoc backup for a VM.
+- **deleteVMBackup**: deletes a VM backup (not support for per restore point 
for Veeam).
+- **listBackups**: lists backups.
+- **restoreBackup**: restore a previous VM backup in-place of a stopped or 
destroyed VM.
+- **restoreVolumeFromBackup**: restore and attach a backed-up volume (of a VM 
backup) to a specified VM.
+
+
+.. |B&R-assignOffering.jpg| image:: /_static/images/B&R-assignOffering.jpg
+   :alt: Assigning an SLA/Policy to a VM.
+   :width: 400 px
+.. |B&R-backup_offering_policy.jpg| image:: 
/_static/images/B&R-backup_offering_policy.jpg
+   :alt: Importing an SLA/Policy offering.
+   :width: 300 px
+.. |B&R-backup_offering.jpg| image:: /_static/images/B&R-backup_offering.jpg
+   :alt: Importing a template backup offering.
+   :width: 300 px
+.. |B&R-createBackup.jpg| image:: /_static/images/B&R-createBackup.jpg
+   :alt: Triggering an adhoc backup for a VM.
+   :width: 400 px
+.. |B&R-BackupSchedule.jpg| image:: /_static/images/B&R-BackupSchedule.jpg
+   :alt: Creating a backup schedule for a VM.
+   :width: 400 px
+.. |B&R-BackupScheduleEntry.jpg| image:: 
/_static/images/B&R-BackupScheduleEntry.jpg
+   :alt: Creating a backup schedule for a VM.
+   :width: 400px
diff --git a/source/adminguide/index.rst b/source/adminguide/index.rst
index 15ed4d0..b4865bb 100644
--- a/source/adminguide/index.rst
+++ b/source/adminguide/index.rst
@@ -81,8 +81,8 @@ Working with Virtual Machines
    virtual_machines
 
 
-Working with Templates
-----------------------
+Working with Templates & ISOs
+------------------------------
 
 .. toctree::
    :maxdepth: 4
diff --git a/source/adminguide/templates.rst b/source/adminguide/templates.rst
index 6c43dba..deb6159 100644
--- a/source/adminguide/templates.rst
+++ b/source/adminguide/templates.rst
@@ -13,6 +13,8 @@
    specific language governing permissions and limitations
    under the License.
 
+Working With Templates
+=======================
 
 A template is a reusable configuration for virtual machines. When users
 launch VMs, they can choose from a list of templates in CloudStack.
@@ -383,6 +385,156 @@ When templates are deleted, the VMs instantiated from 
them will continue
 to run. However, new VMs cannot be created based on the deleted
 template.
 
+Working with ISOs
+===================
+
+CloudStack supports ISOs and their attachment to guest VMs. An ISO is a
+read-only file that has an ISO/CD-ROM style file system. Users can
+upload their own ISOs and mount them on their guest VMs.
+
+ISOs are uploaded based on a URL. HTTP is the supported protocol. Once
+the ISO is available via HTTP specify an upload URL such as
+http://my.web.server/filename.iso.
+
+ISOs may be public or private, like templates.ISOs are not
+hypervisor-specific. That is, a guest on vSphere can mount the exact
+same image that a guest on KVM can mount.
+
+ISO images may be stored in the system and made available with a privacy
+level similar to templates. ISO images are classified as either bootable
+or not bootable. A bootable ISO image is one that contains an OS image.
+CloudStack allows a user to boot a guest VM off of an ISO image. Users
+can also attach ISO images to guest VMs. For example, this enables
+installing PV drivers into Windows. ISO images are not
+hypervisor-specific.
+
+
+Adding an ISO
+---------------
+
+To make additional operating system or other software available for use
+with guest VMs, you can add an ISO. The ISO is typically thought of as
+an operating system image, but you can also add ISOs for other types of
+software, such as desktop applications that you want to be installed as
+part of a template.
+
+#. Log in to the CloudStack UI as an administrator or end user.
+
+#. In the left navigation bar, click Templates.
+
+#. In Select View, choose ISOs.
+
+#. Click Add ISO.
+
+#. In the Add ISO screen, provide the following:
+
+   -  **Name**: Short name for the ISO image. For example, CentOS 6.2
+      64-bit.
+
+   -  **Description**: Display test for the ISO image. For example,
+      CentOS 6.2 64-bit.
+
+   -  **URL**: The URL that hosts the ISO image. The Management Server
+      must be able to access this location via HTTP. If needed you can
+      place the ISO image directly on the Management Server
+
+   -  **Zone**: Choose the zone where you want the ISO to be available,
+      or All Zones to make it available throughout CloudStack.
+
+   -  **Bootable**: Whether or not a guest could boot off this ISO
+      image. For example, a CentOS ISO is bootable, a Microsoft Office
+      ISO is not bootable.
+
+   -  **OS Type**: This helps CloudStack and the hypervisor perform
+      certain operations and make assumptions that improve the
+      performance of the guest. Select one of the following.
+
+      -  If the operating system of your desired ISO image is listed,
+         choose it.
+
+      -  If the OS Type of the ISO is not listed or if the ISO is not
+         bootable, choose Other.
+
+      -  (XenServer only) If you want to boot from this ISO in PV mode,
+         choose Other PV (32-bit) or Other PV (64-bit)
+
+      -  (KVM only) If you choose an OS that is PV-enabled, the VMs
+         created from this ISO will have a SCSI (virtio) root disk. If
+         the OS is not PV-enabled, the VMs will have an IDE root disk.
+         The PV-enabled types are:
+
+         -  Fedora 13
+
+         -  Fedora 12
+
+         -  Fedora 11
+
+         -  Fedora 10
+
+         -  Fedora 9
+
+         -  Other PV
+
+         -  Debian GNU/Linux
+
+         -  CentOS 5.3
+
+         -  CentOS 5.4
+
+         -  CentOS 5.5
+
+         -  Red Hat Enterprise Linux 5.3
+
+         -  Red Hat Enterprise Linux 5.4
+
+         -  Red Hat Enterprise Linux 5.5
+
+         -  Red Hat Enterprise Linux 6
+
+
+      .. note:: 
+         It is not recommended to choose an older version of the OS than 
+         the version in the image. For example, choosing CentOS 5.4 to 
+         support a CentOS 6.2 image will usually not work. In these 
+         cases, choose Other.
+
+   -  **Extractable**: Choose Yes if the ISO should be available for
+      extraction.
+
+   -  **Public**: Choose Yes if this ISO should be available to other
+      users.
+
+   -  **Featured**: Choose Yes if you would like this ISO to be more
+      prominent for users to select. The ISO will appear in the Featured
+      ISOs list. Only an administrator can make an ISO Featured.
+
+#. Click OK.
+
+   The Management Server will download the ISO. Depending on the size of
+   the ISO, this may take a long time. The ISO status column will
+   display Ready once it has been successfully downloaded into secondary
+   storage. Clicking Refresh updates the download percentage.
+
+#. **Important**: Wait for the ISO to finish downloading. If you move on
+   to the next task and try to use the ISO right away, it will appear to
+   fail. The entire ISO must be available before CloudStack can work
+   with it.
+
+
+Attaching an ISO to a VM
+-------------------------
+
+#. In the left navigation, click Instances.
+
+#. Choose the virtual machine you want to work with.
+
+#. Click the Attach ISO button. |iso.png|
+
+#. In the Attach ISO dialog box, select the desired ISO.
+
+#. Click OK.
+
+
 
 .. |sysmanager.png| image:: /_static/images/sysmanager.png
    :alt: System Image Manager
diff --git a/source/adminguide/veeam_plugin.rst 
b/source/adminguide/veeam_plugin.rst
new file mode 100644
index 0000000..14424fb
--- /dev/null
+++ b/source/adminguide/veeam_plugin.rst
@@ -0,0 +1,152 @@
+.. Licensed to the Apache Software Foundation (ASF) under one
+   or more contributor license agreements.  See the NOTICE file
+   distributed with this work for additional information#
+   regarding copyright ownership.  The ASF licenses this file
+   to you under the Apache License, Version 2.0 (the
+   "License"); you may not use this file except in compliance
+   with the License.  You may obtain a copy of the License at
+   http://www.apache.org/licenses/LICENSE-2.0
+   Unless required by applicable law or agreed to in writing,
+   software distributed under the License is distributed on an
+   "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+   KIND, either express or implied.  See the License for the
+   specific language governing permissions and limitations
+   under the License.
+
+.. _Veeam Backup and Recovery Plugin:
+
+Veeam Backup and Recovery Plugin
+=================================
+
+About the Veeam Backup and Recovery Plugin
+-------------------------------------------
+
+There are a couple of important concepts to understand before working with the 
Veeam plugin.
+
+#. Backup Provider Offerings for the Veeam B&R plugin are template backup jobs.
+
+#. Veeams API does not allow for the creation of backup jobs.  Therefore, a 
backup job must be created which will act
+   as a template for all 'backups' which are based on it.  You will need to 
create backup job templates for each of the
+   Backup Offerings which you will be presenting to your users, be they a 
default template for ad-hoc/scheduled backups or
+   'SLA' specific templates (ie Gold offering). Refer to the general B&R for 
information regrading the B&R
+   job types.
+
+#. The backup job templates will be zone specific as they will contain the 
backup destination, and this will be different
+   in each zone (unless you have extreamly fat links between zones).
+
+#. Veeam backup jobs are not allowed to be empty (i.e. they must backup 
something); therefore a dummy tag which
+   is not assigned to any VM must be created via vCenter. The initial backup 
target of the backup job templates is
+   then 'any VM with the dummy tag assigned' i.e. no VMs
+
+#. Veeam's API is not complete and therefore a mix of API commands and 
powershell commands (via SSH) are employed.
+
+#. Veeam cannot explicitly reduce the number of backups that are kept, nor can 
it remove individual *partial* backups and 'coalesce' the
+   remaining image(s)
+
+
+Installing Veeam Backup and Recovery for use with CloudStack
+-------------------------------------------------------------
+
+The B&R Veeam plugin has been tested against Veeam Backup and Recovery 9.5 
update 4b (Enterprise version).  The
+enterprise edition is required for the Enterprise Manager API.  The final 
tested version of Veeam was on a
+Windows Server 2019 (with desktop), although much of the development work was 
done against a Windows Server 2016 OS (with
+desktop).
+
+The following steps give a minimal installation, they do not cover Veeam 
integrations with backup, storage or
+virtualisation hardware.  A number of the steps below may already have been 
carried out if you are already using Veeam Backup
+and Replication, however please read the steps below carefully to ensure that 
your installation meet all requirements for
+compatibility with the B&R Veeam plug-in.
+
+
+#. Install Backup and Replication 9.5 Manager - inc console - default settings
+#. Install Enterprise manager
+#. Install an SSH server on the 'Veeam Backup and Replication Manager' server. 
Windows Server 2019 has 'OpenSSH Server' as a
+   builtin optional feature which is compatible.
+#. Powershell 5.1 is the default version on Windows Server 2019
+
+Once these components are installed, then Veeam services can be configured.  
Please see the VM documentation for details,
+but at a high level you need to have done the following;
+
+#. License the Enterprise Manager & Backup and Replication servers (this can 
be done purely through the Enterprise Manager)
+#. Connect Enterprise Manager to Veeam backup server(s)
+#. Connect Enterprise Manager to vCenter server
+#. Add your 'vSphere' infrastructure to 'Managed Servers' in the Veeam Backup 
& Replication Console
+#. Setup your 'Backup Repositories' in the Veeam Backup & Replication Console. 
 Remember that you will likely want a different
+   target in each zone.
+
+Creating Template jobs
+----------------------
+
+#. As noted above, a dummy VM tag is required in order to create template jobs 
which don't contain any VMs.  This is done via vCenter
+   by navigating to the 'Tags and Custom Attributes' section, and first 
creating a category (if you dont already have a suitable one).
+
+   |BnR-DummyTagCategory.jpg|
+
+#. Then, create a dummy tag in that category.  Be sure to make it clear that 
it is not to be used anywhere.
+
+   |BnR-CreateDummyTag.jpg|
+
+#. Now create the template job in Veeam Backup and Replication Manager. using 
the New Backup Job (Virtual Machine) wizard.
+
+   #. Give the job a name that describes what the job does ie 
*template_job_zone1_default* or *template_daily_job-14_kept*
+      (the end user will not see this name).
+   #. In the Virtual Machines section of the wizard, click 'Add' and select 
the 'VMs and Tags' filter (top right of the 
+      'Add Objects' dialog box). And then select your dummy tag and click on 
Add.
+
+      |BnR-VMsandTags.jpg|
+
+   #. In the Storage section is the correct Backup repository for the zone and 
number of restore points. (note there are a number
+      of other advanaced options which can be set, these are transparent to 
CloudStack. CloudStack will clone this job 'as-is' including
+      all advanced settings.  However changing these settings will only effect 
NEW jobs created from the template, existing jobs will be
+      unchanged.
+   
+   #. The same is true for the Guest Processing section. 
+
+   #. In the Schedule section you, if you are creating an 'SLA' based backup 
template, you would set the job to run automatically and
+      select 'Periodically every' 24hrs and then in the 'Schedule' dialog set 
the hours in which the job is allowed to run.  This allows
+      Veeam to choose the best time to run the backup within a given window.  
If you are creating a template for adhoc/scheduled backups,
+      do not tick 'Run the job automatically' as CloudStack will trigger jobs 
as and when required.
+
+      |BnR-backupschedule.jpg|
+
+   #. Finally, save the job.
+
+
+Connecting CloudStack to Veeam
+-------------------------------
+
+Once Veeam is configured with SSH enabled and at least one template job, we 
can connect CloudStack to your Veeam server.
+
+To do this, you simply update the global settings listed below:
+
+Plug-in specific settings:
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+(all settings can be global or per-zone)
+
+.. cssclass:: table-striped table-bordered table-hover
+
+==================================== ========================
+Configuration                         Description
+==================================== ========================
+backup.plugin.veeam.url              Veeam B&R server URL. Default: 
http://<VEEAM_SERVER_IP>:9398/api/
+backup.plugin.veeam.username         Veeam B&R server username. Default: 
administrator
+backup.plugin.veeam.password         Veeam B&R server password. Default:
+backup.plugin.veeam.validate.ssl     Whether to validate Veeam B&R server 
(SSL/TLS) connection while making API requests. Default: false
+backup.plugin.veeam.request.timeout  Veeam B&R API request timeout in seconds. 
Default: 300
+==================================== ========================
+
+
+.. |BnR-DummyTagCategory.jpg| image:: /_static/images/BnR-DummyTagCategory.jpg
+   :alt: Create Tag Category.
+   :width: 300 px
+.. |BnR-CreateDummyTag.jpg| image:: /_static/images/BnR-CreateDummyTag.jpg
+   :alt: Create Dummy Tag.
+   :width: 300 px
+.. |BnR-VMsandTags.jpg| image:: /_static/images/BnR-VMsandTags.jpg
+   :alt: Select Dummy Tag.
+   :width: 300 px
+.. |BnR-backupschedule.jpg| image:: /_static/images/BnR-backupschedule.jpg
+   :alt: Set recurring SLA schedule.
+   :width: 600 px
+
diff --git a/source/adminguide/virtual_machines.rst 
b/source/adminguide/virtual_machines.rst
index 15bed54..8af8bb6 100644
--- a/source/adminguide/virtual_machines.rst
+++ b/source/adminguide/virtual_machines.rst
@@ -13,9 +13,8 @@
    specific language governing permissions and limitations
    under the License.
    
-
 About Working with Virtual Machines
------------------------------------
+===================================
 
 CloudStack provides administrators with complete control over the
 lifecycle of all guest VMs executing in the cloud. CloudStack provides
@@ -68,96 +67,46 @@ CloudStack will restart it. To shut down an HA-enabled VM, 
you must go
 through the CloudStack UI or API.
 
 
-Best Practices for Virtual Machines
------------------------------------
-
-For VMs to work as expected and provide excellent service, follow these 
-guidelines.
-
-
-Monitor VMs for Max Capacity
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-The CloudStack administrator should monitor the total number of VM
-instances in each cluster, and disable allocation to the cluster if the
-total is approaching the maximum that the hypervisor can handle. Be sure
-to leave a safety margin to allow for the possibility of one or more
-hosts failing, which would increase the VM load on the other hosts as
-the VMs are automatically redeployed. Consult the documentation for your
-chosen hypervisor to find the maximum permitted number of VMs per host,
-then use CloudStack global configuration settings to set this as the
-default limit. Monitor the VM activity in each cluster at all times.
-Keep the total number of VMs below a safe level that allows for the
-occasional host failure. For example, if there are N hosts in the
-cluster, and you want to allow for one host in the cluster to be down at
-any given time, the total number of VM instances you can permit in the
-cluster is at most (N-1) \* (per-host-limit). Once a cluster reaches
-this number of VMs, use the CloudStack UI to disable allocation of more
-VMs to the cluster.
-
-
-Install Required Tools and Drivers
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Be sure the following are installed on each VM:
-
--  For XenServer, install PV drivers and Xen tools on each VM. This will
-   enable live migration and clean guest shutdown. Xen tools are
-   required in order for dynamic CPU and RAM scaling to work.
-
--  For vSphere, install VMware Tools on each VM. This will enable
-   console view to work properly. VMware Tools are required in order for
-   dynamic CPU and RAM scaling to work.
-
-To be sure that Xen tools or VMware Tools is installed, use one of the
-following techniques:
 
--  Create each VM from a template that already has the tools installed;
-   or,
+.. note::
+   **Monitor VMs for Max Capacity**
 
--  When registering a new template, the administrator or user can
-   indicate whether tools are installed on the template. This can be
-   done through the UI or using the updateTemplate API; or,
+   The CloudStack administrator should monitor the total number of VM
+   instances in each cluster, and disable allocation to the cluster if the
+   total is approaching the maximum that the hypervisor can handle. Be sure
+   to leave a safety margin to allow for the possibility of one or more
+   hosts failing, which would increase the VM load on the other hosts as
+   the VMs are automatically redeployed. Consult the documentation for your
+   chosen hypervisor to find the maximum permitted number of VMs per host,
+   then use CloudStack global configuration settings to set this as the
+   default limit. Monitor the VM activity in each cluster at all times.
+   Keep the total number of VMs below a safe level that allows for the
+   occasional host failure. For example, if there are N hosts in the
+   cluster, and you want to allow for one host in the cluster to be down at
+   any given time, the total number of VM instances you can permit in the
+   cluster is at most (N-1) \* (per-host-limit). Once a cluster reaches
+   this number of VMs, use the CloudStack UI to disable allocation of more
+   VMs to the cluster.
 
--  If a user deploys a virtual machine with a template that does not
-   have Xen tools or VMware Tools, and later installs the tools on the
-   VM, then the user can inform CloudStack using the
-   updateVirtualMachine API. After installing the tools and updating the
-   virtual machine, stop and start the VM.
 
 
 VM Lifecycle
-------------
+============
 
 Virtual machines can be in the following states:
 
-|basic-deployment.png|
-
-Once a virtual machine is destroyed, it cannot be recovered. All the
-resources used by the virtual machine will be reclaimed by the system.
-This includes the virtual machine’s IP address.
-
-A stop will attempt to gracefully shut down the operating system, which
-typically involves terminating all the running applications. If the
-operation system cannot be stopped, it will be forcefully terminated.
-This has the same effect as pulling the power cord to a physical
-machine.
-
-A reboot is a stop followed by a start.
-
-CloudStack preserves the state of the virtual machine hard disk until
-the machine is destroyed.
-
-A running virtual machine may fail because of hardware or network
-issues. A failed virtual machine is in the down state.
+- Created
+- Running
+- Stopped
+- Destroyed
+- Expunged
 
-The system places the virtual machine into the down state if it does not
-receive the heartbeat from the hypervisor for three minutes.
+With the intermediate states of
 
-The user can manually restart the virtual machine from the down state.
-
-The system will start the virtual machine from the down state
-automatically if the virtual machine is marked as HA-enabled.
+- Creating
+- Starting
+- Stopping
+- Expunging
 
 
 Creating VMs
@@ -205,7 +154,9 @@ To create a VM from a template:
 To create a VM from an ISO:
 
 .. note:: 
-   (XenServer) Windows VMs running on XenServer require PV drivers, 
+   **XenServer** 
+
+   Windows VMs running on XenServer require PV drivers, 
    which may be provided in the template or added after the VM is 
    created. The PV drivers are necessary for essential management 
    functions such as mounting additional volumes and ISO images, 
@@ -224,6 +175,37 @@ To create a VM from an ISO:
 #. Click Submit and your VM will be created and started.
 
 
+
+Install Required Tools and Drivers
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Be sure the following are installed on each VM:
+
+-  For XenServer, install PV drivers and Xen tools on each VM. This will
+   enable live migration and clean guest shutdown. Xen tools are
+   required in order for dynamic CPU and RAM scaling to work.
+
+-  For vSphere, install VMware Tools on each VM. This will enable
+   console view to work properly. VMware Tools are required in order for
+   dynamic CPU and RAM scaling to work.
+
+To be sure that Xen tools or VMware Tools is installed, use one of the
+following techniques:
+
+-  Create each VM from a template that already has the tools installed;
+   or,
+
+-  When registering a new template, the administrator or user can
+   indicate whether tools are installed on the template. This can be
+   done through the UI or using the updateTemplate API; or,
+
+-  If a user deploys a virtual machine with a template that does not
+   have Xen tools or VMware Tools, and later installs the tools on the
+   VM, then the user can inform CloudStack using the
+   updateVirtualMachine API. After installing the tools and updating the
+   virtual machine, stop and start the VM.
+
+
 Accessing VMs
 -------------
 
@@ -265,296 +247,53 @@ Once a VM instance is created, you can stop, restart, or 
delete it as
 needed. In the CloudStack UI, click Instances, select the VM, and use
 the Stop, Start, Reboot, and Destroy buttons.
 
-When starting a VM, admin users have the option to specify a pod, cluster, or 
host.
-
-
-Assigning VMs to Hosts
-----------------------
-
-At any point in time, each virtual machine instance is running on a
-single host. How does CloudStack determine which host to place a VM on?
-There are several ways:
-
--  Automatic default host allocation. CloudStack can automatically pick
-   the most appropriate host to run each virtual machine.
-
--  Instance type preferences. CloudStack administrators can specify that
-   certain hosts should have a preference for particular types of guest
-   instances. For example, an administrator could state that a host
-   should have a preference to run Windows guests. The default host
-   allocator will attempt to place guests of that OS type on such hosts
-   first. If no such host is available, the allocator will place the
-   instance wherever there is sufficient physical capacity.
-
--  Vertical and horizontal allocation. Vertical allocation consumes all
-   the resources of a given host before allocating any guests on a
-   second host. This reduces power consumption in the cloud. Horizontal
-   allocation places a guest on each host in a round-robin fashion. This
-   may yield better performance to the guests in some cases.
-
--  Admin users preferences. Administrators have the option to specify a
-   pod, cluster, or host to run the VM in. CloudStack will then select
-   a host within the given infrastructure.
-
--  End user preferences. Users can not control exactly which host will
-   run a given VM instance, but they can specify a zone for the VM.
-   CloudStack is then restricted to allocating the VM only to one of the
-   hosts in that zone.
-
--  Host tags. The administrator can assign tags to hosts. These tags can
-   be used to specify which host a VM should use. The CloudStack
-   administrator decides whether to define host tags, then create a
-   service offering using those tags and offer it to the user.
-
--  Affinity groups. By defining affinity groups and assigning VMs to
-   them, the user or administrator can influence (but not dictate) which
-   VMs should run on separate hosts. This feature is to let users
-   specify that certain VMs won't be on the same host.
-
--  CloudStack also provides a pluggable interface for adding new
-   allocators. These custom allocators can provide any policy the
-   administrator desires.
+A stop will attempt to gracefully shut down the operating system, via 
+an ACPI 'stop' command which is similar to pressing the soft power switch
+on a physical server. If the operating system cannot be stopped, it will
+be forcefully terminated. This has the same effect as pulling out the power
+cord from a physical machine.
 
+A reboot should not be considered as a stop followed by a start. In CloudStack,
+a start command reconfigures the virtual machine to the stored parameters in 
+CloudStack's database.  The reboot process does not do this.
 
-Affinity Groups
-~~~~~~~~~~~~~~~
-
-By defining affinity groups and assigning VMs to them, the user or
-administrator can influence (but not dictate) which VMs should run on
-separate hosts. This feature is to let users specify that VMs with the
-same “host anti-affinity” type won’t be on the same host. This serves to
-increase fault tolerance. If a host fails, another VM offering the same
-service (for example, hosting the user's website) is still up and
-running on another host.
-
-The scope of an affinity group is per user account.
-
-
-Creating a New Affinity Group
-'''''''''''''''''''''''''''''
-
-To add an affinity group:
-
-#. Log in to the CloudStack UI as an administrator or user.
-
-#. In the left navigation bar, click Affinity Groups.
-
-#. Click Add affinity group. In the dialog box, fill in the following
-   fields:
-
-   -  Name. Give the group a name.
-
-   -  Description. Any desired text to tell more about the purpose of
-      the group.
-
-   -  Type. The only supported type shipped with CloudStack is Host
-      Anti-Affinity. This indicates that the VMs in this group should
-      avoid being placed on the same host with each other. If you see
-      other types in this list, it means that your installation of
-      CloudStack has been extended with customized affinity group
-      plugins.
-
-
-Assign a New VM to an Affinity Group
-''''''''''''''''''''''''''''''''''''
-
-To assign a new VM to an affinity group:
-
--  Create the VM as usual, as described in `“Creating
-   VMs” <virtual_machines.html#creating-vms>`_. In the Add Instance 
-   wizard, there is a new Affinity tab where you can select the 
-   affinity group.
-
-
-Change Affinity Group for an Existing VM
-''''''''''''''''''''''''''''''''''''''''
-
-To assign an existing VM to an affinity group:
-
-#. Log in to the CloudStack UI as an administrator or user.
-
-#. In the left navigation bar, click Instances.
-
-#. Click the name of the VM you want to work with.
-
-#. Stop the VM by clicking the Stop button.
-
-#. Click the Change Affinity button. |change-affinity-button.png|
-
-
-View Members of an Affinity Group
-'''''''''''''''''''''''''''''''''
-
-To see which VMs are currently assigned to a particular affinity group:
-
-#. In the left navigation bar, click Affinity Groups.
-
-#. Click the name of the group you are interested in.
-
-#. Click View Instances. The members of the group are listed.
-
-   From here, you can click the name of any VM in the list to access all
-   its details and controls.
-
-
-Delete an Affinity Group
-''''''''''''''''''''''''
-
-To delete an affinity group:
-
-#. In the left navigation bar, click Affinity Groups.
-
-#. Click the name of the group you are interested in.
-
-#. Click Delete.
-
-   Any VM that is a member of the affinity group will be disassociated
-   from the group. The former group members will continue to run
-   normally on the current hosts, but if the VM is restarted, it will no
-   longer follow the host allocation rules from its former affinity
-   group.
+When starting a VM, admin users have the option to specify a pod, cluster, or 
host.
 
 
-Virtual Machine Snapshots
+Deleting VMs
 -------------------------
 
-(Supported on VMware, XenServer and KVM (NFS only))
-
-In addition to the existing CloudStack ability to snapshot individual VM
-volumes, you can take a VM snapshot to preserve all the VM's data
-volumes as well as (optionally) its CPU/memory state. This is useful for
-quick restore of a VM. For example, you can snapshot a VM, then make
-changes such as software upgrades. If anything goes wrong, simply
-restore the VM to its previous state using the previously saved VM
-snapshot.
-
-The snapshot is created using the hypervisor's native snapshot facility.
-The VM snapshot includes not only the data volumes, but optionally also
-whether the VM is running or turned off (CPU state) and the memory
-contents. The snapshot is stored in CloudStack's primary storage.
-
-VM snapshots can have a parent/child relationship. Each successive
-snapshot of the same VM is the child of the snapshot that came before
-it. Each time you take an additional snapshot of the same VM, it saves
-only the differences between the current state of the VM and the state
-stored in the most recent previous snapshot. The previous snapshot
-becomes a parent, and the new snapshot is its child. It is possible to
-create a long chain of these parent/child snapshots, which amount to a
-"redo" record leading from the current state of the VM back to the
-original.
-
-After VM snapshots are created, they can be tagged with a key/value pair,
-like many other resources in CloudStack.
-
-KVM supports VM snapshots when using NFS shared storage. If raw block storage
-is used (i.e. Ceph), then VM snapshots are not possible, since there is no 
possibility
-to write RAM memory content anywhere.
-
-If you need more information about VM snapshots on VMware, check out the
-VMware documentation and the VMware Knowledge Base, especially
-`Understanding virtual machine snapshots 
-<http://kb.vmware.com/selfservice/microsites/search.do?cmd=displayKC&externalId=1015180>`_.
-
-
-Limitations on VM Snapshots
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
--  If a VM has some stored snapshots, you can't attach new volume to the
-   VM or delete any existing volumes. If you change the volumes on the
-   VM, it would become impossible to restore the VM snapshot which was
-   created with the previous volume structure. If you want to attach a
-   volume to such a VM, first delete its snapshots.
-
--  VM snapshots which include both data volumes and memory can't be kept
-   if you change the VM's service offering. Any existing VM snapshots of
-   this type will be discarded.
-
--  You can't make a VM snapshot at the same time as you are taking a
-   volume snapshot.
-
--  You should use only CloudStack to create VM snapshots on hosts
-   managed by CloudStack. Any snapshots that you make directly on the
-   hypervisor will not be tracked in CloudStack.
-
-
-Configuring VM Snapshots
-~~~~~~~~~~~~~~~~~~~~~~~~
-
-The cloud administrator can use global configuration variables to
-control the behavior of VM snapshots. To set these variables, go through
-the Global Settings area of the CloudStack UI.
-
-.. cssclass:: table-striped table-bordered table-hover
-
-====================== ========================
-Configuration          Description       Type
-====================== ========================
-vmsnapshots.max        The maximum number of VM snapshots that can be saved 
for any given virtual machine in the cloud. The total possible number of VM 
snapshots in the cloud is (number of VMs) \* vmsnapshots.max. If the number of 
snapshots for any VM ever hits the maximum, the older ones are removed by the 
snapshot expunge job
-vmsnapshot.create.wait Number of seconds to wait for a snapshot job to succeed 
before declaring failure and issuing an error.
-====================== ========================
-
-
-Using VM Snapshots
-~~~~~~~~~~~~~~~~~~
-
-To create a VM snapshot using the CloudStack UI:
-
-#. Log in to the CloudStack UI as a user or administrator.
-
-#. Click Instances.
-
-#. Click the name of the VM you want to snapshot.
-
-#. Click the Take VM Snapshot button. |VMSnapshotButton.png|
-
-   .. note:: 
-      If a snapshot is already in progress, then clicking this button 
-      will have no effect.
-
-#. Provide a name and description. These will be displayed in the VM
-   Snapshots list.
-
-#. (For running VMs only) If you want to include the VM's memory in the
-   snapshot, click the Memory checkbox. This saves the CPU and memory
-   state of the virtual machine. If you don't check this box, then only
-   the current state of the VM disk is saved. Checking this box makes
-   the snapshot take longer.
-
-#. Quiesce VM: check this box if you want to quiesce the file system on
-   the VM before taking the snapshot. Not supported on XenServer when
-   used with CloudStack-provided primary storage.
-
-   When this option is used with CloudStack-provided primary storage,
-   the quiesce operation is performed by the underlying hypervisor
-   (VMware is supported). When used with another primary storage
-   vendor's plugin, the quiesce operation is provided according to the
-   vendor's implementation.
-
-#. Click OK.
+Users can delete their own virtual machines. A running virtual machine
+will be abruptly stopped before it is deleted. Administrators can delete
+any virtual machines.
 
-To delete a snapshot or restore a VM to the state saved in a particular
-snapshot:
+To delete a virtual machine:
 
-#. Navigate to the VM as described in the earlier steps.
+#. Log in to the CloudStack UI as a user or admin.
 
-#. Click View VM Snapshots.
+#. In the left navigation, click Instances.
 
-#. In the list of snapshots, click the name of the snapshot you want to
-   work with.
+#. Choose the VM that you want to delete.
 
-#. Depending on what you want to do:
+#. Click the Destroy Instance button. |Destroyinstance.png|
 
-   To delete the snapshot, click the Delete button. |delete-button.png|
+#. Optionally both expunging and the deletion of any attached volumes can be 
enabled.
 
-   To revert to the snapshot, click the Revert button. |revert-vm.png|
+When a virtual machine is **destroyed**, it can no longer be seen by the end 
user,
+however, it can be seen (and recovered) by a root admin.  In this state it 
still 
+consumes logical resources.  Global settings control the maximum time from a VM
+being destroyed, to the physical disks being removed. When the VM and its 
rooot disk
+have been deleted, the VM is said to have been expunged.
 
-.. note:: 
-   VM snapshots are deleted automatically when a VM is destroyed. You don't 
-   have to manually delete the snapshots in this case.
+Once a virtual machine is **expunged**, it cannot be recovered. All the
+resources used by the virtual machine will be reclaimed by the system,
+This includes the virtual machine’s IP address.  
 
+Managing Virtual Machines
+=========================
 
 Changing the VM Name, OS, or Group
-----------------------------------
+-------------------------------------
 
 After a VM is created, you can modify the display name, operating
 system, and the group it belongs to.
@@ -584,7 +323,7 @@ To access a VM through the CloudStack UI:
 
 
 Appending a Display Name to the Guest VM’s Internal Name
---------------------------------------------------------
+----------------------------------------------------------
 
 Every guest VM has an internal name. The host uses the internal name to
 identify the guest VMs. CloudStack gives you an option to provide a
@@ -619,7 +358,7 @@ No                            False                   UUID  
               i-<us
 
 
 Changing the Service Offering for a VM
---------------------------------------
+----------------------------------------
 
 To upgrade or downgrade the level of compute resources available to a
 virtual machine, you can change the VM's compute offering.
@@ -796,238 +535,392 @@ following conditions:
    cluster to another is enabled by CloudStack support for XenMotion and
    vMotion.)
 
-To manually live migrate a virtual machine
+To manually live migrate a virtual machine
+
+#. Log in to the CloudStack UI as a user or admin.
+
+#. In the left navigation, click Instances.
+
+#. Choose the VM that you want to migrate.
+
+#. Click the Migrate Instance button. |Migrateinstance.png|
+
+#. From the list of suitable hosts, choose the one to which you want to
+   move the VM.
+
+   .. 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.
+
+#. Click OK.
+
+.. note:: 
+      (KVM) If the VM's storage has to be migrated along with the VM, from a 
mounted NFS storage pool to a cluster-wide mounted NFS storage pool, then the 
'migrateVirtualMachineWithVolume' API has to be used. There is no UI 
integration for this feature.
+
+      (CloudMonkey) > migrate virtualmachinewithvolume 
virtualmachineid=<virtual machine uuid> hostid=<destination host uuid> 
migrateto[i].volume=<virtual machine volume number i uuid> 
migrateto[i].pool=<destination storage pool uuid for volume number i>
+
+      where i in [0,..,N] and N = number of volumes of the virtual machine
+
+
+
+Assigning VMs to Hosts
+----------------------
+
+At any point in time, each virtual machine instance is running on a
+single host. How does CloudStack determine which host to place a VM on?
+There are several ways:
+
+-  Automatic default host allocation. CloudStack can automatically pick
+   the most appropriate host to run each virtual machine.
+
+-  Instance type preferences. CloudStack administrators can specify that
+   certain hosts should have a preference for particular types of guest
+   instances. For example, an administrator could state that a host
+   should have a preference to run Windows guests. The default host
+   allocator will attempt to place guests of that OS type on such hosts
+   first. If no such host is available, the allocator will place the
+   instance wherever there is sufficient physical capacity.
+
+-  Vertical and horizontal allocation. Vertical allocation consumes all
+   the resources of a given host before allocating any guests on a
+   second host. This reduces power consumption in the cloud. Horizontal
+   allocation places a guest on each host in a round-robin fashion. This
+   may yield better performance to the guests in some cases.
+
+-  Admin users preferences. Administrators have the option to specify a
+   pod, cluster, or host to run the VM in. CloudStack will then select
+   a host within the given infrastructure.
+
+-  End user preferences. Users can not control exactly which host will
+   run a given VM instance, but they can specify a zone for the VM.
+   CloudStack is then restricted to allocating the VM only to one of the
+   hosts in that zone.
+
+-  Host tags. The administrator can assign tags to hosts. These tags can
+   be used to specify which host a VM should use. The CloudStack
+   administrator decides whether to define host tags, then create a
+   service offering using those tags and offer it to the user.
+
+-  Affinity groups. By defining affinity groups and assigning VMs to
+   them, the user or administrator can influence (but not dictate) which
+   VMs should run on separate hosts. This feature is to let users
+   specify that certain VMs won't be on the same host.
+
+-  CloudStack also provides a pluggable interface for adding new
+   allocators. These custom allocators can provide any policy the
+   administrator desires.
+
+
+Affinity Groups
+~~~~~~~~~~~~~~~
+
+By defining affinity groups and assigning VMs to them, the user or
+administrator can influence (but not dictate) which VMs should run on
+separate hosts. This feature is to let users specify that VMs with the
+same “host anti-affinity” type won’t be on the same host. This serves to
+increase fault tolerance. If a host fails, another VM offering the same
+service (for example, hosting the user's website) is still up and
+running on another host.
+
+The scope of an affinity group is per user account.
+
+
+Creating a New Affinity Group
+'''''''''''''''''''''''''''''
+
+To add an affinity group:
+
+#. Log in to the CloudStack UI as an administrator or user.
+
+#. In the left navigation bar, click Affinity Groups.
+
+#. Click Add affinity group. In the dialog box, fill in the following
+   fields:
+
+   -  Name. Give the group a name.
+
+   -  Description. Any desired text to tell more about the purpose of
+      the group.
+
+   -  Type. The only supported type shipped with CloudStack is Host
+      Anti-Affinity. This indicates that the VMs in this group should
+      avoid being placed on the same host with each other. If you see
+      other types in this list, it means that your installation of
+      CloudStack has been extended with customized affinity group
+      plugins.
+
+
+Assign a New VM to an Affinity Group
+''''''''''''''''''''''''''''''''''''
+
+To assign a new VM to an affinity group:
+
+-  Create the VM as usual, as described in `“Creating
+   VMs” <virtual_machines.html#creating-vms>`_. In the Add Instance 
+   wizard, there is a new Affinity tab where you can select the 
+   affinity group.
+
+
+Change Affinity Group for an Existing VM
+''''''''''''''''''''''''''''''''''''''''
 
-#. Log in to the CloudStack UI as a user or admin.
+To assign an existing VM to an affinity group:
 
-#. In the left navigation, click Instances.
+#. Log in to the CloudStack UI as an administrator or user.
 
-#. Choose the VM that you want to migrate.
+#. In the left navigation bar, click Instances.
 
-#. Click the Migrate Instance button. |Migrateinstance.png|
+#. Click the name of the VM you want to work with.
 
-#. From the list of suitable hosts, choose the one to which you want to
-   move the VM.
+#. Stop the VM by clicking the Stop button.
 
-   .. 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.
+#. Click the Change Affinity button. |change-affinity-button.png|
 
-#. Click OK.
 
-.. note:: 
-      (KVM) If the VM's storage has to be migrated along with the VM, from a 
mounted NFS storage pool to a cluster-wide mounted NFS storage pool, then the 
'migrateVirtualMachineWithVolume' API has to be used. There is no UI 
integration for this feature.
+View Members of an Affinity Group
+'''''''''''''''''''''''''''''''''
 
-      (CloudMonkey) > migrate virtualmachinewithvolume 
virtualmachineid=<virtual machine uuid> hostid=<destination host uuid> 
migrateto[i].volume=<virtual machine volume number i uuid> 
migrateto[i].pool=<destination storage pool uuid for volume number i>
+To see which VMs are currently assigned to a particular affinity group:
 
-      where i in [0,..,N] and N = number of volumes of the virtual machine
+#. In the left navigation bar, click Affinity Groups.
 
+#. Click the name of the group you are interested in.
 
-Deleting VMs
-------------
+#. Click View Instances. The members of the group are listed.
 
-Users can delete their own virtual machines. A running virtual machine
-will be abruptly stopped before it is deleted. Administrators can delete
-any virtual machines.
+   From here, you can click the name of any VM in the list to access all
+   its details and controls.
 
-To delete a virtual machine:
 
-#. Log in to the CloudStack UI as a user or admin.
+Delete an Affinity Group
+''''''''''''''''''''''''
 
-#. In the left navigation, click Instances.
+To delete an affinity group:
 
-#. Choose the VM that you want to delete.
+#. In the left navigation bar, click Affinity Groups.
 
-#. Click the Destroy Instance button. |Destroyinstance.png|
+#. Click the name of the group you are interested in.
 
-#. Optionally both expunging and the deletion of any attached volumes can be 
enabled.
+#. Click Delete.
+
+   Any VM that is a member of the affinity group will be disassociated
+   from the group. The former group members will continue to run
+   normally on the current hosts, but if the VM is restarted, it will no
+   longer follow the host allocation rules from its former affinity
+   group.
 
 
-Working with ISOs
------------------
+Changing a VM's Base Image
+--------------------------
 
-CloudStack supports ISOs and their attachment to guest VMs. An ISO is a
-read-only file that has an ISO/CD-ROM style file system. Users can
-upload their own ISOs and mount them on their guest VMs.
+Every VM is created from a base image, which is a template or ISO which
+has been created and stored in CloudStack. Both cloud administrators and
+end users can create and modify templates, ISOs, and VMs.
 
-ISOs are uploaded based on a URL. HTTP is the supported protocol. Once
-the ISO is available via HTTP specify an upload URL such as
-http://my.web.server/filename.iso.
+In CloudStack, you can change an existing VM's base image from one
+template to another, or from one ISO to another. (You can not change
+from an ISO to a template, or from a template to an ISO).
 
-ISOs may be public or private, like templates.ISOs are not
-hypervisor-specific. That is, a guest on vSphere can mount the exact
-same image that a guest on KVM can mount.
+For example, suppose there is a template based on a particular operating
+system, and the OS vendor releases a software patch. The administrator
+or user naturally wants to apply the patch and then make sure existing
+VMs start using it. Whether a software update is involved or not, it's
+also possible to simply switch a VM from its current template to any
+other desired template.
 
-ISO images may be stored in the system and made available with a privacy
-level similar to templates. ISO images are classified as either bootable
-or not bootable. A bootable ISO image is one that contains an OS image.
-CloudStack allows a user to boot a guest VM off of an ISO image. Users
-can also attach ISO images to guest VMs. For example, this enables
-installing PV drivers into Windows. ISO images are not
-hypervisor-specific.
+To change a VM's base image, call the restoreVirtualMachine API command
+and pass in the virtual machine ID and a new template ID. The template
+ID parameter may refer to either a template or an ISO, depending on
+which type of base image the VM was already using (it must match the
+previous type of image). When this call occurs, the VM's root disk is
+first destroyed, then a new root disk is created from the source
+designated in the template ID parameter. The new root disk is attached
+to the VM, and now the VM is based on the new template.
 
+You can also omit the template ID parameter from the
+restoreVirtualMachine call. In this case, the VM's root disk is
+destroyed and recreated, but from the same template or ISO that was
+already in use by the VM.
 
-Adding an ISO
-~~~~~~~~~~~~~
 
-To make additional operating system or other software available for use
-with guest VMs, you can add an ISO. The ISO is typically thought of as
-an operating system image, but you can also add ISOs for other types of
-software, such as desktop applications that you want to be installed as
-part of a template.
+Advanced VM Instance Settings
+-----------------------------
 
-#. Log in to the CloudStack UI as an administrator or end user.
+Each user VM has a set of "details" associated with it (as visible via 
listVirtualMachine API call) - those "details" are shown on the "Settings" tab 
of the VM in the GUI (words "setting(s)" and "detail(s)" are here used 
interchangeably). 
 
-#. In the left navigation bar, click Templates.
+The Settings tab is always present/visible, but settings can be changed only 
when the VM is in a Stopped state. 
+Some VM details/settings can be hidden via "user.vm.blacklisted.details" 
global setting (you can find below the list of those hidden by default).
 
-#. In Select View, choose ISOs.
+When adding a new setting or modifying the existing ones, setting names are 
shown/offered in a drop-down list, as well as their possible values (with the 
exception of boolean or numerical values).
 
-#. Click Add ISO.
+Read-only details/settings that are hidden by default:
 
-#. In the Add ISO screen, provide the following:
+- rootdisksize
+- cpuOvercommitRatio 
+- memoryOvercommitRatio 
+- Message.ReservedCapacityFreed.Flag
 
-   -  **Name**: Short name for the ISO image. For example, CentOS 6.2
-      64-bit.
+An example list of settings as well as their possible values are shown on the 
images below:
 
-   -  **Description**: Display test for the ISO image. For example,
-      CentOS 6.2 64-bit.
+|vm-settings-dropdown-list.PNG|
+(VMware hypervisor)
 
-   -  **URL**: The URL that hosts the ISO image. The Management Server
-      must be able to access this location via HTTP. If needed you can
-      place the ISO image directly on the Management Server
+|vm-settings-values-dropdown-list.PNG|
+(VMware disk controllers)
 
-   -  **Zone**: Choose the zone where you want the ISO to be available,
-      or All Zones to make it available throughout CloudStack.
+|vm-settings-values1-dropdown-list.PNG|
+(VMware NIC models)
 
-   -  **Bootable**: Whether or not a guest could boot off this ISO
-      image. For example, a CentOS ISO is bootable, a Microsoft Office
-      ISO is not bootable.
+|vm-settings-values-dropdown-KVM-list.PNG|
+(KVM disk controllers)
 
-   -  **OS Type**: This helps CloudStack and the hypervisor perform
-      certain operations and make assumptions that improve the
-      performance of the guest. Select one of the following.
 
-      -  If the operating system of your desired ISO image is listed,
-         choose it.
+Virtual Machine Snapshots
+=========================
 
-      -  If the OS Type of the ISO is not listed or if the ISO is not
-         bootable, choose Other.
+(Supported on VMware, XenServer and KVM (NFS only))
 
-      -  (XenServer only) If you want to boot from this ISO in PV mode,
-         choose Other PV (32-bit) or Other PV (64-bit)
+In addition to the existing CloudStack ability to snapshot individual VM
+volumes, you can take a VM snapshot to preserve all the VM's data
+volumes as well as (optionally) its CPU/memory state. This is useful for
+quick restore of a VM. For example, you can snapshot a VM, then make
+changes such as software upgrades. If anything goes wrong, simply
+restore the VM to its previous state using the previously saved VM
+snapshot.
 
-      -  (KVM only) If you choose an OS that is PV-enabled, the VMs
-         created from this ISO will have a SCSI (virtio) root disk. If
-         the OS is not PV-enabled, the VMs will have an IDE root disk.
-         The PV-enabled types are:
+The snapshot is created using the hypervisor's native snapshot facility.
+The VM snapshot includes not only the data volumes, but optionally also
+whether the VM is running or turned off (CPU state) and the memory
+contents. The snapshot is stored in CloudStack's primary storage.
 
-         -  Fedora 13
+VM snapshots can have a parent/child relationship. Each successive
+snapshot of the same VM is the child of the snapshot that came before
+it. Each time you take an additional snapshot of the same VM, it saves
+only the differences between the current state of the VM and the state
+stored in the most recent previous snapshot. The previous snapshot
+becomes a parent, and the new snapshot is its child. It is possible to
+create a long chain of these parent/child snapshots, which amount to a
+"redo" record leading from the current state of the VM back to the
+original.
 
-         -  Fedora 12
+After VM snapshots are created, they can be tagged with a key/value pair,
+like many other resources in CloudStack.
 
-         -  Fedora 11
+KVM supports VM snapshots when using NFS shared storage. If raw block storage
+is used (i.e. Ceph), then VM snapshots are not possible, since there is no 
possibility
+to write RAM memory content anywhere.
 
-         -  Fedora 10
+If you need more information about VM snapshots on VMware, check out the
+VMware documentation and the VMware Knowledge Base, especially
+`Understanding virtual machine snapshots 
+<http://kb.vmware.com/selfservice/microsites/search.do?cmd=displayKC&externalId=1015180>`_.
 
-         -  Fedora 9
 
-         -  Other PV
+Limitations on VM Snapshots
+---------------------------
 
-         -  Debian GNU/Linux
+-  If a VM has some stored snapshots, you can't attach new volume to the
+   VM or delete any existing volumes. If you change the volumes on the
+   VM, it would become impossible to restore the VM snapshot which was
+   created with the previous volume structure. If you want to attach a
+   volume to such a VM, first delete its snapshots.
 
-         -  CentOS 5.3
+-  VM snapshots which include both data volumes and memory can't be kept
+   if you change the VM's service offering. Any existing VM snapshots of
+   this type will be discarded.
 
-         -  CentOS 5.4
+-  You can't make a VM snapshot at the same time as you are taking a
+   volume snapshot.
 
-         -  CentOS 5.5
+-  You should use only CloudStack to create VM snapshots on hosts
+   managed by CloudStack. Any snapshots that you make directly on the
+   hypervisor will not be tracked in CloudStack.
 
-         -  Red Hat Enterprise Linux 5.3
 
-         -  Red Hat Enterprise Linux 5.4
+Configuring VM Snapshots
+------------------------
 
-         -  Red Hat Enterprise Linux 5.5
+The cloud administrator can use global configuration variables to
+control the behavior of VM snapshots. To set these variables, go through
+the Global Settings area of the CloudStack UI.
 
-         -  Red Hat Enterprise Linux 6
+.. cssclass:: table-striped table-bordered table-hover
 
-      .. note:: 
-         It is not recommended to choose an older version of the OS than 
-         the version in the image. For example, choosing CentOS 5.4 to 
-         support a CentOS 6.2 image will usually not work. In these 
-         cases, choose Other.
+====================== ========================
+Configuration          Description       Type
+====================== ========================
+vmsnapshots.max        The maximum number of VM snapshots that can be saved 
for any given virtual machine in the cloud. The total possible number of VM 
snapshots in the cloud is (number of VMs) \* vmsnapshots.max. If the number of 
snapshots for any VM ever hits the maximum, the older ones are removed by the 
snapshot expunge job
+vmsnapshot.create.wait Number of seconds to wait for a snapshot job to succeed 
before declaring failure and issuing an error.
+====================== ========================
 
-   -  **Extractable**: Choose Yes if the ISO should be available for
-      extraction.
 
-   -  **Public**: Choose Yes if this ISO should be available to other
-      users.
+Using VM Snapshots
+------------------
 
-   -  **Featured**: Choose Yes if you would like this ISO to be more
-      prominent for users to select. The ISO will appear in the Featured
-      ISOs list. Only an administrator can make an ISO Featured.
+To create a VM snapshot using the CloudStack UI:
 
-#. Click OK.
+#. Log in to the CloudStack UI as a user or administrator.
 
-   The Management Server will download the ISO. Depending on the size of
-   the ISO, this may take a long time. The ISO status column will
-   display Ready once it has been successfully downloaded into secondary
-   storage. Clicking Refresh updates the download percentage.
+#. Click Instances.
 
-#. **Important**: Wait for the ISO to finish downloading. If you move on
-   to the next task and try to use the ISO right away, it will appear to
-   fail. The entire ISO must be available before CloudStack can work
-   with it.
+#. Click the name of the VM you want to snapshot.
 
+#. Click the Take VM Snapshot button. |VMSnapshotButton.png|
 
-Attaching an ISO to a VM
-~~~~~~~~~~~~~~~~~~~~~~~~
+   .. note:: 
+      If a snapshot is already in progress, then clicking this button 
+      will have no effect.
 
-#. In the left navigation, click Instances.
+#. Provide a name and description. These will be displayed in the VM
+   Snapshots list.
 
-#. Choose the virtual machine you want to work with.
+#. (For running VMs only) If you want to include the VM's memory in the
+   snapshot, click the Memory checkbox. This saves the CPU and memory
+   state of the virtual machine. If you don't check this box, then only
+   the current state of the VM disk is saved. Checking this box makes
+   the snapshot take longer.
 
-#. Click the Attach ISO button. |iso.png|
+#. Quiesce VM: check this box if you want to quiesce the file system on
+   the VM before taking the snapshot. Not supported on XenServer when
+   used with CloudStack-provided primary storage.
 
-#. In the Attach ISO dialog box, select the desired ISO.
+   When this option is used with CloudStack-provided primary storage,
+   the quiesce operation is performed by the underlying hypervisor
+   (VMware is supported). When used with another primary storage
+   vendor's plugin, the quiesce operation is provided according to the
+   vendor's implementation.
 
 #. Click OK.
 
+To delete a snapshot or restore a VM to the state saved in a particular
+snapshot:
 
-Changing a VM's Base Image
-~~~~~~~~~~~~~~~~~~~~~~~~~~
+#. Navigate to the VM as described in the earlier steps.
 
-Every VM is created from a base image, which is a template or ISO which
-has been created and stored in CloudStack. Both cloud administrators and
-end users can create and modify templates, ISOs, and VMs.
+#. Click View VM Snapshots.
 
-In CloudStack, you can change an existing VM's base image from one
-template to another, or from one ISO to another. (You can not change
-from an ISO to a template, or from a template to an ISO).
+#. In the list of snapshots, click the name of the snapshot you want to
+   work with.
 
-For example, suppose there is a template based on a particular operating
-system, and the OS vendor releases a software patch. The administrator
-or user naturally wants to apply the patch and then make sure existing
-VMs start using it. Whether a software update is involved or not, it's
-also possible to simply switch a VM from its current template to any
-other desired template.
+#. Depending on what you want to do:
 
-To change a VM's base image, call the restoreVirtualMachine API command
-and pass in the virtual machine ID and a new template ID. The template
-ID parameter may refer to either a template or an ISO, depending on
-which type of base image the VM was already using (it must match the
-previous type of image). When this call occurs, the VM's root disk is
-first destroyed, then a new root disk is created from the source
-designated in the template ID parameter. The new root disk is attached
-to the VM, and now the VM is based on the new template.
+   To delete the snapshot, click the Delete button. |delete-button.png|
 
-You can also omit the template ID parameter from the
-restoreVirtualMachine call. In this case, the VM's root disk is
-destroyed and recreated, but from the same template or ISO that was
-already in use by the VM.
+   To revert to the snapshot, click the Revert button. |revert-vm.png|
+
+.. note:: 
+   VM snapshots are deleted automatically when a VM is destroyed. You don't 
+   have to manually delete the snapshots in this case.
+
+
+Virtual Machine Backups (Backup and Recovery Feature)
+=====================================================
 
+.. include:: backup_and_recovery.rst
 
 Using SSH Keys for Authentication
----------------------------------
+=================================
 
 In addition to the username and password authentication, CloudStack
 supports using SSH keys to log in to the cloud infrastructure for
@@ -1040,7 +933,7 @@ files. Using a single SSH key pair, you can manage 
multiple instances.
 
 
 Creating an Instance Template that Supports SSH Keys
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+----------------------------------------------------
 
 Create an instance template that supports SSH Keys.
 
@@ -1078,7 +971,7 @@ Create an instance template that supports SSH Keys.
 
 
 Creating the SSH Keypair
-~~~~~~~~~~~~~~~~~~~~~~~~
+------------------------
 
 You must make a call to the createSSHKeyPair api method. You can either
 use the CloudStack Python API library or the curl commands to make the
@@ -1137,7 +1030,7 @@ keypair called "keypair-doc" for the admin account in the 
root domain:
 
 
 Creating an Instance
-~~~~~~~~~~~~~~~~~~~~
+--------------------
 
 After you save the SSH keypair file, you must create an instance by
 using the template that you created at `Section 5.2.1, “ Creating an
@@ -1161,7 +1054,7 @@ environment.
 
 
 Logging In Using the SSH Keypair
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+---------------------------------
 
 To test your SSH key generation is successful, check whether you can log
 in to the cloud setup.
@@ -1177,7 +1070,7 @@ The -i parameter tells the ssh client to use a ssh key 
found at
 
 
 Resetting SSH Keys
-~~~~~~~~~~~~~~~~~~
+------------------
 
 With the API command resetSSHKeyForVirtualMachine, a user can set or
 reset the SSH keypair assigned to a virtual machine. A lost or
@@ -1189,7 +1082,7 @@ call resetSSHKeyForVirtualMachine.
 
 
 Assigning GPU/vGPU to Guest VMs
--------------------------------
+===============================
 
 CloudStack can deploy guest VMs with Graphics Processing Unit (GPU) or Virtual
 Graphics Processing Unit (vGPU) capabilities on XenServer hosts. At the time of
@@ -1243,7 +1136,7 @@ CloudStack provides you with the following capabilities:
   in case of GRID cards, and capacity of the cards.
 
 Prerequisites and System Requirements
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+-------------------------------------
 
 Before proceeding, ensure that you have these prerequisites:
 
@@ -1292,7 +1185,7 @@ Before continuing with configuration, consider the 
following:
 - Notification thresholds for GPU resource is not supported.
 
 Supported GPU Devices
-~~~~~~~~~~~~~~~~~~~~~
+---------------------
 
 .. cssclass:: table-striped table-bordered table-hover
 
@@ -1312,7 +1205,7 @@ vGPU        - GRID K100
 =========== ========================
 
 GPU/vGPU Assignment Workflow
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+-----------------------------
 
 
 CloudStack follows the below sequence of operations to provide GPU/vGPU 
support for VMs:
@@ -1345,43 +1238,9 @@ CloudStack follows the below sequence of operations to 
provide GPU/vGPU support
     
       GPU resources are released automatically when you stop a VM. Once the 
destroy VM is successful, CloudStack will make a resource call to the host to 
get the remaining GPU capacity in the card and update the database accordingly.
 
-   
-  
-VM Instance Settings
-~~~~~~~~~~~~~~~~~~~~
-
-Each user VM has a set of "details" associated with it (as visible via 
listVirtualMachine API call) - those "details" are shown on the "Settings" tab 
of the VM in the GUI (words "setting(s)" and "detail(s)" are here used 
interchangeably). 
-
-The Settings tab is always present/visible, but settings can be changed only 
when the VM is in a Stopped state. 
-Some VM details/settings can be hidden via "user.vm.blacklisted.details" 
global setting (you can find below the list of those hidden by default).
-
-When adding a new setting or modifying the existing ones, setting names are 
shown/offered in a drop-down list, as well as their possible values (with the 
exception of boolean or numerical values).
-
-Read-only details/settings that are hidden by default:
-
-- rootdisksize
-- cpuOvercommitRatio 
-- memoryOvercommitRatio 
-- Message.ReservedCapacityFreed.Flag
-
-An example list of settings as well as their possible values are shown on the 
images below:
-
-|vm-settings-dropdown-list.PNG|
-(VMware hypervisor)
-
-|vm-settings-values-dropdown-list.PNG|
-(VMware disk controllers)
-
-|vm-settings-values1-dropdown-list.PNG|
-(VMware NIC models)
-
-|vm-settings-values-dropdown-KVM-list.PNG|
-(KVM disk controllers)
-
-
-    
-.. |basic-deployment.png| image:: /_static/images/basic-deployment.png
-   :alt: Basic two-machine CloudStack deployment
+       
+.. |vm-lifecycle.png| image:: /_static/images/vm-lifecycle.png
+   :alt: Virtual Machine State Model
 .. |VMSnapshotButton.png| image:: /_static/images/VMSnapshotButton.png
    :alt: button to restart a VPC
 .. |delete-button.png| image:: /_static/images/delete-button.png

Reply via email to