Mount CephFS on Windows

ceph-dokan is used to mount CephFS filesystems on Windows. It leverages Dokany, a Windows driver that allows implementing filesystems in userspace in a manner similar to FUSE.

See the installation guide to get started.

Note

See the OS recommendations for information about client package support.

Usage

Mounting filesystems

Run the following command to mount a Ceph filesystem:

ceph-dokan.exe -c c:\ceph.conf -l x

This command mounts the default Ceph filesystem using the drive letter x. If ceph.conf is present in the default location (%ProgramData%\ceph\ceph.conf, then this argument is optional.

The -l argument allows the use of an empty folder as the mount point instead of a drive letter.

The uid and gid used for mounting the filesystem default to 0 and can be changed using the following ceph.conf options:

[client]
# client_permissions = true
client_mount_uid = 1000
client_mount_gid = 1000

If you have more than one file system on your Ceph cluster, use the option --client_fs to mount the non-default file system:

mkdir -Force C:\mnt\mycephfs2
ceph-dokan.exe --mountpoint C:\mnt\mycephfs2 --client_fs mycephfs2

Mount CephFS subdirectories by using the --root-path parameter:

ceph-dokan -l y --root-path /a

If the -o --removable flags are set, the mounts will show up in the Get-Volume results:

PS C:\> Get-Volume -FriendlyName "Ceph*" | `
        Select-Object -Property @("DriveLetter", "Filesystem", "FilesystemLabel")

DriveLetter Filesystem FilesystemLabel
----------- ---------- ---------------
          Z Ceph       Ceph
          W Ceph       Ceph - new_fs

Run ceph-dokan --help for a full list of arguments.

Credentials

The --id option passes the name of the CephX user whose keyring is used when mounting CephFS. The following commands are equivalent:

ceph-dokan --id foo -l x
ceph-dokan --name client.foo -l x

Unmounting filesystems

The mount can be removed by either issuing ctrl-c or using the unmap command, like so:

ceph-dokan.exe unmap -l x

Note

When unmapping Ceph filesystems, you must specify the mount point argument that was used at the time of the creation of the mapping.

Limitations

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 that change file ownership or permissions.

CephFS doesn’t support mandatory file locks, which Windows relies heavily upon. Ceph relies upon Dokan to handle file locks, which are only enforced locally.

Unlike rbd-wnbd, ceph-dokan doesn’t provide a service command. To make a CephFS mount survive host reboots, use NSSM.

Troubleshooting

See the Windows troubleshooting page.

Brought to you by the Ceph Foundation

The Ceph Documentation is a community resource funded and hosted by the non-profit Ceph Foundation. If you would like to support this and our other efforts, please consider joining now.