TARSNAP(1)

📦

version 1.0.41 · 2 versions

1.0.41 · arch rolling (latest)
1.0.41 · ubuntu stonking

💾 `TARSNAP(1)` — manipulate remote encrypted backups 💾

okay bestie, welcome to the General Commands Manual page for tarsnap, aka your remote encrypted backup baddie. we're talking create, read, delete, and otherwise manage online backups — and yes, it's literally giving main character energy. 🫶

✨ NAME ✨

tarsnap — manipulate remote encrypted backups.

🌸 SYNOPSIS 🌸

the synopsis is giving choose-your-own-adventure, so here it is exactly, no cap:

       tarsnap {-c} --keyfile key-file --cachedir cache-dir -f archive-name
               [options] [files | directories]
       tarsnap {-d} --keyfile key-file --cachedir cache-dir -f archive-name
               [options]
       tarsnap {-t | -x} --keyfile key-file -f archive-name [options]
               [patterns]
       tarsnap {-r} --keyfile key-file -f archive-name
       tarsnap {--list-archives} --keyfile key-file
       tarsnap {--print-stats} --keyfile key-file --cachedir cache-dir
               [-f archive-name]
       tarsnap {--recover} --keyfile key-file --cachedir cache-dir
       tarsnap {--fsck} --keyfile key-file --cachedir cache-dir
       tarsnap {--fsck-prune} --keyfile key-file --cachedir cache-dir
       tarsnap {--initialize-cachedir} --keyfile key-file --cachedir cache-dir
       tarsnap {--nuke} --keyfile key-file
       tarsnap --verify-config
       tarsnap --version

💖 DESCRIPTION 💖

tarsnap creates, reads, deletes, and otherwise manages online backups. iconic behavior, honestly.

bestie, the very first option you give tarsnap is a mode indicator, and it has to be one of these:

-c — Create an archive containing the specified items and name. 🎀
-d — Delete the specified archive.
-t — List archive contents to stdout.
-x — Extract to disk from the archive.
-r — Read the specified archive, convert it to a tar stream, and write it to stdout.
--list-archives — Print the names of archives stored. If the -v flag is specified one or more times, the creation time of each archive is also printed; if the -v flag is specified two or more times, the command line with which tarsnap was invoked to create each archive is also printed. 👑
--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.
--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.
--fsck — Perform some integrity checks on the archives stored, and reconstruct the cache directory cache-dir. In the unlikely event that there are corrupted archives, tarsnap will exit and request that it be run with the --fsck-prune option.
--fsck-prune — Run as --fsck, but if corrupt archives are detected, prune the broken data.
--initialize-cachedir — Create and initialize the cachedir. This option is intended for the GUI and is not needed for command-line usage.
--nuke — Delete all of the archives stored. To protect against accidental data loss, tarsnap will ask you to type the text No Tomorrow when using the --nuke command. 💀
--verify-config — Check the configuration file(s) for syntactic errors.
--version — Print version number of tarsnap, and exit.

in -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. 🦋

in -t or -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 tcsh(1). note that these follow the POSIX rules for pattern matching, e.g., [] are special characters which can be escaped with a backslash. ✨

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.

🎀 OPTIONS 🎀

okay now the options — and bestie, I did not skip a single one. 💅

@archive-file — (c mode only) The specified archive file is read and the entries in it will be appended to the current archive. If archive-file is - then the archive will be read from the standard input. As an example, this little cutie:

tarsnap -c --keyfile key-file --cachedir cache-dir -f
mybackup @backup.tar

reads the archive file backup.tar from disk and stores it using tarsnap.

@@archive-name — (c mode only) The specified tarsnap archive is read and the entries in it will be appended to the current archive.
--aggressive-networking — (c mode only) Use multiple TCP connections to send data to the tarsnap 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. 🔥
--archive-names filename — Read a list of archive names from filename.
-C 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.
--cachedir cache-dir — (c, d, print-stats, and fsck modes only) Cache information about the archives stored by tarsnap in the directory cache-dir. The contents of this directory will not be backed up by tarsnap, so it should not be used for any other purpose. If the directory cache-dir is lost, it can be reconstructed by running tarsnap --fsck. 🫶
--check-links — (c mode only) Issue a warning message unless all links to each file are archived.
--checkpoint-bytes bytespercheckpoint — (c mode only) Create a checkpoint after every bytespercheckpoint bytes of uploaded data. The value 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.
--chroot — (x mode only) chroot() to the current directory after processing any -C options and before extracting any files.
--configfile filename — Add 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.
--creationtime 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.
--csv-file filename — (use with --print-stats) Write statistics in CSV format to a file.
--disk-pause X — (c mode only) Pause for X ms between storing archive entries and after every 64 kB of file data. This will slow down tarsnap 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 --disk-pause 10 will approximately double the time taken.
--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 -v option is used), progress messages (if the --progress-bytes option is used), and final statistics printed (if the --print-stats option is used) will be almost identical (typically within a few kB or a fraction of a percent) to if tarsnap is run without the --dry-run option.

Note that the --maxbw option does not work in combination with --dry-run, since no bandwidth is actually used, and that since tarsnap does not contact the tarsnap 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 @@archive-name, then some network bandwidth will be used while tarsnap reads metadata about archive-name from the tarsnap server.

Furthermore, --dry-run will not check whether the cache directory is out of sync.

--dry-run-metadata — (c mode only) Don't really create an archive; just simulate doing so. This is similar to --dry-run, except that it doesn't read any files; it only processes filesystem metadata.

This is significantly faster than a regular --dry-run, but it is still suitable for checking which filesystem entries will be archived (with -v), or getting the total uncompressed archive size (via --totals or --progress-bytes).

This option cannot be used with --print-stats.

--dump-config — Print out the command-line and all non-blank lines read from config files.
--exclude 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.
-f archive-name — (c, d, x, t, r, list-archives, and print-stats modes only) Operate on the archive archive-name. In mode c, if archive creation is interrupted by ^Q, the SIGQUIT signal, or reaching the bandwidth limit specified via a --maxbw option, the archive will be stored with .part appended to its name. In mode print-stats, if archive-name is *, statistics will be printed for every archive. In the print-stats and d modes, -f 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.

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).

As a special case, if used with --list-archives --hashes then -f indicates a tapehash instead of an 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. (-f cannot be used with --list-archives if it does not also include --hashes.)

--force-resources — bestie, this one lets the decryption of a passphrase-encrypted key file keep going even when it’s expected to eat a whole lot of memory or CPU time. Like, it’s gonna be a lot, but you’re forcing it anyway. 💅
-H — (c mode only) symlinks named right on the command line get followed; the target of the link is what gets archived, not the link itself. Slay for following the vibe.
-h — (c mode only) literally just a synonym for -L. Same energy.
--hashes — (list-archives mode only) prints hashes of archive names. If you specify -v one or more times, it also prints the archive name. This is for the GUI, and ngl you don’t need it for command-line usage. 🫶
--humanize-numbers — uses SI prefixes to make the numbers printed by --print-stats and SIGINFO more readable. Cute little numbers, no cap.
-I — synonym for -T. iconic shortcut behavior.
--include pattern — (c, x, and t modes only) process only files or directories that match the specified pattern. Important: exclusions specified with --exclude take precedence over inclusions. If no inclusions are explicitly specified, all entries are processed by default. The --include option is especially useful when filtering archives. For example, this command

tarsnap -c -f foo-backup --include='*foo*' @@all-backup

creates a new archive foo-backup containing only the entries from all-backup containing the string ‘foo’. Obsessed with a filtered archive moment.

--insane-filesystems — (c mode only) allows descent into synthetic filesystems such as procfs. Normally archiving those filesystems is a silly thing to do, hence the name. It’s giving “we’re doing it anyway” energy. 😭
--iso-dates — (t mode only) prints file and directory dates as yyyy-mm-dd hh:mm:ss. 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. Date formatting but make it ISO.
-k — (x mode only) do not overwrite existing files. Specifically, if a file appears more than once in an archive, later copies will not overwrite earlier copies. Respecting the existing files fr fr.
--keep-going — (d and print-stats modes only) keep deleting or printing statistics after finding that one of the archives specified does not exist. No rage-quitting the whole run over one missing archive. 🫶
--keep-newer-files — (x mode only) do not overwrite existing files that are newer than the versions appearing in the archive being extracted. Protect the newer files, periodt.
--keyfile key-file — (all modes) obtain encryption, authentication, and access keys from key-file. This file should have been generated by tarsnap-keygen(1). Key file is the main character here.
-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. Follow the link, bestie.
-l — synonym for the --check-links option. Just a little alias moment.
--lowmem — (c mode only) reduces 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. Low memory, high vibes.
-m — (x mode only) do not extract modification time. By default, the modification time is set to the time stored in the archive. So -m is like “leave the mtime alone.”
--maxbw numbytes — (c mode only) interrupt archival if more than numbytes bytes of upstream bandwidth is used (see INTERRUPTING ARCHIVAL below for details). Bandwidth limit with a dramatic exit.
--maxbw-rate bytespersecond — limit download and upload bandwidth used to bytespersecond bytes per second. Both directions get the cap. ✨
--maxbw-rate-down bytespersecond — limit download bandwidth used to bytespersecond bytes per second. Down only, bestie.
--maxbw-rate-up bytespersecond — limit upload bandwidth used to bytespersecond bytes per second. Up only, no cap on the down.
-n — (c mode only) do not recursively archive the contents of directories. Just the directory itself, not the whole tree. Shallow but on purpose.
--newer date — (c, x, t modes only) only include files and directories newer than the specified date. This compares ctime entries. Newer-than filter, ctime edition. 🕰️
--newer-mtime date — (c mode only) like --newer, except it compares mtime entries instead of ctime entries. Same idea, mtime flavor.
--newer-than filename — (c mode only) only include files and directories newer than the specified file. This compares ctime entries. Compare against a file instead of a date, ctime style.
--newer-mtime-than filename — (c mode only) like --newer-than, except it compares mtime entries instead of ctime entries. File comparison, mtime edition.
--no-aggressive-networking — ignore any aggressive-networking option specified in a configuration file. Config said aggressive, command line said no thanks. 💅
--no-config-exclude — ignore any exclude option specified in a configuration file. Normally exclude options specified via configuration files and the command line all take effect. This one just tells the config excludes to chill.
--no-config-include — ignore any include option specified in a configuration file. Normally include options specified via configuration files and the command line all take effect. Config includes? Not today.
--no-default-config — do not read the default configuration files /etc/tarsnap/tarsnap.conf, $XDG_CONFIG_HOME/tarsnap/tarsnap.conf, and ~/.tarsnaprc. No default config, no extra opinions.
--no-disk-pause — ignore any disk-pause option specified in a configuration file. The disk-pause vibe has been cancelled.
--no-force-resources — ignore any force-resources option specified in a configuration file. No forcing from the config.
--no-humanize-numbers — ignore any humanize-numbers option specified in a configuration file. Numbers stay un-humanized if config tried it.
--no-insane-filesystems — ignore any insane-filesystems option specified in a configuration file. The config cannot make the filesystems insane on your behalf. 😭
--no-iso-dates — ignore any iso-dates option specified in a configuration file. The config’s ISO date agenda is ignored.
--no-maxbw — ignore any maxbw option specified in a configuration file. Config bandwidth cap? Not necessarily.
--no-maxbw-rate-down — ignore any maxbw-rate-down option specified in a configuration file. If a 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 --no-maxbw-rate-up is also specified). Careful with the cross-effects, bestie. 🫶
--no-maxbw-rate-up — ignore any maxbw-rate-up option specified in a configuration file. If a 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 --no-maxbw-rate-down is also specified). Same energy, opposite direction.
--no-noatime — ignore any noatime option specified in a configuration file. Config noatime? Ignored.
--no-nodump — ignore any nodump option specified in a configuration file. Config nodump? Ignored.
--no-print-stats — ignore any print-stats option specified in a configuration file. No stats from config, thank you.
--no-progress-bytes — ignore any progress-bytes option specified in a configuration file. Progress bytes from config? Nope.
--no-quiet — ignore any quiet option specified in a configuration file. Config tried to be quiet; you said no.
--no-retry-forever — ignore any retry-forever option specified in a configuration file. Forever-retry vibe from config gets dismissed.
--no-snaptime — ignore any snaptime option specified in a configuration file. Config snaptime? Ignored.
--no-store-atime — ignore any store-atime option specified in a configuration file. Config atime storage? Also ignored.
--no-totals — ignore any totals option specified in a configuration file. The config cannot force totals on you.
--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. When it works, it’s a little time-saver; when it doesn’t, it’s not supported. 🤷
--nodump — (c mode only) honor the nodump file flag by skipping this file or directory. If the file says nodump, we skip it. Respect.
--noisy-warnings — be verbose when warning about network glitches. This is probably only useful for debugging purposes. Loud warnings, debugging bestie energy.
--normalmem — ignore any lowmem or verylowmem option specified in a configuration file. Going back to normal memory behavior, no matter what the config wanted.
--null — (use with -I, -T, or -X) synonym for --null-input. Kept for historical reasons and compatibility with other tar utilities. A legacy icon. 👑
--null-input — (use with -I, -T, or -X) filenames, archive names, and patterns are separated by null characters, not by newlines. This is often used to read filenames output by the -print0 option to find(1). Null-separated input, super handy with find -print0. ✨
--null-output — (x, t, list-archives, and print-stats modes only) archive names, filenames, and lines in output are separated by null characters, not by newlines. 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. Null-separated output with very specific null counts — keep them exact, bestie.
--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. Numbers only, no names.
-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. Output redirection but make it iconic.
-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 -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. Important caveat, not me forgetting it. 🫶
--one-file-system — (c mode only) do not cross mount points. Stay on this filesystem, bestie.
-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, tarsnap will refuse to extract archive entries whose pathnames contain .. or whose target directory would be altered by a symlink. This option suppresses these behaviors. Big safety behavior; -P turns it off. Be careful, no cap.
-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 tarsnap, the file mode is restored for newly-created regular files, and all other types of entries receive default permissions. If tarsnap is being run by root, the default is to restore the owner unless the -o option is also specified. Permission preservation with all the details intact.
--passphrase method:arg — read the passphrase using the specified method. Passphrase method selected, periodt.
dev:tty-stdin — tries to read your passphrase from /dev/tty, and if that's a no-go, it falls back to stdin. Lowkey this is the default behaviour, so it's probably what you're already getting. 💅
dev:stdin-once — reads the passphrase from stdin, and does it only once even when you're encrypting. Heads up tho: you can't use this if infile is also stdin (aka -). 🫶
dev:tty-once — reads the passphrase from /dev/tty, and again, only once even when encrypting. ✨
env:VAR — reads the passphrase from the environment variable named by VAR.

⚠️ Storing a passphrase in an environment variable may be a security risk. Only use this option if you are certain that you know what you are doing. Like, actually certain bestie 😭

file:FILENAME — reads the passphrase from the file specified by FILENAME.

⚠️ Storing a passphrase in a file may be a security risk. Only use this option if you are certain that you know what you are doing. (Same energy, same warning, no cap.) 💀

--print-stats — (c and d modes only) prints statistics for the archive being created (c mode) or deleted (d mode). Wanna know what the output even looks like? Check out "PRINTING ARCHIVE STATISTICS" below, it's all laid out there. 📊
--progress-bytes X — shows a progress message every time X bytes get processed — same vibe as the one you'd get from SIGUSR1 or SIGINFO. It happens at most once per file. ✨
-q, --fast-read — (x and t modes only) extracts or lists only the first archive entry that matches each pattern or filename operand, then dips out as soon as every specified pattern or filename has been matched. By default tarsnap always reads the archive all the way to the very end, because there can be multiple entries with the same name and, by convention, later entries overwrite earlier ones. This one's literally just a performance optimization, iykyk 🏃‍♀️💨
--quiet — skips printing some warnings. Right now the ones this silences 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's likely that other warnings will get silenced by this option in future versions of tarsnap. So like, don't be shocked if the list grows 🫣
--resume-extract — (x mode only) doesn't extract files whose filesize and mtime match files that already exist on disk. Mainly used to resume an archive extraction that got interrupted (annoying 😤). The mtime comparison ignores sub-second timestamp precision, since not all filesystems support that. This differs from -k in that --resume-extract will overwrite a file if the size or modification time don't match — which can happen if tarsnap gets killed partway through extracting a file. 💅
--retry-forever — makes tarsnap keep trying to reconnect to the tarsnap server forever, instead of giving up after 5-10 minutes. Super useful for people with excessively flaky networks, or on mobile devices that regularly lose their internet connections for extended periods of time. It's not enabled by default since continued failures generally indicate a problem which should be investigated by the user — so like, it's a choice, not a fix 🔌✨
-S — (x mode only) extracts files as sparse files. For every block on disk, it checks first if it contains any non-NULL bytes and seeks over it otherwise. Works similar to the conv=sparse option of dd. Iconic efficiency behaviour honestly 🦋
-s pattern — modifies file or archive member names according to pattern. The pattern has the format /old/new/[gps]. Here's the breakdown, bestie:
- 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, and \1 to \9 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. 👀
--snaptime filename — (c mode only) this option MUST be specified when creating a backup from a filesystem snapshot, and 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 tarsnap failing to recognize that a file has been modified.) Like, it's not optional, it's a must-must. 🔥
--store-atime — (c mode only) enables the storing of file access times. The default behaviour of tarsnap 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) — because tarsnap itself accesses files and thereby causes their access times to be changed. Basically it'd be tarsnap snitching on itself 😭
--strip-components count — (x mode only) removes the specified number of leading path elements. Pathnames with fewer elements will be silently skipped (no drama, just quietly ignored 🫶). Note that the pathname is edited after checking inclusion/exclusion patterns but before security checks. Order matters, bestie.
-T filename — (c, x, and t modes only) in x or t mode, tarsnap will read the list of names to be extracted from filename. In c mode, tarsnap will read names to be archived from filename. The special name “-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 --null-input is specified. Note that --null-input also disables the special handling of lines containing “-C”. If filename is “-” then the list of names will be read from the standard input. 📝

💡 Note: If you are generating lists of files using find(1), you probably want to use -n as well. Trust, you'll want it.

--totals — (c mode only) prints the size of the archive after creating it. This option is provided mainly for compatibility with GNU tar; in most situations the --print-stats option will be far more useful. So like, it's giving legacy support 🌸
-U — (x mode only) unlinks files before creating them. Without this option, tarsnap 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. So yeah, -U is the "break the links" girlie 💅
-v — (c, d, t, x, and list-archives modes only) produces verbose output. In create and extract modes, tarsnap will list each file name as it is read from or written to the archive. In delete mode, tarsnap will list the name of each archive as it is deleted. In list mode, tarsnap will produce output similar to that of ls(1). Additional -v options will provide additional detail. Stack 'em up for maximum tea ☕✨
--verify-config — checks the configuration file(s) for syntactic errors. A little vibe check for your config 🧚
--version — prints the version number of tarsnap, and exits. Short, sweet, slays 👑
--verylowmem — (c mode only) reduces memory usage by approximately a factor of 2 beyond the memory usage when --lowmem is specified, by not caching anything. For when your machine is struggling 😭
-w — (c and x modes only) asks for confirmation for every action. Yes, every single one. Very "are you sure?" of it 🙈
-X filename — (c, x, and t modes only) reads a list of exclusion patterns from the specified file. See --exclude for more information about the handling of exclusions. 💜

🚨 SIGNALS 🚨

tarsnap handles the following signals — here's the whole lineup, bestie:

💫 SIGUSR1 & SIGINFO

On receipt of the SIGUSR1 signal or (on platforms where it exists) the SIGINFO signal, tarsnap 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 tarsnap server. So like, don't @ me if the numbers are a little off 💀

😴 SIGSTOP & SIGTSTP

On receipt of a SIGSTOP or SIGTSTP signal, the kernel will suspend the tarsnap process. Upon receiving a SIGCONT signal, tarsnap will reconnect to the server (if necessary) and continue the specified task. It's giving "nap time then back to business" 🛌➡️💅

📌 SIGUSR2

On receipt of the SIGUSR2 signal, if tarsnap is creating an archive (mode c), it will create a checkpoint at the current position. Little save point, love that for you 🎀

🛑 SIGQUIT

On receipt of the SIGQUIT signal, if tarsnap is creating an archive (mode c) it will truncate the archive at the current position and exit (see "INTERRUPTING ARCHIVAL" below). Like, it actually stops — so know what you're doing before you send it 😤

📊 PRINTING ARCHIVE STATISTICS 📊

okay so there are literally four commands that print stats about archives, and they're all serving different vibes:

Global statistics, that's it: tarsnap --print-stats
Global statistics plus info about specific archive(s): tarsnap --print-stats -f archive-name1 [-f ...]
Global statistics plus info about all the archives: tarsnap --print-stats -f '*'
Global statistics plus info about the archive(s) you just created or deleted: tarsnap -c --print-stats -f archive-name DIR — and — tarsnap -d --print-stats -f archive-name1 [-f ...]

tarsnap will print a table that looks like this, bestie:

                                       Total size  Compressed size
All archives                         104491640436      51510524844
  (unique data)                       14830618089       7733620463
This archive                            808723344        289077325
New data                                 17858641          5658308

So in this example, the combined size of every archive tarsnap has stored using the same keys is 104 GB, and combined post-compression that would be 51 GB — but after the duplicate blocks get yeeted, there's only 14.8 GB left, which compresses down to 7.7 GB. (And it's that 7.7 GB that actually lives on the Tarsnap service, so that's the amount you're paying for, periodt.) The newly created archive is 808 MB (compressible to 289 MB), but only 17.8 MB of that is actually new data, and after compression only 5.6 MB gets uploaded to the Tarsnap server. efficient queen 💅

When tarsnap --print-stats is executed as a command, the table goes to the standard output. But when the --print-stats option is used while you're creating or deleting archives, the table is printed to the standard error device instead. different stage, same star ✨

Global statistics are calculated based on the current cache directory — no keyfile needed, no querying the Tarsnap servers. it just knows. 🔮

✋ INTERRUPTING ARCHIVAL ✋

Upon receipt of the SIGQUIT signal or Ctrl+Q, or if the bandwidth limit specified via a --maxbw option is reached, tarsnap will interrupt the creation of an archive and truncate it at the current position. When an archive is truncated, it gets named according to the user-specified name plus ".part" — that suffix is literally there to denote the fact that it's incomplete. Such a truncated archive may be useful in its own right, but it also has the benefit that future attempts to archive the same data will be faster and use less bandwidth. sad for the archive, iconic for your future self 🫶

🔥 FIREWALLS 🔥

tarsnap communicates with the tarsnap 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 tarsnap 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. so don't get too attached to it, ngl 🙈

🌿 ENVIRONMENT 🌿

The following environment variables affect the execution of tarsnap:

LANG — the locale to use. See environ(7) for more information.
TZ — the timezone to use when displaying dates. See environ(7) for more information.

📁 FILES 📁

/etc/tarsnap/tarsnap.conf — the system global tarsnap 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. hierarchy, bestie 👑
$XDG_CONFIG_HOME/tarsnap/tarsnap.conf — a tarsnap configuration file for the current user. If the environment variable XDG_CONFIG_HOME is empty, the default value of ~/.config/tarsnap/tarsnap.conf will be used. Parameters specified here take effect unless they are specified via ~/.tarsnaprc or the command line.
~/.tarsnaprc — another location for the tarsnap configuration file for the current user. Parameters specified here take effect unless they are specified via the command line. the classic, the original, the moment 💜

🎬 EXIT STATUS 🎬

The tarsnap utility exits 0 on success, and >0 if an error occurs.

An exit code of 2 indicates that an error has occurred and the server-side state was modified. so like, it broke but it also changed stuff on the server — read that number carefully 🔴

💫 EXAMPLES 💫

tarsnap-keygen --keyfile /usr/tarsnap.key --user me@example.com
--machine myserver

Perform a backup of /usr/home and /other/stuff/to/backup:

tarsnap --keyfile /usr/tarsnap.key --cachedir /usr/tarsnap-cache
-c -f backup-2008-04-24 /usr/home /other/stuff/to/backup

Perform another backup, a day later; this is much faster since tarsnap will avoid storing data which was previously stored:

tarsnap --keyfile /usr/tarsnap.key --cachedir /usr/tarsnap-cache
-c -f backup-2008-04-25 /usr/home /other/stuff/to/backup

List the archives:

tarsnap --keyfile /usr/tarsnap.key --list-archives

Delete the first backup, leaving the second backup intact:

tarsnap --keyfile /usr/tarsnap.key --cachedir /usr/tarsnap-cache
-d -f backup-2008-04-24

List the files in the remaining backup:

tarsnap --keyfile /usr/tarsnap.key -tv -f backup-2008-04-25

Restore two users' home directories from the backup:

tarsnap --keyfile /usr/tarsnap.key -x -f backup-2008-04-25
usr/home/auser usr/home/anotheruser

In /etc/crontab to create a backup of the entire system at 10:32 each day:

      32 10 * * * root tarsnap --keyfile /usr/tarsnap.key --cachedir
      /usr/tarsnap-cache -c -f backup-`date +\%Y\%m\%d` /

Note that the --keyfile and --cachedir options can be specified via the tarsnap.conf(5) configuration file, in which case they may be omitted from the command line. your crontab stays clean, your backups stay cute 🌸

🛡️ SECURITY 🛡️

Certain security issues are common to many archiving programs, including tarsnap. In particular, carefully-crafted archives can request that tarsnap 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. And if the archive is being extracted by the superuser, literally any file on the system can potentially be overwritten. 😭 There are three ways this can happen. Although tarsnap has mechanisms to protect against each one, savvy users should be aware of the implications:

Archive entries can have absolute pathnames. By default, tarsnap removes the leading / character from filenames before restoring them to guard against this problem.
Archive entries can have pathnames that include .. components. By default, tarsnap will not extract files containing .. components in their pathname.
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, tarsnap 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 -U is specified, any intermediate symlink will also be unconditionally removed. If neither -U nor -P is specified, tarsnap will refuse to extract the entry. the audacity 💀

Although tarsnap 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 key-file, you may wish to examine the contents of archive(s) with

tarsnap -t --keyfile key-file -f archive-name

before extraction. Note that the -P option to tarsnap disables the security checks above and allows you to extract an archive while preserving any absolute pathnames, .. components, or symlinks to other directories. so like, -P is that girl but she plays fast and loose, yk? ⚠️

📜 HISTORY 📜

A 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 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 FreeBSD beginning with FreeBSD 1.0, but was replaced by Tim Kientzle's bsdtar utility and libarchive(3) library in FreeBSD 5.3.

tarsnap is built around bsdtar and libarchive(3). ancestry reveal, honestly 🧬✨

🐛 BUGS 🐛

This program follows ISO/IEC 9945-1:1996 (“POSIX.1”) for the definition of the -l option to tar(5). Note that GNU tar prior to version 1.15 treated -l as a synonym for the --one-file-system option.
To archive a file called @foo, @@foo, or -foo you must specify it as ./@foo, ./@@foo, or ./-foo, respectively.
In create mode, a leading ./ is always removed. A leading / is stripped unless the -P option is specified.
Hard link information may be lost if an archive file which is included via the @archive-file option is in a non-"tar" format. (This is a consequence of the incompatible ways that different archive formats store hardlink information.)
There are alternative long options for many of the short options that are deliberately not documented. secret menu, no cap 🤫
The limit specified by a --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.
If tarsnap is run with standard input, standard output, and standard error redirected and inside a chroot where terminal devices are not exposed, Ctrl+Q will not be mapped to SIGQUIT and will consequently not trigger the truncation of the current archive.

and that's the whole page, bestie! 🎀 this one's from the Debian fam, dated March 20, 2025 — go forth and back up responsibly, mwah 💖🦋

📦 where this page comes from

arch rolling: tarsnap 1.0.41-1 · custom
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash-1017 on 2026-11-04: a language model's rewrite of the original, under its terms