summaryrefslogtreecommitdiffstats
path: root/doc/man/8/mount.ceph.rst
diff options
context:
space:
mode:
Diffstat (limited to 'doc/man/8/mount.ceph.rst')
-rw-r--r--doc/man/8/mount.ceph.rst259
1 files changed, 259 insertions, 0 deletions
diff --git a/doc/man/8/mount.ceph.rst b/doc/man/8/mount.ceph.rst
new file mode 100644
index 000000000..fbe8790dd
--- /dev/null
+++ b/doc/man/8/mount.ceph.rst
@@ -0,0 +1,259 @@
+:orphan:
+
+========================================
+ mount.ceph -- mount a Ceph file system
+========================================
+
+.. program:: mount.ceph
+
+Synopsis
+========
+
+| **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. 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
+
+where "name" is the RADOS client name (referred to hereafter as "RADOS user",
+and meaning any individual or system actor such as an application).
+
+Mount helper can fill in the cluster FSID by reading the ceph configuration file.
+Its recommended 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 "=" 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
+passed only after these fixed arguments.
+
+
+Options
+=======
+
+Basic
+-----
+
+:command:`conf`
+ Path to a ceph.conf file. This is used to initialize the Ceph context
+ for autodiscovery of monitor addresses and auth secrets. The default is
+ to use the standard search path for ceph.conf files.
+
+:command:`mount_timeout`
+ int (seconds), Default: 60
+
+:command:`ms_mode=<legacy|crc|secure|prefer-crc|prefer-secure>`
+ Set the connection mode that the client uses for transport. The available
+ modes are:
+
+ - ``legacy``: use messenger v1 protocol to talk to the cluster
+
+ - ``crc``: use messenger v2, without on-the-wire encryption
+
+ - ``secure``: use messenger v2, with on-the-wire encryption
+
+ - ``prefer-crc``: crc mode, if denied agree to secure mode
+
+ - ``prefer-secure``: secure mode, if denied agree to crc mode
+
+: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
+ the secret on the command line. To avoid this, use the secretfile option.
+
+:command:`secretfile`
+ path to file containing the secret key to use with CephX
+
+:command:`recover_session=<no|clean>`
+ Set auto reconnect mode in the case where the client is blocklisted. The
+ available modes are ``no`` and ``clean``. The default is ``no``.
+
+ - ``no``: never attempt to reconnect when client detects that it has been
+ blocklisted. Blocklisted clients will not attempt to reconnect and
+ their operations will fail too.
+
+ - ``clean``: client reconnects to the Ceph cluster automatically when it
+ detects that it has been blocklisted. During reconnect, client drops
+ dirty data/metadata, invalidates page caches and writable file handles.
+ After reconnect, file locks become stale because the MDS loses track of
+ them. If an inode contains any stale file locks, read/write on the inode
+ is not allowed until applications release all stale file locks.
+
+:command: `fs=<fs-name>`
+ Specify the non-default file system to be mounted, when using the old syntax.
+
+:command: `mds_namespace=<fs-name>`
+ A synonym of "fs=" (Deprecated).
+
+Advanced
+--------
+:command:`cap_release_safety`
+ int, Default: calculated
+
+:command:`caps_wanted_delay_max`
+ int, cap release delay, Default: 60
+
+:command:`caps_wanted_delay_min`
+ int, cap release delay, Default: 5
+
+:command:`dirstat`
+ funky `cat dirname` for stats, Default: off
+
+:command:`nodirstat`
+ no funky `cat dirname` for stats
+
+:command:`ip`
+ my ip
+
+:command:`noasyncreaddir`
+ no dcache readdir
+
+:command:`nocrc`
+ no data crc on writes
+
+:command:`noshare`
+ create a new client instance, instead of sharing an existing instance of
+ a client mounting the same cluster
+
+:command:`osdkeepalive`
+ int, Default: 5
+
+:command:`osd_idle_ttl`
+ int (seconds), Default: 60
+
+:command:`rasize`
+ int (bytes), max readahead. Default: 8388608 (8192*1024)
+
+:command:`rbytes`
+ Report the recursive size of the directory contents for st_size on
+ directories. Default: off
+
+:command:`norbytes`
+ Do not report the recursive size of the directory contents for
+ st_size on directories.
+
+:command:`readdir_max_bytes`
+ int, Default: 524288 (512*1024)
+
+:command:`readdir_max_entries`
+ int, Default: 1024
+
+:command:`rsize`
+ int (bytes), max read size. Default: 16777216 (16*1024*1024)
+
+:command:`snapdirname`
+ string, set the name of the hidden snapdir. Default: .snap
+
+:command:`write_congestion_kb`
+ int (kb), max writeback in flight. scale with available
+ memory. Default: calculated from available memory
+
+:command:`wsize`
+ int (bytes), max write size. Default: 16777216 (16*1024*1024) (writeback
+ uses smaller of wsize and stripe unit)
+
+:command:`wsync`
+ Execute all namespace operations synchronously. This ensures that the
+ namespace operation will only complete after receiving a reply from
+ the MDS. This is the default.
+
+:command:`nowsync`
+ Allow the client to do namespace operations asynchronously. When this
+ option is enabled, a namespace operation may complete before the MDS
+ replies, if it has sufficient capabilities to do so.
+
+Examples
+========
+
+Mount the full file system::
+
+ mount -t ceph fs_user@.mycephfs2=/ /mnt/mycephfs
+
+Mount only part of the namespace/file system::
+
+ mount.ceph fs_user@.mycephfs2=/some/directory/in/cephfs /mnt/mycephfs
+
+Pass the monitor host's IP address, optionally::
+
+ 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 fs_user@.mycephfs2=/ /mnt/mycephfs -o mon_addr=192.168.0.1:7000
+
+If there are multiple monitors, pass each address separated by a `/`::
+
+ 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 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 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
+
+To mount using the old syntax::
+
+ mount -t ceph 192.168.0.1:/ /mnt/mycephfs
+
+Availability
+============
+
+**mount.ceph** is part of Ceph, a massively scalable, open-source, distributed
+storage system. Please refer to the Ceph documentation at https://docs.ceph.com
+for more information.
+
+Feature Availability
+====================
+
+The ``recover_session=`` option was added to mainline Linux kernels in v5.4.
+``wsync`` and ``nowsync`` were added in v5.7.
+
+See also
+========
+
+:doc:`ceph-fuse <ceph-fuse>`\(8),
+:doc:`ceph <ceph>`\(8)