Adding upstream version 18.2.2.upstream/18.2.2

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

1 files changed, 133 insertions, 0 deletions

diff --git a/README.windows.rst b/README.windows.rst
new file mode 100644
index 000000000..2c2419c08
--- /dev/null
+++ b/README.windows.rst
@@ -0,0 +1,133 @@
+About
+-----
+
+The Ceph client tools and libraries can be natively used on Windows. This avoids
+the need of having additional layers such as iSCSI gateways or SMB shares,
+drastically improving the performance.
+
+.. _building:
+Building
+--------
+
+At the moment, mingw gcc >= 8 is the only supported compiler for building ceph
+components for Windows. Support for msvc and clang will be added soon.
+
+`win32_build.sh`_ can be used for cross compiling Ceph and its dependencies.
+It may be called from a Linux environment, including Windows Subsystem for
+Linux. MSYS2 and CygWin may also work but those weren't tested.
+
+This script currently supports Ubuntu 20.04 and openSUSE Tumbleweed, but it
+may be easily adapted to run on other Linux distributions, taking into
+account different package managers, package names or paths (e.g. mingw paths).
+
+.. _win32_build.sh: win32_build.sh
+
+The script accepts the following flags:
+
+=================  ===============================  ===============================
+Flag               Description                      Default value
+=================  ===============================  ===============================
+OS                 Host OS distribution, for mingw  ubuntu (also valid: suse)
+                   and other OS specific settings.
+CEPH_DIR           The Ceph source code directory.  The same as the script.
+BUILD_DIR          The directory where the          $CEPH_DIR/build
+                   generated artifacts will be
+                   placed.
+DEPS_DIR           The directory where the Ceph     $CEPH_DIR/build.deps
+                   dependencies will be built.
+NUM_WORKERS        The number of workers to use     The number of vcpus
+                   when building Ceph.              available
+CLEAN_BUILD        Clean the build directory.
+SKIP_BUILD         Run cmake without actually
+                   performing the build.
+SKIP_TESTS         Skip building Ceph tests.
+SKIP_ZIP           If unset, we'll build a zip
+                   archive containing the
+                   generated binaries.
+ZIP_DEST           Where to put a zip containing    $BUILD_DIR/ceph.zip
+                   the generated binaries.
+EMBEDDED_DBG_SYM   By default, the generated
+                   archive will contain a .debug
+                   subfolder, having the debug
+                   symbols. If this flag is set,
+                   the debug symbols will remain
+                   embedded in the executables.
+ENABLE_SHARED      Dynamically link Ceph libs.      False
+=================  ===============================  ===============================
+
+The following command will build the binaries and add them to a zip archive
+along with all the required DLLs. By default, the debug symbols are extracted
+from the binaries and placed in the ".debug" folder of the archive.
+
+.. code:: bash
+
+    SKIP_TESTS=1 ./win32_build.sh
+
+In order to disable a flag, such as ``CLEAN_BUILD``, leave it undefined.
+
+``win32_build.sh`` will fetch dependencies using ``win32_deps_build.sh``. If
+all dependencies are successfully prepared, this potentially time consuming
+step will be skipped by subsequent builds. Be aware that you may have to do
+a clean build (using the ``CLEAN_BUILD`` flag) when the dependencies change
+(e.g. after switching to a more recent Ceph version by doing a ``git pull``).
+
+Make sure to explicitly pass the "OS" parameter when directly calling
+``win32_deps_build.sh``. Also, be aware of the fact that it will use the distro
+specific package manager, which will require privileged rights.
+
+.. _installing:
+Installing
+----------
+
+MSI installer
+=============
+
+Using the MSI installer is the recommended way of installing Ceph on Windows.
+Please check the `installation guide`_ for more details.
+
+Manual installation
+===================
+
+In order to manually install ``ceph``, start by unzipping the
+binaries that you may have obtained by following the building_ step.
+
+You may want to update the environment PATH variable, including the Ceph
+path. Assuming that you've copied the Ceph binaries to ``C:\Ceph``, you may
+use the following Powershell command:
+
+.. code:: bash
+
+    [Environment]::SetEnvironmentVariable("Path", "$env:PATH;C:\ceph", "Machine")
+
+In order to mount Ceph filesystems, you will have to install Dokany.
+You may fetch the installer as well as the source code from the Dokany
+Github repository: https://github.com/dokan-dev/dokany/releases
+
+Make sure to install Dokany 2.0.5 or later.
+
+In order to map RBD images, the ``WNBD`` driver must be installed. Please
+check out this page for more details about ``WNBD`` and the install process:
+https://github.com/cloudbase/wnbd
+
+The following command can be used to configure the ``ceph-rbd`` service.
+Please update the ``rbd-wnbd.exe`` path accordingly.
+
+.. code:: PowerShell
+
+    New-Service -Name "ceph-rbd" `
+                -Description "Ceph RBD Mapping Service" `
+                -BinaryPathName "c:\ceph\rbd-wnbd.exe service" `
+                -StartupType Automatic
+
+Further reading
+---------------
+
+* `installation guide`_
+* `RBD Windows documentation`_
+* `Ceph Dokan documentation`_
+* `Windows troubleshooting`_
+
+.. _Ceph Dokan documentation: https://docs.ceph.com/en/latest/cephfs/ceph-dokan/
+.. _RBD Windows documentation: https://docs.ceph.com/en/latest/rbd/rbd-windows/
+.. _Windows troubleshooting: https://docs.ceph.com/en/latest/install/windows-troubleshooting
+.. _installation guide: https://docs.ceph.com/en/latest/install/windows-install