Provided by: borgbackup_1.1.15-1~ubuntu1.18.04.2_amd64 
NAME
borg - deduplicating and encrypting backup tool
SYNOPSIS
borg [common options] <command> [options] [arguments]
DESCRIPTION
BorgBackup (short: Borg) is a deduplicating backup program. Optionally, it supports compression and
authenticated encryption.
The main goal of Borg is to provide an efficient and secure way to backup data. The data deduplication
technique used makes Borg suitable for daily backups since only changes are stored. The authenticated
encryption technique makes it suitable for backups to not fully trusted targets.
Borg stores a set of files in an archive. A repository is a collection of archives. The format of
repositories is Borg-specific. Borg does not distinguish archives from each other in any way other than
their name, it does not matter when or where archives were created (e.g. different hosts).
EXAMPLES
A step-by-step example
1. Before a backup can be made a repository has to be initialized:
$ borg init --encryption=repokey /path/to/repo
2. Backup the ~/src and ~/Documents directories into an archive called Monday:
$ borg create /path/to/repo::Monday ~/src ~/Documents
3. The next day create a new archive called Tuesday:
$ borg create --stats /path/to/repo::Tuesday ~/src ~/Documents
This backup will be a lot quicker and a lot smaller since only new never before seen data is stored.
The --stats option causes Borg to output statistics about the newly created archive such as the amount
of unique data (not shared with other archives):
------------------------------------------------------------------------------
Archive name: Tuesday
Archive fingerprint: bd31004d58f51ea06ff735d2e5ac49376901b21d58035f8fb05dbf866566e3c2
Time (start): Tue, 2016-02-16 18:15:11
Time (end): Tue, 2016-02-16 18:15:11
Duration: 0.19 seconds
Number of files: 127
------------------------------------------------------------------------------
Original size Compressed size Deduplicated size
This archive: 4.16 MB 4.17 MB 26.78 kB
All archives: 8.33 MB 8.34 MB 4.19 MB
Unique chunks Total chunks
Chunk index: 132 261
------------------------------------------------------------------------------
4. List all archives in the repository:
$ borg list /path/to/repo
Monday Mon, 2016-02-15 19:14:44
Tuesday Tue, 2016-02-16 19:15:11
5. List the contents of the Monday archive:
$ borg list /path/to/repo::Monday
drwxr-xr-x user group 0 Mon, 2016-02-15 18:22:30 home/user/Documents
-rw-r--r-- user group 7961 Mon, 2016-02-15 18:22:30 home/user/Documents/Important.doc
...
6. Restore the Monday archive by extracting the files relative to the current directory:
$ borg extract /path/to/repo::Monday
7. Recover disk space by manually deleting the Monday archive:
$ borg delete /path/to/repo::Monday
NOTE:
Borg is quiet by default (it works on WARNING log level). You can use options like --progress or
--list to get specific reports during command execution. You can also add the -v (or --verbose or
--info) option to adjust the log level to INFO to get other informational messages.
NOTES
Positional Arguments and Options: Order matters
Borg only supports taking options (-s and --progress in the example) to the left or right of all
positional arguments (repo::archive and path in the example), but not in between them:
borg create -s --progress repo::archive path # good and preferred
borg create repo::archive path -s --progress # also works
borg create -s repo::archive path --progress # works, but ugly
borg create repo::archive -s --progress path # BAD
This is due to a problem in the argparse module: https://bugs.python.org/issue15112
Repository URLs
Local filesystem (or locally mounted network filesystem):
/path/to/repo - filesystem path to repo directory, absolute path
path/to/repo - filesystem path to repo directory, relative path
Also, stuff like ~/path/to/repo or ~other/path/to/repo works (this is expanded by your shell).
Note: you may also prepend a file:// to a filesystem path to get URL style.
Remote repositories accessed via ssh user@host:
user@host:/path/to/repo - remote repo, absolute path
ssh://user@host:port/path/to/repo - same, alternative syntax, port can be given
Remote repositories with relative paths can be given using this syntax:
user@host:path/to/repo - path relative to current directory
user@host:~/path/to/repo - path relative to user's home directory
user@host:~other/path/to/repo - path relative to other's home directory
Note: giving user@host:/./path/to/repo or user@host:/~/path/to/repo or user@host:/~other/path/to/repo is
also supported, but not required here.
Remote repositories with relative paths, alternative syntax with port:
ssh://user@host:port/./path/to/repo - path relative to current directory
ssh://user@host:port/~/path/to/repo - path relative to user's home directory
ssh://user@host:port/~other/path/to/repo - path relative to other's home directory
If you frequently need the same repo URL, it is a good idea to set the BORG_REPO environment variable to
set a default for the repo URL:
export BORG_REPO='ssh://user@host:port/path/to/repo'
Then just leave away the repo URL if only a repo URL is needed and you want to use the default - it will
be read from BORG_REPO then.
Use :: syntax to give the repo URL when syntax requires giving a positional argument for the repo (e.g.
borg mount :: /mnt).
Repository / Archive Locations
Many commands want either a repository (just give the repo URL, see above) or an archive location, which
is a repo URL followed by ::archive_name.
Archive names must not contain the / (slash) character. For simplicity, maybe also avoid blanks or other
characters that have special meaning on the shell or in a filesystem (borg mount will use the archive
name as directory name).
If you have set BORG_REPO (see above) and an archive location is needed, use ::archive_name - the repo
URL part is then read from BORG_REPO.
Logging
Borg writes all log output to stderr by default. But please note that something showing up on stderr does
not indicate an error condition just because it is on stderr. Please check the log levels of the messages
and the return code of borg for determining error, warning or success conditions.
If you want to capture the log output to a file, just redirect it:
borg create repo::archive myfiles 2>> logfile
Custom logging configurations can be implemented via BORG_LOGGING_CONF.
The log level of the builtin logging configuration defaults to WARNING. This is because we want Borg to
be mostly silent and only output warnings, errors and critical messages, unless output has been requested
by supplying an option that implies output (e.g. --list or --progress).
Log levels: DEBUG < INFO < WARNING < ERROR < CRITICAL
Use --debug to set DEBUG log level - to get debug, info, warning, error and critical level output.
Use --info (or -v or --verbose) to set INFO log level - to get info, warning, error and critical level
output.
Use --warning (default) to set WARNING log level - to get warning, error and critical level output.
Use --error to set ERROR log level - to get error and critical level output.
Use --critical to set CRITICAL log level - to get critical level output.
While you can set misc. log levels, do not expect that every command will give different output on
different log levels - it's just a possibility.
WARNING:
Options --critical and --error are provided for completeness, their usage is not recommended as you
might miss important information.
Return codes
Borg can exit with the following return codes (rc):
───────────────────────────────────────────────────────
Return code Meaning
───────────────────────────────────────────────────────
0 success (logged as INFO)
───────────────────────────────────────────────────────
1 warning (operation reached its normal
end, but there were warnings -- you
should check the log, logged as
WARNING)
───────────────────────────────────────────────────────
2 error (like a fatal error, a local or
remote exception, the operation did
not reach its normal end, logged as
ERROR)
───────────────────────────────────────────────────────
128+N killed by signal N (e.g. 137 == kill
-9)
┌─────────────┬───────────────────────────────────────┐
│ │ │
--
SEE ALSO │ │ │ │ │
--
AUTHOR │ │ │ │ │
The Borg Collective │ │ │ │ │
│ │ │ │ │
│ │ │ │ │