Merge release branch 4.19 to main

* 4.19:
  notes on POD-subnets (#391)
  Documentation for checkVolume API (#380)
  Document advance DRS settings (#374)
  veeam: update API commands and versions in doc (#357)
  Update virtual_machines.rst (#353)

source/adminguide/backup_and_recovery.rst

@@ -98,7 +98,7 @@ 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
+- **importBackupOffering**: 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
 
@@ -168,10 +168,10 @@ Supported APIs:
 - **listBackupSchedule**: returns backup schedule of an Instance if defined.
 - **deleteBackupSchedule**: deletes backup schedule of an Instance.
 - **createBackup**: creates an adhoc backup for an Instance.
-- **deleteVMBackup**: deletes an Instance backup (not support for per restore point for Veeam).
+- **deleteBackup**: deletes an Instance backup (not support for per restore point for Veeam).
 - **listBackups**: lists backups.
 - **restoreBackup**: restore a previous Instance backup in-place of a stopped or destroyed Instance.
-- **restoreVolumeFromBackup**: restore and attach a backed-up volume (of an Instance backup) to a specified Instance.
+- **restoreVolumeFromBackupAndAttachToVM**: restore and attach a backed-up volume (of an Instance backup) to a specified Instance.
 
 
 .. |B&R-assignOffering.png| image:: /_static/images/B&R-assignOffering.png

source/adminguide/clusters.rst

@@ -74,6 +74,30 @@ Following are the configuration parameters for DRS.
    Very high value for ``drs.max.migrations`` can result in management server using up all of it's workers for DRS tasks
    and not being able to execute other tasks.
 
+There are some advanced parameters that can be configured for DRS. These parameters impact the way imbalance is calculated
+for a cluster. Do not change these parameters unless you know what you are doing.
+
+.. list-table:: Advanced DRS related cluster parameters
+   :header-rows: 1
+
+   * - Parameter
+     - Default
+     - Description
+   * - ``drs.metric.type``
+     - `used`
+     - The metric type used to measure imbalance in a cluster. This can completely change the imbalance value. 
+       Possible values are free, used.
+   * - ``drs.metric.use.ratio``
+     - `true`
+     - Whether to use ratio of selected metric & total. Useful when the cluster has hosts with different capacities.
+   * - ``drs.imbalance.condensed.skip.threshold``
+     - `0.95`
+     - Threshold to ignore the metric for a host while calculating the imbalance to decide whether DRS is required for 
+       a cluster. This is to avoid cases when the calculated imbalance gets skewed due to a single host having a very 
+       high/low metric value resulting in imbalance being higher than 1. If ``drs.metric.type`` is ``free``, set a lower 
+       value and if it is ``used`` set a higher value. The value should be between `0.0` and `1.0`. 
+       This is applicable only for Condensed algorithm.
+
 Executing manual DRS on a cluster
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 DRS can also be manually executed for a cluster.

source/adminguide/storage.rst

@@ -962,6 +962,54 @@ Bytes read/write, as well as the total IO/s, are exposed via UI, as shown in the
 These statistics are obtained from the hypervisor directly and they represent
 "current" bytes/s and IO/s values at the time of collection.
 
+Check and repair Volume
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+When there are any leaks or any inconsistencies in the volume, then the checkVolume API can be used to
+check for any such errors in the volume and helps in repairing them. This feature is currently available only
+for KVM and volumes with QCOW2 format. This API uses "qemu-img check" command on the KVM host.
+
+Also, a global or storage pool level setting "volume.check.and.repair.leaks.before.use" is available which allows
+to check and repair any leaks of the volume during instance start and volume attach operations.
+This will help in repairing any leaks of the volume before using it. This is a blocking operation, meaning
+instance start or volume attach will be performed only after the check and repair operation is completed.
+The setting helps in defining whether to allow this operation or not.
+
+checkVolume API takes two parameters as input
+
+-  "id" for the volume UUID
+
+-  "repair" an optional parameter whether to repair the volume or not. Parameter takes "leaks" or "all" as the input.
+
+Following is the example for checkVolume API usage and the result in the volume response.
+
+.. code:: bash
+
+   [root@mgmt]# cmk check volume id=55937826-2f08-414a-9eef-4c6b7d6fd3b1 repair=leaks
+   {
+   .
+   .
+   "volumecheckresult": {
+   "allocated-clusters": "110",
+   "check-errors": "0",
+   "leaks": 73,
+   "filename": "/mnt/e72364b6-eab0-369f-af0b-2ec8bed9d8ac/55937826-2f08-414a-9eef-4c6b7d6fd3b1",
+   "format": "qcow2",
+   "fragmented-clusters": "32",
+   "image-end-offset": "7995392",
+   "total-clusters": "131072"
+   },
+   "volumerepairresult": {
+   "allocated-clusters": "110",
+   "check-errors": "0",
+   "leaks-fixed": 73,
+   "filename": "/mnt/e72364b6-eab0-369f-af0b-2ec8bed9d8ac/55937826-2f08-414a-9eef-4c6b7d6fd3b1",
+   "format": "qcow2",
+   "fragmented-clusters": "32",
+   "image-end-offset": "7995392",
+   "total-clusters": "131072"
+   },
+   }
 
 Working with Volume Snapshots
 -----------------------------

source/adminguide/veeam_plugin.rst

@@ -47,7 +47,7 @@ There are a couple of important concepts to understand before working with the V
 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
+The B&R Veeam plugin has been tested against Veeam Backup and Recovery 11 and 12.  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).
@@ -58,7 +58,7 @@ and Replication, however please read the steps below carefully to ensure that yo
 compatibility with the B&R Veeam plug-in.
 
 
-#. Install Backup and Replication 9.5 Manager - inc console - default settings
+#. Install Backup and Replication 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.
@@ -126,15 +126,18 @@ Plug-in specific settings:
 
 .. 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
-==================================== ========================
+======================================= ========================
+Configuration                            Description
+======================================= ========================
+backup.plugin.veeam.url                 Veeam B&R server URL. Default: http://<VEEAM_SERVER_IP>:9398/api/
+backup.plugin.veeam.version             Veeam B&R server version. CloudStack will get Veeam server version via PowerShell commands if it is 0 or not set
+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
+backup.plugin.veeam.task.poll.interval  The time interval in seconds when the management server polls for Veeam task status. Default: 5
+backup.plugin.veeam.task.poll.max.retry The max number of retrying times when the management server polls for Veeam task status. Default: 120
+======================================= ========================
 
 
 .. |BnR-DummyTagCategory.jpg| image:: /_static/images/BnR-DummyTagCategory.jpg

source/installguide/configuration.rst

@@ -407,6 +407,9 @@ Basic Zone Configuration
 #. In a new zone, CloudStack adds the first pod for you. You can always
    add more pods later. For an overview of what a pod is, see :ref:`about-pods`
 
+.. note::
+   The network described below must be a subnet of the physical network marked as type "management".
+
    To configure the first pod, enter the following, then click Next:
 
    -  **Pod Name.** A name for the pod.
@@ -602,6 +605,9 @@ Core Zone
 #. In a new zone, CloudStack adds the first pod for you. You can always
    add more pods later. For an overview of what a pod is, see :ref:`about-pods`
 
+.. note::
+   The network described below must be a subnet of the physical network marked as type "management".
+
    To configure the first pod, enter the following, then click Next:
 
    -  **Pod Name.** (Obligatory) A name for the pod.
@@ -850,6 +856,9 @@ can add more pods at any time using the procedure in this section.
       Secondary Storage VMs, Console Proxy VMs, and DHCP. For more
       information, see System Reserved IP Addresses.
 
+.. note::
+   * The network described above must be a subnet of the management network.
+
 #. Click OK.
 
 

source/quickinstallationguide/qig.rst

@@ -730,6 +730,9 @@ will assign IPs from this range to system VMs. This will also be part of our loc
 
 #. End Reserved system IP - we will use ``172.16.10.30`` # (or e.g. 192.168.1.30)
 
+.. note::
+   * The network described above must be a subnet of the management network.
+
 Click "Next" to continue.
 
 Guest Traffic