From cfe8f050359aa77823c77dd481cdbe9266f41fce Mon Sep 17 00:00:00 2001 From: Xiubo Li Date: Fri, 26 Nov 2021 16:27:17 +0800 Subject: [PATCH] doc: fix the style of the cephfs capability doc Signed-off-by: Xiubo Li --- doc/cephfs/capabilities.rst | 90 +++++++++++++++++++------------------ 1 file changed, 47 insertions(+), 43 deletions(-) diff --git a/doc/cephfs/capabilities.rst b/doc/cephfs/capabilities.rst index 0db40e51d56..e5e9bb08583 100644 --- a/doc/cephfs/capabilities.rst +++ b/doc/cephfs/capabilities.rst @@ -80,21 +80,21 @@ Abilities granted by each cap While that is how capabilities are granted (and communicated), the important bit is what they actually allow the client to do: -* PIN: this just pins the inode into memory. This is sufficient to allow the - client to get to the inode number, as well as other immutable things like +* **PIN**: this just pins the inode into memory. This is sufficient to allow + the client to get to the inode number, as well as other immutable things like major or minor numbers in a device inode, or symlink contents. -* AUTH: this grants the ability to get to the authentication-related metadata. +* **AUTH**: this grants the ability to get to the authentication-related metadata. In particular, the owner, group and mode. Note that doing a full permission check may require getting at ACLs as well, which are stored in xattrs. -* LINK: the link count of the inode +* **LINK**: the link count of the inode -* XATTR: ability to access or manipulate xattrs. Note that since ACLs are +* **XATTR**: ability to access or manipulate xattrs. Note that since ACLs are stored in xattrs, it's also sometimes necessary to access them when checking permissions. -* FILE: this is the big one. These allow the client to access and manipulate +* **FILE**: this is the big one. These allow the client to access and manipulate file data. It also covers certain metadata relating to file data -- the size, mtime, atime and ctime, in particular. @@ -130,49 +130,53 @@ it will fail. The loner client will always get all the capabilities. The filelock will control files' partial metadatas' and the file contents' access permissions. The metadatas include **mtime**, **atime**, **size**, etc. -**Fs**: Once a client has it, all other clients are denied **Fw**. +* **Fs**: Once a client has it, all other clients are denied **Fw**. -**Fx**: Only the loner client is allowed this capability. Once the lock state transitions - to LOCK_EXCL, the loner client is granted this along with all other file capabilities - except the **Fl**. +* **Fx**: Only the loner client is allowed this capability. Once the lock state + transitions to LOCK_EXCL, the loner client is granted this along with all other + file capabilities except the **Fl**. -**Fr**: Once a client has it, the **Fb** capability will be already revoked from all - the other clients. +* **Fr**: Once a client has it, the **Fb** capability will be already revoked from + all the other clients. - If clients only request to read the file, the lock state will be transferred - to LOCK_SYNC stable state directly. All the clients can be granted **Fscrl** - capabilities from the auth MDS and **Fscr** capabilities from the replica MDSes. + If clients only request to read the file, the lock state will be transferred + to LOCK_SYNC stable state directly. All the clients can be granted **Fscrl** + capabilities from the auth MDS and **Fscr** capabilities from the replica MDSes. - If multiple clients read from and write to the same file, then the lock state - will be transferred to LOCK_MIX stable state finally and all the clients could - have the **Frwl** capabilities from the auth MDS, and the **Fr** from the replica - MDSes. The **Fcb** capabilities won't be granted to all the clients and the - clients will do sync read/write. + If multiple clients read from and write to the same file, then the lock state + will be transferred to LOCK_MIX stable state finally and all the clients could + have the **Frwl** capabilities from the auth MDS, and the **Fr** from the replica + MDSes. The **Fcb** capabilities won't be granted to all the clients and the + clients will do sync read/write. -**Fw**: If there is no loner client and once a client have this capability, the **Fsxcb** - capabilities won't be granted to other clients. +* **Fw**: If there is no loner client and once a client have this capability, the + **Fsxcb** capabilities won't be granted to other clients. - If multiple clients read from and write to the same file, then the lock state - will be transferred to LOCK_MIX stable state finally and all the clients could - have the **Frwl** capabilities from the auth MDS, and the **Fr** from the replica - MDSes. The **Fcb** capabilities won't be granted to all the clients and the - clients will do sync read/write. + If multiple clients read from and write to the same file, then the lock state + will be transferred to LOCK_MIX stable state finally and all the clients could + have the **Frwl** capabilities from the auth MDS, and the **Fr** from the replica + MDSes. The **Fcb** capabilities won't be granted to all the clients and the + clients will do sync read/write. -**Fc**: This capability means the clients could cache file read and should be issued - together with **Fr** capability and only in this use case will it make sense. - While actually in some stable or interim transitional states they tend to keep - the **Fc** allowed even the **Fr** capability isn't granted as this can avoid - forcing clients to drop full caches, for example on a simple file size extension - or truncating use case. +* **Fc**: This capability means the clients could cache file read and should be + issued together with **Fr** capability and only in this use case will it make + sense. -**Fb**: This capability means the clients could buffer file write and should be issued - together with **Fw** capability and only in this use case will it make sense. - While actually in some stable or interim transitional states they tend to keep - the **Fc** allowed even the **Fw** capability isn't granted as this can avoid - forcing clients to drop dirty buffers, for example on a simple file size extension - or truncating use case. + While actually in some stable or interim transitional states they tend to keep + the **Fc** allowed even the **Fr** capability isn't granted as this can avoid + forcing clients to drop full caches, for example on a simple file size extension + or truncating use case. -**Fl**: This capability means the clients could perform lazy io. LazyIO relaxes POSIX - semantics. Buffered reads/writes are allowed even when a file is opened by multiple - applications on multiple clients. Applications are responsible for managing cache - coherency themselves. +* **Fb**: This capability means the clients could buffer file write and should be + issued together with **Fw** capability and only in this use case will it make + sense. + + While actually in some stable or interim transitional states they tend to keep + the **Fc** allowed even the **Fw** capability isn't granted as this can avoid + forcing clients to drop dirty buffers, for example on a simple file size extension + or truncating use case. + +* **Fl**: This capability means the clients could perform lazy io. LazyIO relaxes + POSIX semantics. Buffered reads/writes are allowed even when a file is opened by + multiple applications on multiple clients. Applications are responsible for managing + cache coherency themselves.