Adding upstream version 18.2.2.upstream/18.2.2

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 235 insertions, 0 deletions

diff --git a/doc/rbd/rbd-windows.rst b/doc/rbd/rbd-windows.rst
new file mode 100644
index 000000000..df4bd172e
--- /dev/null
+++ b/doc/rbd/rbd-windows.rst
@@ -0,0 +1,235 @@
+==============
+RBD on Windows
+==============
+
+The ``rbd`` command can be used to create, remove, import, export, map or
+unmap images exactly like it would on Linux. Make sure to check the
+`RBD basic commands`_ guide.
+
+``librbd.dll`` is also available for applications that can natively use Ceph.
+
+Please check the `installation guide`_ to get started.
+
+Windows service
+===============
+On Windows, ``rbd-wnbd`` daemons are managed by a centralized service. This allows
+decoupling the daemons from the Windows session from which they originate. At
+the same time, the service is responsible of recreating persistent mappings,
+usually when the host boots.
+
+Note that only one such service may run per host.
+
+By default, all image mappings are persistent. Non-persistent mappings can be
+requested using the ``-onon-persistent`` ``rbd`` flag.
+
+Persistent mappings are recreated when the service starts, unless explicitly
+unmapped. The service disconnects the mappings when being stopped. This also
+allows adjusting the Windows service start order so that RBD images can be
+mapped before starting services that may depend on it, such as VMMS.
+
+In order to be able to reconnect the images, ``rbd-wnbd`` stores mapping
+information in the Windows registry at the following location:
+``SYSTEM\CurrentControlSet\Services\rbd-wnbd``.
+
+The following command can be used to configure the service. Please update
+the ``rbd-wnbd.exe`` path accordingly::
+
+    New-Service -Name "ceph-rbd" `
+                -Description "Ceph RBD Mapping Service" `
+                -BinaryPathName "c:\ceph\rbd-wnbd.exe service" `
+                -StartupType Automatic
+
+Note that the Ceph MSI installer takes care of creating the ``ceph-rbd``
+Windows service.
+
+Usage
+=====
+
+Integration
+-----------
+
+RBD images can be exposed to the OS and host Windows partitions or they can be
+attached to Hyper-V VMs in the same way as iSCSI disks.
+
+Starting with Openstack Wallaby, the Nova Hyper-V driver can attach RBD Cinder
+volumes to Hyper-V VMs.
+
+Mapping images
+--------------
+
+The workflow and CLI is similar to the Linux counterpart, with a few
+notable differences:
+
+* device paths cannot be requested. The disk number and path will be picked by
+  Windows. If a device path is provided by the used when mapping an image, it
+  will be used as an identifier, which can also be used when unmapping the
+  image.
+* the ``show`` command was added, which describes a specific mapping.
+  This can be used for retrieving the disk path.
+* the ``service`` command was added, allowing ``rbd-wnbd`` to run as a Windows service.
+  All mappings are by default persistent, being recreated when the service
+  stops, unless explicitly unmapped. The service disconnects the mappings
+  when being stopped.
+* the ``list`` command also includes a ``status`` column.
+
+The purpose of the ``service`` mode is to ensure that mappings survive reboots
+and that the Windows service start order can be adjusted so that RBD images can
+be mapped before starting services that may depend on it, such as VMMS.
+
+The mapped images can either be consumed by the host directly or exposed to
+Hyper-V VMs.
+
+Hyper-V VM disks
+----------------
+
+The following sample imports an RBD image and boots a Hyper-V VM using it::
+
+    # Feel free to use any other image. This one is convenient to use for
+    # testing purposes because it's very small (~15MB) and the login prompt
+    # prints the pre-configured password.
+    wget http://download.cirros-cloud.net/0.5.1/cirros-0.5.1-x86_64-disk.img `
+         -OutFile cirros-0.5.1-x86_64-disk.img
+
+    # We'll need to make sure that the imported images are raw (so no qcow2 or vhdx).
+    # You may get qemu-img from https://cloudbase.it/qemu-img-windows/
+    # You can add the extracted location to $env:Path or update the path accordingly.
+    qemu-img convert -O raw cirros-0.5.1-x86_64-disk.img cirros-0.5.1-x86_64-disk.raw
+
+    rbd import cirros-0.5.1-x86_64-disk.raw
+    # Let's give it a hefty 100MB size.
+    rbd resize cirros-0.5.1-x86_64-disk.raw --size=100MB
+
+    rbd device map cirros-0.5.1-x86_64-disk.raw
+
+    # Let's have a look at the mappings.
+    rbd device list
+    Get-Disk
+
+    $mappingJson = rbd-wnbd show cirros-0.5.1-x86_64-disk.raw --format=json
+    $mappingJson = $mappingJson | ConvertFrom-Json
+
+    $diskNumber = $mappingJson.disk_number
+
+    New-VM -VMName BootFromRBD -MemoryStartupBytes 512MB
+    # The disk must be turned offline before it can be passed to Hyper-V VMs
+    Set-Disk -Number $diskNumber -IsOffline $true
+    Add-VMHardDiskDrive -VMName BootFromRBD -DiskNumber $diskNumber
+    Start-VM -VMName BootFromRBD
+
+Windows partitions
+------------------
+
+The following sample creates an empty RBD image, attaches it to the host and
+initializes a partition::
+
+    rbd create blank_image --size=1G
+    rbd device map blank_image -onon-persistent
+
+    $mappingJson = rbd-wnbd show blank_image --format=json
+    $mappingJson = $mappingJson | ConvertFrom-Json
+
+    $diskNumber = $mappingJson.disk_number
+
+    # The disk must be online before creating or accessing partitions.
+    Set-Disk -Number $diskNumber -IsOffline $false
+
+    # Initialize the disk, partition it and create a filesystem.
+    Get-Disk -Number $diskNumber | `
+        Initialize-Disk -PassThru | `
+        New-Partition -AssignDriveLetter -UseMaximumSize | `
+        Format-Volume -Force -Confirm:$false
+
+    # Show the partition letter (for example, "D:" or "F:"):
+    (Get-Partition -DiskNumber $diskNumber).DriveLetter
+
+SAN policy
+----------
+
+The Windows SAN policy determines which disks will be automatically mounted.
+The default policy (``offlineShared``) specifies that:
+
+  All newly discovered disks that do not reside on a shared bus (such as SCSI
+  and iSCSI) are brought online and made read-write. Disks that are left
+  offline will be read-only by default."
+
+Note that recent WNBD driver versions report rbd-wnbd disks as SAS, which is
+also considered a shared bus. As a result, the disks will be offline and
+read-only by default.
+
+In order to turn a disk online (mounting the disk partitions) and clear the
+read-only flag, use the following commands::
+
+  Set-Disk -Number $diskNumber -IsOffline $false
+  Set-Disk -Number $diskNumber -IsReadOnly $false
+
+Please check the `Limitations`_ section to learn about the Windows limitations
+that affect automatically mounted disks.
+
+Windows documentation:
+
+* `SAN policy reference`_
+* `san command`_
+* `StorageSetting command`_
+
+Limitations
+-----------
+
+CSV support
+~~~~~~~~~~~
+
+At the moment, the Microsoft Failover Cluster can't use WNBD disks as
+Cluster Shared Volumes (CSVs) underlying storage. The main reason is that
+``WNBD`` and ``rbd-wnbd`` don't support the *SCSI Persistent Reservations*
+feature yet.
+
+Hyper-V disk addressing
+~~~~~~~~~~~~~~~~~~~~~~~
+
+.. warning::
+  Hyper-V identifies passthrough VM disks by number instead of SCSI ID, although
+  the disk number can change across host reboots. This means that the VMs can end
+  up using incorrect disks after rebooting the host, which is an important
+  security concern. This issue also affects iSCSI and Fibre Channel disks.
+
+There are a few possible ways of avoiding this Hyper-V limitation:
+
+* use an NTFS/ReFS partition to store VHDX image files instead of directly
+  attaching the RBD image. This may slightly impact the IO performance.
+* use the Hyper-V ``AutomaticStartAction`` setting to prevent the VMs from
+  booting with the incorrect disks and have a script that updates VM disks
+  attachments before powering them back on. The ``ElementName`` field of the
+  `Msvm_StorageAllocationSettingData`_ `WMI`_ class may be used to label VM
+  disk attachments.
+* use the Openstack Hyper-V driver, which automatically refreshes the VM disk
+  attachments before powering them back on.
+
+Automatically mounted disks
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Disks that are marked as "online" or "writable" will remain so after being
+reconnected (e.g. due to host reboots, Ceph service restarts, etc).
+
+Unfortunately, Windows restores the disk status based on the disk number,
+ignoring the disk unique identifier. However, the disk numbers can change
+after being reconnected. This issue also affects iSCSI and Fibre Channel disks.
+
+Let's assume that the `SAN policy`_ is set to ``offlineShared``, three
+RBD images are attached and disk 1 is turned online. After a reboot, disk 1
+will become online but it may now correspond to a different RBD image. This can
+be an issue if the disk that was mounted on the host was actually meant for a
+VM.
+
+Troubleshooting
+===============
+
+Please consult the `Windows troubleshooting`_ page.
+
+.. _Windows troubleshooting: ../../install/windows-troubleshooting
+.. _installation guide: ../../install/windows-install
+.. _RBD basic commands: ../rados-rbd-cmds
+.. _WNBD driver: https://github.com/cloudbase/wnbd
+.. _Msvm_StorageAllocationSettingData: https://docs.microsoft.com/en-us/windows/win32/hyperv_v2/msvm-storageallocationsettingdata
+.. _WMI: https://docs.microsoft.com/en-us/windows/win32/wmisdk/wmi-start-page
+.. _san command: https://learn.microsoft.com/en-us/windows-server/administration/windows-commands/san
+.. _StorageSetting command: https://learn.microsoft.com/en-us/powershell/module/storage/set-storagesetting?view=windowsserver2022-ps
+.. _SAN policy reference: https://learn.microsoft.com/en-us/windows-hardware/customize/desktop/unattend/microsoft-windows-partitionmanager-sanpolicy