diff options
Diffstat (limited to 'README.windows.rst')
| -rw-r--r-- | README.windows.rst | 133 |
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 |