>From e974a0f0dd7edc808a8abad6848ec75fc68e6cfe Mon Sep 17 00:00:00 2001 From: Pavel Raiskup Date: Wed, 15 Aug 2012 14:44:08 +0200 Subject: [PATCH 5/5] Documentation for XATTRS & SELinux & POSIX ACLs --- doc/tar.texi | 280 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 278 insertions(+), 2 deletions(-) diff --git a/doc/tar.texi b/doc/tar.texi index afb77ab..8029768 100644 --- a/doc/tar.texi +++ b/doc/tar.texi @@ -37,8 +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, 2011 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 @@ -158,6 +158,7 @@ How to Create Archives How to List Archives * list dir:: +* List Extended Attributes:: How to Extract Members from an Archive @@ -1488,6 +1489,7 @@ for a detailed discussion of globbing patterns and related @menu * list dir:: +* List Extended Attributes:: @end menu @node list dir @@ -1518,6 +1520,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. address@hidden List Extended Attributes address@hidden 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. + address@hidden @bullet address@hidden +Show only pure extended attributes. + address@hidden +$ 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 address@hidden 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. + address@hidden Show only POSIX ACLs - the character you should look for is '+': + address@hidden +$ 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 address@hidden smallexample + address@hidden Show only SELinux - the key character is '.': + address@hidden +$ 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 address@hidden smallexample + address@hidden +Show info about ACLs, SELinux and general extended attributes together: + address@hidden +$ 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 address@hidden 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). + address@hidden itemize + +The example of double verbose mode is here. In this output the single verbose +characters '.', '+' and '*' are also present after the permission string. + address@hidden +$ 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 address@hidden 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: + address@hidden +$ 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 address@hidden 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 address@hidden and @option{--acls}). + @node extract @section How to Extract Members from an Archive @cindex Extraction @@ -2363,6 +2475,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}. address@hidden address@hidden --acls +Causes @command{tar} to store/restore/list POSIX ACL's. @xref{Attributes}. + @opsummary{after-date} @item --after-date @@ -2911,6 +3027,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}. address@hidden address@hidden --no-acls +Causes @command{tar} not to store, extract or list POSIX ACL's. address@hidden + @opsummary{no-anchored} @item --no-anchored An exclude pattern can match any subsequence of the name's components. @@ -2994,11 +3115,20 @@ locations. Usually @command{tar} determines automatically whether the archive can be seeked or not. Use this option to disable this mechanism. address@hidden address@hidden --no-selinux +Causes @command{tar} not to store, extract or list SELinux security context. address@hidden + @opsummary{no-unquote} @item --no-unquote Treat all input file or member names literally, do not interpret escape sequences. @xref{input name quoting}. address@hidden address@hidden --no-xattrs +Causes @command{tar} not to store, extract or list xattrs. @xref{Attributes}. + @opsummary{no-wildcards} @item --no-wildcards Do not use wildcards. @@ -3231,6 +3361,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). address@hidden address@hidden --selinux +Causes @command{tar} to store, extract or list SELinux security context. address@hidden + @opsummary{show-defaults} @item --show-defaults @@ -3458,6 +3593,11 @@ Enable or disable warning messages identified by @var{keyword}. The messages are suppressed if @var{keyword} is prefixed with @samp{no-}. @xref{warnings}. address@hidden address@hidden --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. @@ -4193,6 +4333,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}. address@hidden xattr-write address@hidden xattr-write address@hidden: Cannot set '%s' extended attribute for file '%s'} address@hidden@samp{%s: Cannot set POSIX ACLs for file '%s'} address@hidden@samp{%s: Cannot set SELinux context for file '%s'} @end table @subheading Keywords controlling incremental extraction: @@ -8712,6 +8857,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{}. @@ -9336,6 +9483,135 @@ Same as both @option{--same-permissions} and @option{--same-order}. This option is deprecated, and will be removed in @GNUTAR{} version 1.23. address@hidden xattrs address@hidden --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 address@hidden 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 address@hidden 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 address@hidden Extended Attributes}). + address@hidden 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. + address@hidden no-xattrs address@hidden --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. + address@hidden xattrs-include address@hidden xattrs-exclude address@hidden --xattrs-include=MASK address@hidden --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. + address@hidden @bullet address@hidden +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: + address@hidden --xattrs --xattrs-include='*' --xattrs-exclude='user.restricted.*' +-cf archive.tar FILES} address@hidden +And, when we want to extract only some specific domain from an archive - we can +use: + address@hidden --xattrs --xattrs-include='security.capability' -xf archive.tar +FILES} address@hidden 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). + address@hidden selinux address@hidden --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 address@hidden 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. + address@hidden no-selinux address@hidden --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. + address@hidden acls address@hidden --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 address@hidden 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 address@hidden 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. + address@hidden no-acls address@hidden --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.7.11.2