tarsnap/tar/tarsnap.1-mdoc.in

.\" Copyright 2007-2025 Tarsnap Backup Inc.
.\" All rights reserved.
.\"
.\" Portions of the file below are covered by the following license:
.\"
.\" Copyright (c) 2003-2007 Tim Kientzle
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\" $FreeBSD: src/usr.bin/tar/bsdtar.1,v 1.46 2008/12/06 07:37:55 kientzle Exp $
.\"
.Dd @DATE@
.Dt TARSNAP 1
.Os
.Sh NAME
.Nm tarsnap
.Nd manipulate remote encrypted backups
.Sh SYNOPSIS
.Nm
.Brq Fl c
.Fl -keyfile Ar key-file
.Fl -cachedir Ar cache-dir
.Fl f Ar archive-name
.Op Ar options
.Op Ar files | Ar directories
.Nm
.Brq Fl d
.Fl -keyfile Ar key-file
.Fl -cachedir Ar cache-dir
.Fl f Ar archive-name
.Op Ar options
.Nm
.Brq Fl t | Fl x
.Fl -keyfile Ar key-file
.Fl f Ar archive-name
.Op Ar options
.Op Ar patterns
.Nm
.Brq Fl r
.Fl -keyfile Ar key-file
.Fl f Ar archive-name
.Nm
.Brq Fl -list-archives
.Fl -keyfile Ar key-file
.Nm
.Brq Fl -print-stats
.Fl -keyfile Ar key-file
.Fl -cachedir Ar cache-dir
.Op Fl f Ar archive-name
.Nm
.Brq Fl -recover
.Fl -keyfile Ar key-file
.Fl -cachedir Ar cache-dir
.Nm
.Brq Fl -fsck
.Fl -keyfile Ar key-file
.Fl -cachedir Ar cache-dir
.Nm
.Brq Fl -fsck-prune
.Fl -keyfile Ar key-file
.Fl -cachedir Ar cache-dir
.Nm
.Brq Fl -initialize-cachedir
.Fl -keyfile Ar key-file
.Fl -cachedir Ar cache-dir
.Nm
.Brq Fl -nuke
.Fl -keyfile Ar key-file
.Nm
.Fl -verify-config
.Nm
.Fl -version
.Sh DESCRIPTION
.Nm
creates, reads, deletes, and otherwise manages online backups.
.Pp
The first option to
.Nm
is a mode indicator from the following list:
.Bl -tag -compact -width indent
.It Fl c
Create an archive containing the specified items and name.
.It Fl d
Delete the specified archive.
.It Fl t
List archive contents to stdout.
.It Fl x
Extract to disk from the archive.
.It Fl r
Read the specified archive, convert it to a tar stream, and write it
to stdout.
.It Fl -list-archives
Print the names of archives stored.
If the
.Fl v
flag is specified one or more times, the creation
time of each archive is also printed;
if the
.Fl v
flag is specified two or more times, the command
line with which
.Nm
was invoked to create each archive is also printed.
.It Fl -print-stats
Print global statistics concerning the archives stored, and optionally
information about individual archive(s).
See "PRINTING ARCHIVE STATISTICS" below for information on the output format.
.It Fl -recover
Recover a partial archive from a checkpoint if such an archive exists.
This is also done automatically the next time an archive is created
or deleted.
.It Fl -fsck
Perform some integrity checks on the archives stored, and reconstruct the
cache directory
.Ar cache-dir .
In the unlikely event that there are corrupted archives,
.Nm
will exit and request that it be run with the
.Fl -fsck-prune
option.
.It Fl -fsck-prune
Run as
.Fl -fsck ,
but if corrupt archives are detected, prune the broken data.
.It Fl -initialize-cachedir
Create and initialize the cachedir.
This option is intended for the GUI and is not needed for command-line usage.
.It Fl -nuke
Delete all of the archives stored.
To protect against accidental data loss,
.Nm
will ask you to type the text "No Tomorrow" when using the
.Fl -nuke
command.
.It Fl -verify-config
Check the configuration file(s) for syntactic errors.
.It Fl -version
Print version number of
.Nm ,
and exit.
.El
.Pp
In
.Fl c
mode, each specified file or directory is added to the
archive in the order specified on the command line.
By default, the contents of each directory are also archived.
.Pp
In
.Fl t
or
.Fl x
mode, the entire command line
is read and parsed before the archive is opened.
The pathnames or patterns on the command line indicate
which items in the archive should be processed.
Patterns are shell-style globbing patterns as
documented in
.Xr tcsh 1 .
Note that these follow the POSIX rules for pattern matching, e.g.,
.Sq []
are special characters which can be escaped with a backslash.
.Pp
Two concurrent create or delete operations may not be performed with the same
key.
Extracting or listing archives may be performed in parallel with any other
operation.
.Sh OPTIONS
.Bl -tag -width indent
.It Cm @ Ns Pa archive-file
(c mode only)
The specified archive file is read and the entries
in it will be appended to the current archive.
If
.Pa archive-file
is
.Dq -
then the archive will be read from the standard input.
As an example,
.Dl Nm Fl c Fl -keyfile Ar key-file Fl -cachedir Ar cache-dir Fl f Ar mybackup Cm @ Ns Pa backup.tar
reads the archive file
.Pa backup.tar
from disk and stores it using
.Nm .
.It Cm @@ Ns Ar archive-name
(c mode only)
The specified
.Nm
archive is read and the entries in it will be
appended to the current archive.
.It Fl -aggressive-networking
(c mode only)
Use multiple TCP connections to send data to the
.Nm
server.
If the upload rate is congestion-limited rather than
being limited by individual bottleneck(s), this may
allow tarsnap to use a significantly larger fraction
of the available bandwidth, at the expense of slowing
down any other network traffic.
.It Fl -archive-names Ar filename
Read a list of archive names from
.Ar filename .
.It Fl C Ar directory
(c and x modes only)
In c mode, this changes the directory before adding
the following files.
In x mode, change directories after opening the archive
but before extracting entries from the archive.
.It Fl -cachedir Ar cache-dir
(c, d, print-stats, and fsck modes only)
Cache information about the archives stored by
.Nm
in the directory
.Ar cache-dir .
The contents of this directory will not be backed up by
.Nm ,
so it should not be used for any other purpose.
If the directory
.Ar cache-dir
is lost, it can be reconstructed by running
.Nm Fl -fsck .
.It Fl -check-links
(c mode only)
Issue a warning message unless all links to each file are archived.
.It Fl -checkpoint-bytes Ar bytespercheckpoint
(c mode only)
Create a checkpoint after every
.Ar bytespercheckpoint
bytes of uploaded data.
The value
.Ar bytespercheckpoint
must be at least 1000000, and a higher value is recommended since
creating a checkpoint in an archive can take a few seconds and several
hundred kB of bandwidth.
.It Fl -chroot
(x mode only)
.Fn chroot
to the current directory after processing any
.Fl C
options and before extracting any files.
.It Fl -configfile Ar filename
Add
.Ar filename
to the list of configuration files to be read; options set via these take
priority over the default configuration files.
This option can be specified multiple times, in which case all the files
will be read; where settings conflict, the earlier configuration file will
take priority.
.It Fl -creationtime Ar X
(c mode only)
Manually specify a creation time (a unix timestamp) for the archive.
This is unlikely to be useful when tarsnap is being invoked directly from the
command line.
.It Fl -csv-file Ar filename
(use with
.Fl -print-stats )
Write statistics in CSV format to a file.
.It Fl -disk-pause Ar X
(c mode only)
Pause for
.Ar X
ms between storing archive entries and after every 64 kB of file data.
This will slow down
.Nm
and thereby reduce its impact on other applications.
For archiving files which are stored on an ATA disk and are not in the
operating system disk cache, a value of
.Fl -disk-pause Ar 10
will approximately double the time taken.
.It Fl -dry-run
(c mode only)
Don't really create an archive; just simulate doing so.
The list of paths added to an archive (if the
.Fl v
option is used), progress messages (if the
.Fl -progress-bytes
option is used), and final statistics printed (if the
.Fl -print-stats
option is used) will be almost identical (typically
within a few kB or a fraction of a percent) to if
.Nm
is run without the
.Fl -dry-run
option.
.Pp
Note that the
.Fl -maxbw
option does not work in combination with
.Fl -dry-run ,
since no bandwidth is actually used, and that since
.Nm
does not contact the
.Nm
server when performing a dry run, it will not detect an
attempt to create an archive with the same name as one
which already exists.
If an existing archive is being copied via
.Cm @@ Ns Ar archive-name ,
then some network bandwidth will be used while
.Nm
reads metadata about
.Ar archive-name
from the tarsnap server.
.Pp
Furthermore,
.Fl -dry-run
will not check whether the cache directory is out of sync.
.It Fl -dry-run-metadata
(c mode only)
Don't really create an archive; just simulate doing so.
This is similar to
.Fl -dry-run ,
except that it doesn't read any files; it only processes filesystem metadata.
.Pp
This is significantly faster than a regular
.Fl -dry-run ,
but it is still suitable for checking which filesystem entries will be
archived (with
.Fl v ) ,
or getting the total uncompressed archive size (via
.Fl -totals
or
.Fl -progress-bytes ) .
.Pp
This option cannot be used with
.Fl -print-stats .
.It Fl -dump-config
Print out the command-line and all non-blank lines read from config files.
.It Fl -exclude Ar pattern
(c, x, and t modes only)
Do not process files or directories that match the
specified pattern.
Note that exclusions take precedence over patterns or filenames
specified on the command line.
.It Fl f Ar archive-name
(c, d, x, t, r, list-archives, and print-stats modes only)
Operate on the archive
.Ar archive-name .
In mode c, if archive creation is interrupted by \&^Q,
the SIGQUIT signal, or reaching the bandwidth limit
specified via a
.Fl -maxbw
option, the archive will be stored with
".part" appended to its name.
In mode print-stats, if
.Ar archive-name
is *, statistics will be printed for every archive.
In the print-stats and d modes,
.Fl f Ar archive-name
can be specified multiple times, in which case the operation
(printing statistics, or deletion) will be performed for each
of the specified archives.
.Pp
Note that each archive created must have a different name; consequently
many users find it useful to include timestamps in archive names when
repeatedly creating archives from the same files/directories (e.g.,
daily backups).
.Pp
As a special case, if used with
.Fl -list-archives -hashes
then
.Fl f
indicates a
.Ar tapehash
instead of an
.Ar archive-name ,
and will print metadata about the specified archive(s).
This combination of options is intended for the GUI and is not needed for
command-line usage.
.Po Fl f
cannot be used with
.Fl -list-archives
if it does not also include
.Fl -hashes .
.Pc
.It Fl -force-resources
Force the decryption of a passphrase-encrypted key file to proceed
even if it is anticipated to require an excessive amount of memory
or CPU time.
.It Fl H
(c mode only)
Symbolic links named on the command line will be followed; the
target of the link will be archived, not the link itself.
.It Fl h
(c mode only)
Synonym for
.Fl L .
.It Fl -hashes
(list-archives mode only)
Print hashes of archive names.
If the
.Fl v
flag is specified one or more times, print the archive name as well.
.Pp
This option is intended for the GUI and is not needed for command-line usage.
.It Fl -humanize-numbers
Use SI prefixes to make numbers printed by
.Fl -print-stats
and SIGINFO more readable.
.It Fl I
Synonym for
.Fl T .
.It Fl -include Ar pattern
(c, x, and t modes only)
Process only files or directories that match the specified pattern.
Note that exclusions specified with
.Fl -exclude
take precedence over inclusions.
If no inclusions are explicitly specified, all entries are processed by
default.
The
.Fl -include
option is especially useful when filtering archives.
For example, the command
.Dl Nm Fl c Fl f Ar foo-backup Fl -include='*foo*' Cm @@ Ns Ar all-backup
creates a new archive
.Ar foo-backup
containing only the entries from
.Ar all-backup
containing the string
.Sq foo .
.It Fl -insane-filesystems
(c mode only)
Allow descent into synthetic filesystems such as procfs.
Normally archiving of such filesystems is a silly thing to do, hence the
name of the option.
.It Fl -iso-dates
(t mode only)
Print file and directory dates as yyyy-mm-dd hh:mm:ss.
.Pp
The default is to use the same format as 'ls -l': If the files were modified
within the past six months, print the month, day, hour, and minutes; otherwise,
print the month, day, and year.
.It Fl k
(x mode only)
Do not overwrite existing files.
In particular, if a file appears more than once in an archive,
later copies will not overwrite earlier copies.
.It Fl -keep-going
(d and print-stats modes only)
Continue deleting or printing statistics after finding that one
of the archives specified does not exist.
.It Fl -keep-newer-files
(x mode only)
Do not overwrite existing files that are newer than the
versions appearing in the archive being extracted.
.It Fl -keyfile Pa key-file
(all modes)
Obtain encryption, authentication, and access keys from
.Ar key-file .
This file should have been generated by
.Xr tarsnap-keygen 1 .
.It Fl L
(c mode only)
All symbolic links will be followed.
Normally, symbolic links are archived as such.
With this option, the target of the link will be archived instead.
.It Fl l
This is a synonym for the
.Fl -check-links
option.
.It Fl -lowmem
(c mode only)
Reduce memory usage by not caching small files.
This may be useful when backing up files of average size less
than 1 MB if the available RAM in kilobytes is less than the
number of files being backed up.
.It Fl m
(x mode only)
Do not extract modification time.
By default, the modification time is set to the time stored in the archive.
.It Fl -maxbw Ar numbytes
(c mode only)
Interrupt archival if more than
.Ar numbytes
bytes of upstream bandwidth is used (see INTERRUPTING ARCHIVAL
below for details).
.It Fl -maxbw-rate Ar bytespersecond
Limit download and upload bandwidth used to
.Ar bytespersecond
bytes per second.
.It Fl -maxbw-rate-down Ar bytespersecond
Limit download bandwidth used to
.Ar bytespersecond
bytes per second.
.It Fl -maxbw-rate-up Ar bytespersecond
Limit upload bandwidth used to
.Ar bytespersecond
bytes per second.
.It Fl n
(c mode only)
Do not recursively archive the contents of directories.
.It Fl -newer Ar date
(c, x, t modes only)
Only include files and directories newer than the specified date.
This compares ctime entries.
.It Fl -newer-mtime Ar date
(c mode only)
Like
.Fl -newer ,
except it compares mtime entries instead of ctime entries.
.It Fl -newer-than Pa filename
(c mode only)
Only include files and directories newer than the specified file.
This compares ctime entries.
.It Fl -newer-mtime-than Pa filename
(c mode only)
Like
.Fl -newer-than ,
except it compares mtime entries instead of ctime entries.
.It Fl -no-aggressive-networking
Ignore any
.Cm aggressive-networking
option specified in a configuration file.
.It Fl -no-config-exclude
Ignore any
.Cm exclude
option specified in a configuration file.
Normally
.Cm exclude
options specified via configuration files and the command line
all take effect.
.It Fl -no-config-include
Ignore any
.Cm include
option specified in a configuration file.
Normally
.Cm include
options specified via configuration files and the command line
all take effect.
.It Fl -no-default-config
Do not read the default configuration files
.Pa @sysconfdir@/tarsnap.conf ,
.Pa $XDG_CONFIG_HOME/tarsnap/tarsnap.conf ,
and
.Pa ~/.tarsnaprc .
.It Fl -no-disk-pause
Ignore any
.Cm disk-pause
option specified in a configuration file.
.It Fl -no-force-resources
Ignore any
.Cm force-resources
option specified in a configuration file.
.It Fl -no-humanize-numbers
Ignore any
.Cm humanize-numbers
option specified in a configuration file.
.It Fl -no-insane-filesystems
Ignore any
.Cm insane-filesystems
option specified in a configuration file.
.It Fl -no-iso-dates
Ignore any
.Cm iso-dates
option specified in a configuration file.
.It Fl -no-maxbw
Ignore any
.Cm maxbw
option specified in a configuration file.
.It Fl -no-maxbw-rate-down
Ignore any
.Cm maxbw-rate-down
option specified in a configuration file.
If a
.Cm maxbw-rate
option is specified in a configuration file, it will
not affect the download bandwidth used, but may affect
the upload bandwidth used (unless
.Fl -no-maxbw-rate-up
is also specified).
.It Fl -no-maxbw-rate-up
Ignore any
.Cm maxbw-rate-up
option specified in a configuration file.
If a
.Cm maxbw-rate
option is specified in a configuration file, it will
not affect the upload bandwidth used, but may affect
the download bandwidth used (unless
.Fl -no-maxbw-rate-down
is also specified).
.It Fl -no-noatime
Ignore any
.Cm noatime
option specified in a configuration file.
.It Fl -no-nodump
Ignore any
.Cm nodump
option specified in a configuration file.
.It Fl -no-print-stats
Ignore any
.Cm print-stats
option specified in a configuration file.
.It Fl -no-progress-bytes
Ignore any
.Cm progress-bytes
option specified in a configuration file.
.It Fl -no-quiet
Ignore any
.Cm quiet
option specified in a configuration file.
.It Fl -no-retry-forever
Ignore any
.Cm retry-forever
option specified in a configuration file.
.It Fl -no-snaptime
Ignore any
.Cm snaptime
option specified in a configuration file.
.It Fl -no-store-atime
Ignore any
.Cm store-atime
option specified in a configuration file.
.It Fl -no-totals
Ignore any
.Cm totals
option specified in a configuration file.
.It Fl -noatime
(c mode only)
Ask the operating system to not update the atime when reading files or
directories.  Not supported by all operating systems and filesystems.
.It Fl -nodump
(c mode only)
Honor the nodump file flag by skipping this file or directory.
.It Fl -noisy-warnings
Be verbose when warning about network glitches.
This is probably only useful for debugging purposes.
.It Fl -normalmem
Ignore any
.Cm lowmem
or
.Cm verylowmem
option specified in a configuration file.
.It Fl -null
(use with
.Fl I ,
.Fl T ,
or
.Fl X )
Synonym for
.Fl -null-input .
Kept for historical reasons and compatibility with other tar utilities.
.It Fl -null-input
(use with
.Fl I ,
.Fl T ,
or
.Fl X )
Filenames, archive names, and patterns are separated by null characters,
not by newlines.
This is often used to read filenames output by the
.Fl print0
option to
.Xr find 1 .
.It Fl -null-output
(x, t, and list-archives modes only)
Archive names and filenames in output are separated by null characters, not by
newlines.
.Pp
If there are multiple fields on a line, they will be separated by two null
characters.
If a command line is printed within one of those fields, each argument will be
separated by three null characters.
.It Fl -numeric-owner
(x mode only)
Ignore symbolic user and group names when restoring archives to disk,
only numeric uid and gid values will be obeyed.
.It Fl O
(x and t modes only)
In extract (-x) mode, files will be written to standard out rather than
being extracted to disk.
In list (-t) mode, the file listing will be written to stderr rather than
the usual stdout.
.It Fl o
(x mode only)
Use the user and group of the user running the program rather
than those specified in the archive.
Note that this has no significance unless
.Fl p
is specified, and the program is being run by the root user.
In this case, the file modes and flags from
the archive will be restored, but ACLs or owner information in
the archive will be discarded.
.It Fl -one-file-system
(c mode only)
Do not cross mount points.
.It Fl P
(c, x, and t modes only)
Preserve pathnames.
By default, absolute pathnames (those that begin with a /
character) have the leading slash removed both when creating archives
and extracting from them.
Also,
.Nm
will refuse to extract archive entries whose pathnames contain
.Pa ..
or whose target directory would be altered by a symlink.
This option suppresses these behaviors.
.It Fl p
(x mode only)
Preserve file permissions.
Attempt to restore the full permissions, including owner, file modes, file
flags and ACLs, if available, for each item extracted from the archive.
By default, newly-created files are owned by the user running
.Nm ,
the file mode is restored for newly-created regular files, and
all other types of entries receive default permissions.
If
.Nm
is being run by root, the default is to restore the owner unless the
.Fl o
option is also specified.
.It Fl -passphrase Ar method:arg
Read the passphrase using the specified method.
.Bl -tag -width aa
.It Ar dev:tty-stdin
Attempt to read the passphrase from /dev/tty; if that fails, read it from stdin.
This is the default behaviour.
.It Ar dev:stdin-once
Attempt to read the passphrase from stdin, and do so only once even when
encrypting.
This cannot be used if
.Ar infile
is also stdin (aka '-').
.It Ar dev:tty-once
Attempt to read the passphrase from /dev/tty, and do so only once
even when encrypting.
.It Ar env:VAR
Read the passphrase from the environment variable specified by
.Ar VAR .
.Pp
.Bf Em
Storing a passphrase in an environment variable may be a security risk.
.Ef
Only use this option if you are certain that you know what you are doing.
.It Ar file:FILENAME
Read the passphrase from the file specified by
.Ar FILENAME .
.Pp
.Bf Em
Storing a passphrase in a file may be a security risk.
.Ef
Only use this option if you are certain that you know what you are doing.
.El
.It Fl -print-stats
(c and d modes only)
Print statistics for the archive being created (c mode) or delete (d mode).
See "PRINTING ARCHIVE STATISTICS" below for information on the output format.
.It Fl -progress-bytes Ar X
Display a progress message (as if generated from SIGUSR1 or SIGINFO) after
processing each
.Ar X
bytes.
Occurs at most once per file.
.It Fl q ( Fl -fast-read )
(x and t modes only)
Extract or list only the first archive entry that matches each pattern
or filename operand.
Exit as soon as each specified pattern or filename has been matched.
By default, the archive is always read to the very end, since
there can be multiple entries with the same name and, by convention,
later entries overwrite earlier entries.
This option is provided as a performance optimization.
.It Fl -quiet
Avoid printing some warnings.
Currently the warnings which are silenced by this option are
"Removing leading '/' ...",
"Not adding cache directory to archive",
"... file may have grown while being archived",
and
"Skipping entry on filesystem of type ...",
but it is likely that other
warnings will be silenced by this option in future versions of
.Nm .
.It Fl -resume-extract
(x mode only)
Don't extract files whose filesize and mtime matches existing files on the
disk.
Primarily used to resume an archive extraction which was interrupted.
The mtime comparison ignores sub-second timestamp precision, as this is not
supported on all filesystems.
This differs from
.Fl k
in that
.Fl -resume-extract
will overwrite a file if the size or modification time do not match, as can
happen if tarsnap is killed partway through extracting a file.
.It Fl -retry-forever
This option causes tarsnap to continue trying to reconnect to the
tarsnap server forever, instead of giving up after 5-10 minutes.
This may be useful for people with excessively flaky networks, or
on mobile devices which regularly lose their internet connections
for extended periods of time.
This is not enabled by default since continued failures generally indicate a
problem which should be investigated by the user.
.It Fl S
(x mode only)
Extract files as sparse files.
For every block on disk, check first if it contains any non-NULL bytes and seek
over it otherwise.
This works similar to the conv=sparse option of dd.
.It Fl s Ar pattern
Modify file or archive member names according to
.Pa pattern .
The pattern has the format /old/new/[gps].
old is a basic regular expression.
If it doesn't apply, the pattern is skipped.
new is the replacement string of the matched part.
~ is substituted with the match, \e1 to \e9 with the contents of
the corresponding captured group.
The optional trailing g specifies that matching should continue
after the matched part and stop on the first unmatched pattern.
The optional trailing s specifies that the pattern applies to the value
of symbolic links.
The optional trailing p specifies that after a successful substitution
the original path name and the new path name should be printed to
standard error.
.It Fl -snaptime Pa filename
(c mode only)
This option MUST be specified when creating a backup from a filesystem
snapshot, and
.Pa filename
must have a modification time prior to when the filesystem snapshot was
created.
(This is necessary to prevent races between file modification and snapshot
creation which could result in
.Nm
failing to recognize that a file has been modified.)
.It Fl -store-atime
(c mode only)
Enable the storing of file access times.
The default behaviour of
.Nm
is to not store file access times, since this can cause a significant amount
of bandwidth and storage to be wasted when the same set of files are archived
several times (e.g., if daily backup archives are created) due to
.Nm
itself accessing files and thereby causing their access times to be changed.
.It Fl -strip-components Ar count
(x mode only)
Remove the specified number of leading path elements.
Pathnames with fewer elements will be silently skipped.
Note that the pathname is edited after checking inclusion/exclusion patterns
but before security checks.
.It Fl T Ar filename
(c, x, and t modes only)
In x or t mode,
.Nm
will read the list of names to be extracted from
.Pa filename .
In c mode,
.Nm
will read names to be archived from
.Pa filename .
The special name
.Dq -C
on a line by itself will cause the current directory to be changed to
the directory specified on the following line.
Names are terminated by newlines unless
.Fl -null-input
is specified.
Note that
.Fl -null-input
also disables the special handling of lines containing
.Dq -C .
If
.Pa filename
is
.Dq -
then the list of names will be read from the standard input.
Note:  If you are generating lists of files using
.Xr find 1 ,
you probably want to use
.Fl n
as well.
.It Fl -totals
(c mode only)
Print the size of the archive after creating it.
This option is provided mainly for compatibility with GNU tar; in most
situations the
.Fl -print-stats
option will be far more useful.
.It Fl U
(x mode only)
Unlink files before creating them.
Without this option,
.Nm
overwrites existing files, which preserves existing hardlinks.
With this option, existing hardlinks will be broken, as will any
symlink that would affect the location of an extracted file.
.It Fl v
(c, d, t, x, and list-archives modes only)
Produce verbose output.
In create and extract modes,
.Nm
will list each file name as it is read from or written to
the archive.
In delete mode,
.Nm
will list the name of each archive as it is deleted.
In list mode,
.Nm
will produce output similar to that of
.Xr ls 1 .
Additional
.Fl v
options will provide additional detail.
.It Fl -verify-config
Check the configuration file(s) for syntactic errors.
.It Fl -version
Print version number of
.Nm ,
and exit.
.It Fl -verylowmem
(c mode only)
Reduce memory usage, by approximately a factor of 2 beyond
the memory usage when
.Fl -lowmem
is specified, by not caching anything.
.It Fl w
(c and x modes only)
Ask for confirmation for every action.
.It Fl X Ar filename
(c, x, and t modes only)
Read a list of exclusion patterns from the specified file.
See
.Fl -exclude
for more information about the handling of exclusions.
.El
.Sh SIGNALS
.Nm
handles the following signals:
.Bl -tag -width "SIGUSR2"
.It SIGUSR1 & SIGINFO
On receipt of the SIGUSR1 signal or (on platforms where it exists) the
SIGINFO signal,
.Nm
prints the current file or directory being processed, and (for files)
its progress within the file.
It also prints the number of files and the number of uncompressed bytes
processed.
Note that due to network buffering the file position will not align precisely
with how much data has been sent to or received from the
.Nm
server.
.It SIGSTOP & SIGTSTP
On receipt of a SIGSTOP or SIGTSTP signal, the kernel will suspend the
.Nm
process.
Upon receiving a SIGCONT signal,
.Nm
will reconnect to the server (if necessary) and continue the specified task.
.It SIGUSR2
On receipt of the SIGUSR2 signal, if
.Nm
is creating an archive (mode c), it will create a checkpoint at the
current position.
.It SIGQUIT
On receipt of the SIGQUIT signal, if
.Nm
is creating an archive (mode c) it will truncate the archive at the
current position and exit (see "INTERRUPTING ARCHIVAL" below).
.El
.Sh PRINTING ARCHIVE STATISTICS
There are four commands which print statistics about archives:
.Bl -bullet -width indent
.It
Global statistics:
.Dl Nm Fl -print-stats
.It
Global statistics and info about specific archive(s):
.Dl Nm Fl -print-stats Fl f Ar archive-name1 Op Fl f Ar ...
.It
Global statistics and info about all archives:
.Dl Nm Fl -print-stats Fl f Ar '*'
.It
Global statistics and info about the archive(s) that were just created or
deleted:
.Dl Nm Fl c Fl -print-stats Fl f Ar archive-name Ar DIR
.Dl Nm Fl d Fl -print-stats Fl f Ar archive-name1 Op Fl f Ar ...
.El
.Pp
.Nm
will print a table in the following format:
.Bd -literal
                                       Total size  Compressed size
All archives                         104491640436      51510524844
  (unique data)                       14830618089       7733620463
This archive                            808723344        289077325
New data                                 17858641          5658308
.Ed
.Pp
In this example, the combined size of all archives stored by
.Nm
using the same keys is 104 GB, and the combined size post-compression
would be 51 GB; but after removing duplicate blocks, there is only 14.8 GB
which is compressed down to 7.7 GB.
(It is this 7.7 GB which is stored via the Tarsnap service and must
thus be paid for.)
The newly created archive is 808 MB in size (compressible to 289 MB), but
only 17.8 MB of the data is new, and after compression only 5.6 MB is
uploaded to the Tarsnap server.
.Pp
When
.Nm
.Fl -print-stats
is executed as a command, the table is printed to the standard output;
when the
.Fl -print-stats
option is used while creating or deleting archives, the table is printed
to the standard error device.
.Pp
Global statistics are calculated based on the current cache directory, without
using the keyfile or querying the Tarsnap servers.
.Sh INTERRUPTING ARCHIVAL
Upon receipt of the
.Dv SIGQUIT
signal or \&^Q,
or if the bandwidth limit specified via a
.Fl -maxbw
option is reached,
.Nm
will interrupt the creation of an archive and truncate it
at the current position.
When an archive is truncated, it will be named according to
the user-specified name plus ".part" to denote the fact that
it is incomplete.
Such a truncated archive may be useful in its own right, but
also offers the benefit that future attempts to archive the
same data will be faster and use less bandwidth.
.Sh FIREWALLS
.Nm
communicates with the
.Nm
server via a TCP connection to port 9279; in some environments
it may be necessary to add a firewall rule to allow outgoing
TCP connections to this port.
At the present time (July 2009) there is only one IP address in
use for the
.Nm
server, so network administrators may wish to hard-code that IP
address; however, it is likely that at some point in the future
that IP address will change and/or other IP addresses will be
added.
.Sh ENVIRONMENT
The following environment variables affect the execution of
.Nm :
.Bl -tag -width ".Ev BLOCKSIZE"
.It Ev LANG
The locale to use.
See
.Xr environ 7
for more information.
.It Ev TZ
The timezone to use when displaying dates.
See
.Xr environ 7
for more information.
.El
.Sh FILES
.Bl -tag -width indent
.It Pa @sysconfdir@/tarsnap.conf
The system global
.Nm
configuration file.
Parameters specified here only take effect if they are not
specified via the current user's local configuration file
or via the command line.
.It Pa $XDG_CONFIG_HOME/tarsnap/tarsnap.conf
A
.Nm
configuration file for the current user.
If the environment variable
.Ev XDG_CONFIG_HOME
is empty, the default value of
.Pa ~/.config/tarsnap/tarsnap.conf
will be used.
Parameters specified here take effect unless they are specified via
.Pa ~/.tarsnaprc
or the command line.
.It Pa ~/.tarsnaprc
Another location for the
.Nm
configuration file for the current user.
Parameters specified here take effect unless they are
specified via the command line.
.El
.Sh EXIT STATUS
.Ex -std
.Pp
An exit code of 2 indicates that an error has occurred and the server-side
state was modified.
.Sh EXAMPLES
Register with the server and generate keys:
.Dl Nm tarsnap-keygen Fl -keyfile Pa /usr/tarsnap.key Fl -user Ar me@example.com Fl -machine Ar myserver
.Pp
Perform a backup of
.Pa /usr/home
and
.Pa /other/stuff/to/backup :
.Dl Nm Fl -keyfile Pa /usr/tarsnap.key Fl -cachedir Pa /usr/tarsnap-cache Fl c Fl f Ar backup-2008-04-24 Pa /usr/home Pa /other/stuff/to/backup
.Pp
Perform another backup, a day later;
this is much faster since tarsnap will avoid
storing data which was previously stored:
.Dl Nm Fl -keyfile Pa /usr/tarsnap.key Fl -cachedir Pa /usr/tarsnap-cache Fl c Fl f Ar backup-2008-04-25 Pa /usr/home Pa /other/stuff/to/backup
.Pp
List the archives:
.Dl Nm Fl -keyfile Pa /usr/tarsnap.key Fl -list-archives
.Pp
Delete the first backup, leaving the second backup intact:
.Dl Nm Fl -keyfile Pa /usr/tarsnap.key Fl -cachedir Pa /usr/tarsnap-cache Fl d Fl f Ar backup-2008-04-24
.Pp
List the files in the remaining backup:
.Dl Nm Fl -keyfile Pa /usr/tarsnap.key Fl tv Fl f Ar backup-2008-04-25
.Pp
Restore two users' home directories from the backup:
.Dl Nm Fl -keyfile Pa /usr/tarsnap.key Fl x Fl f Ar backup-2008-04-25 Pa usr/home/auser Pa usr/home/anotheruser
.Pp
In
.Pa /etc/crontab
to create a backup of the entire system at 10:32 each day:
.Dl 32 10 * * * root Nm Fl -keyfile Pa /usr/tarsnap.key Fl -cachedir Pa /usr/tarsnap-cache Fl c Fl f Ar backup-`date +\e%Y\e%m\e%d` Pa /
.Pp
Note that the
.Fl -keyfile
and
.Fl -cachedir
options can be specified via the
.Xr tarsnap.conf 5
configuration file, in which case they may be omitted
from the command line.
.Sh SECURITY
Certain security issues are common to many archiving programs, including
.Nm .
In particular, carefully-crafted archives can request that
.Nm
extract files to locations outside of the target directory.
This can potentially be used to cause unwitting users to overwrite
files they did not intend to overwrite.
If the archive is being extracted by the superuser, any file
on the system can potentially be overwritten.
There are three ways this can happen.
Although
.Nm
has mechanisms to protect against each one,
savvy users should be aware of the implications:
.Bl -bullet -width indent
.It
Archive entries can have absolute pathnames.
By default,
.Nm
removes the leading
.Pa /
character from filenames before restoring them to guard against this problem.
.It
Archive entries can have pathnames that include
.Pa ..
components.
By default,
.Nm
will not extract files containing
.Pa ..
components in their pathname.
.It
Archive entries can exploit symbolic links to restore
files to other directories.
An archive can restore a symbolic link to another directory,
then use that link to restore a file into that directory.
To guard against this,
.Nm
checks each extracted path for symlinks.
If the final path element is a symlink, it will be removed
and replaced with the archive entry.
If
.Fl U
is specified, any intermediate symlink will also be unconditionally removed.
If neither
.Fl U
nor
.Fl P
is specified,
.Nm
will refuse to extract the entry.
.El
.Pp
Although
.Nm
cryptographically signs archives in such a manner that it is believed
to be unfeasible for an attacker to forge an archive without having
possession of
.Ar key-file ,
you may wish to examine the contents of archive(s) with
.Dl Nm Fl t Fl -keyfile Ar key-file Fl f Ar archive-name
before extraction.
Note that the
.Fl P
option to
.Nm
disables the security checks above and allows you to extract
an archive while preserving any absolute pathnames,
.Pa ..
components, or symlinks to other directories.
.Sh SEE ALSO
.Xr tarsnap-keygen 1 ,
.Xr tar 5 ,
.Xr tarsnap.conf 5
.Sh HISTORY
A
.Nm tar
command appeared in Seventh Edition Unix, which was
released in January, 1979.
There have been numerous other implementations,
many of which extended the file format.
John Gilmore's
.Nm pdtar
public-domain implementation (circa November, 1987)
was quite influential, and formed the basis of GNU tar.
GNU tar was included as the standard system tar
in
.Fx
beginning with
.Fx 1.0 ,
but was replaced by Tim Kientzle's
.Nm bsdtar
utility and
.Xr libarchive 3
library in
.Fx 5.3 .
.Pp
.Nm
is built around
.Nm bsdtar
and
.Xr libarchive 3 .
.Sh BUGS
This program follows
.St -p1003.1-96
for the definition of the
.Fl l
option to
.Xr tar 5 .
Note that GNU tar prior to version 1.15 treated
.Fl l
as a synonym for the
.Fl -one-file-system
option.
.Pp
To archive a file called
.Pa @foo ,
.Pa @@foo ,
or
.Pa -foo
you must specify it as
.Pa ./@foo ,
.Pa ./@@foo ,
or
.Pa ./-foo ,
respectively.
.Pp
In create mode, a leading
.Pa ./
is always removed.
A leading
.Pa /
is stripped unless the
.Fl P
option is specified.
.Pp
Hard link information may be lost if an archive file which is included via the
.Cm @ Ns Pa archive-file
option is in a non-"tar" format.
(This is a consequence of the incompatible ways that different archive
formats store hardlink information.)
.Pp
There are alternative long options for many of the short options that
are deliberately not documented.
.Pp
The limit specified by a
.Fl -maxbw
option is not strictly enforced;
in particular, due to the need to cleanly terminate an archive, the
amount of bandwidth used may slightly exceed the limit.
.Pp
If
.Nm
is run with standard input, standard output, and standard error
redirected and inside a chroot where terminal devices are not
exposed, \&^Q will not be mapped to SIGQUIT and will consequently not
trigger the truncation of the current archive.