Skip to contentSkip to conversation

chattr.1 updates

PATCH In review Eric Biggers 2 participants 8 messages Nov 18, 2019

lore
Share & tools
lore
#0 lore raw

cover chattr.1 updates

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(-)
Signature · 1 line
2.24.0
#1 lore raw

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

From: Eric Biggers <[email protected]>

Document the verity file attribute ('V').

---
 misc/chattr.1.in | 12 +++++++++++-
 1 file changed, 11 insertions(+), 1 deletion(-)
misc/chattr.1.in +11 -1
index 1c9e8964..2122a13e 100644
@@ -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 <[email protected]>.  It is currently being
Signature · 1 line
2.24.0
#2 lore raw

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

In reply to Eric Biggers

From: Eric Biggers <[email protected]>

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.

---
 misc/chattr.1.in | 5 ++---
 1 file changed, 2 insertions(+), 3 deletions(-)
misc/chattr.1.in +2 -3
index 2122a13e..18b316e3 100644
@@ -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).
Signature · 1 line
2.24.0
#3 lore raw

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

In reply to Eric Biggers

From: Eric Biggers <[email protected]>

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

---
 misc/chattr.1.in | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
misc/chattr.1.in +1 -1
index 18b316e3..1baacf17 100644
@@ -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 '='
Signature · 1 line
2.24.0
#4 lore raw

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

In reply to Eric Biggers

From: Eric Biggers <[email protected]>

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

---
 misc/chattr.1.in | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)
misc/chattr.1.in +6 -6
index 1baacf17..cc751fe8 100644
@@ -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
Signature · 1 line
2.24.0
#5 lore raw

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

In reply to Eric Biggers

From: Eric Biggers <[email protected]>

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.

---
 misc/chattr.1.in | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)
misc/chattr.1.in +2 -2
index cc751fe8..870397ae 100644
@@ -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.
Signature · 1 line
2.24.0
#6 lore raw

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

In reply to Eric Biggers

From: Eric Biggers <[email protected]>

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

---
 misc/chattr.1.in | 9 +++++----
 1 file changed, 5 insertions(+), 4 deletions(-)
misc/chattr.1.in +5 -4
index 870397ae..66e791db 100644
@@ -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).
Signature · 1 line
2.24.0
#7 lore raw
In reply to Eric Biggers
Quoted 12 lines · 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"

Quoted 2 lines
 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