[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.3 Options Used by `--create'

The previous chapter described the basics of how to use `--create' (`-c') to create an archive from a set of files. See section How to Create Archives. This section described advanced options to be used with `--create'.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.3.1 Overriding File Metadata

As described above, a tar archive keeps, for each member it contains, its metadata, such as modification time, mode and ownership of the file. GNU tar allows to replace these data with other values when adding files to the archive. The options described in this section affect creation of archives of any type. For POSIX archives, see also Controlling Extended Header Keywords, for additional ways of controlling metadata, stored in the archive.

`--mode=permissions'

When adding files to an archive, tar will use permissions for the archive members, rather than the permissions from the files. permissions can be specified either as an octal number or as symbolic permissions, like with chmod (See Permissions: (fileutils)File permissions section `File permissions' in GNU file utilities. This reference also has useful information for those not being overly familiar with the UNIX permission system). Using latter syntax allows for more flexibility. For example, the value `a+rw' adds read and write permissions for everybody, while retaining executable bits on directories or on any other file already marked as executable:

 
$ tar -c -f archive.tar --mode='a+rw' .
`--mtime=date'

When adding files to an archive, tar will use date as the modification time of members when creating archives, instead of their actual modification times. The argument date can be either a textual date representation in almost arbitrary format (see section Date input formats) or a name of an existing file, starting with `/' or `.'. In the latter case, the modification time of that file will be used.

The following example will set the modification date to 00:00:00, January 1, 1970:

 
$ tar -c -f archive.tar --mtime='1970-01-01' .

When used with `--verbose' (see section The `--verbose' Option) GNU tar will try to convert the specified date back to its textual representation and compare it with the one given with `--mtime' options. If the two dates differ, tar will print a warning saying what date it will use. This is to help user ensure he is using the right date.

For example:

 
$ tar -c -f archive.tar -v --mtime=yesterday .
tar: Option --mtime: Treating date 'yesterday' as 2006-06-20
13:06:29.152478
…

When used with `--clamp-mtime' GNU tar will only set the modification date to date on files whose actual modification date is later than date. This is to make it easy to build reproducible archives given a common timestamp for generated files while still retaining the original timestamps of untouched files.

 
$ tar -c -f archive.tar --clamp-mtime --mtime=@$SOURCE_DATE_EPOCH .
`--owner=user'

Specifies that tar should use user as the owner of members when creating archives, instead of the user associated with the source file.

If user contains a colon, it is taken to be of the form name:id where a nonempty name specifies the user name and a nonempty id specifies the decimal numeric user ID. If user does not contain a colon, it is taken to be a user number if it is one or more decimal digits; otherwise it is taken to be a user name.

If a name is given but no number, the number is inferred from the current host's user database if possible, and the file's user number is used otherwise. If a number is given but no name, the name is inferred from the number if possible, and an empty name is used otherwise. If both name and number are given, the user database is not consulted, and the name and number need not be valid on the current host.

There is no value indicating a missing number, and `0' usually means root. Some people like to force `0' as the value to offer in their distributions for the owner of files, because the root user is anonymous anyway, so that might as well be the owner of anonymous archives. For example:

 
$ tar -c -f archive.tar --owner=0 .

or:

 
$ tar -c -f archive.tar --owner=root .
`--group=group'

Files added to the tar archive will have a group ID of group, rather than the group from the source file. As with `--owner', the argument group can be an existing group symbolic name, or a decimal numeric group ID, or name:id.

The `--owner' and `--group' options affect all files added to the archive. GNU tar provides also two options that allow for more detailed control over owner translation:

`--owner-map=file'

Read UID translation map from file.

When reading, empty lines are ignored. The `#' sign, unless quoted, introduces a comment, which extends to the end of the line. Each nonempty line defines mapping for a single UID. It must consist of two fields separated by any amount of whitespace. The first field defines original username and UID. It can be a valid user name or a valid UID prefixed with a plus sign. In both cases the corresponding UID or user name is inferred from the current host's user database.

The second field defines the UID and username to map the original one to. Its format can be the same as described above. Otherwise, it can have the form newname:newuid, in which case neither newname nor newuid are required to be valid as per the user database.

For example, consider the following file:

 
+10     bin
smith   root:0

Given this file, each input file that is owner by UID 10 will be stored in archive with owner name `bin' and owner UID corresponding to `bin'. Each file owned by user `smith' will be stored with owner name `root' and owner ID 0. Other files will remain unchanged.

When used together with `--owner-map', the `--owner' option affects only files whose owner is not listed in the map file.

`--group-map=file'

Read GID translation map from file.

The format of file is the same as for `--owner-map' option:

Each nonempty line defines mapping for a single GID. It must consist of two fields separated by any amount of whitespace. The first field defines original group name and GID. It can be a valid group name or a valid GID prefixed with a plus sign. In both cases the corresponding GID or user name is inferred from the current host's group database.

The second field defines the GID and group name to map the original one to. Its format can be the same as described above. Otherwise, it can have the form newname:newgid, in which case neither newname nor newgid are required to be valid as per the group database.

When used together with `--group-map', the `--group' option affects only files whose owner group is not rewritten using the map file.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.3.2 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. GNU tar can store extended file attributes along with the files. This feature is controlled by the following command line arguments:

`--xattrs'

Enable extended attributes support. When used with `--create', this option instructs GNU tar created archive. This implies POSIX.1-2001 archive format (`--format=pax').

When used with `--extract', this option tells tar, for each file extracted, to read stored attributes from the archive and to apply them to the file.

`--no-xattrs'

Disable extended attributes support. This is the default.

Attribute names are strings prefixed by a namespace name and a dot. Currently, four namespaces exist: `user', `trusted', `security' and `system'. By default, when `--xattr' is used, all names are stored in the archive (or extracted, if using `--extract'). This can be controlled using the following options:

`--xattrs-exclude=pattern'

Specify exclude pattern for extended attributes.

`--xattrs-include=pattern'

Specify include pattern for extended attributes.

Here, the pattern is POSIX regular expression. For example, the following command:

 
$ tar --xattrs --xattrs-exclude='^user\.' -c a.tar .

will include in the archive `a.tar' all attributes, except those from the `user' namespace.

Any number of these options can be given, thereby creating lists of include and exclude patterns.

When both options are used, first `--xattrs-inlcude' is applied to select the set of attribute names to keep, and then `--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 `--xattrs-inlcude' and don't match any of the regexps from `--xattrs-exclude'.

When listing the archive, if both `--xattrs' and `--verbose' options are given, files that have extended attributes are marked with an asterisk following their permission mask. For example:

 
-rw-r--r--* smith/users      110 2016-03-16 16:07 file

When two or more `--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 `x' indicating extended attribute. It is followed by a colon, length of the attribute and its name, e.g.:

 
-rw-r--r--* smith/users      110 2016-03-16 16:07 file
  x:  7 user.mime_type
  x: 32 trusted.md5sum

File access control lists (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:

`--acls'

Enable POSIX ACLs support. When used with `--create', this option instructs GNU tar to store ACLs in the created archive. This implies POSIX.1-2001 archive format (`--format=pax').

When used with `--extract', this option tells tar, to restore ACLs for each file extracted (provided they are present in the archive).

`--no-acls'

Disable POSIX ACLs support. This is the default.

When listing the archive, if both `--acls' and `--verbose' options are given, files that have ACLs are marked with a plus sing following their permission mask. For example:

 
-rw-r--r--+ smith/users      110 2016-03-16 16:07 file

When two or more `--verbose' options are given, a detailed listing of ACL is printed after each file entry:

 
-rw-r--r--+ smith/users      110 2016-03-16 16:07 file
  a: user::rw-,user:gray:-w-,group::r--,mask::rw-,other::r--
 

Security-Enhanced Linux (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 (MAC). Support for SELinux attributes is controlled by the following command line options:

`--selinux'

Enable the SELinux context support.

`--no-selinux'

Disable SELinux context support.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.3.3 Ignore Fail Read

`--ignore-failed-read'

Do not exit with nonzero on unreadable files or directories.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]

This document was generated on May, 16 2016 using texi2html 1.76.