README.windows.rst

   1 About
   2 -----
   3
   4 The Ceph client tools and libraries can be natively used on Windows. This avoids
   5 the need of having additional layers such as iSCSI gateways or SMB shares,
   6 drastically improving the performance.
   7
   8 .. _building:
   9 Building
  10 --------
  11
  12 At the moment, mingw gcc >= 8 is the only supported compiler for building ceph
  13 components for Windows. Support for msvc and clang will be added soon.
  14
  15 `win32_build.sh`_ can be used for cross compiling Ceph and its dependencies.
  16 It may be called from a Linux environment, including Windows Subsystem for
  17 Linux. MSYS2 and CygWin may also work but those weren't tested.
  18
  19 This script currently supports Ubuntu 20.04 and openSUSE Tumbleweed, but it
  20 may be easily adapted to run on other Linux distributions, taking into
  21 account different package managers, package names or paths (e.g. mingw paths).
  22
  23 .. _win32_build.sh: win32_build.sh
  24
  25 The script accepts the following flags:
  26
  27 =================  ===============================  ===============================
  28 Flag               Description                      Default value
  29 =================  ===============================  ===============================
  30 OS                 Host OS distribution, for mingw  ubuntu (also valid: suse)
  31                    and other OS specific settings.
  32 CEPH_DIR           The Ceph source code directory.  The same as the script.
  33 BUILD_DIR          The directory where the          $CEPH_DIR/build
  34                    generated artifacts will be
  35                    placed.
  36 DEPS_DIR           The directory where the Ceph     $CEPH_DIR/build.deps
  37                    dependencies will be built.
  38 NUM_WORKERS        The number of workers to use     The number of vcpus
  39                    when building Ceph.              available
  40 CLEAN_BUILD        Clean the build directory.
  41 SKIP_BUILD         Run cmake without actually
  42                    performing the build.
  43 SKIP_TESTS         Skip building Ceph tests.
  44 SKIP_ZIP           If unset, we'll build a zip
  45                    archive containing the
  46                    generated binaries.
  47 ZIP_DEST           Where to put a zip containing    $BUILD_DIR/ceph.zip
  48                    the generated binaries.
  49 EMBEDDED_DBG_SYM   By default, the generated
  50                    archive will contain a .debug
  51                    subfolder, having the debug
  52                    symbols. If this flag is set,
  53                    the debug symbols will remain
  54                    embedded in the executables.
  55 ENABLE_SHARED      Dynamically link Ceph libs.      False
  56 =================  ===============================  ===============================
  57
  58 The following command will build the binaries and add them to a zip archive
  59 along with all the required DLLs. By default, the debug symbols are extracted
  60 from the binaries and placed in the ".debug" folder of the archive.
  61
  62 .. code:: bash
  63
  64     SKIP_TESTS=1 ./win32_build.sh
  65
  66 In order to disable a flag, such as ``CLEAN_BUILD``, leave it undefined.
  67
  68 ``win32_build.sh`` will fetch dependencies using ``win32_deps_build.sh``. If
  69 all dependencies are successfully prepared, this potentially time consuming
  70 step will be skipped by subsequent builds. Be aware that you may have to do
  71 a clean build (using the ``CLEAN_BUILD`` flag) when the dependencies change
  72 (e.g. after switching to a more recent Ceph version by doing a ``git pull``).
  73
  74 Make sure to explicitly pass the "OS" parameter when directly calling
  75 ``win32_deps_build.sh``. Also, be aware of the fact that it will use the distro
  76 specific package manager, which will require privileged rights.
  77
  78 .. _installing:
  79 Installing
  80 ----------
  81
  82 MSI installer
  83 =============
  84
  85 Using the MSI installer is the recommended way of installing Ceph on Windows.
  86 Please check the `installation guide`_ for more details.
  87
  88 Manual installation
  89 ===================
  90
  91 In order to manually install ``ceph``, start by unzipping the
  92 binaries that you may have obtained by following the building_ step.
  93
  94 You may want to update the environment PATH variable, including the Ceph
  95 path. Assuming that you've copied the Ceph binaries to ``C:\Ceph``, you may
  96 use the following Powershell command:
  97
  98 .. code:: bash
  99
 100     [Environment]::SetEnvironmentVariable("Path", "$env:PATH;C:\ceph", "Machine")
 101
 102 In order to mount Ceph filesystems, you will have to install Dokany.
 103 You may fetch the installer as well as the source code from the Dokany
 104 Github repository: https://github.com/dokan-dev/dokany/releases
 105
 106 The minimum supported Dokany version is 1.3.1. At the time of the writing,
 107 Dokany 2.0 is in Beta stage and is unsupported.
 108
 109 In order to map RBD images, the ``WNBD`` driver must be installed. Please
 110 check out this page for more details about ``WNBD`` and the install process:
 111 https://github.com/cloudbase/wnbd
 112
 113 The following command can be used to configure the ``ceph-rbd`` service.
 114 Please update the ``rbd-wnbd.exe`` path accordingly.
 115
 116 .. code:: PowerShell
 117
 118     New-Service -Name "ceph-rbd" `
 119                 -Description "Ceph RBD Mapping Service" `
 120                 -BinaryPathName "c:\ceph\rbd-wnbd.exe service" `
 121                 -StartupType Automatic
 122
 123 Further reading
 124 ---------------
 125
 126 * `installation guide`_
 127 * `RBD Windows documentation`_
 128 * `Ceph Dokan documentation`_
 129 * `Windows troubleshooting`_
 130
 131 .. _Ceph Dokan documentation: https://docs.ceph.com/en/latest/cephfs/ceph-dokan/
 132 .. _RBD Windows documentation: https://docs.ceph.com/en/latest/rbd/rbd-windows/
 133 .. _Windows troubleshooting: https://docs.ceph.com/en/latest/install/windows-troubleshooting
 134 .. _installation guide: https://docs.ceph.com/en/latest/install/windows-install