CephFS as a regular file system with native kernel performance. It is the
client of choice for most use-cases.
+.. note:: CephFS mount device string now uses a new (v2) syntax. The mount
+ helper (and the kernel) is backward compatible with the old syntax.
+ This means that the old syntax can still be used for mounting with
+ newer mount helpers and kernel. However, it is recommended to use
+ the new syntax whenever possible.
+
Prerequisites
=============
========
In general, the command to mount CephFS via kernel driver looks like this::
- mount -t ceph {device-string}:{path-to-mounted} {mount-point} -o {key-value-args} {other-args}
+ 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 to
mount CephFS with the kernel driver::
- mkdir /mnt/mycephfs
- mount -t ceph :/ /mnt/mycephfs -o name=foo
+ mkdir /mnt/mycephfs
+ mount -t ceph <name>@<fsid>.<fs_name>=/ /mnt/mycephfs
-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``.
+``name`` is the username of the CephX user we are using to mount CephFS.
+``fsid`` is the FSID of the ceph cluster which can be found using
+``ceph fsid`` command. ``fs_name`` is the file system to mount. The kernel
+driver requires MON's socket and the secret key for the CephX user, e.g.::
-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 cephuser@b3acfc0d-575f-41d3-9c91-0e7ed3dbb3fa.cephfs=/ -o mon_addr=192.168.0.1:6789,secret=AQATSKdNGBnwLhAAnNDKnH65FmVKpXZJVasUeQ==
- mount -t ceph 192.168.0.1:6789,192.168.0.2:6789:/ /mnt/mycephfs -o name=foo,secret=AQATSKdNGBnwLhAAnNDKnH65FmVKpXZJVasUeQ==
+When using the mount helper, monitor hosts and FSID are optional. ``mount.ceph``
+helper figures out these details automatically by finding and reading ceph conf
+file, .e.g::
-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 cephuser@.cephfs=/ -o secret=AQATSKdNGBnwLhAAnNDKnH65FmVKpXZJVasUeQ==
- mount -t ceph :/ /mnt/mycephfs -o name=foo,secretfile=/etc/ceph/foo.secret
+.. note:: Note that the dot (``.``) still needs to be a part of the device string.
-Ensure the permissions on the secret key file are appropriate (preferably,
-``600``).
+A potential problem with the above command 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``::
-In case CephX is disabled, you can omit ``-o`` and the list of key-value
-arguments that follow it::
+ mount -t ceph cephuser@.cephfs=/ /mnt/mycephfs -o secretfile=/etc/ceph/cephuser.secret
- mount -t ceph :/ /mnt/mycephfs
+Ensure the permissions on the secret key file are appropriate (preferably, ``600``).
-To mount a subtree of the CephFS root, append the path to the device string::
+Multiple monitor hosts can be passed by separating each address with a ``/``::
+
+ mount -t ceph cephuser@.cephfs=/ /mnt/mycephfs -o mon_addr=192.168.0.1:6789/192.168.0.2:6789,secretfile=/etc/ceph/cephuser.secret
- mount -t ceph :/subvolume/dir1/dir2 /mnt/mycephfs -o name=fs
+In case CephX is disabled, you can omit any credential related options::
-If you have more than one file system on your Ceph cluster, you can mount the
-non-default FS as follows::
+ mount -t ceph cephuser@.cephfs=/ /mnt/mycephfs
+
+.. note:: The ceph user name still needs to be passed as part of the device string.
+
+To mount a subtree of the CephFS root, append the path to the device string::
- mount -t ceph :/ /mnt/mycephfs2 -o name=fs,fs=mycephfs2
+ mount -t ceph cephuser@.cephfs=/subvolume/dir1/dir2 /mnt/mycephfs -o secretfile=/etc/ceph/cephuser.secret
Unmounting CephFS
=================
To mount CephFS in your file systems table as a kernel driver, add the
following to ``/etc/fstab``::
- [{ipaddress}:{port}]:/ {mount}/{mountpoint} ceph [name=username,secret=secretkey|secretfile=/path/to/secretfile],[{mount.options}]
+ {name}@.{fs_name}=/ {mount}/{mountpoint} ceph [mon_addr={ipaddress},secret=secretkey|secretfile=/path/to/secretfile],[{mount.options}] {fs_freq} {fs_passno}
For example::
- :/ /mnt/ceph ceph name=admin,noatime,_netdev 0 2
+ cephuser@.cephfs=/ /mnt/ceph ceph mon_addr=192.168.0.1:6789,noatime,_netdev 0 0
-The default for the ``name=`` parameter is ``guest``. If the ``secret`` or
-``secretfile`` options are not specified then the mount helper will attempt to
-find a secret for the given ``name`` in one of the configured keyrings.
+If the ``secret`` or ``secretfile`` options are not specified then the mount helper
+will attempt to find a secret for the given ``name`` in one of the configured keyrings.
See `User Management`_ for details on CephX user management and mount.ceph_
manual for more options it can take. For troubleshooting, see
Synopsis
========
-| **mount.ceph** [*mon1_socket*\ ,\ *mon2_socket*\ ,...]:/[*subdir*] *dir* [
- -o *options* ]
+| **mount.ceph** *name*@*fsid*.*fs_name*=/[*subdir*] *dir* [-o *options* ]
Description
**mount.ceph** is a helper for mounting the Ceph file system on a Linux host.
It serves to resolve monitor hostname(s) into IP addresses and read
authentication keys from disk; the Linux kernel client component does most of
-the real work. In fact, it is possible to mount a non-authenticated Ceph file
-system without mount.ceph by specifying monitor address(es) by IP::
-
- mount -t ceph 1.2.3.4:/ /mnt/mycephfs
-
-The first argument is the device part of the mount command. It includes host's
-socket and path within CephFS that will be mounted at the mount point. The
-socket, obviously, takes the form ip_address[:port]. If the port is not
-specified, the Ceph default of 6789 is assumed. Multiple monitor addresses can
-be passed by separating them by commas. Only one monitor is needed to mount
-successfully; the client will learn about all monitors from any responsive
-monitor. However, it is a good idea to specify more than one in case the one
-happens to be down at the time of mount.
-
-If the host portion of the device is left blank, then **mount.ceph** will
-attempt to determine monitor addresses using local configuration files
-and/or DNS SRV records. In similar way, if authentication is enabled on Ceph
-cluster (which is done using CephX) and options ``secret`` and ``secretfile``
-are not specified in the command, the mount helper will spawn a child process
-that will use the standard Ceph library routines to find a keyring and fetch
-the secret from it.
+the real work. To mount a Ceph file system use::
+
+ mount.ceph name@07fe3187-00d9-42a3-814b-72a4d5e7d5be.fs_name=/ /mnt/mycephfs -o mon_addr=1.2.3.4
+
+Mount helper can fill in the cluster FSID by reading the ceph configuration file.
+Its recommeded to call the mount helper via mount(8) as per::
+
+ mount -t ceph name@.fs_name=/ /mnt/mycephfs -o mon_addr=1.2.3.4
+
+Note that the dot ``.`` still needs to be a part of the device string in this case.
+
+The first argument is the device part of the mount command. It includes the
+RADOS user for authentication, the file system name and a path within CephFS
+that will be mounted at the mount point.
+
+Monitor addresses can be passed using ``mon_addr`` mount option. Multiple monitor
+addresses can be passed by separating addresses with a slash (`/`). Only one
+monitor is needed to mount successfully; the client will learn about all monitors
+from any responsive monitor. However, it is a good idea to specify more than one
+in case the one happens to be down at the time of mount. Monitor addresses takes
+the form ip_address[:port]. If the port is not specified, the Ceph default of 6789
+is assumed.
+
+If monitor addresses are not specified, then **mount.ceph** will attempt to determine
+monitor addresses using local configuration files and/or DNS SRV records. In similar
+way, if authentication is enabled on Ceph cluster (which is done using CephX) and
+options ``secret`` and ``secretfile`` are not specified in the command, the mount
+helper will spawn a child process that will use the standard Ceph library routines
+to find a keyring and fetch the secret from it (including the monitor address and
+FSID if those not specified).
A sub-directory of the file system can be mounted by specifying the (absolute)
-path to the sub-directory right after ":" after the socket in the device part
-of the mount command.
+path to the sub-directory right after "=" in the device part of the mount command.
Mount helper application conventions dictate that the first two options are
device to be mounted and the mountpoint for that device. Options must be
for autodiscovery of monitor addresses and auth secrets. The default is
to use the standard search path for ceph.conf files.
-:command: `fs=<fs-name>`
- Specify the non-default file system to be mounted. Not passing this
- option mounts the default file system.
-
-:command: `mds_namespace=<fs-name>`
- A synonym of "fs=" and its use is deprecated.
-
:command:`mount_timeout`
int (seconds), Default: 60
- ``prefer-secure``: secure mode, if denied agree to crc mode
-:command:`name`
- RADOS user to authenticate as when using CephX. Default: guest
+:command:`mon_addr`
+ Monitor address of the cluster in the form of ip_address[:port]
+
+:command:`fsid`
+ Cluster FSID. This can be found using `ceph fsid` command.
:command:`secret`
secret key for use with CephX. This option is insecure because it exposes
Mount the full file system::
- mount.ceph :/ /mnt/mycephfs
-
-Assuming mount.ceph is installed properly, it should be automatically invoked
-by mount(8)::
-
- mount -t ceph :/ /mnt/mycephfs
+ mount -t ceph fs_user@.mycephfs2=/ /mnt/mycephfs
Mount only part of the namespace/file system::
- mount.ceph :/some/directory/in/cephfs /mnt/mycephfs
-
-Mount non-default FS, in case cluster has multiple FSs::
-
- mount -t ceph :/ /mnt/mycephfs2 -o fs=mycephfs2
-
- or
-
- mount -t ceph :/ /mnt/mycephfs2 -o mds_namespace=mycephfs2 # This option name is deprecated.
+ mount.ceph fs_user@.mycephfs2=/some/directory/in/cephfs /mnt/mycephfs
Pass the monitor host's IP address, optionally::
- mount.ceph 192.168.0.1:/ /mnt/mycephfs
+ mount.ceph fs_user@.mycephfs2=/ /mnt/mycephfs -o mon_addr=192.168.0.1
Pass the port along with IP address if it's running on a non-standard port::
- mount.ceph 192.168.0.1:7000:/ /mnt/mycephfs
-
-If there are multiple monitors, passes addresses separated by a comma::
+ mount.ceph fs_user@.mycephfs2=/ /mnt/mycephfs -o mon_addr=192.168.0.1:7000
- mount.ceph 192.168.0.1,192.168.0.2,192.168.0.3:/ /mnt/mycephfs
+If there are multiple monitors, pass each address separated by a `/`::
-If authentication is enabled on Ceph cluster::
-
- mount.ceph :/ /mnt/mycephfs -o name=fs_username
+ mount.ceph fs_user@.mycephfs2=/ /mnt/mycephfs -o mon_addr=192.168.0.1/192.168.0.2/192.168.0.3
Pass secret key for CephX user optionally::
- mount.ceph :/ /mnt/mycephfs -o name=fs_username,secret=AQATSKdNGBnwLhAAnNDKnH65FmVKpXZJVasUeQ==
+ mount.ceph fs_user@.mycephfs2=/ /mnt/mycephfs -o secret=AQATSKdNGBnwLhAAnNDKnH65FmVKpXZJVasUeQ==
Pass file containing secret key to avoid leaving secret key in shell's command
history::
- mount.ceph :/ /mnt/mycephfs -o name=fs_username,secretfile=/etc/ceph/fs_username.secret
+ mount.ceph fs_user@.mycephfs2=/ /mnt/mycephfs -o secretfile=/etc/ceph/fs_username.secret
+
+If authentication is disabled on Ceph cluster, omit the credential related option::
+ mount.ceph fs_user@.mycephfs2=/ /mnt/mycephfs
Availability
============
projects / ceph.git / commitdiff