doc: add ceph-dokan documentation

This change documents ceph-dokan, describing the prerequisites,
usage and limitations.

Some of this was mentioned in README.windows.rst but is now being
moved to the Ceph doc pages.

Signed-off-by: Lucian Petrut <lpetrut@cloudbasesolutions.com>

README.windows.rst

@@ -16,7 +16,7 @@ components for Windows. Support for msvc and clang will be added soon.
 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 18.04 and openSUSE Tumbleweed, but it
+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).
 
@@ -136,8 +136,8 @@ 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 use 1.3.1, which at time of the writing is the latest
-stable release.
+The minimum supported Dokany version is 1.3.1. At the time of the writing,
+Dokany 2.0 is in Beta stage and is unsupported.
 
 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:
@@ -167,8 +167,12 @@ accordingly.
         keyring = C:/ProgramData/ceph/keyring
         ; log file = C:/ProgramData/ceph/out/$name.$pid.log
         admin socket = C:/ProgramData/ceph/out/$name.$pid.asok
+
+        ; client_permissions = true
+        ; client_mount_uid = 1000
+        ; client_mount_gid = 1000
     [global]
-        mon host =  [v2:xx.xx.xx.xx:40623,v1:xx.xx.xx.xx:40624] [v2:xx.xx.xx.xx:40625,v1:xx.xx.xx.xx:40626] [v2:xx.xx.xx.xx:40627,v1:xx.xx.xx.xx:40628]
+        mon host = <ceph_monitor_addresses>
 
 Assuming that you're going to use this config sample, don't forget to
 also copy your keyring file to the specified location and make sure
@@ -215,32 +219,7 @@ Usage
 Cephfs
 ======
 
-In order to mount a ceph filesystem, the following command can be used:
-
-.. code:: PowerShell
-
-    ceph-dokan.exe -c c:\ceph.conf -l x
-
-The above command will mount the default ceph filesystem using the drive
-letter ``x``. If ``ceph.conf`` is placed at the default location, which
-is ``%ProgramData%\ceph\ceph.conf``, then this argument becomes optional.
-
-The ``-l`` argument also allows using an empty folder as a mountpoint
-instead of a drive letter.
-
-The uid and gid used for mounting the filesystem defaults to 0 and may be
-changed using the ``-u`` and ``-g`` arguments. ``-n`` can be used in order
-to skip enforcing permissions on client side. Be aware that Windows ACLs
-are ignored. Posix ACLs are supported but cannot be modified using the
-current CLI. In the future, we may add some command actions to change
-file ownership or permissions.
-
-For debugging purposes, ``-d`` and ``s`` might be used. The first one will
-enable debug output and the latter will enable stderr logging. By default,
-debug messages are sent to a connected debugger.
-
-You may use ``--help`` to get the full list of available options. The
-current syntax is up for discussion and might change.
+Please check the `ceph-dokan documentation`_ for more details.
 
 RBD
 ===
@@ -411,3 +390,5 @@ At the same time, WNBD driver counters can be fetched using:
 
 Note that the ``wnbd-client`` mapping identifier will be the full RBD image spec
 (the ``device`` column of the ``rbd device list`` output).
+
+.. _ceph-dokan documentation: https://docs.ceph.com/en/latest/cephfs/ceph-dokan/

doc/cephfs/ceph-dokan.rst

@@ -0,0 +1,92 @@
+=======================
+Mount CephFS on Windows
+=======================
+
+``ceph-dokan`` can be used for mounting CephFS filesystems on Windows.
+It leverages Dokany, a Windows driver that allows implementing filesystems in
+userspace, pretty much like FUSE.
+
+Prerequisites
+=============
+
+Dokany
+------
+
+``ceph-dokan`` requires Dokany to be installed. You may fetch the installer as
+well as the source code from the Dokany Github repository:
+https://github.com/dokan-dev/dokany/releases
+
+The minimum supported Dokany version is 1.3.1. At the time of the writing,
+Dokany 2.0 is in Beta stage and is unsupported.
+
+Supported platforms
+-------------------
+
+Windows Server 2019 and Windows Server 2016 are supported. Previous Windows
+Server versions, including Windows client versions such as Windows 10, might
+work but haven't been tested.
+
+Configuration
+=============
+
+``ceph-dokan`` requires minimal configuration. Please check the
+`Windows configuration sample`_ to get started.
+
+You'll also need a keyring file. The `General Prerequisites`_ page provides a
+simple example, showing how a new CephX user can be created and how its secret
+key can be retrieved.
+
+For more details on CephX user management, see the `Client Authentication`_
+and :ref:`User Management <user-management>`.
+
+Usage
+=====
+
+In order to mount a ceph filesystem, the following command can be used::
+
+    ceph-dokan.exe -c c:\ceph.conf -l x
+
+This will mount the default ceph filesystem using the drive letter ``x``.
+If ``ceph.conf`` is placed at the default location, which is
+``%ProgramData%\ceph\ceph.conf``, then this argument becomes optional.
+
+The ``-l`` argument also allows using an empty folder as a mountpoint
+instead of a drive letter.
+
+The uid and gid used for mounting the filesystem default to 0 and may be
+changed using the following ``ceph.conf`` options::
+
+    [client]
+    # client_permissions = true
+    client_mount_uid = 1000
+    client_mount_gid = 1000
+
+Please use ``ceph-dokan --help`` for a full list of arguments.
+
+Credentials
+-----------
+
+The ``--id`` option passes the name of the CephX user whose keyring we intend to
+use for mounting CephFS. The following commands are equivalent::
+
+    ceph-dokan --id foo -l x
+    ceph-dokan --name client.foo -l x
+
+Limitations
+-----------
+
+Be aware that Windows ACLs are ignored. Posix ACLs are supported but cannot be
+modified using the current CLI. In the future, we may add some command actions
+to change file ownership or permissions.
+
+Another thing to note is that cephfs doesn't support mandatory file locks, which
+Windows is heavily rely upon. At the moment, we're letting Dokan handle file
+locks, which are only enforced locally.
+
+Unlike ``rbd-wnbd``, ``ceph-dokan`` doesn't currently provide a ``service``
+command. In order for the cephfs mount to survive host reboots, consider using
+``NSSM``.
+
+.. _Windows configuration sample: ../windows-basic-config
+.. _General Prerequisites: ../mount-prerequisites
+.. _Client Authentication: ../client-auth

doc/cephfs/createfs.rst

@@ -67,11 +67,13 @@ Once the file system is created and the MDS is active, you are ready to mount
 the file system.  If you have created more than one file system, you will
 choose which to use when mounting.
 
-	- `Mount CephFS`_
-	- `Mount CephFS as FUSE`_
+  - `Mount CephFS`_
+  - `Mount CephFS as FUSE`_
+  - `Mount CephFS on Windows`_
 
 .. _Mount CephFS: ../../cephfs/mount-using-kernel-driver
 .. _Mount CephFS as FUSE: ../../cephfs/mount-using-fuse
+.. _Mount CephFS on Windows: ../../cephfs/ceph-dokan
 
 If you have created more than one file system, and a client does not
 specify a file system when mounting, you can control which file system

doc/cephfs/index.rst

@@ -113,6 +113,7 @@ Mounting CephFS
     Mount CephFS: Prerequisites <mount-prerequisites>
     Mount CephFS using Kernel Driver <mount-using-kernel-driver>
     Mount CephFS using FUSE <mount-using-fuse>
+    Mount CephFS on Windows <ceph-dokan>
     Use the CephFS Shell <cephfs-shell>
     Supported Features of Kernel Driver <kernel-features>
     Manual: ceph-fuse <../../man/8/ceph-fuse>

doc/cephfs/mount-prerequisites.rst

@@ -6,6 +6,8 @@ You can use CephFS by mounting it to your local filesystem or by using
 FUSE`_. Both have their own advantages. Read the following section to
 understand more about both of these ways to mount CephFS.
 
+For Windows CephFS mounts, please check the `ceph-dokan`_ page.
+
 Which CephFS Client?
 --------------------
 
@@ -68,3 +70,4 @@ Ceph MON resides.
 .. _cephfs-shell: ../cephfs-shell
 .. _using kernel: ../mount-using-kernel-driver
 .. _using FUSE: ../mount-using-fuse
+.. _ceph-dokan: ../ceph-dokan

doc/cephfs/windows-basic-config.rst

@@ -0,0 +1,46 @@
+:orphan:
+
+===========================
+Windows basic configuration
+===========================
+
+This page describes the minimum Ceph configuration required for using the
+client components on Windows.
+
+ceph.conf
+=========
+
+The default location for the ``ceph.conf`` file on Windows is
+``%ProgramData%\ceph\ceph.conf``, which usually expands to
+``C:\ProgramData\ceph\ceph.conf``.
+
+Below you may find a sample. Please fill in the monitor addresses
+accordingly::
+
+    [global]
+        log to stderr = true
+        ; Uncomment the following in order to use the Windows Event Log
+        ; log to syslog = true
+
+        run dir = C:/ProgramData/ceph/out
+        crash dir = C:/ProgramData/ceph/out
+
+        ; Use the following to change the cephfs client log level
+        ; debug client = 2
+    [client]
+        keyring = C:/ProgramData/ceph/keyring
+        ; log file = C:/ProgramData/ceph/out/$name.$pid.log
+        admin socket = C:/ProgramData/ceph/out/$name.$pid.asok
+
+        ; client_permissions = true
+        ; client_mount_uid = 1000
+        ; client_mount_gid = 1000
+    [global]
+        mon host = <ceph_monitor_addresses>
+
+Don't forget to also copy your keyring file to the specified location and make
+sure that the configured directories exist (e.g. ``C:\ProgramData\ceph\out``).
+
+Please use slashes ``/`` instead of backslashes ``\`` as path separators
+within ``ceph.conf``.
+