ceph/doc/cephfs/client-auth.rst

   1 ================================
   2 CephFS Client Capabilities
   3 ================================
   4
   5 Use Ceph authentication capabilities to restrict your filesystem clients
   6 to the lowest possible level of authority needed.
   7
   8 .. note::
   9
  10     Path restriction and layout modification restriction are new features
  11     in the Jewel release of Ceph.
  12
  13 Path restriction
  14 ================
  15
  16 By default, clients are not restricted in what paths they are allowed to mount.
  17 Further, when clients mount a subdirectory, e.g., /home/user, the MDS does not
  18 by default verify that subsequent operations
  19 are ‘locked’ within that directory.
  20
  21 To restrict clients to only mount and work within a certain directory, use
  22 path-based MDS authentication capabilities.
  23
  24 Syntax
  25 ------
  26
  27 To grant rw access to the specified directory only, we mention the specified
  28 directory while creating key for a client using the following syntax. ::
  29
  30  ceph fs authorize *filesystem_name* client.*client_name* /*specified_directory* rw
  31
  32 For example, to restrict client ``foo`` to writing only in the ``bar`` directory of filesystem ``cephfs_a``, use ::
  33
  34  ceph fs authorize cephfs_a client.foo / r /bar rw
  35
  36  results in:
  37
  38  client.foo
  39    key: *key*
  40    caps: [mds] allow r, allow rw path=/bar
  41    caps: [mon] allow r
  42    caps: [osd] allow rw tag cephfs data=cephfs_a
  43
  44 To completely restrict the client to the ``bar`` directory, omit the
  45 root directory ::
  46
  47  ceph fs authorize cephfs_a client.foo /bar rw
  48
  49 Note that if a client's read access is restricted to a path, they will only
  50 be able to mount the filesystem when specifying a readable path in the
  51 mount command (see below).
  52
  53 Supplying ``all`` or ``*`` as the filesystem name will grant access to every
  54 file system. Note that it is usually necessary to quote ``*`` to protect it from
  55 the shell.
  56
  57 See `User Management - Add a User to a Keyring`_. for additional details on user management
  58
  59 To restrict a client to the specified sub-directory only, we mention the specified
  60 directory while mounting using the following syntax. ::
  61
  62  ./ceph-fuse -n client.*client_name* *mount_path* -r *directory_to_be_mounted*
  63
  64 for example, to restrict client ``foo`` to ``mnt/bar`` directory, we will use. ::
  65
  66  ./ceph-fuse -n client.foo mnt -r /bar
  67
  68 Free space reporting
  69 --------------------
  70
  71 By default, when a client is mounting a sub-directory, the used space (``df``)
  72 will be calculated from the quota on that sub-directory, rather than reporting
  73 the overall amount of space used on the cluster.
  74
  75 If you would like the client to report the overall usage of the filesystem,
  76 and not just the quota usage on the sub-directory mounted, then set the
  77 following config option on the client:
  78
  79 ::
  80
  81     client quota df = false
  82
  83 If quotas are not enabled, or no quota is set on the sub-directory mounted,
  84 then the overall usage of the filesystem will be reported irrespective of
  85 the value of this setting.
  86
  87 Layout and Quota restriction (the 'p' flag)
  88 ===========================================
  89
  90 To set layouts or quotas, clients require the 'p' flag in addition to 'rw'.
  91 This restricts all the attributes that are set by special extended attributes
  92 with a "ceph." prefix, as well as restricting other means of setting
  93 these fields (such as openc operations with layouts).
  94
  95 For example, in the following snippet client.0 can modify layouts and quotas
  96 on the filesystem cephfs_a, but client.1 cannot.
  97
  98 ::
  99
 100     client.0
 101         key: AQAz7EVWygILFRAAdIcuJ12opU/JKyfFmxhuaw==
 102         caps: [mds] allow rwp
 103         caps: [mon] allow r
 104         caps: [osd] allow rw tag cephfs data=cephfs_a
 105
 106     client.1
 107         key: AQAz7EVWygILFRAAdIcuJ12opU/JKyfFmxhuaw==
 108         caps: [mds] allow rw
 109         caps: [mon] allow r
 110         caps: [osd] allow rw tag cephfs data=cephfs_a
 111
 112
 113 Snapshot restriction (the 's' flag)
 114 ===========================================
 115
 116 To create or delete snapshots, clients require the 's' flag in addition to 'rw'.
 117 Note that when capability string also contains the 'p' flag, the 's' flag must
 118 appear after it (all flags except 'rw' must be specified in alphabetical order).
 119
 120 For example, in the following snippet client.0 can create or delete snapshots
 121 in the ``bar`` directory of filesystem ``cephfs_a``.
 122
 123 ::
 124
 125     client.0
 126         key: AQAz7EVWygILFRAAdIcuJ12opU/JKyfFmxhuaw==
 127         caps: [mds] allow rw, allow rws path=/bar
 128         caps: [mon] allow r
 129         caps: [osd] allow rw tag cephfs data=cephfs_a
 130
 131
 132 .. _User Management - Add a User to a Keyring: ../../rados/operations/user-management/#add-a-user-to-a-keyring
 133
 134 Network restriction
 135 ===================
 136
 137 ::
 138
 139  client.foo
 140    key: *key*
 141    caps: [mds] allow r network 10.0.0.0/8, allow rw path=/bar network 10.0.0.0/8
 142    caps: [mon] allow r network 10.0.0.0/8
 143    caps: [osd] allow rw tag cephfs data=cephfs_a network 10.0.0.0/8
 144
 145 The optional ``{network/prefix}`` is a standard network name and
 146 prefix length in CIDR notation (e.g., ``10.3.0.0/16``).  If present,
 147 the use of this capability is restricted to clients connecting from
 148 this network.