[e2fsprogs PATCH 0/6] chattr.1 updates

[e2fsprogs PATCH 0/6] chattr.1 updates

[Eric Biggers]

This series updates the chattr(1) man page to document the verity file
attribute ('V'), improve the documentation for the encryption file
attribute ('E'), and make a few other cleanups.

Eric Biggers (6):
  chattr.1: document the verity attribute
  chattr.1: adjust documentation for encryption attribute
  chattr.1: add casefold attribute to mode string
  chattr.1: fix some grammatical errors
  chattr.1: clarify that ext4 doesn't support tail-merging either
  chattr.1: say "cleared" instead of "reset"

 misc/chattr.1.in | 40 +++++++++++++++++++++++++---------------
 1 file changed, 25 insertions(+), 15 deletions(-)

-- 
2.24.0

[PATCH 1/6] chattr.1: document the verity attribute

[Eric Biggers]

From: Eric Biggers <ebiggers@google.com>

Document the verity file attribute ('V').

Signed-off-by: Eric Biggers <ebiggers@google.com>
---
 misc/chattr.1.in | 12 +++++++++++-
 1 file changed, 11 insertions(+), 1 deletion(-)

diff --git a/misc/chattr.1.in b/misc/chattr.1.in
index 1c9e8964..2122a13e 100644
--- a/misc/chattr.1.in
+++ b/misc/chattr.1.in
@@ -52,7 +52,8 @@ The following attributes are read-only, and may be listed by
 but not modified by chattr:
 encrypted (E),
 indexed directory (I),
-and inline data (N).
+inline data (N),
+and verity (V).
 .PP
 Not all flags are supported or utilized by all filesystems; refer to
 filesystem-specific man pages such as
@@ -189,6 +190,15 @@ saved.  This allows the user to ask for its undeletion.  Note: please
 make sure to read the bugs and limitations section at the end of this
 document.
 .PP
+A file with the 'V' attribute set has fs-verity enabled.  It cannot be
+written to, and the filesystem will automatically verify all data read
+from it against a cryptographic hash that covers the entire file's
+contents, e.g. via a Merkle tree.  This makes it possible to efficiently
+authenticate the file.  This attribute may not be set or reset using
+.BR chattr (1),
+although it can be displayed by
+.BR lsattr (1).
+.PP
 .SH AUTHOR
 .B chattr
 was written by Remy Card <Remy.Card@linux.org>.  It is currently being
-- 
2.24.0

[PATCH 2/6] chattr.1: adjust documentation for encryption attribute

[Eric Biggers]

From: Eric Biggers <ebiggers@google.com>

Adjust the documentation for the encryption attribute ('E') to clarify
that encryption isn't experimental anymore and isn't restricted to
regular files, and that the encryption is done by the filesystem.

Signed-off-by: Eric Biggers <ebiggers@google.com>
---
 misc/chattr.1.in | 5 ++---
 1 file changed, 2 insertions(+), 3 deletions(-)

diff --git a/misc/chattr.1.in b/misc/chattr.1.in
index 2122a13e..18b316e3 100644
--- a/misc/chattr.1.in
+++ b/misc/chattr.1.in
@@ -114,9 +114,8 @@ The 'e' attribute indicates that the file is using extents for mapping
 the blocks on disk.  It may not be removed using
 .BR chattr (1).
 .PP
-The 'E' attribute is used by the experimental encryption patches to
-indicate that the file has been encrypted.  It may not be
-set or reset using
+A file, directory, or symlink with the 'E' attribute set is encrypted by the
+filesystem.  This attribute may not be set or reset using
 .BR chattr (1),
 although it can be displayed by
 .BR lsattr (1).
-- 
2.24.0

[PATCH 3/6] chattr.1: add casefold attribute to mode string

[Eric Biggers]

From: Eric Biggers <ebiggers@google.com>

When the casefold attribute ('F') was added to the chattr man page, it
was forgotten to add it to the mode string.  Add it.

Signed-off-by: Eric Biggers <ebiggers@google.com>
---
 misc/chattr.1.in | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/misc/chattr.1.in b/misc/chattr.1.in
index 18b316e3..1baacf17 100644
--- a/misc/chattr.1.in
+++ b/misc/chattr.1.in
@@ -23,7 +23,7 @@ chattr \- change file attributes on a Linux file system
 .B chattr
 changes the file attributes on a Linux file system.
 .PP
-The format of a symbolic mode is +-=[aAcCdDeijPsStTu].
+The format of a symbolic mode is +-=[aAcCdDeFijPsStTu].
 .PP
 The operator '+' causes the selected attributes to be added to the
 existing attributes of the files; '-' causes them to be removed; and '='
-- 
2.24.0

[PATCH 4/6] chattr.1: fix some grammatical errors

[Eric Biggers]

From: Eric Biggers <ebiggers@google.com>

- "can only be open" => "can only be opened"
- "is not candidate" => "is not a candidate"
- "written ... on the disk" => "written ... to the disk"

Signed-off-by: Eric Biggers <ebiggers@google.com>
---
 misc/chattr.1.in | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/misc/chattr.1.in b/misc/chattr.1.in
index 1baacf17..cc751fe8 100644
--- a/misc/chattr.1.in
+++ b/misc/chattr.1.in
@@ -79,9 +79,9 @@ Set the file's version/generation number.
 .BI \-p " project"
 Set the file's project number.
 .SH ATTRIBUTES
-A file with the 'a' attribute set can only be open in append mode for writing.
-Only the superuser or a process possessing the CAP_LINUX_IMMUTABLE
-capability can set or clear this attribute.
+A file with the 'a' attribute set can only be opened in append mode for
+writing.  Only the superuser or a process possessing the
+CAP_LINUX_IMMUTABLE capability can set or clear this attribute.
 .PP
 When a file with the 'A' attribute set is accessed, its atime record is
 not modified.  This avoids a certain amount of disk I/O for laptop
@@ -102,12 +102,12 @@ be fully stable.  If the 'C' flag is set on a directory, it will have no
 effect on the directory, but new files created in that directory will
 have the No_COW attribute set.)
 .PP
-A file with the 'd' attribute set is not candidate for backup when the
+A file with the 'd' attribute set is not a candidate for backup when the
 .BR dump (8)
 program is run.
 .PP
 When a directory with the 'D' attribute set is modified,
-the changes are written synchronously on the disk; this is equivalent to
+the changes are written synchronously to the disk; this is equivalent to
 the 'dirsync' mount option applied to a subset of the files.
 .PP
 The 'e' attribute indicates that the file is using extents for mapping
@@ -164,7 +164,7 @@ and written back to the disk.  Note: please make sure to read the bugs
 and limitations section at the end of this document.
 .PP
 When a file with the 'S' attribute set is modified,
-the changes are written synchronously on the disk; this is equivalent to
+the changes are written synchronously to the disk; this is equivalent to
 the 'sync' mount option applied to a subset of the files.
 .PP
 A file with the 't' attribute will not have a partial block fragment at
-- 
2.24.0

[PATCH 5/6] chattr.1: clarify that ext4 doesn't support tail-merging either

[Eric Biggers]

From: Eric Biggers <ebiggers@google.com>

This old text was never updated to mention ext4 in addition to ext2 and
ext3.  Do so now.  Also don't bother to mention old unmerged patches.

Signed-off-by: Eric Biggers <ebiggers@google.com>
---
 misc/chattr.1.in | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/misc/chattr.1.in b/misc/chattr.1.in
index cc751fe8..870397ae 100644
--- a/misc/chattr.1.in
+++ b/misc/chattr.1.in
@@ -171,8 +171,8 @@ A file with the 't' attribute will not have a partial block fragment at
 the end of the file merged with other files (for those filesystems which
 support tail-merging).  This is necessary for applications such as LILO
 which read the filesystem directly, and which don't understand tail-merged
-files.  Note: As of this writing, the ext2 or ext3 filesystems do not
-(yet, except in very experimental patches) support tail-merging.
+files.  Note: As of this writing, the ext2, ext3, and ext4 filesystems do
+not support tail-merging.
 .PP
 A directory with the 'T' attribute will be deemed to be the top of
 directory hierarchies for the purposes of the Orlov block allocator.
-- 
2.24.0

[PATCH 6/6] chattr.1: say "cleared" instead of "reset"

[Eric Biggers]

From: Eric Biggers <ebiggers@google.com>

Setting a bit to 0 is normally called "clearing", not "resetting"; and
chattr.1 already says "clear" in some places.  Use "clear" consistently.

Signed-off-by: Eric Biggers <ebiggers@google.com>
---
 misc/chattr.1.in | 9 +++++----
 1 file changed, 5 insertions(+), 4 deletions(-)

diff --git a/misc/chattr.1.in b/misc/chattr.1.in
index 870397ae..66e791db 100644
--- a/misc/chattr.1.in
+++ b/misc/chattr.1.in
@@ -115,7 +115,7 @@ the blocks on disk.  It may not be removed using
 .BR chattr (1).
 .PP
 A file, directory, or symlink with the 'E' attribute set is encrypted by the
-filesystem.  This attribute may not be set or reset using
+filesystem.  This attribute may not be set or cleared using
 .BR chattr (1),
 although it can be displayed by
 .BR lsattr (1).
@@ -132,7 +132,7 @@ Only the superuser or a process possessing the CAP_LINUX_IMMUTABLE
 capability can set or clear this attribute.
 .PP
 The 'I' attribute is used by the htree code to indicate that a directory
-is being indexed using hashed trees.  It may not be set or reset using
+is being indexed using hashed trees.  It may not be set or cleared using
 .BR chattr (1),
 although it can be displayed by
 .BR lsattr (1).
@@ -146,7 +146,8 @@ attribute has no effect.  Only the superuser or a process possessing the
 CAP_SYS_RESOURCE capability can set or clear this attribute.
 .PP
 A file with the 'N' attribute set indicates that the file has data
-stored inline, within the inode itself. It may not be set or reset using
+stored inline, within the inode itself. It may not be set or cleared
+using
 .BR chattr (1),
 although it can be displayed by
 .BR lsattr (1).
@@ -193,7 +194,7 @@ A file with the 'V' attribute set has fs-verity enabled.  It cannot be
 written to, and the filesystem will automatically verify all data read
 from it against a cryptographic hash that covers the entire file's
 contents, e.g. via a Merkle tree.  This makes it possible to efficiently
-authenticate the file.  This attribute may not be set or reset using
+authenticate the file.  This attribute may not be set or cleared using
 .BR chattr (1),
 although it can be displayed by
 .BR lsattr (1).
-- 
2.24.0

Re: [e2fsprogs PATCH 0/6] chattr.1 updates

[Theodore Y. Ts'o]

On Sun, Nov 17, 2019 at 05:48:46PM -0800, Eric Biggers wrote:
> This series updates the chattr(1) man page to document the verity file
> attribute ('V'), improve the documentation for the encryption file
> attribute ('E'), and make a few other cleanups.
> 
> Eric Biggers (6):
>   chattr.1: document the verity attribute
>   chattr.1: adjust documentation for encryption attribute
>   chattr.1: add casefold attribute to mode string
>   chattr.1: fix some grammatical errors
>   chattr.1: clarify that ext4 doesn't support tail-merging either
>   chattr.1: say "cleared" instead of "reset"
> 
>  misc/chattr.1.in | 40 +++++++++++++++++++++++++---------------
>  1 file changed, 25 insertions(+), 15 deletions(-)

Thanks for the updates to the chattr man page.  I've applied it to the
maint branch.

				- Ted