-====================================
- Mount CephFS with the Kernel Driver
-====================================
+=================================
+ Mount CephFS using Kernel Driver
+=================================
-It is recommended to install the ``/sbin/mount.ceph`` kernel mount
-helper if working with the kernel cephfs driver. To mount CephFS with
-the kernel driver you may use the ``mount`` command::
+Prerequisite
+------------
+Before mounting CephFS, copy the Ceph configuration file and keyring for the
+CephX user that has CAPS to mount MDS to the client host (where CephFS will be
+mounted and used) from the host where Ceph Monitor resides. Please note that
+it's possible to mount CephFS without conf and keyring, but in that case, you
+would have to pass the MON's socket and CephX user's secret key manually to
+every mount command you run.
- # mkdir /mnt/mycephfs
- # mount -t ceph :/ /mnt/mycephfs
+#. Generate a minimal conf file for the client host and place it at a
+ standard location::
-Omitting the monitor addresses will cue ``mount.ceph`` to look them up
-in the local configuration file. If you know at least one of the monitor
-addresses and ports you can specify them directly in a comma-separated
-list, and the kernel will avoid looking them up::
+ # on client host
+ mkdir /etc/ceph
+ ssh {user}@{mon-host} "sudo ceph config generate-minimal-conf" | sudo tee /etc/ceph/ceph.conf
- # mount -t ceph 192.168.0.1:6789,192.168.0.2:6789:/ /mnt/mycephfs
+ Alternatively, you may copy the conf file. But the above method creates a
+ conf with minimum details which is better.
-To mount a subtree of the cephfs root, append the path to the device
-string ::
+#. Ensure that the conf file has appropriate permissions::
- # mount -t ceph :/subvolume/dir1/dir2 /mnt/mycephfs -o name=fs
+ chmod 644 /etc/ceph/ceph.conf
-To mount the Ceph file system with ``cephx`` authentication enabled, the
-kernel must authenticate with the cluster. The default ``name=`` option
-is ``guest``. The mount.ceph helper will automatically attempt to find
-a secret key in a cephx keyring if it's not specified. For example, to
-mount the filesystem as the cephx user ``fs``::
+#. Create a CephX user and get its secret key::
- # mount -t ceph :/ /mnt/mycephfs -o name=fs
+ ssh {user}@{mon-host} "sudo ceph fs authorize cephfs client.foo / rw" | sudo tee /etc/ceph/ceph.client.foo.keyring
-The secret can also be specified manually with the ``secret=`` option.::
+ In above command, replace ``cephfs`` with the name of your CephFS, ``foo``
+ by the name you want for CephX user and ``/`` by the path within your
+ CephFS for which you want to allow access to the client and ``rw`` stands
+ for, both, read and write permissions. Alternatively, you may copy the Ceph
+ keyring from the MON host to client host at ``/etc/ceph`` but creating a
+ keyring specific to the client host is better.
- # mount -t ceph :/ /mnt/mycephfs -o name=fs,secret=AQATSKdNGBnwLhAAnNDKnH65FmVKpXZJVasUeQ==
+.. note:: If you get 2 prompts for password while running above any of 2 above
+ command, run ``sudo ls`` (or any other trivial command with sudo)
+ immediately before these commands.
-For legacy usage, mount.ceph can be told to read a lone secret from a
-file. For example::
+#. Ensure that the keyring has appropriate permissions::
- # mount -t ceph :/ /mnt/mycephfs -o name=fs,secretfile=/etc/ceph/admin.secret
+ chmod 600 /etc/ceph/ceph.client.foo.keyring
-See `User Management`_ for details on cephx.
+#. ``mount.ceph`` helper is installed with Ceph packages. If for some reason
+ installing these packages is not feasible and/or ``mount.ceph`` is not
+ present on the system, you can still mount CephFS, but you'll need to
+ explicitly pass the monitor addreses and CephX user keyring. To verify that
+ it is installed, do::
-If you have more than one file system, specify which one to mount using
-the ``mds_namespace`` option, e.g.::
+ stat /sbin/mount.ceph
- # mount -t ceph :/ -o name=fs,mds_namespace=myfs
+Synopsis
+--------
+In general, the command to mount CephFS via kernel driver looks like this::
-To unmount the Ceph file system, you may use the ``umount`` command. For example::
+ mount -t ceph {device-string}:{path-to-mounted} {mount-point} -o {key-value-args} {other-args}
- # umount /mnt/mycephfs
+Mounting CephFS
+---------------
+On Ceph clusters, CephX is enabled by default. Use ``mount`` command to
+mount CephFS with the kernel driver::
+
+ mkdir /mnt/mycephfs
+ 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. The
+default value for ``name`` is ``guest``.
+
+The kernel driver also requires MON's socket and the secret key for the CephX
+user. In case of the above command, ``mount.ceph`` helper figures out these
+details automatically by finding and reading Ceph conf file and keyring. In
+case you don't have these files on the host where you're running mount
+command, you can pass these details yourself too::
+
+ 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 problem
+with the command above is that the secret key is left in your shell's command
+history. To prevent that you can copy the secret key inside a file and pass
+the file by using the option ``secretfile`` instead of ``secret``::
+
+ 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-value
+arguments that follow it::
+
+ mount -t ceph :/ /mnt/mycephfs
+
+To mount a subtree of the CephFS root, append the path to the device string::
+
+ 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 the
+non-default FS on your local FS as follows::
+
+ 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::
+
+ umount /mnt/mycephfs
.. tip:: Ensure that you are not within the file system directories before
executing this command.
-See `mount.ceph`_ for details. For troubleshooting, see :ref:`kernel_mount_debugging`.
+See fstab_ to find out how to make kernel mounted CephFS persist across
+reboots, `User Management`_ for details on CephX user management and
+mount.ceph_ manual for more options it can take. For troubleshooting, see
+:ref:`kernel_mount_debugging`.
-.. _mount.ceph: ../../man/8/mount.ceph/
+.. _fstab: ../fstab/#kernel-driver
.. _User Management: ../../rados/operations/user-management/
+.. _mount.ceph: ../../man/8/mount.ceph/
projects / ceph.git / commitdiff