[tar] doc: commit also forgotten patch
Pavel Raiskup
praiskup at fedoraproject.org
Wed Aug 14 07:15:41 UTC 2013
commit 2852f8c68ff101ca2121c7013be2c2dcbc88a60b
Author: Pavel Raiskup <praiskup at redhat.com>
Date: Wed Aug 14 09:14:33 2013 +0200
doc: commit also forgotten patch
Version: 1.26-28
Related: #996753
tar-1.26-docu-xattrs.patch | 372 ++++++++++++++++++++++++++++++++++++++++++++
1 files changed, 372 insertions(+), 0 deletions(-)
---
diff --git a/tar-1.26-docu-xattrs.patch b/tar-1.26-docu-xattrs.patch
new file mode 100644
index 0000000..14d047e
--- /dev/null
+++ b/tar-1.26-docu-xattrs.patch
@@ -0,0 +1,372 @@
+diff --git a/doc/tar.texi b/doc/tar.texi
+index d678db9..ab8a0c8 100644
+--- a/doc/tar.texi
++++ b/doc/tar.texi
+@@ -37,7 +37,8 @@ This manual is for @acronym{GNU} @command{tar} (version
+ from archives.
+
+ Copyright @copyright{} 1992, 1994, 1995, 1996, 1997, 1999, 2000, 2001,
+-2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 Free Software Foundation, Inc.
++2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012 Free Software
++Foundation, Inc.
+
+ @quotation
+ Permission is granted to copy, distribute and/or modify this document
+@@ -162,6 +163,7 @@ How to Create Archives
+ How to List Archives
+
+ * list dir::
++* List Extended Attributes::
+
+ How to Extract Members from an Archive
+
+@@ -1492,6 +1494,7 @@ for a detailed discussion of globbing patterns and related
+
+ @menu
+ * list dir::
++* List Extended Attributes::
+ @end menu
+
+ @node list dir
+@@ -1522,6 +1525,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.
+
++ at node List Extended Attributes
++ at 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.
++
++ at itemize @bullet
++ at item
++Show only pure extended attributes.
++
++ at 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
++ at 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.
++
++ at item Show only POSIX ACLs - the character you should look for is '+':
++
++ at 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
++ at end smallexample
++
++ at item Show only SELinux - the key character is '.':
++
++ at 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
++ at end smallexample
++
++ at item
++Show info about ACLs, SELinux and general extended attributes together:
++
++ at 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
++ at 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).
++
++ at 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.
++
++ at 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
++ at 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:
++
++ at 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
++ at 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
++ at option{--selinux} and @option{--acls}).
++
+ @node extract
+ @section How to Extract Members from an Archive
+ @cindex Extraction
+@@ -2371,6 +2484,10 @@ Normally when creating an archive, @command{tar} strips an initial
+ @samp{/} from member names. This option disables that behavior.
+ @xref{absolute}.
+
++ at opsummary{acls}
++ at item --acls
++Causes @command{tar} to store/restore/list POSIX ACL's. @xref{Attributes}.
++
+ @opsummary{after-date}
+ @item --after-date
+
+@@ -2919,6 +3036,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}.
+
++ at opsummary{no-acls}
++ at item --no-acls
++Causes @command{tar} not to store, extract or list POSIX ACL's.
++ at xref{Attributes}.
++
+ @opsummary{no-anchored}
+ @item --no-anchored
+ An exclude pattern can match any subsequence of the name's components.
+@@ -3002,11 +3124,20 @@ locations. Usually @command{tar} determines automatically whether
+ the archive can be seeked or not. Use this option to disable this
+ mechanism.
+
++ at opsummary{no-selinux}
++ at item --no-selinux
++Causes @command{tar} not to store, extract or list SELinux security context.
++ at 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}.
+
++ at opsummary{no-xattrs}
++ at 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.
+@@ -3239,6 +3370,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).
+
++ at opsummary{selinux}
++ at item --selinux
++Causes @command{tar} to store, extract or list SELinux security context.
++ at xref{Attributes}.
++
+ @opsummary{show-defaults}
+ @item --show-defaults
+
+@@ -3466,6 +3602,11 @@ Enable or disable warning messages identified by @var{keyword}. The
+ messages are suppressed if @var{keyword} is prefixed with @samp{no-}.
+ @xref{warnings}.
+
++ at opsummary{xattrs}
++ at 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.
+@@ -4218,6 +4359,11 @@ tar (child): trying gzip
+ This means that @command{tar} first tried to decompress
+ @file{archive.Z} using @command{compress}, and, when that
+ failed, switched to @command{gzip}.
++ at kwindex xattr-write
++ at item xattr-write
++ at 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:
+@@ -8770,6 +8916,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{}.
+@@ -9412,6 +9560,135 @@ Same as both @option{--same-permissions} and @option{--same-order}.
+
+ This option is deprecated, and will be removed in @GNUTAR{} version 1.23.
+
++ at opindex xattrs
++ at 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
++ at 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
++ at 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
++ at pxref{List Extended Attributes}).
++
++ at 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.
++
++ at opindex no-xattrs
++ at 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.
++
++ at opindex xattrs-include
++ at opindex xattrs-exclude
++ at item --xattrs-include=MASK
++ at 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.
++
++ at itemize @bullet
++ at 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:
++
++ at command{tar --xattrs --xattrs-include='*' --xattrs-exclude='user.restricted.*'
++-cf archive.tar FILES}
++ at item
++And, when we want to extract only some specific domain from an archive - we can
++use:
++
++ at command{tar --xattrs --xattrs-include='security.capability' -xf archive.tar
++FILES}
++ at 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).
++
++ at opindex selinux
++ at 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
++ at 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.
++
++ at opindex no-selinux
++ at 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.
++
++ at opindex acls
++ at 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
++ at 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
++ at 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.
++
++ at opindex no-acls
++ at 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
More information about the scm-commits
mailing list