doc: flesh out MDS auth docs

...including updating for 'rwp'.

Signed-off-by: John Spray <john.spray@redhat.com>

diff --git a/doc/cephfs/client-auth.rst b/doc/cephfs/client-auth.rst
new file mode 100644 (file)
index 0000000..ad4af2d
--- /dev/null
+++ b/doc/cephfs/client-auth.rst
@@ -0,0 +1,81 @@
+================================
+CephFS Client Capabilities
+================================
+
+Use Ceph authentication capabilities to restrict your filesystem clients
+to the lowest possible level of authority needed.
+
+Path restriction
+================
+
+By default, clients are not restricted in what paths they are allowed to mount.
+Further, when clients mount a subdirectory, e.g., /home/user, the MDS does not
+by default verify that subsequent operations
+are ‘locked’ within that directory.
+
+To restrict clients to only mount and work within a certain directory, use
+path-based MDS authentication capabilities.
+
+Syntax
+------
+
+To grant rw access to the specified directory only, we mention the specified
+directory while creating key for a client following the undermentioned syntax. ::
+
+./ceph auth get-or-create client.*client_name* mon 'allow r' mds 'allow r, allow rw path=/*specified_directory*' osd 'allow rw pool=data'
+
+for example, to restrict client ``foo`` to ``bar`` directory, we will use. ::
+
+./ceph auth get-or-create client.foo mon 'allow r' mds 'allow r, allow rw path=/bar' osd 'allow rw pool=data'
+
+
+To restrict a client to the specfied sub-directory only, we mention the specified
+directory while mounting following the undermentioned syntax. ::
+
+./ceph-fuse -n client.*client_name* *mount_path* -r *directory_to_be_mounted*
+
+for example, to restrict client ``foo`` to ``mnt/bar`` directory, we will use. ::
+
+./ceph-fuse -n client.foo mnt -r /bar
+
+OSD restriction
+===============
+
+To prevent clients from writing or reading data to pools other than
+those in use for CephFS, set an OSD authentication capability that
+restricts access to the CephFS data pool(s):
+
+::
+    client.0
+        key: AQAz7EVWygILFRAAdIcuJ12opU/JKyfFmxhuaw==
+        caps: [mds] allow rw
+        caps: [mon] allow r
+        caps: [osd] allow rw pool=data1, allow rw pool=data2
+
+You may also restrict clients from writing data by using 'r' instead of
+'rw' in OSD capabilities.  This does not affect the ability of the client
+to update filesystem metadata for these files, but it will prevent them
+from persistently writing data in a way that would be visible to other clients.
+
+Layout modification restriction
+===============================
+
+To prevent clients from modifying the data pool used for files or
+directories, use the 'p' modifier in MDS authentication capabilities.
+
+For example, in the following snippet client.0 can modify the pool used
+for files, but client.1 cannot.
+
+::
+    client.0
+        key: AQAz7EVWygILFRAAdIcuJ12opU/JKyfFmxhuaw==
+        caps: [mds] allow rwp
+        caps: [mon] allow r
+        caps: [osd] allow rw pool=data
+
+    client.1
+        key: AQAz7EVWygILFRAAdIcuJ12opU/JKyfFmxhuaw==
+        caps: [mds] allow rw
+        caps: [mon] allow r
+        caps: [osd] allow rw pool=data
+

diff --git a/doc/cephfs/index.rst b/doc/cephfs/index.rst
index 67e1468b64778ab6bcfc0baff5522f4c877eea80..63dfad7fa3542a5e0c4d122a27a0ad12245857e1 100644 (file)
--- a/doc/cephfs/index.rst
+++ b/doc/cephfs/index.rst
@@ -90,6 +90,7 @@ authentication keyring.
        Handling full filesystems <full>
        Troubleshooting <troubleshooting>
        Disaster recovery <disaster-recovery>
+       Client authentication <client-auth>
 
 .. raw:: html
 

diff --git a/doc/cephfs/path-based restriction.rst b/doc/cephfs/path-based restriction.rst
deleted file mode 100644 (file)
index 8522efc..0000000
--- a/doc/cephfs/path-based restriction.rst
+++ /dev/null
@@ -1,31 +0,0 @@
-================================
- Restrict Access to a Directory
-================================
-
-CephFS mostly assumes a controlled environment where clients are not restricted
-in what paths they are allowed to mount. And if they do mount a subdirectory,
-e.g., /home/user, the MDS does not currently verify that subsequent operations
-are ‘locked’ within that directory. Path-based restriction allows us to restrict
-a client to a particular directory in the file system.
-
-Syntax
-======
-
-To grant rw access to the specified directory only, we mention the specified
-directory while creating key for a client following the undermentioned syntax. ::
-
-./ceph auth get-or-create client.*client_name* mon 'allow r' mds 'allow r, allow rw path=/*specified_directory*' osd 'allow rwx'
-
-for example, to restrict client ``foo`` to ``bar`` directory, we will use. ::
-
-./ceph auth get-or-create client.foo mon 'allow r' mds 'allow r, allow rw path=/bar' osd 'allow rwx'
-
-
-To restrict a client to the specfied sub-directory only, we mention the specified
-directory while mounting following the undermentioned syntax. ::
-
-./ceph-fuse -n client.*client_name* *mount_path* -r *directory_to_be_mounted*
-
-for example, to restrict client ``foo`` to ``mnt/bar`` directory, we will use. ::
-
-./ceph-fuse -n client.foo mnt -r /bar