* Date input formats::
* Formats::
* Media::
+* Reliability and security::
Appendices
* Pure numbers in date strings:: 19931219, 1440.
* Seconds since the Epoch:: @@1078100502.
* Specifying time zone rules:: TZ="America/New_York", TZ="UTC0".
-* Authors of get_date:: Bellovin, Eggert, Salz, Berets, et al.
+* Authors of parse_datetime:: Bellovin, Eggert, Salz, Berets, et al.
Controlling the Archive Format
@smallexample
@group
-V--------- 0/0 1536 2006-06-09 13:07 MyVolume--Volume Header--
--rw-r--r-- gray/staff 456783 2006-06-09 12:06 aspic--Continued at
-byte 32456--
--rw-r--r-- gray/staff 62373 2006-06-09 12:06 apple
-lrwxrwxrwx gray/staff 0 2006-06-09 13:01 angst -> apple
--rw-r--r-- gray/staff 35793 2006-06-09 12:06 blues
-hrw-r--r-- gray/staff 0 2006-06-09 12:06 music link to blues
+V--------- 0/0 1536 2006-06-09 13:07 MyVolume--Volume Header--
+-rw-r--r-- gray/staff 456783 2006-06-09 12:06 aspic--Continued at byte 32456--
+-rw-r--r-- gray/staff 62373 2006-06-09 12:06 apple
+lrwxrwxrwx gray/staff 0 2006-06-09 13:01 angst -> apple
+-rw-r--r-- gray/staff 35793 2006-06-09 12:06 blues
+hrw-r--r-- gray/staff 0 2006-06-09 12:06 music link to blues
@end group
@end smallexample
@smallexample
$ @kbd{tar --list --verbose --file=collection.tar folk}
--rw-r--r-- myself user 62 1990-05-23 10:55 folk
+-rw-r--r-- myself/user 62 1990-05-23 10:55 folk
@end smallexample
@cindex listing member and file names
@command{tar} responds:
@smallexample
-drwxrwxrwx myself user 0 1990-05-31 21:49 practice/
--rw-r--r-- myself user 42 1990-05-21 13:29 practice/blues
--rw-r--r-- myself user 62 1990-05-23 10:55 practice/folk
--rw-r--r-- myself user 40 1990-05-21 13:30 practice/jazz
--rw-r--r-- myself user 10240 1990-05-31 21:49 practice/collection.tar
+drwxrwxrwx myself/user 0 1990-05-31 21:49 practice/
+-rw-r--r-- myself/user 42 1990-05-21 13:29 practice/blues
+-rw-r--r-- myself/user 62 1990-05-23 10:55 practice/folk
+-rw-r--r-- myself/user 40 1990-05-21 13:30 practice/jazz
+-rw-r--r-- myself/user 10240 1990-05-31 21:49 practice/collection.tar
@end smallexample
When you use a directory name as a file name argument, @command{tar} acts on
produces this:
@smallexample
--rw-r--r-- me user 28 1996-10-18 16:31 jazz
--rw-r--r-- me user 21 1996-09-23 16:44 blues
--rw-r--r-- me user 20 1996-09-23 16:44 folk
+-rw-r--r-- me/user 28 1996-10-18 16:31 jazz
+-rw-r--r-- me/user 21 1996-09-23 16:44 blues
+-rw-r--r-- me/user 20 1996-09-23 16:44 folk
@end smallexample
@node extracting files
@smallexample
$ @kbd{tar -xvvf music.tar practice/folk practice/jazz}
--rw-r--r-- me user 28 1996-10-18 16:31 practice/jazz
--rw-r--r-- me user 20 1996-09-23 16:44 practice/folk
+-rw-r--r-- me/user 28 1996-10-18 16:31 practice/jazz
+-rw-r--r-- me/user 20 1996-09-23 16:44 practice/folk
@end smallexample
@noindent
@subsection Old Option Style
@cindex options, old style
@cindex old option style
+@cindex option syntax, traditional
-Like short options, @dfn{old options} are single letters. However, old options
+As far as we know, all @command{tar} programs, @acronym{GNU} and
+non-@acronym{GNU}, support @dfn{old options}: that is, if the first
+argument does not start with @samp{-}, it is assumed to specify option
+letters. @GNUTAR{} supports old options not only for historical
+reasons, but also because many people are used to them. If the first
+argument does not start with a dash, you are announcing the old option
+style instead of the short option style; old options are decoded
+differently.
+
+Like short options, old options are single letters. However, old options
must be written together as a single clumped set, without spaces separating
-them or dashes preceding them@footnote{Beware that if you precede options
-with a dash, you are announcing the short option style instead of the
-old option style; short options are decoded differently.}. This set
+them or dashes preceding them. This set
of letters must be the first to appear on the command line, after the
@command{tar} program name and some white space; old options cannot appear
anywhere else. The letter of an old option is exactly the same letter as
Here, @samp{20} is the argument of @option{-b} and @samp{/dev/rmt0} is
the argument of @option{-f}.
-On the other hand, this old style syntax makes it difficult to match
+The old style syntax can make it difficult to match
option letters with their corresponding arguments, and is often
confusing. In the command @w{@samp{tar cvbf 20 /dev/rmt0}}, for example,
@samp{20} is the argument for @option{-b}, @samp{/dev/rmt0} is the
second example, however, uses @file{z} as the value for option
@samp{f} --- probably not what was intended.
-Old options are kept for compatibility with old versions of @command{tar}.
-
This second example could be corrected in many ways, among which the
following are equivalent:
@kbd{tar cf archive.tar.gz -z file}
@end smallexample
-@cindex option syntax, traditional
-As far as we know, all @command{tar} programs, @acronym{GNU} and
-non-@acronym{GNU}, support old options. @GNUTAR{}
-supports them not only for historical reasons, but also because many
-people are used to them. For compatibility with Unix @command{tar},
-the first argument is always treated as containing command and option
-letters even if it doesn't start with @samp{-}. Thus, @samp{tar c} is
-equivalent to @w{@samp{tar -c}:} both of them specify the
-@option{--create} (@option{-c}) command to create an archive.
-
@node Mixing
@subsection Mixing Option Styles
@item --dereference
@itemx -h
-When creating a @command{tar} archive, @command{tar} will archive the
-file that a symbolic link points to, rather than archiving the
-symlink. @xref{dereference}.
+When reading or writing a file to be archived, @command{tar} accesses
+the file that a symbolic link points to, rather than the symlink
+itself. @xref{dereference}.
@opsummary{directory}
@item --directory=@var{dir}
@item --group=@var{group}
Files added to the @command{tar} archive will have a group @acronym{ID} of @var{group},
-rather than the group from the source file. @var{group} is first decoded
-as a group symbolic name, but if this interpretation fails, it has to be
-a decimal numeric group @acronym{ID}. @xref{override}.
+rather than the group from the source file. @var{group} can specify a
+symbolic name, or a numeric @acronym{ID}, or both as
+@var{name}:@var{id}. @xref{override}.
Also see the comments for the @option{--owner=@var{user}} option.
Specifies that @command{tar} should use @var{user} as the owner of members
when creating archives, instead of the user associated with the source
-file. @var{user} is first decoded as a user symbolic name, but if
-this interpretation fails, it has to be a decimal numeric user @acronym{ID}.
+file. @var{user} can specify a symbolic name, or a numeric
+@acronym{ID}, or both as @var{name}:@var{id}.
@xref{override}.
This option does not affect extraction from archives.
Verbose output appears on the standard output except when an archive is
being written to the standard output, as with @samp{tar --create
---file=- --verbose} (@samp{tar cfv -}, or even @samp{tar cv}---if the
+--file=- --verbose} (@samp{tar cvf -}, or even @samp{tar cv}---if the
installer let standard output be the default archive). In that case
@command{tar} writes verbose output to the standard error stream.
@cindex @samp{Ignoring unknown extended header keyword `%s'}, warning message
@item unknown-keyword
@samp{Ignoring unknown extended header keyword `%s'}
+@kwindex decompress-program
+@item decompress-program
+Controls verbose description of failures occurring when trying to run
+alternative decompressor programs (@pxref{alternative decompression
+programs}). This warning is disabled by default (unless
+@option{--verbose} is used). A common example of what you can get
+when using this warning is:
+
+@smallexample
+$ @kbd{tar --warning=decompress-program -x -f archive.Z}
+tar (child): cannot run compress: No such file or directory
+tar (child): trying gzip
+@end smallexample
+
+This means that @command{tar} first tried to decompress
+@file{archive.Z} using @command{compress}, and, when that
+failed, switched to @command{gzip}.
@end table
@subheading Keywords controlling incremental extraction:
@smallexample
@kbd{tar --create --file=empty-archive.tar --files-from=/dev/null}
-@kbd{tar cfT empty-archive.tar /dev/null}
+@kbd{tar -cf empty-archive.tar -T /dev/null}
@end smallexample
@xopindex{extract, complementary notes}
@smallexample
$ @kbd{tar --list --file=collection.tar}
--rw-r--r-- me user 28 1996-10-18 16:31 jazz
--rw-r--r-- me user 21 1996-09-23 16:44 blues
--rw-r--r-- me user 20 1996-09-23 16:44 folk
--rw-r--r-- me user 20 1996-09-23 16:44 rock
+-rw-r--r-- me/user 28 1996-10-18 16:31 jazz
+-rw-r--r-- me/user 21 1996-09-23 16:44 blues
+-rw-r--r-- me/user 20 1996-09-23 16:44 folk
+-rw-r--r-- me/user 20 1996-09-23 16:44 rock
@end smallexample
@node multiple
@smallexample
$ @kbd{tar --list --verbose --file=collection.tar}
--rw-r--r-- me user 28 1996-10-18 16:31 jazz
--rw-r--r-- me user 21 1996-09-23 16:44 blues
--rw-r--r-- me user 20 1996-09-23 16:44 folk
--rw-r--r-- me user 20 1996-09-23 16:44 rock
--rw-r--r-- me user 58 1996-10-24 18:30 blues
+-rw-r--r-- me/user 28 1996-10-18 16:31 jazz
+-rw-r--r-- me/user 21 1996-09-23 16:44 blues
+-rw-r--r-- me/user 20 1996-09-23 16:44 folk
+-rw-r--r-- me/user 20 1996-09-23 16:44 rock
+-rw-r--r-- me/user 58 1996-10-24 18:30 blues
@end smallexample
@noindent
@smallexample
$ @kbd{tar --extract -vv --occurrence --file=collection.tar blues}
--rw-r--r-- me user 21 1996-09-23 16:44 blues
+-rw-r--r-- me/user 21 1996-09-23 16:44 blues
@end smallexample
@xref{Writing}, for more information on @option{--extract} and
@smallexample
$ @kbd{tar -tvf bluesrock.tar}
--rw-r--r-- melissa user 105 1997-01-21 19:42 blues
--rw-r--r-- melissa user 33 1997-01-20 15:34 rock
+-rw-r--r-- melissa/user 105 1997-01-21 19:42 blues
+-rw-r--r-- melissa/user 33 1997-01-20 15:34 rock
$ @kbd{tar -tvf jazzfolk.tar}
--rw-r--r-- melissa user 20 1996-09-23 16:44 folk
--rw-r--r-- melissa user 65 1997-01-30 14:15 jazz
+-rw-r--r-- melissa/user 20 1996-09-23 16:44 folk
+-rw-r--r-- melissa/user 65 1997-01-30 14:15 jazz
@end smallexample
We can concatenate these two archives with @command{tar}:
Specifies that @command{tar} should use @var{user} as the owner of members
when creating archives, instead of the user associated with the source
-file. The argument @var{user} can be either an existing user symbolic
-name, or a decimal numeric user @acronym{ID}.
+file.
+
+If @var{user} contains a colon, it is taken to be of the form
+@var{name}:@var{id} where a nonempty @var{name} specifies the user
+name and a nonempty @var{id} specifies the decimal numeric user
+@acronym{ID}. If @var{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 @samp{0} usually means
@code{root}. Some people like to force @samp{0} as the value to offer in
@opindex group
Files added to the @command{tar} archive will have a group @acronym{ID} of @var{group},
-rather than the group from the source file. The argument @var{group}
-can be either an existing group symbolic name, or a decimal numeric group @acronym{ID}.
+rather than the group from the source file. As with @option{--owner},
+the argument @var{group} can be an existing group symbolic name, or a
+decimal numeric group @acronym{ID}, or @var{name}:@var{id}.
@end table
@node Ignore Failed Read
$ @kbd{tar -c -f archive.tar -C / home}
@end smallexample
-@include getdate.texi
+@xref{Integrity}, for some of the security-related implications
+of using this option.
+
+@include parse-datetime.texi
@node Formats
@chapter Controlling the Archive Format
For example:
@smallexample
-$ @kbd{tar cfz archive.tar.gz .}
+$ @kbd{tar czf archive.tar.gz .}
@end smallexample
You can also let @GNUTAR{} select the compression program based on
compression:
@smallexample
-$ @kbd{tar cfa archive.tar.bz2 .}
+$ @kbd{tar caf archive.tar.bz2 .}
@end smallexample
@noindent
whereas the following one will use @command{lzma}:
@smallexample
-$ @kbd{tar cfa archive.tar.lzma .}
+$ @kbd{tar caf archive.tar.lzma .}
@end smallexample
For a complete list of file name suffixes recognized by @GNUTAR{},
falls back to using archive name suffix to determine its format
(@pxref{auto-compress}, for a list of recognized suffixes).
+@anchor{alternative decompression programs}
+@cindex alternative decompression programs
+Some compression programs are able to handle different compression
+formats. @GNUTAR{} uses this, if the principal decompressor for the
+given format is not available. For example, if @command{compress} is
+not installed, @command{tar} will try to use @command{gzip}. As of
+version @value{VERSION} the following alternatives are
+tried@footnote{To verbosely trace the decompressor selection, use the
+@option{--warning=decompress-program} option
+(@pxref{warnings,decompress-program}).}:
+
+@multitable @columnfractions 0.3 0.3 0.3
+@headitem Format @tab Main decompressor @tab Alternatives
+@item compress @tab compress @tab gzip
+@item lzma @tab lzma @tab xz
+@item bzip2 @tab bzip2 @tab lbzip2
+@end multitable
+
The only case when you have to specify a decompression option while
reading the archive is when reading from a pipe or from a tape drive
that does not support random access. However, in this case @GNUTAR{}
invocation of @GNUTAR{}:
@smallexample
-$ @kbd{cat archive.tar.gz | tar tfz -}
+$ @kbd{cat archive.tar.gz | tar tzf -}
@end smallexample
Notice also, that there are several restrictions on operations on
use @env{GZIP} as in the example below:
@smallexample
-$ @kbd{GZIP=--best tar cfz archive.tar.gz subdir}
+$ @kbd{GZIP=--best tar czf archive.tar.gz subdir}
@end smallexample
@noindent
Normally, when @command{tar} archives a symbolic link, it writes a
block to the archive naming the target of the link. In that way, the
@command{tar} archive is a faithful record of the file system contents.
-@option{--dereference} (@option{-h}) is used with @option{--create} (@option{-c}), and causes
-@command{tar} to archive the files symbolic links point to, instead of
-the links themselves. When this option is used, when @command{tar}
-encounters a symbolic link, it will archive the linked-to file,
-instead of simply recording the presence of a symbolic link.
-
-The name under which the file is stored in the file system is not
-recorded in the archive. To record both the symbolic link name and
-the file name in the system, archive the file under both names. If
-all links were recorded automatically by @command{tar}, an extracted file
-might be linked to a file name that no longer exists in the file
-system.
-
-If a linked-to file is encountered again by @command{tar} while creating
-the same archive, an entire second copy of it will be stored. (This
-@emph{might} be considered a bug.)
+When @option{--dereference} (@option{-h}) is used with
+@option{--create} (@option{-c}), @command{tar} archives the files
+symbolic links point to, instead of
+the links themselves.
-So, for portable archives, do not archive symbolic links as such,
-and use @option{--dereference} (@option{-h}): many systems do not support
+When creating portable archives, use @option{--dereference}
+(@option{-h}): some systems do not support
symbolic links, and moreover, your distribution might be unusable if
it contains unresolved symbolic links.
+When reading from an archive, the @option{--dereference} (@option{-h})
+option causes @command{tar} to follow an already-existing symbolic
+link when @command{tar} writes or reads a file named in the archive.
+Ordinarily, @command{tar} does not follow such a link, though it may
+remove the link before writing a new file. @xref{Dealing with Old
+Files}.
+
+The @option{--dereference} option is unsafe if an untrusted user can
+modify directories while @command{tar} is running. @xref{Security}.
+
@node hard links
@subsection Hard Links
@cindex File names, using hard links
@smallexample
@group
-$ ls
--rw-r--r-- 2 gray staff 4 2007-10-30 15:11 one
--rw-r--r-- 2 gray staff 4 2007-10-30 15:11 jeden
+$ ls -l
+-rw-r--r-- 2 gray staff 4 2007-10-30 15:11 one
+-rw-r--r-- 2 gray staff 4 2007-10-30 15:11 jeden
@end group
@end smallexample
the following:
@smallexample
-$ tar cfvv ../archive.tar .
+$ tar cvvf ../archive.tar .
drwxr-xr-x gray/staff 0 2007-10-30 15:13 ./
-rw-r--r-- gray/staff 4 2007-10-30 15:11 ./jeden
hrw-r--r-- gray/staff 0 2007-10-30 15:11 ./one link to ./jeden
@smallexample
$ @kbd{tar --create --multi-volume --file=/dev/tape0 --file=/dev/tape1 @var{files}}
-$ @kbd{tar cMff /dev/tape0 /dev/tape1 @var{files}}
+$ @kbd{tar -cM -f /dev/tape0 -f /dev/tape1 @var{files}}
@end smallexample
The second method is to use the @samp{n} response to the tape-change
@smallexample
@group
$ @kbd{tar --verbose --list --file=iamanarchive}
-V--------- 0 0 0 1992-03-07 12:01 iamalabel--Volume Header--
--rw-r--r-- ringo user 40 1990-05-21 13:30 iamafilename
+V--------- 0/0 0 1992-03-07 12:01 iamalabel--Volume Header--
+-rw-r--r-- ringo/user 40 1990-05-21 13:30 iamafilename
@end group
@end smallexample
@smallexample
@group
-$ @kbd{tar cfMV /dev/tape "Daily backup for `date +%Y-%m-%d`"}
+$ @kbd{tar -cM -f /dev/tape -V "Daily backup for `date +%Y-%m-%d`"}
$ @kbd{tar --create --file=/dev/tape --multi-volume \
--label="Daily backup for `date +%Y-%m-%d`"}
@end group
which can be removed from the center of a tape reel, or some other
changeable feature.
+@node Reliability and security
+@chapter Reliability and Security
+
+The @command{tar} command reads and writes files as any other
+application does, and is subject to the usual caveats about
+reliability and security. This section contains some commonsense
+advice on the topic.
+
+@menu
+* Reliability::
+* Security::
+@end menu
+
+@node Reliability
+@section Reliability
+
+Ideally, when @command{tar} is creating an archive, it reads from a
+file system that is not being modified, and encounters no errors or
+inconsistencies while reading and writing. If this is the case, the
+archive should faithfully reflect what was read. Similarly, when
+extracting from an archive, ideally @command{tar} ideally encounters
+no errors and the extracted files faithfully reflect what was in the
+archive.
+
+However, when reading or writing real-world file systems, several
+things can go wrong; these include permissions problems, corruption of
+data, and race conditions.
+
+@menu
+* Permissions problems::
+* Data corruption and repair::
+* Race conditions::
+@end menu
+
+@node Permissions problems
+@subsection Permissions Problems
+
+If @command{tar} encounters errors while reading or writing files, it
+normally reports an error and exits with nonzero status. The work it
+does may therefore be incomplete. For example, when creating an
+archive, if @command{tar} cannot read a file then it cannot copy the
+file into the archive.
+
+@node Data corruption and repair
+@subsection Data Corruption and Repair
+
+If an archive becomes corrupted by an I/O error, this may corrupt the
+data in an extracted file. Worse, it may corrupt the file's metadata,
+which may cause later parts of the archive to become misinterpreted.
+An tar-format archive contains a checksum that most likely will detect
+errors in the metadata, but it will not detect errors in the data.
+
+If data corruption is a concern, you can compute and check your own
+checksums of an archive by using other programs, such as
+@command{cksum}.
+
+When attempting to recover from a read error or data corruption in an
+archive, you may need to skip past the questionable data and read the
+rest of the archive. This requires some expertise in the archive
+format and in other software tools.
+
+@node Race conditions
+@subsection Race conditions
+
+If some other process is modifying the file system while @command{tar}
+is reading or writing files, the result may well be inconsistent due
+to race conditions. For example, if another process creates some
+files in a directory while @command{tar} is creating an archive
+containing the directory's files, @command{tar} may see some of the
+files but not others, or it may see a file that is in the process of
+being created. The resulting archive may not be a snapshot of the
+file system at any point in time. If an application such as a
+database system depends on an accurate snapshot, restoring from the
+@command{tar} archive of a live file system may therefore break that
+consistency and may break the application. The simplest way to avoid
+the consistency issues is to avoid making other changes to the file
+system while tar is reading it or writing it.
+
+When creating an archive, several options are available to avoid race
+conditions. Some hosts have a way of snapshotting a file system, or
+of temporarily suspending all changes to a file system, by (say)
+suspending the only virtual machine that can modify a file system; if
+you use these facilities and have @command{tar -c} read from a
+snapshot when creating an archive, you can avoid inconsistency
+problems. More drastically, before starting @command{tar} you could
+suspend or shut down all processes other than @command{tar} that have
+access to the file system, or you could unmount the file system and
+then mount it read-only.
+
+When extracting from an archive, one approach to avoid race conditions
+is to create a directory that no other process can write to, and
+extract into that.
+
+@node Security
+@section Security
+
+In some cases @command{tar} may be used in an adversarial situation,
+where an untrusted user is attempting to gain information about or
+modify otherwise-inaccessible files. Dealing with untrusted data
+(that is, data generated by an untrusted user) typically requires
+extra care, because even the smallest mistake in the use of
+@command{tar} is more likely to be exploited by an adversary than by a
+race condition.
+
+@menu
+* Privacy::
+* Integrity::
+* Live untrusted data::
+* Security rules of thumb::
+@end menu
+
+@node Privacy
+@subsection Privacy
+
+Standard privacy concerns apply when using @command{tar}. For
+example, suppose you are archiving your home directory into a file
+@file{/archive/myhome.tar}. Any secret information in your home
+directory, such as your SSH secret keys, are copied faithfully into
+the archive. Therefore, if your home directory contains any file that
+should not be read by some other user, the archive itself should be
+not be readable by that user. And even if the archive's data are
+inaccessible to untrusted users, its metadata (such as size or
+last-modified date) may reveal some information about your home
+directory; if the metadata are intended to be private, the archive's
+parent directory should also be inaccessible to untrusted users.
+
+One precaution is to create @file{/archive} so that it is not
+accessible to any user, unless that user also has permission to access
+all the files in your home directory.
+
+Similarly, when extracting from an archive, take care that the
+permissions of the extracted files are not more generous than what you
+want. Even if the archive itself is readable only to you, files
+extracted from it have their own permissions that may differ.
+
+@node Integrity
+@subsection Integrity
+
+When creating archives, take care that they are not writable by a
+untrusted user; otherwise, that user could modify the archive, and
+when you later extract from the archive you will get incorrect data.
+
+When @command{tar} extracts from an archive, by default it writes into
+files relative to the working directory. If the archive was generated
+by an untrusted user, that user therefore can write into any file
+under the working directory. If the working directory contains a
+symbolic link to another directory, the untrusted user can also write
+into any file under the referenced directory. When extracting from an
+untrusted archive, it is therefore good practice to create an empty
+directory and run @command{tar} in that directory.
+
+When extracting from two or more untrusted archives, each one should
+be extracted independently, into different empty directories.
+Otherwise, the first archive could create a symbolic link into an area
+outside the working directory, and the second one could follow the
+link and overwrite data that is not under the working directory. For
+example, when restoring from a series of incremental dumps, the
+archives should have been created by a trusted process, as otherwise
+the incremental restores might alter data outside the working
+directory.
+
+If you use the @option{--absolute-names} (@option{-P}) option when
+extracting, @command{tar} respects any file names in the archive, even
+file names that begin with @file{/} or contain @file{..}. As this
+lets the archive overwrite any file in your system that you can write,
+the @option{--absolute-names} (@option{-P}) option should be used only
+for trusted archives.
+
+Conversely, with the @option{--keep-old-files} (@option{-k}) option,
+@command{tar} refuses to replace existing files when extracting; and
+with the @option{--no-overwrite-dir} option, @command{tar} refuses to
+replace the permissions or ownership of already-existing directories.
+These options may help when extracting from untrusted archives.
+
+@node Live untrusted data
+@subsection Dealing with Live Untrusted Data
+
+Extra care is required when creating from or extracting into a file
+system that is accessible to untrusted users. For example, superusers
+who invoke @command{tar} must be wary about its actions being hijacked
+by an adversary who is reading or writing the file system at the same
+time that @command{tar} is operating.
+
+When creating an archive from a live file system, @command{tar} is
+vulnerable to denial-of-service attacks. For example, an adversarial
+user could create the illusion of an indefinitely-deep directory
+hierarchy @file{d/e/f/g/...} by creating directories one step ahead of
+@command{tar}, or the illusion of an indefinitely-long file by
+creating a sparse file but arranging for blocks to be allocated just
+before @command{tar} reads them. There is no easy way for
+@command{tar} to distinguish these scenarios from legitimate uses, so
+you may need to monitor @command{tar}, just as you'd need to monitor
+any other system service, to detect such attacks.
+
+While a superuser is extracting from an archive into a live file
+system, an untrusted user might replace a directory with a symbolic
+link, in hopes that @command{tar} will follow the symbolic link and
+extract data into files that the untrusted user does not have access
+to. Even if the archive was generated by the superuser, it may
+contain a file such as @file{d/etc/passwd} that the untrusted user
+earlier created in order to break in; if the untrusted user replaces
+the directory @file{d/etc} with a symbolic link to @file{/etc} while
+@command{tar} is running, @command{tar} will overwrite
+@file{/etc/passwd}. This attack can be prevented by extracting into a
+directory that is inaccessible to untrusted users.
+
+Similar attacks via symbolic links are also possible when creating an
+archive, if the untrusted user can modify an ancestor of a top-level
+argument of @command{tar}. For example, an untrusted user that can
+modify @file{/home/eve} can hijack a running instance of @samp{tar -cf
+- /home/eve/Documents/yesterday} by replacing
+@file{/home/eve/Documents} with a symbolic link to some other
+location. Attacks like these can be prevented by making sure that
+untrusted users cannot modify any files that are top-level arguments
+to @command{tar}, or any ancestor directories of these files.
+
+@node Security rules of thumb
+@subsection Security Rules of Thumb
+
+This section briefly summarizes rules of thumb for avoiding security
+pitfalls.
+
+@itemize @bullet
+
+@item
+Protect archives at least as much as you protect any of the files
+being archived.
+
+@item
+Extract from an untrusted archive only into an otherwise-empty
+directory. This directory and its parent should be accessible only to
+trusted users. For example:
+
+@example
+@group
+$ @kbd{chmod go-rwx .}
+$ @kbd{mkdir -m go-rwx dir}
+$ @kbd{cd dir}
+$ @kbd{tar -xvf /archives/got-it-off-the-net.tar.gz}
+@end group
+@end example
+
+As a corollary, do not do an incremental restore from an untrusted archive.
+
+@item
+Do not let untrusted users access files extracted from untrusted
+archives without checking first for problems such as setuid programs.
+
+@item
+Do not let untrusted users modify directories that are ancestors of
+top-level arguments of @command{tar}. For example, while you are
+executing @samp{tar -cf /archive/u-home.tar /u/home}, do not let an
+untrusted user modify @file{/}, @file{/archive}, or @file{/u}.
+
+@item
+Pay attention to the diagnostics and exit status of @command{tar}.
+
+@item
+When archiving live file systems, monitor running instances of
+@command{tar} to detect denial-of-service attacks.
+
+@item
+Avoid unusual options such as @option{--absolute-names} (@option{-P}),
+@option{--dereference} (@option{-h}), @option{--overwrite},
+@option{--recursive-unlink}, and @option{--remove-files} unless you
+understand their security implications.
+
+@end itemize
+
@node Changes
@appendix Changes