ceph/doc/cephfs/mount-using-fuse.rst

   1 ========================
   2  Mount CephFS using FUSE
   3 ========================
   4
   5 `ceph-fuse`_ is an alternate way of mounting CephFS, although it mounts it
   6 in userspace. Therefore, performance of FUSE can be relatively lower but FUSE
   7 clients can be more manageable, especially while upgrading CephFS.
   8
   9 Prerequisites
  10 =============
  11
  12 Complete General Prerequisites
  13 ------------------------------
  14 Go through the prerequisites required by both, kernel as well as FUSE mounts,
  15 in `Mount CephFS: Prerequisites`_ page.
  16
  17 ``fuse.conf`` option
  18 --------------------
  19
  20 #. If you are mounting Ceph with FUSE not as superuser/root user/system admin
  21    you would need to add the option ``user_allow_other`` to ``/etc/fuse.conf``
  22    (under no section in the conf).
  23
  24 Synopsis
  25 ========
  26 In general, the command to mount CephFS via FUSE looks like this::
  27
  28     ceph-fuse {mountpoint} {options}
  29
  30 Mounting CephFS
  31 ===============
  32 To FUSE-mount the Ceph file system, use the ``ceph-fuse`` command::
  33
  34     mkdir /mnt/mycephfs
  35     ceph-fuse --id foo /mnt/mycephfs
  36
  37 Option ``-id`` passes the name of the CephX user whose keyring we intend to
  38 use for mounting CephFS. In the above command, it's ``foo``. You can also use
  39 ``-n`` instead, although ``--id`` is evidently easier::
  40
  41     ceph-fuse -n client.foo /mnt/mycephfs
  42
  43 In case the keyring is not present in standard locations, you may pass it
  44 too::
  45
  46     ceph-fuse --id foo -k /path/to/keyring /mnt/mycephfs
  47
  48 You may pass the MON's socket too, although this is not mandatory::
  49
  50     ceph-fuse --id foo -m 192.168.0.1:6789 /mnt/mycephfs
  51
  52 You can also mount a specific directory within CephFS instead of mounting
  53 root of CephFS on your local FS::
  54
  55     ceph-fuse --id foo -r /path/to/dir /mnt/mycephfs
  56
  57 If you have more than one FS on your Ceph cluster, use the option
  58 ``--client_fs`` to mount the non-default FS::
  59
  60     ceph-fuse --id foo --client_fs mycephfs2 /mnt/mycephfs2
  61
  62 You may also add a ``client_fs`` setting to your ``ceph.conf``
  63
  64 Unmounting CephFS
  65 =================
  66
  67 Use ``umount`` to unmount CephFS like any other FS::
  68
  69     umount /mnt/mycephfs
  70
  71 .. tip:: Ensure that you are not within the file system directories before
  72    executing this command.
  73
  74 Persistent Mounts
  75 =================
  76
  77 To mount CephFS as a file system in user space, add the following to ``/etc/fstab``::
  78
  79        #DEVICE PATH       TYPE      OPTIONS
  80        none    /mnt/mycephfs  fuse.ceph ceph.id={user-ID}[,ceph.conf={path/to/conf.conf}],_netdev,defaults  0 0
  81
  82 For example::
  83
  84        none    /mnt/mycephfs  fuse.ceph ceph.id=myuser,_netdev,defaults  0 0
  85        none    /mnt/mycephfs  fuse.ceph ceph.id=myuser,ceph.conf=/etc/ceph/foo.conf,_netdev,defaults  0 0
  86
  87 Ensure you use the ID (e.g., ``myuser``, not ``client.myuser``). You can pass
  88 any valid ``ceph-fuse`` option to the command line this way.
  89
  90 To mount a subdirectory of the CephFS, add the following to ``/etc/fstab``::
  91
  92        none    /mnt/mycephfs  fuse.ceph ceph.id=myuser,ceph.client_mountpoint=/path/to/dir,_netdev,defaults  0 0
  93
  94 ``ceph-fuse@.service`` and ``ceph-fuse.target`` systemd units are available.
  95 As usual, these unit files declare the default dependencies and recommended
  96 execution context for ``ceph-fuse``. After making the fstab entry shown above,
  97 run following commands::
  98
  99     systemctl start ceph-fuse@/mnt/mycephfs.service
 100     systemctl enable ceph-fuse.target
 101     systemctl enable ceph-fuse@-mnt-mycephfs.service
 102
 103 See :ref:`User Management <user-management>` for details on CephX user management and `ceph-fuse`_
 104 manual for more options it can take. For troubleshooting, see
 105 :ref:`ceph_fuse_debugging`.
 106
 107 .. _ceph-fuse: ../../man/8/ceph-fuse/#options
 108 .. _Mount CephFS\: Prerequisites: ../mount-prerequisites