From: Sergey Poznyakoff Date: Wed, 16 Mar 2016 18:08:00 +0000 (+0200) Subject: Document xattrs, ACL and SELinux-related options. X-Git-Tag: release_1_29~17 X-Git-Url: https://git.gag.com/?a=commitdiff_plain;h=e4b246c14abc36ed3f4cb36b929e287223a9139f;p=debian%2Ftar Document xattrs, ACL and SELinux-related options. * doc/tar.1: Document all options. * doc/tar.texi: Likewise. --- diff --git a/doc/tar.1 b/doc/tar.1 index fabe60a7..26a354a3 100644 --- a/doc/tar.1 +++ b/doc/tar.1 @@ -13,7 +13,7 @@ .\" .\" You should have received a copy of the GNU General Public License .\" along with this program. If not, see . -.TH TAR 1 "December 5, 2015" "TAR" "GNU TAR Manual" +.TH TAR 1 "March 16, 2016" "TAR" "GNU TAR Manual" .SH NAME tar \- an archiving utility .SH SYNOPSIS @@ -583,6 +583,34 @@ Using \fB\-\-sort=inode\fR reduces the number of disk seeks made when creating the archive and thus can considerably speed up archivation. This sorting order is supported only if the underlying system provides the necessary information. +.SS Extended file attributes +.TP +.B \-\-acls +Enable POSIX ACLs support. +.TP +.B \-\-no\-acls +Disable POSIX ACLs support. +.TP +.B \-\-selinux +Enable SELinux context support. +.TP +.B \-\-no-selinux +Disable SELinux context support. +.TP +.B \-\-xattrs +Enable extended attributes support. +.TP +.B \-\-no\-xattrs +Disable extended attributes support. +.TP +.BI \-\-xattrs\-exclude= PATTERN +Specify the exclude pattern for xattr keys. \fIPATTERN\fR is a POSIX +regular expression, e.g. \fB\-\-xattrs\-exclude='^user\.'\fR, to exclude +attributes from the user namespace. +.TP +.BI \-\-xattrs\-include= PATTERN +Specify the include pattern for xattr keys. \fIPATTERN\fR is a POSIX +regular expression. .SS Device selection and switching .TP \fB\-f\fR, \fB\-\-file\fR=\fIARCHIVE\fR diff --git a/doc/tar.texi b/doc/tar.texi index 7f299cdf..87af540c 100644 --- a/doc/tar.texi +++ b/doc/tar.texi @@ -36,7 +36,7 @@ This manual is for @acronym{GNU} @command{tar} (version @value{VERSION}, @value{UPDATED}), which creates and extracts files from archives. -Copyright @copyright{} 1992, 1994--1997, 1999--2001, 2003--2013 Free +Copyright @copyright{} 1992, 1994--1997, 1999--2001, 2003--2016 Free Software Foundation, Inc. @quotation @@ -228,6 +228,7 @@ Updating an Archive Options Used by @option{--create} * override:: Overriding File Metadata. +* Extended File Attributes:: * Ignore Failed Read:: Options Used by @option{--extract} @@ -2370,6 +2371,10 @@ Normally when creating an archive, @command{tar} strips an initial treats names specially if they have initial @samp{/} or internal @samp{..}. This option disables that behavior. @xref{absolute}. +@opsummary{acls} +@item --acls +Enable POSIX ACLs support. @xref{Extended File Attributes, acls}. + @opsummary{after-date} @item --after-date @@ -2847,7 +2852,7 @@ Specifies that @command{tar} should ask the user for confirmation before performing potentially destructive options, such as overwriting files. @xref{interactive}. -@opsummary{--keep-directory-symlink} +@opsummary{keep-directory-symlink} @item --keep-directory-symlink This option changes the behavior of tar when it encounters a symlink @@ -2974,6 +2979,10 @@ contents have changed (as opposed to just @option{--newer}, which will also back up files for which any status information has changed). @xref{after}. +@opsummary{no-acls} +@item --no-acls +Disable the POSIX ACLs support. @xref{Extended File Attributes, acls}. + @opsummary{no-anchored} @item --no-anchored An exclude pattern can match any subsequence of the name's components. @@ -3057,6 +3066,10 @@ locations. Usually @command{tar} determines automatically whether the archive can be seeked or not. Use this option to disable this mechanism. +@opsummary{no-selinux} +@item --no-selinux +Disable SELinux context support. @xref{Extended File Attributes, SELinux}. + @opsummary{no-unquote} @item --no-unquote Treat all input file or member names literally, do not interpret @@ -3087,6 +3100,10 @@ Do not use wildcards. Wildcards do not match @samp{/}. @xref{controlling pattern-matching}. +@opsummary{no-xattrs} +@item --no-xattrs +Disable extended attributes support. @xref{Extended File Attributes, xattrs}. + @opsummary{null} @item --null @@ -3340,6 +3357,11 @@ in cases when such recognition fails. It takes effect only if the archive is open for reading (e.g. with @option{--list} or @option{--extract} options). +@opsummary{selinux} +@item --selinux +Enable the SELinux context support. +@xref{Extended File Attributes, selinux}. + @opsummary{show-defaults} @item --show-defaults @@ -3628,6 +3650,22 @@ Use wildcards when matching member names with patterns. Wildcards match @samp{/}. @xref{controlling pattern-matching}. +@opsummary{xattrs} +@item --xattrs +Enable extended attributes support. @xref{Extended File Attributes, xattrs}. + +@opsummary{xattrs-exclude} +@item --xattrs-exclude=@var{pattern} +Specify exclude pattern for xattr keys. +@xref{Extended File Attributes, xattrs-exclude}. + +@opsummary{xattrs-include} +@item --xattrs-include=@var{pattern}. +Specify include pattern for xattr keys. @var{pattern} is a POSIX +regular expression, e.g. @samp{--xattrs-exclude='^user\.'} to include +only attributes from the user namespace. +@xref{Extended File Attributes, xattrs-include}. + @opsummary{xz} @item --xz @itemx -J @@ -5299,6 +5337,7 @@ The previous chapter described the basics of how to use @menu * override:: Overriding File Metadata. +* Extended File Attributes:: * Ignore Failed Read:: @end menu @@ -5480,6 +5519,142 @@ option affects only files whose owner group is not rewritten using the map file. @end table +@node Extended File Attributes +@subsection Extended File Attributes + +Extended file attributes are name-value pairs that can be +associated with each node in a file system. Despite the fact that +POSIX.1e draft which proposed them has been withdrawn, the extended +file attributes are supported by many file systems. @GNUTAR{} can +store extended file attributes along with the files. This feature is +controlled by the following command line arguments: + +@table @option +@item --xattrs +Enable extended attributes support. When used with @option{--create}, +this option instructs @GNUTAR to store extended file attribute in the +created archive. This implies POSIX.1-2001 archive format +(@option{--format=pax}). + +When used with @option{--extract}, this option tells @command{tar}, +for each file extracted, to read stored attributes from the archive +and to apply them to the file. + +@item --no-xattrs +Disable extended attributes support. This is the default. +@end table + +Attribute names are strings prefixed by a @dfn{namespace} name and a dot. +Currently, four namespaces exist: @samp{user}, @samp{trusted}, +@samp{security} and @samp{system}. By default, when @option{--xattr} +is used, all names are stored in the archive (or extracted, if using +@option{--extract}). This can be controlled using the following +options: + +@table @option +@item --xattrs-exclude=@var{pattern} +Specify exclude pattern for extended attributes. + +@item --xattrs-include=@var{pattern} +Specify include pattern for extended attributes. +@end table + +Here, the @var{pattern} is POSIX regular expression. For example, the +following command: + +@example +$ @kbd{tar --xattrs --xattrs-exclude='^user\.' -c a.tar .} +@end example + +will include in the archive @file{a.tar} all attributes, except those +from the @samp{user} namespace. + +Any number of these options can be given, thereby creating lists of +include and exclude patterns. + +When both options are used, first @option{--xattrs-inlcude} is applied +to select the set of attribute names to keep, and then +@option{--xattrs-exclude} is applied to the resulting set. In other +words, only those attributes will be stored, whose names match one +of the regexps in @option{--xattrs-inlcude} and don't match any of +the regexps from @option{--xattrs-exclude}. + +When listing the archive, if both @option{--xattrs} and +@option{--verbose} options are given, files that have extended +attributes are marked with an asterisk following their permission +mask. For example: + +@example +-rw-r--r--* smith/users 110 2016-03-16 16:07 file +@end example + +When two or more @option{--verbose} options are given, a detailed +listing of extended attributes is printed after each file entry. Each +attribute is listed on a separate line, which begins with two spaces +and the letter @samp{x} indicating extended attribute. It is followed +by a colon, length of the attribute and its name, e.g.: + +@example +-rw-r--r--* smith/users 110 2016-03-16 16:07 file + x: 7 user.mime_type + x: 32 trusted.md5sum +@end example + +File access control lists (@dfn{ACL}) are another actively used feature +proposed by the POSIX.1e standard. Each ACL consists of a set of ACL +entries, each of which describes the access permissions on the file for +an individual user or a group of users as a combination of read, write +and search/execute permissions. + +Whether or not to use ACLs is controlled by the following two options: + +@table @option +@item --acls +Enable POSIX ACLs support. When used with @option{--create}, +this option instructs @GNUTAR{} to store ACLs in the +created archive. This implies POSIX.1-2001 archive format +(@option{--format=pax}). + +When used with @option{--extract}, this option tells @command{tar}, +to restore ACLs for each file extracted (provided they are present +in the archive). + +@item --no-acls +Disable POSIX ACLs support. This is the default. +@end table + +When listing the archive, if both @option{--acls} and +@option{--verbose} options are given, files that have ACLs are marked +with a plus sing following their permission mask. For example: + +@example +-rw-r--r--+ smith/users 110 2016-03-16 16:07 file +@end example + +When two or more @option{--verbose} options are given, a detailed +listing of ACL is printed after each file entry: + +@example +@group +-rw-r--r--+ smith/users 110 2016-03-16 16:07 file + a: user::rw-,user:gray:-w-,group::r--,mask::rw-,other::r-- +@end group +@end example + +@dfn{Security-Enhanced Linux} (@dfn{SELinux} for short) is a Linux +kernel security module that provides a mechanism for supporting access +control security policies, including so-called mandatory access +controls (@dfn{MAC}). Support for SELinux attributes is controlled by +the following command line options: + +@table @option +@item --selinux +Enable the SELinux context support. + +@item --no-selinux +Disable SELinux context support. +@end table + @node Ignore Failed Read @subsection Ignore Fail Read