1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
|
.. _cephfs-mount-using-kernel-driver:
=================================
Mount CephFS using Kernel Driver
=================================
The CephFS kernel driver is part of the Linux kernel. It makes possible the
mounting of CephFS as a regular file system with native kernel performance. It
is the client of choice for most use-cases.
.. note:: The CephFS mount device string now uses a new syntax ("v2"). The
mount helper is backward compatible with the old syntax. 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 with the kernel.
Prerequisites
=============
Complete General Prerequisites
------------------------------
Go through the prerequisites required by both kernel and FUSE mounts,
as described on the `Mount CephFS: Prerequisites`_ page.
Is mount helper present?
------------------------
The ``mount.ceph`` helper is installed by Ceph packages. The helper passes the
monitor address(es) and CephX user keyrings, saving the Ceph admin the effort
of passing these details explicitly while mounting CephFS. If the helper is not
present on the client machine, CephFS can still be mounted using the kernel
driver but only by passing these details explicitly to the ``mount`` command.
To check whether ``mount.ceph`` is present on your system, run the following
command:
.. prompt:: bash #
stat /sbin/mount.ceph
Which Kernel Version?
---------------------
Because the kernel client is distributed as part of the Linux kernel (and not
as part of the packaged Ceph releases), you will need to consider which kernel
version to use on your client nodes. Older kernels are known to include buggy
Ceph clients and may not support features that more recent Ceph clusters
support.
Remember that the "latest" kernel in a stable Linux distribution is likely
to be years behind the latest upstream Linux kernel where Ceph development
takes place (including bug fixes).
As a rough guide, as of Ceph 10.x (Jewel), you should be using a least a 4.x
kernel. If you absolutely have to use an older kernel, you should use the
fuse client instead of the kernel client.
This advice does not apply if you are using a Linux distribution that includes
CephFS support. In that case, the distributor is responsible for backporting
fixes to their stable kernel. Check with your vendor.
Synopsis
========
This is the general form of the command for mounting CephFS via the kernel driver:
.. prompt:: bash #
mount -t ceph {device-string}={path-to-mounted} {mount-point} -o {key-value-args} {other-args}
Mounting CephFS
===============
CephX authentication is enabled by default in Ceph clusters. Use the ``mount``
command to use the kernel driver to mount CephFS:
.. prompt:: bash #
mkdir /mnt/mycephfs
mount -t ceph <name>@<fsid>.<fs_name>=/ /mnt/mycephfs
#. ``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 the
``ceph fsid`` command. ``fs_name`` is the file system to mount. The kernel
driver requires a ceph Monitor's address and the secret key of the CephX
user. For example:
.. prompt:: bash #
mount -t ceph cephuser@b3acfc0d-575f-41d3-9c91-0e7ed3dbb3fa.cephfs=/ -o mon_addr=192.168.0.1:6789,secret=AQATSKdNGBnwLhAAnNDKnH65FmVKpXZJVasUeQ==
When using the mount helper, monitor hosts and FSID are optional. The
``mount.ceph`` helper discovers these details by finding and reading the ceph
conf file. For example:
.. prompt:: bash #
mount -t ceph cephuser@.cephfs=/ -o secret=AQATSKdNGBnwLhAAnNDKnH65FmVKpXZJVasUeQ==
.. note:: Note that the dot (``.`` in the string ``cephuser@.cephfs``) must be
a part of the device string.
A weakness of this method is that it will leave the secret key in your shell's
command history. To avoid this, copy the secret key inside a file and pass the
file by using the option ``secretfile`` instead of ``secret``. For example:
.. prompt:: bash #
mount -t ceph cephuser@.cephfs=/ /mnt/mycephfs -o secretfile=/etc/ceph/cephuser.secret
Ensure that the permissions on the secret key file are appropriate (preferably,
``600``).
Multiple monitor hosts can be passed by separating addresses with a ``/``:
.. prompt:: bash #
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
If CephX is disabled, omit any credential-related options. For example:
.. prompt:: bash #
mount -t ceph cephuser@.cephfs=/ /mnt/mycephfs
.. note:: The Ceph user name must 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 cephuser@.cephfs=/subvolume/dir1/dir2 /mnt/mycephfs -o secretfile=/etc/ceph/cephuser.secret
Backward Compatibility
======================
The old syntax is supported for backward compatibility.
To mount CephFS with the kernel driver, run the following commands:
.. prompt:: bash #
mkdir /mnt/mycephfs
mount -t ceph :/ /mnt/mycephfs -o name=admin
The key-value argument right after the option ``-o`` is the CephX credential.
``name`` is the username of the CephX user that is mounting CephFS.
To mount a non-default FS (in this example, ``cephfs2``), run commands of the following form. These commands are to be used in cases in which the cluster
has multiple file systems:
.. prompt:: bash #
mount -t ceph :/ /mnt/mycephfs -o name=admin,fs=cephfs2
or
.. prompt:: bash #
mount -t ceph :/ /mnt/mycephfs -o name=admin,mds_namespace=cephfs2
.. note:: The option ``mds_namespace`` is deprecated. Use ``fs=`` instead when
using the old syntax for mounting.
Unmounting CephFS
=================
To unmount the Ceph file system, use the ``umount`` command, as in this
example:
.. prompt:: bash #
umount /mnt/mycephfs
.. tip:: Ensure that you are not within the file system directories before
executing this command.
Persistent Mounts
==================
To mount CephFS in your file systems table as a kernel driver, add the
following to ``/etc/fstab``::
{name}@.{fs_name}=/ {mount}/{mountpoint} ceph [mon_addr={ipaddress},secret=secretkey|secretfile=/path/to/secretfile],[{mount.options}] {fs_freq} {fs_passno}
For example::
cephuser@.cephfs=/ /mnt/ceph ceph mon_addr=192.168.0.1:6789,noatime,_netdev 0 0
If the ``secret`` or ``secretfile`` options are not specified, 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 the mount.ceph_
manual for a list of the options it recognizes. For troubleshooting, see
:ref:`kernel_mount_debugging`.
.. _fstab: ../fstab/#kernel-driver
.. _Mount CephFS\: Prerequisites: ../mount-prerequisites
.. _mount.ceph: ../../man/8/mount.ceph/
.. _User Management: ../../rados/operations/user-management/
|
