doc/cephfs: document the pool_namespace layout attr

...including the new ability to clear it.

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

diff --git a/doc/cephfs/file-layouts.rst b/doc/cephfs/file-layouts.rst
index c09d8f548ed3e6e525273013087f38e9ce4e5078..e72fa69b062595606f19833054f2cfb6197a8daa 100644 (file)
--- a/doc/cephfs/file-layouts.rst
+++ b/doc/cephfs/file-layouts.rst
@@ -21,6 +21,10 @@ Layout fields
 pool
     String, giving ID or name.  Which RADOS pool a file's data objects will be stored in.
 
+pool_namespace
+    String.  Within the data pool, which RADOS namespace the objects will
+    be written to.  Empty by default (i.e. default namespace).
+
 stripe_unit
     Integer in bytes.  The size (in bytes) of a block of data used in the RAID 0 distribution of a file. All stripe units for a file have equal size. The last stripe unit is typically incomplete–i.e. it represents the data at the end of the file as well as unused “space” beyond it up to the end of the fixed stripe unit size.
 
@@ -111,6 +115,33 @@ Layout fields are modified using ``setfattr``:
     $ setfattr -n ceph.file.layout.stripe_count -v 4 file1
     setfattr: file1: Directory not empty
     
+Clearing layouts
+----------------
+
+If you wish to remove an explicit layout from a directory, to revert to
+inherting the layout of its ancestor, you can do so:
+
+.. code-block:: bash
+
+    setfattr -x ceph.dir.layout mydir
+
+Similarly, if you have set the ``pool_namespace`` attribute and wish
+to modify the layout to use the default namespace instead:
+
+.. code-block:: bash
+
+    # Create a dir and set a namespace on it
+    mkdir mydir
+    setfattr -n ceph.dir.layout.pool_namespace -v foons mydir
+    getfattr -n ceph.dir.layout mydir
+    ceph.dir.layout="stripe_unit=4194304 stripe_count=1 object_size=4194304 pool=cephfs_data_a pool_namespace=foons"
+
+    # Clear the namespace from the directory's layout
+    setfattr -x ceph.dir.layout.pool_namespace mydir
+    getfattr -n ceph.dir.layout mydir
+    ceph.dir.layout="stripe_unit=4194304 stripe_count=1 object_size=4194304 pool=cephfs_data_a"
+
+
 Inheritance of layouts
 ----------------------