From eaa415f1693546693dfb145d717208657cc9095b Mon Sep 17 00:00:00 2001 From: Lucian Petrut Date: Fri, 5 Mar 2021 13:14:29 +0000 Subject: [PATCH] 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 --- README.windows.rst | 41 ++++--------- doc/cephfs/ceph-dokan.rst | 92 +++++++++++++++++++++++++++++ doc/cephfs/createfs.rst | 6 +- doc/cephfs/index.rst | 1 + doc/cephfs/mount-prerequisites.rst | 3 + doc/cephfs/windows-basic-config.rst | 46 +++++++++++++++ 6 files changed, 157 insertions(+), 32 deletions(-) create mode 100644 doc/cephfs/ceph-dokan.rst create mode 100644 doc/cephfs/windows-basic-config.rst diff --git a/README.windows.rst b/README.windows.rst index 48cb5b7c351..4e950a777fe 100644 --- a/README.windows.rst +++ b/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 = 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/ diff --git a/doc/cephfs/ceph-dokan.rst b/doc/cephfs/ceph-dokan.rst new file mode 100644 index 00000000000..27eb75e20d2 --- /dev/null +++ b/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 `. + +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 diff --git a/doc/cephfs/createfs.rst b/doc/cephfs/createfs.rst index b1a5b3b7db3..537a46b25d5 100644 --- a/doc/cephfs/createfs.rst +++ b/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 diff --git a/doc/cephfs/index.rst b/doc/cephfs/index.rst index 479cdfc40ce..32c1d00e062 100644 --- a/doc/cephfs/index.rst +++ b/doc/cephfs/index.rst @@ -113,6 +113,7 @@ Mounting CephFS Mount CephFS: Prerequisites Mount CephFS using Kernel Driver Mount CephFS using FUSE + Mount CephFS on Windows Use the CephFS Shell Supported Features of Kernel Driver Manual: ceph-fuse <../../man/8/ceph-fuse> diff --git a/doc/cephfs/mount-prerequisites.rst b/doc/cephfs/mount-prerequisites.rst index f5a14345589..2f9a22c31bc 100644 --- a/doc/cephfs/mount-prerequisites.rst +++ b/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 diff --git a/doc/cephfs/windows-basic-config.rst b/doc/cephfs/windows-basic-config.rst new file mode 100644 index 00000000000..082c10c1a56 --- /dev/null +++ b/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 = + +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``. +