6334ff4be0
Per release notes: https://savannah.gnu.org/forum/forum.php?forum_id=8037 Version: 1.28-1
381 lines
14 KiB
Diff
381 lines
14 KiB
Diff
From 914bb84cb71ebb63c40bc27f4d017cc0a0a39bf2 Mon Sep 17 00:00:00 2001
|
|
From: rpm-build <rpm-build>
|
|
Date: Mon, 28 Jul 2014 08:15:14 +0200
|
|
Subject: [PATCH 6/9] Add documentation which was not yet pushed upstream
|
|
|
|
Upstream bugreport:
|
|
http://lists.gnu.org/archive/html/bug-tar/2012-08/msg00012.html
|
|
http://www.mail-archive.com/bug-tar@gnu.org/msg04135.html
|
|
|
|
Related: #996753
|
|
|
|
---
|
|
doc/tar.texi | 276 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
|
|
1 file changed, 276 insertions(+)
|
|
|
|
diff --git a/doc/tar.texi b/doc/tar.texi
|
|
index db79824..a000f3f 100644
|
|
--- a/doc/tar.texi
|
|
+++ b/doc/tar.texi
|
|
@@ -161,6 +161,7 @@ How to Create Archives
|
|
How to List Archives
|
|
|
|
* list dir::
|
|
+* List Extended Attributes::
|
|
|
|
How to Extract Members from an Archive
|
|
|
|
@@ -1491,6 +1492,7 @@ for a detailed discussion of globbing patterns and related
|
|
|
|
@menu
|
|
* list dir::
|
|
+* List Extended Attributes::
|
|
@end menu
|
|
|
|
@node list dir
|
|
@@ -1521,6 +1523,116 @@ drwxrwxrwx myself/user 0 1990-05-31 21:49 practice/
|
|
When you use a directory name as a file name argument, @command{tar} acts on
|
|
all the files (including sub-directories) in that directory.
|
|
|
|
+@node List Extended Attributes
|
|
+@unnumberedsubsec Listing xattrs, POSIX ACLs and SELinux context
|
|
+
|
|
+From upstream GNU tar 1.26.9, tar is able to store, extract and list extended
|
|
+file attributes. Listing of those attributes is then active only in verbose and
|
|
+double-verbose mode.
|
|
+
|
|
+This section exercises how to list attributes on examples. Lets start with
|
|
+simple verbose mode. This output is inspired by GNU @command{ls -l} command
|
|
+output.
|
|
+
|
|
+@itemize @bullet
|
|
+@item
|
|
+Show only pure extended attributes.
|
|
+
|
|
+@smallexample
|
|
+$ tar --xattrs --list -v archive.tar
|
|
+-rw-rwxr-- user/group 0 2012-08-08 15:15 acls.txt
|
|
+-rw-rw-r--* user/group 0 2012-08-08 15:15 xattrs.txt
|
|
+@end smallexample
|
|
+
|
|
+Note the asterisk on the third line! It reflects the situation that the file
|
|
+'xattrs.txt' has some extended attribute set. The default mode (same as if you
|
|
+are extracting extended attributes) shows information only about extended
|
|
+attributes from 'user.*' domain. Anyway, feel free to change the sensitivity
|
|
+using @option{--xattrs-include} or @option{--xattrs-exclude} options.
|
|
+
|
|
+@item Show only POSIX ACLs - the character you should look for is '+':
|
|
+
|
|
+@smallexample
|
|
+$ tar --acls --list -v archive.tar
|
|
+-rw-rwxr--+ praiskup/praiskup 0 2012-08-08 15:15 acls.txt
|
|
+-rw-rw-r-- praiskup/praiskup 0 2012-08-08 15:15 xattrs.txt
|
|
+@end smallexample
|
|
+
|
|
+@item Show only SELinux - the key character is '.':
|
|
+
|
|
+@smallexample
|
|
+$ tar --selinux --list -v archive.tar
|
|
+-rw-rw-r--. praiskup/praiskup 0 2012-08-08 15:16 selinux_only.txt
|
|
+-rw-rw-r-- praiskup/praiskup 0 2012-08-08 15:15 xattrs.txt
|
|
+@end smallexample
|
|
+
|
|
+@item
|
|
+Show info about ACLs, SELinux and general extended attributes together:
|
|
+
|
|
+@smallexample
|
|
+$ tar --selinux --acls --xattrs --list -v archive.tar
|
|
+-rw-rw-r--. praiskup/praiskup 0 2012-08-08 15:16 selinux_only.txt
|
|
+-rw-rwxr--+ praiskup/praiskup 0 2012-08-08 15:15 acls.txt
|
|
+-rw-rw-r--. praiskup/praiskup 0 2012-08-08 15:15 xattrs.txt
|
|
+@end smallexample
|
|
+
|
|
+In this case, the priority of character is '+' > '.' > '*'. You don't see the
|
|
+general extended attributes flag ('*' character) on this example because it is
|
|
+hidden by '.' (meaning that the file has SELinux context set).
|
|
+
|
|
+@end itemize
|
|
+
|
|
+The example of double verbose mode is here. In this output the single verbose
|
|
+characters '.', '+' and '*' are also present after the permission string.
|
|
+
|
|
+@smallexample
|
|
+$ tar --xattrs --selinux --acls -tvvf archive.tar
|
|
+-rw-rw-r--. praiskup/praiskup 0 2012-08-08 15:16 selinux_only.txt
|
|
+ s: unconfined_u:object_r:user_tmp_t:s0
|
|
+-rw-rwxr--+ praiskup/praiskup 0 2012-08-08 15:15 acls.txt
|
|
+ s: unconfined_u:object_r:user_tmp_t:s0
|
|
+ a: user::rw-,user:tester:rwx,group::rw-,mask::rwx,other::r--
|
|
+-rw-rw-r--. praiskup/praiskup 0 2012-08-08 15:15 xattrs.txt
|
|
+ s: unconfined_u:object_r:user_tmp_t:s0
|
|
+ x: 12 user.xattr
|
|
+ x: 12 user.we_like_tar
|
|
+@end smallexample
|
|
+
|
|
+This mode extends tar's output with additional lines beginning with
|
|
+distinguishing characters - 's' for SELinux context, 'a' for POSIX Access
|
|
+Control Lists and 'x' for generic extended attributes.
|
|
+
|
|
+In this format, POSIX ACLs are written in SHORT TEXT FORM as specified in manual
|
|
+page @command{man 5 acl}.
|
|
+
|
|
+Use the @option{--xattrs-include} again if you want to print other than default
|
|
+'user.*' extended attributes domain:
|
|
+
|
|
+@smallexample
|
|
+$ tar --xattrs --xattrs-include='*' --acls --selinux -tvvf archive.tar
|
|
+-rw-rw-r--. praiskup/praiskup 0 2012-08-08 15:16 selinux_only.txt
|
|
+ s: unconfined_u:object_r:user_tmp_t:s0
|
|
+ x: 36 security.selinux
|
|
+-rw-rwxr--+ praiskup/praiskup 0 2012-08-08 15:15 acls.txt
|
|
+ s: unconfined_u:object_r:user_tmp_t:s0
|
|
+ a: user::rw-,user:tester:rwx,group::rw-,mask::rwx,other::r--
|
|
+ x: 36 security.selinux
|
|
+ x: 44 system.posix_acl_access
|
|
+-rw-rw-r--. praiskup/praiskup 0 2012-08-08 15:15 xattrs.txt
|
|
+ s: unconfined_u:object_r:user_tmp_t:s0
|
|
+ x: 36 security.selinux
|
|
+ x: 12 user.xattr
|
|
+ x: 12 user.we_like_tar
|
|
+@end smallexample
|
|
+
|
|
+As is in @pxref{Option Summary} section described, tar by default stores all
|
|
+extended attributes that are available (not only 'user.*' domain). It means
|
|
+that the SELinux context and POSIX ACLs (because they are implemented using the
|
|
+generic extended attributes on usual file system) may be stored twice sometimes
|
|
+-- firstly in "raw" file system binary format and secondly in more portable way
|
|
+-- using appropriate system calls (invoked by @command{tar} options
|
|
+@option{--selinux} and @option{--acls}).
|
|
+
|
|
@node extract
|
|
@section How to Extract Members from an Archive
|
|
@cindex Extraction
|
|
@@ -2368,6 +2480,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
|
|
+Causes @command{tar} to store/restore/list POSIX ACL's. @xref{Attributes}.
|
|
+
|
|
@opsummary{after-date}
|
|
@item --after-date
|
|
|
|
@@ -2953,6 +3069,11 @@ 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
|
|
+Causes @command{tar} not to store, extract or list POSIX ACL's.
|
|
+@xref{Attributes}.
|
|
+
|
|
@opsummary{no-anchored}
|
|
@item --no-anchored
|
|
An exclude pattern can match any subsequence of the name's components.
|
|
@@ -3036,11 +3157,20 @@ 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
|
|
+Causes @command{tar} not to store, extract or list SELinux security context.
|
|
+@xref{Attributes}.
|
|
+
|
|
@opsummary{no-unquote}
|
|
@item --no-unquote
|
|
Treat all input file or member names literally, do not interpret
|
|
escape sequences. @xref{input name quoting}.
|
|
|
|
+@opsummary{no-xattrs}
|
|
+@item --no-xattrs
|
|
+Causes @command{tar} not to store, extract or list xattrs. @xref{Attributes}.
|
|
+
|
|
@opsummary{no-wildcards}
|
|
@item --no-wildcards
|
|
Do not use wildcards.
|
|
@@ -3286,6 +3416,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
|
|
+Causes @command{tar} to store, extract or list SELinux security context.
|
|
+@xref{Attributes}.
|
|
+
|
|
@opsummary{show-defaults}
|
|
@item --show-defaults
|
|
|
|
@@ -3541,6 +3676,11 @@ Enable or disable warning messages identified by @var{keyword}. The
|
|
messages are suppressed if @var{keyword} is prefixed with @samp{no-}.
|
|
@xref{warnings}.
|
|
|
|
+@opsummary{xattrs}
|
|
+@item --xattrs
|
|
+Causes @command{tar} to store, restore or list extended file attributes. For
|
|
+more info see @xref{Attributes}.
|
|
+
|
|
@opsummary{wildcards}
|
|
@item --wildcards
|
|
Use wildcards when matching member names with patterns.
|
|
@@ -4363,6 +4503,11 @@ failed, switched to @command{gzip}.
|
|
@cindex @samp{Record size = %lu blocks}, warning message
|
|
@item record-size
|
|
@samp{Record size = %lu blocks}
|
|
+@kwindex xattr-write
|
|
+@item xattr-write
|
|
+@samp{%s: Cannot set '%s' extended attribute for file '%s'}
|
|
+@*@samp{%s: Cannot set POSIX ACLs for file '%s'}
|
|
+@*@samp{%s: Cannot set SELinux context for file '%s'}
|
|
@end table
|
|
|
|
@subheading Keywords controlling incremental extraction:
|
|
@@ -8968,6 +9113,8 @@ implementation able to read @samp{ustar} archives will be able to read
|
|
most @samp{posix} archives as well, with the only exception that any
|
|
additional information (such as long file names etc.) will in such
|
|
case be extracted as plain text files along with the files it refers to.
|
|
+This is the only format that can store ACLs, SELinux context and extended
|
|
+attributes.
|
|
|
|
This archive format will be the default format for future versions
|
|
of @GNUTAR{}.
|
|
@@ -9607,6 +9754,135 @@ Same as both @option{--same-permissions} and @option{--same-order}.
|
|
|
|
This option is deprecated, and will be removed in @GNUTAR{} version 1.23.
|
|
|
|
+@opindex xattrs
|
|
+@item --xattrs
|
|
+This option causes @command{tar} to store, restore or list the extended file
|
|
+attributes (for information about extended attributes see @command{man(5)
|
|
+attr}).
|
|
+
|
|
+Note that all extended attributes are stored "as-is" (in file system binary
|
|
+format) and the resulting archive may be not fully portable. See the
|
|
+@option{--selinux} and @option{--acls} options when you want to deal with these
|
|
+types of extended attributes in a better way.
|
|
+
|
|
+The @option{--xattrs} option implies the option @option{--format=posix} when
|
|
+tar is in @option{--create} operation mode. It is the only one format which
|
|
+hase usable headers for storing additional file information like extended
|
|
+attributes are.
|
|
+
|
|
+By default, all extended attributes are stored into the archive. The reason is
|
|
+that we want to make the backup process as complete as possible by default. On
|
|
+the other hand, during extracting only the 'user.*' domain is extracted by
|
|
+default. Anyway, this default behaviour may be easily modified by the
|
|
+@option{--xattrs-include} and @option{--xattrs-exclude} options.
|
|
+
|
|
+When you list an archive in verbose mode
|
|
+(@command{tar --xattrs --verbose -tf archive.tar}), tar shows the '*' character
|
|
+after the permissions string of concrete file ringht to tell you that at least
|
|
+one extended attribute is stored with corresponding file.
|
|
+
|
|
+Double verbose mode (@command{tar --xattrs -tvvf archive.tar}) prints the
|
|
+extended attribute length (in bytes) and its ASCII key (for printed examples
|
|
+@pxref{List Extended Attributes}).
|
|
+
|
|
+@option{--xattrs} option has no equivalent short option.
|
|
+
|
|
+Warnings which occur during impossible writing of extended attributes to
|
|
+a file system may be suppressed using the @option{--warning=no-xattr-write}
|
|
+option.
|
|
+
|
|
+@opindex no-xattrs
|
|
+@item --no-xattrs
|
|
+This option causes @command{tar} not to store/extract or list the current
|
|
+extended attributes. This option does not affect options @option{--no-selinux}
|
|
+or @option{--no-acls}.
|
|
+
|
|
+The @option{--no-xattrs} option has no equivalent short option name.
|
|
+
|
|
+@opindex xattrs-include
|
|
+@opindex xattrs-exclude
|
|
+@item --xattrs-include=MASK
|
|
+@itemx --xattrs-exclude=MASK
|
|
+
|
|
+These options allows the xattr store/restore/list process to be more fine
|
|
+grained. The default configuration is that @option{--create} mode handles all
|
|
+available extended attributes and the @option{--extract}/@option{--list} mode
|
|
+handles only 'user.*' domain. These options may be used for editing of this
|
|
+default behaviour.
|
|
+
|
|
+@itemize @bullet
|
|
+@item
|
|
+Lets say we want to store all attributes except some "public restricted" domain
|
|
+(e.g. 'user.restricted.*' domain. The correct way how to do it is:
|
|
+
|
|
+@command{tar --xattrs --xattrs-include='*' --xattrs-exclude='user.restricted.*'
|
|
+-cf archive.tar FILES}
|
|
+@item
|
|
+And, when we want to extract only some specific domain from an archive - we can
|
|
+use:
|
|
+
|
|
+@command{tar --xattrs --xattrs-include='security.capability' -xf archive.tar
|
|
+FILES}
|
|
+@end itemize
|
|
+
|
|
+Multiple passed include/exclude patterns are combined together. The attribute
|
|
+is covered then only if (1) at least one of all include patterns matches its
|
|
+keyword and (2) no exclude pattern matches its keyword.
|
|
+
|
|
+When only include pattern is set - exclude pattern is left in default mode (and
|
|
+vice versa).
|
|
+
|
|
+@opindex selinux
|
|
+@item --selinux
|
|
+This option causes @command{tar} to store/extract/list the SELinux context
|
|
+information into/from an archive. Command @command{tar} is able to show info
|
|
+whether the SELinux context is present in archived file using the verbose
|
|
+listing mode (@command{tar --selinux -tvf archive.tar}). It shows the '.'
|
|
+character after permission string in that case. Double-verbose listing mode
|
|
+(@command{tar -tvvf archive.tar}) then prints the full SELinux context to
|
|
+standard output, @pxref{List Extended Attributes} for printed example.
|
|
+
|
|
+This option implies the @option{--format=posix} when @command{tar} works in
|
|
+@option{--create} operation mode.
|
|
+
|
|
+Warnings complaining that SELinux context may not be written to a file system
|
|
+may be suppressed by the @option{--warning=no-xattr-write} option.
|
|
+
|
|
+The @option{--selinux} option has no equivalent short option name.
|
|
+
|
|
+@opindex no-selinux
|
|
+@item --no-selinux
|
|
+This option causes @command{tar} not to store the current SELinux security
|
|
+context information in the archive and not to extract any SELinux information in
|
|
+an archive.
|
|
+
|
|
+The @option{--no-selinux} option has no equivalent short option name.
|
|
+
|
|
+@opindex acls
|
|
+@item --acls
|
|
+This option causes @command{tar} to store the current POSIX access control lists
|
|
+into the archive or restore POSIX ACLs from an archive. It also allows
|
|
+@command{tar} to show whether archived file contains ACLs when the verbose mode
|
|
+is active (@option{tar --acls -tvf} shows the symbol '+' after the permission
|
|
+characters in that case). Double-verbose mode allows @command{tar} to list
|
|
+contained POSIX ACLs (@command{tar --acls -tvvf archive.tar}), for printed
|
|
+examples @pxref{List Extended Attributes}.
|
|
+
|
|
+This option implies the @option{--format=posix} when @command{tar} works in
|
|
+@option{--create} operation mode.
|
|
+
|
|
+Warnings complaining that POSIX ACLs may not be written to a file system may be
|
|
+suppressed by the @option{--warning=no-xattr-write} option.
|
|
+
|
|
+The @option{--acls} option has no equivalent short form.
|
|
+
|
|
+@opindex no-acls
|
|
+@item --no-acls
|
|
+This option causes @command{tar} not to store the current POSIX ACL into the
|
|
+archive and not to extract any POSIX ACL information from an archive.
|
|
+
|
|
+The @option{--no-acls} option has no equivalent short option name.
|
|
+
|
|
@end table
|
|
|
|
@node Portability
|
|
--
|
|
1.9.3
|
|
|