src/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``, use ::
  33
  34  ceph fs authorize cephfs client.foo / r /bar rw
  35
  36 To completely restrict the client to the ``bar`` directory, omit the
  37 root directory ::
  38
  39  ceph fs authorize cephfs client.foo /bar rw
  40
  41 Note that if a client's read access is restricted to a path, they will only
  42 be able to mount the filesystem when specifying a readable path in the
  43 mount command (see below).
  44
  45
  46 See `User Management - Add a User to a Keyring`_. for additional details on user management
  47
  48 To restrict a client to the specfied sub-directory only, we mention the specified
  49 directory while mounting using the following syntax. ::
  50
  51  ./ceph-fuse -n client.*client_name* *mount_path* -r *directory_to_be_mounted*
  52
  53 for example, to restrict client ``foo`` to ``mnt/bar`` directory, we will use. ::
  54
  55  ./ceph-fuse -n client.foo mnt -r /bar
  56
  57 Free space reporting
  58 --------------------
  59
  60 By default, when a client is mounting a sub-directory, the used space (``df``)
  61 will be calculated from the quota on that sub-directory, rather than reporting
  62 the overall amount of space used on the cluster.
  63
  64 If you would like the client to report the overall usage of the filesystem,
  65 and not just the quota usage on the sub-directory mounted, then set the
  66 following config option on the client:
  67
  68 ::
  69
  70     client quota df = false
  71
  72 If quotas are not enabled, or no quota is set on the sub-directory mounted,
  73 then the overall usage of the filesystem will be reported irrespective of
  74 the value of this setting.
  75
  76 Layout and Quota restriction (the 'p' flag)
  77 ===========================================
  78
  79 To set layouts or quotas, clients require the 'p' flag in addition to 'rw'.
  80 This restricts all the attributes that are set by special extended attributes
  81 with a "ceph." prefix, as well as restricting other means of setting
  82 these fields (such as openc operations with layouts).
  83
  84 For example, in the following snippet client.0 can modify layouts and quotas,
  85 but client.1 cannot.
  86
  87 ::
  88
  89     client.0
  90         key: AQAz7EVWygILFRAAdIcuJ12opU/JKyfFmxhuaw==
  91         caps: [mds] allow rwp
  92         caps: [mon] allow r
  93         caps: [osd] allow rw pool=data
  94
  95     client.1
  96         key: AQAz7EVWygILFRAAdIcuJ12opU/JKyfFmxhuaw==
  97         caps: [mds] allow rw
  98         caps: [mon] allow r
  99         caps: [osd] allow rw pool=data
 100
 101
 102 .. _User Management - Add a User to a Keyring: ../../rados/operations/user-management/#add-a-user-to-a-keyring