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 following the undermentioned syntax. ::
  29
  30 ./ceph auth get-or-create client.*client_name* mon 'allow r' mds 'allow r, allow rw path=/*specified_directory*' osd 'allow rw pool=data'
  31
  32 for example, to restrict client ``foo`` to writing only in the ``bar`` directory,
  33 we will use: ::
  34
  35 ./ceph auth get-or-create client.foo mon 'allow r' mds 'allow r, allow rw path=/bar' osd 'allow rw pool=data'
  36
  37 To completely restrict the client to the ``bar`` directory, omit the
  38 unqualified "allow r" clause: ::
  39
  40 ./ceph auth get-or-create client.foo mon 'allow r' mds 'allow rw path=/bar' osd 'allow rw pool=data'
  41
  42 Note that if a client's read access is restricted to a path, they will only
  43 be able to mount the filesystem when specifying a readable path in the
  44 mount command (see below).
  45
  46
  47 See `User Management - Add a User to a Keyring`_. for additional details on user management
  48
  49 To restrict a client to the specfied sub-directory only, we mention the specified
  50 directory while mounting following the undermentioned syntax. ::
  51
  52 ./ceph-fuse -n client.*client_name* *mount_path* -r *directory_to_be_mounted*
  53
  54 for example, to restrict client ``foo`` to ``mnt/bar`` directory, we will use. ::
  55
  56 ./ceph-fuse -n client.foo mnt -r /bar
  57
  58 Free space reporting
  59 --------------------
  60
  61 By default, when a client is mounting a sub-directory, the used space (``df``)
  62 will be calculated from the quota on that sub-directory, rather than reporting
  63 the overall amount of space used on the cluster.
  64
  65 If you would like the client to report the overall usage of the filesystem,
  66 and not just the quota usage on the sub-directory mounted, then set the
  67 following config option on the client:
  68
  69 ::
  70
  71     client quota df = false
  72
  73 If quotas are not enabled, or no quota is set on the sub-directory mounted,
  74 then the overall usage of the filesystem will be reported irrespective of
  75 the value of this setting.
  76
  77 OSD restriction
  78 ===============
  79
  80 To prevent clients from writing or reading data to pools other than
  81 those in use for CephFS, set an OSD authentication capability that
  82 restricts access to the CephFS data pool(s):
  83
  84 ::
  85
  86     client.0
  87         key: AQAz7EVWygILFRAAdIcuJ12opU/JKyfFmxhuaw==
  88         caps: [mds] allow rw
  89         caps: [mon] allow r
  90         caps: [osd] allow rw pool=data1, allow rw pool=data2
  91
  92 .. note::
  93
  94     Without a corresponding MDS path restriction, the OSD capabilities above do
  95     **not** restrict file deletions outside of the ``data1`` and ``data2``
  96     pools.
  97
  98 You may also restrict clients from writing data by using 'r' instead of
  99 'rw' in OSD capabilities.  This does not affect the ability of the client
 100 to update filesystem metadata for these files, but it will prevent them
 101 from persistently writing data in a way that would be visible to other clients.
 102
 103 Layout and Quota restriction (the 'p' flag)
 104 ===========================================
 105
 106 To set layouts or quotas, clients require the 'p' flag in addition to 'rw'.
 107 This restricts all the attributes that are set by special extended attributes
 108 with a "ceph." prefix, as well as restricting other means of setting
 109 these fields (such as openc operations with layouts).
 110
 111 For example, in the following snippet client.0 can modify layouts and quotas,
 112 but client.1 cannot.
 113
 114 ::
 115
 116     client.0
 117         key: AQAz7EVWygILFRAAdIcuJ12opU/JKyfFmxhuaw==
 118         caps: [mds] allow rwp
 119         caps: [mon] allow r
 120         caps: [osd] allow rw pool=data
 121
 122     client.1
 123         key: AQAz7EVWygILFRAAdIcuJ12opU/JKyfFmxhuaw==
 124         caps: [mds] allow rw
 125         caps: [mon] allow r
 126         caps: [osd] allow rw pool=data
 127
 128
 129 .. _User Management - Add a User to a Keyring: ../../rados/operations/user-management/#add-a-user-to-a-keyring