ceph/doc/cephfs/mount-prerequisites.rst

   1 Mount CephFS: Prerequisites
   2 ===========================
   3
   4 You can use CephFS by mounting it to your local filesystem or by using
   5 `cephfs-shell`_. CephFS can be mounted `using kernel`_ as well as `using
   6 FUSE`_. Both have their own advantages. Read the following section to
   7 understand more about both of these ways to mount CephFS.
   8
   9 For Windows CephFS mounts, please check the `ceph-dokan`_ page.
  10
  11 Which CephFS Client?
  12 --------------------
  13
  14 The FUSE client is the most accessible and the easiest to upgrade to the
  15 version of Ceph used by the storage cluster, while the kernel client will
  16 always gives better performance.
  17
  18 When encountering bugs or performance issues, it is often instructive to
  19 try using the other client, in order to find out whether the bug was
  20 client-specific or not (and then to let the developers know).
  21
  22 General Pre-requisite for Mounting CephFS
  23 -----------------------------------------
  24 Before mounting CephFS, ensure that the client host (where CephFS has to be
  25 mounted and used) has a copy of the Ceph configuration file (i.e.
  26 ``ceph.conf``) and a keyring of the CephX user that has permission to access
  27 the MDS. Both of these files must already be present on the host where the
  28 Ceph MON resides.
  29
  30 #. Generate a minimal conf file for the client host and place it at a
  31    standard location::
  32
  33     # on client host
  34     mkdir -p -m 755 /etc/ceph
  35     ssh {user}@{mon-host} "sudo ceph config generate-minimal-conf" | sudo tee /etc/ceph/ceph.conf
  36
  37    Alternatively, you may copy the conf file. But the above method generates
  38    a conf with minimal details which is usually sufficient. For more
  39    information, see `Client Authentication`_ and :ref:`bootstrap-options`.
  40
  41 #. Ensure that the conf has appropriate permissions::
  42
  43     chmod 644 /etc/ceph/ceph.conf
  44
  45 #. Create a CephX user and get its secret key::
  46
  47     ssh {user}@{mon-host} "sudo ceph fs authorize cephfs client.foo / rw" | sudo tee /etc/ceph/ceph.client.foo.keyring
  48
  49    In above command, replace ``cephfs`` with the name of your CephFS, ``foo``
  50    by the name you want for your CephX user and ``/`` by the path within your
  51    CephFS for which you want to allow access to the client host and ``rw``
  52    stands for both read and write permissions. Alternatively, you may copy the
  53    Ceph keyring from the MON host to client host at ``/etc/ceph`` but creating
  54    a keyring specific to the client host is better. While creating a CephX
  55    keyring/client, using same client name across multiple machines is perfectly
  56    fine.
  57
  58    .. note:: If you get 2 prompts for password while running above any of 2
  59              above command, run ``sudo ls`` (or any other trivial command with
  60              sudo) immediately before these commands.
  61
  62 #. Ensure that the keyring has appropriate permissions::
  63
  64     chmod 600 /etc/ceph/ceph.client.foo.keyring
  65
  66 .. note:: There might be few more prerequisites for kernel and FUSE mounts
  67    individually, please check respective mount documents.
  68
  69 .. _Client Authentication: ../client-auth
  70 .. _cephfs-shell: ../cephfs-shell
  71 .. _using kernel: ../mount-using-kernel-driver
  72 .. _using FUSE: ../mount-using-fuse
  73 .. _ceph-dokan: ../ceph-dokan