Mount CephFS using Kernel Driver

Prerequisite

Before mounting CephFS, copy the Ceph configuration file and keyring for theCephX user that has CAPS to mount MDS to the client host (where CephFS will bemounted and used) from the host where Ceph Monitor resides. Please note thatit’s possible to mount CephFS without conf and keyring, but in that case, youwould have to pass the MON’s socket and CephX user’s secret key manually toevery mount command you run.

  • Generate a minimal conf file for the client host and place it at astandard location:
  1. # on client host
  2. mkdir /etc/ceph
  3. ssh {user}@{mon-host} "sudo ceph config generate-minimal-conf" | sudo tee /etc/ceph/ceph.conf

Alternatively, you may copy the conf file. But the above method creates aconf with minimum details which is better.

  • Ensure that the conf file has appropriate permissions:
  1. chmod 644 /etc/ceph/ceph.conf
  • Create a CephX user and get its secret key:
  1. ssh {user}@{mon-host} "sudo ceph fs authorize cephfs client.foo / rw" | sudo tee /etc/ceph/ceph.client.foo.keyring

In above command, replace cephfs with the name of your CephFS, fooby the name you want for CephX user and / by the path within yourCephFS for which you want to allow access to the client and rw standsfor, both, read and write permissions. Alternatively, you may copy the Cephkeyring from the MON host to client host at /etc/ceph but creating akeyring specific to the client host is better.

Note

If you get 2 prompts for password while running above any of 2 abovecommand, run sudo ls (or any other trivial command with sudo)immediately before these commands.

  • Ensure that the keyring has appropriate permissions:
  1. chmod 600 /etc/ceph/ceph.client.foo.keyring
  • mount.ceph helper is installed with Ceph packages. If for some reasoninstalling these packages is not feasible and/or mount.ceph is notpresent on the system, you can still mount CephFS, but you’ll need toexplicitly pass the monitor addreses and CephX user keyring. To verify thatit is installed, do:
  1. stat /sbin/mount.ceph

Synopsis

In general, the command to mount CephFS via kernel driver looks like this:

  1. mount -t ceph {device-string}:{path-to-mounted} {mount-point} -o {key-value-args} {other-args}

Mounting CephFS

On Ceph clusters, CephX is enabled by default. Use mount command tomount CephFS with the kernel driver:

  1. mkdir /mnt/mycephfs
  2. mount -t ceph :/ /mnt/mycephfs -o name=foo

The key-value argument right after option -o is CephX credential;name is the username of the CephX user we are using to mount CephFS. Thedefault value for name is guest.

The kernel driver also requires MON’s socket and the secret key for the CephXuser. In case of the above command, mount.ceph helper figures out thesedetails automatically by finding and reading Ceph conf file and keyring. Incase you don’t have these files on the host where you’re running mountcommand, you can pass these details yourself too:

  1. mount -t ceph 192.168.0.1:6789,192.168.0.2:6789:/ /mnt/mycephfs -o name=foo,secret=AQATSKdNGBnwLhAAnNDKnH65FmVKpXZJVasUeQ==

Passing a single MON socket in above command works too. A potential problemwith the command above is that the secret key is left in your shell’s commandhistory. To prevent that you can copy the secret key inside a file and passthe file by using the option secretfile instead of secret:

  1. mount -t ceph :/ /mnt/mycephfs -o name=foo,secretfile=/etc/ceph/foo.secret

Ensure the permissions on the secret key file are appropriate (preferably,600).

In case CephX is disabled, you can omit -o and the list of key-valuearguments that follow it:

  1. mount -t ceph :/ /mnt/mycephfs

To mount a subtree of the CephFS root, append the path to the device string:

  1. mount -t ceph :/subvolume/dir1/dir2 /mnt/mycephfs -o name=fs

If you have more than one file system on your Ceph cluster, you can mount thenon-default FS on your local FS as follows:

  1. mount -t ceph :/ /mnt/mycephfs2 -o name=fs,mds_namespace=mycephfs2

Unmounting CephFS

To unmount the Ceph file system, use the umount command as usual:

  1. umount /mnt/mycephfs

Tip

Ensure that you are not within the file system directories beforeexecuting this command.

Persistent Mounts

To mount CephFS in your file systems table as a kernel driver, add thefollowing to /etc/fstab:

  1. [{ipaddress}:{port}]:/ {mount}/{mountpoint} ceph [name=username,secret=secretkey|secretfile=/path/to/secretfile],[{mount.options}]

For example:

  1. :/     /mnt/ceph    ceph    name=admin,noatime,_netdev    0       2

The default for the name= parameter is guest. If the secret orsecretfile options are not specified then the mount helper will attempt tofind a secret for the given name in one of the configured keyrings.

See User Management for details on CephX user management and mount.cephmanual for more options it can take. For troubleshooting, seeKernel mount debugging.