ceph/doc/man/8/mount.ceph.rst

   1 :orphan:
   2
   3 ========================================
   4  mount.ceph -- mount a Ceph file system
   5 ========================================
   6
   7 .. program:: mount.ceph
   8
   9 Synopsis
  10 ========
  11
  12 | **mount.ceph** *name*@*fsid*.*fs_name*=/[*subdir*] *dir* [-o *options* ]
  13
  14
  15 Description
  16 ===========
  17
  18 **mount.ceph** is a helper for mounting the Ceph file system on a Linux host.
  19 It serves to resolve monitor hostname(s) into IP addresses and read
  20 authentication keys from disk; the Linux kernel client component does most of
  21 the real work. To mount a Ceph file system use::
  22
  23   mount.ceph name@07fe3187-00d9-42a3-814b-72a4d5e7d5be.fs_name=/ /mnt/mycephfs -o mon_addr=1.2.3.4
  24
  25 Mount helper can fill in the cluster FSID by reading the ceph configuration file.
  26 Its recommended to call the mount helper via mount(8) as per::
  27
  28   mount -t ceph name@.fs_name=/ /mnt/mycephfs -o mon_addr=1.2.3.4
  29
  30 Note that the dot ``.`` still needs to be a part of the device string in this case.
  31
  32 The first argument is the device part of the mount command. It includes the
  33 RADOS user for authentication, the file system name and a path within CephFS
  34 that will be mounted at the mount point.
  35
  36 Monitor addresses can be passed using ``mon_addr`` mount option. Multiple monitor
  37 addresses can be passed by separating addresses with a slash (`/`). Only one
  38 monitor is needed to mount successfully; the client will learn about all monitors
  39 from any responsive monitor. However, it is a good idea to specify more than one
  40 in case the one happens to be down at the time of mount. Monitor addresses takes
  41 the form ip_address[:port]. If the port is not specified, the Ceph default of 6789
  42 is assumed.
  43
  44 If monitor addresses are not specified, then **mount.ceph** will attempt to determine
  45 monitor addresses using local configuration files and/or DNS SRV records. In similar
  46 way, if authentication is enabled on Ceph cluster (which is done using CephX) and
  47 options ``secret`` and ``secretfile`` are not specified in the command, the mount
  48 helper will spawn a child process that will use the standard Ceph library routines
  49 to find a keyring and fetch the secret from it (including the monitor address and
  50 FSID if those not specified).
  51
  52 A sub-directory of the file system can be mounted by specifying the (absolute)
  53 path to the sub-directory right after "=" in the device part of the mount command.
  54
  55 Mount helper application conventions dictate that the first two options are
  56 device to be mounted and the mountpoint for that device. Options must be
  57 passed only after these fixed arguments.
  58
  59
  60 Options
  61 =======
  62
  63 Basic
  64 -----
  65
  66 :command:`conf`
  67     Path to a ceph.conf file. This is used to initialize the Ceph context
  68     for autodiscovery of monitor addresses and auth secrets. The default is
  69     to use the standard search path for ceph.conf files.
  70
  71 :command:`mount_timeout`
  72     int (seconds), Default: 60
  73
  74 :command:`ms_mode=<legacy|crc|secure|prefer-crc|prefer-secure>`
  75     Set the connection mode that the client uses for transport. The available
  76     modes are:
  77
  78     - ``legacy``: use messenger v1 protocol to talk to the cluster
  79
  80     - ``crc``: use messenger v2, without on-the-wire encryption
  81
  82     - ``secure``: use messenger v2, with on-the-wire encryption
  83
  84     - ``prefer-crc``: crc mode, if denied agree to secure mode
  85
  86     - ``prefer-secure``: secure mode, if denied agree to crc mode
  87
  88 :command:`mon_addr`
  89     Monitor address of the cluster in the form of ip_address[:port]
  90
  91 :command:`fsid`
  92     Cluster FSID. This can be found using `ceph fsid` command.
  93
  94 :command:`secret`
  95     secret key for use with CephX. This option is insecure because it exposes
  96     the secret on the command line. To avoid this, use the secretfile option.
  97
  98 :command:`secretfile`
  99     path to file containing the secret key to use with CephX
 100
 101 :command:`recover_session=<no|clean>`
 102     Set auto reconnect mode in the case where the client is blocklisted. The
 103     available modes are ``no`` and ``clean``. The default is ``no``.
 104
 105     - ``no``: never attempt to reconnect when client detects that it has been
 106       blocklisted. Blocklisted clients will not attempt to reconnect and
 107       their operations will fail too.
 108
 109     - ``clean``: client reconnects to the Ceph cluster automatically when it
 110       detects that it has been blocklisted. During reconnect, client drops
 111       dirty data/metadata, invalidates page caches and writable file handles.
 112       After reconnect, file locks become stale because the MDS loses track of
 113       them. If an inode contains any stale file locks, read/write on the inode
 114       is not allowed until applications release all stale file locks.
 115
 116 Advanced
 117 --------
 118 :command:`cap_release_safety`
 119     int, Default: calculated
 120
 121 :command:`caps_wanted_delay_max`
 122     int, cap release delay, Default: 60
 123
 124 :command:`caps_wanted_delay_min`
 125     int, cap release delay, Default: 5
 126
 127 :command:`dirstat`
 128     funky `cat dirname` for stats, Default: off
 129
 130 :command:`nodirstat`
 131     no funky `cat dirname` for stats
 132
 133 :command:`ip`
 134     my ip
 135
 136 :command:`noasyncreaddir`
 137     no dcache readdir
 138
 139 :command:`nocrc`
 140     no data crc on writes
 141
 142 :command:`noshare`
 143     create a new client instance, instead of sharing an existing instance of
 144     a client mounting the same cluster
 145
 146 :command:`osdkeepalive`
 147     int, Default: 5
 148
 149 :command:`osd_idle_ttl`
 150     int (seconds), Default: 60
 151
 152 :command:`rasize`
 153     int (bytes), max readahead. Default: 8388608 (8192*1024)
 154
 155 :command:`rbytes`
 156     Report the recursive size of the directory contents for st_size on
 157     directories.  Default: off
 158
 159 :command:`norbytes`
 160     Do not report the recursive size of the directory contents for
 161     st_size on directories.
 162
 163 :command:`readdir_max_bytes`
 164     int, Default: 524288 (512*1024)
 165
 166 :command:`readdir_max_entries`
 167     int, Default: 1024
 168
 169 :command:`rsize`
 170     int (bytes), max read size. Default: 16777216 (16*1024*1024)
 171
 172 :command:`snapdirname`
 173     string, set the name of the hidden snapdir. Default: .snap
 174
 175 :command:`write_congestion_kb`
 176     int (kb), max writeback in flight. scale with available
 177     memory. Default: calculated from available memory
 178
 179 :command:`wsize`
 180     int (bytes), max write size. Default: 16777216 (16*1024*1024) (writeback
 181     uses smaller of wsize and stripe unit)
 182
 183 :command:`wsync`
 184     Execute all namespace operations synchronously. This ensures that the
 185     namespace operation will only complete after receiving a reply from
 186     the MDS. This is the default.
 187
 188 :command:`nowsync`
 189     Allow the client to do namespace operations asynchronously. When this
 190     option is enabled, a namespace operation may complete before the MDS
 191     replies, if it has sufficient capabilities to do so.
 192
 193 Examples
 194 ========
 195
 196 Mount the full file system::
 197
 198     mount -t ceph fs_user@.mycephfs2=/ /mnt/mycephfs
 199
 200 Mount only part of the namespace/file system::
 201
 202     mount.ceph fs_user@.mycephfs2=/some/directory/in/cephfs /mnt/mycephfs
 203
 204 Pass the monitor host's IP address, optionally::
 205
 206     mount.ceph fs_user@.mycephfs2=/ /mnt/mycephfs -o mon_addr=192.168.0.1
 207
 208 Pass the port along with IP address if it's running on a non-standard port::
 209
 210     mount.ceph fs_user@.mycephfs2=/ /mnt/mycephfs -o mon_addr=192.168.0.1:7000
 211
 212 If there are multiple monitors, pass each address separated by a `/`::
 213
 214    mount.ceph fs_user@.mycephfs2=/ /mnt/mycephfs -o mon_addr=192.168.0.1/192.168.0.2/192.168.0.3
 215
 216 Pass secret key for CephX user optionally::
 217
 218     mount.ceph fs_user@.mycephfs2=/ /mnt/mycephfs -o secret=AQATSKdNGBnwLhAAnNDKnH65FmVKpXZJVasUeQ==
 219
 220 Pass file containing secret key to avoid leaving secret key in shell's command
 221 history::
 222
 223     mount.ceph fs_user@.mycephfs2=/ /mnt/mycephfs -o secretfile=/etc/ceph/fs_username.secret
 224
 225 If authentication is disabled on Ceph cluster, omit the credential related option::
 226
 227     mount.ceph fs_user@.mycephfs2=/ /mnt/mycephfs
 228
 229 Availability
 230 ============
 231
 232 **mount.ceph** is part of Ceph, a massively scalable, open-source, distributed
 233 storage system. Please refer to the Ceph documentation at https://docs.ceph.com
 234 for more information.
 235
 236 Feature Availability
 237 ====================
 238
 239 The ``recover_session=`` option was added to mainline Linux kernels in v5.4.
 240 ``wsync`` and ``nowsync`` were added in v5.7.
 241
 242 See also
 243 ========
 244
 245 :doc:`ceph-fuse <ceph-fuse>`\(8),
 246 :doc:`ceph <ceph>`\(8)