path: root/docs/man/borg.1

.\" Man page generated from reStructuredText.
.
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "BORG" 1 "2023-08-30" "" "borg backup tool"
.SH NAME
borg \- deduplicating and encrypting backup tool
.SH SYNOPSIS
.sp
borg [common options] <command> [options] [arguments]
.SH DESCRIPTION
.\" we don't include the README.rst here since we want to keep this terse.
.
.sp
BorgBackup (short: Borg) is a deduplicating backup program.
Optionally, it supports compression and authenticated encryption.
.sp
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.
.sp
Borg stores a set of files in an \fIarchive\fP\&. A \fIrepository\fP is a collection
of \fIarchives\fP\&. 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).
.SH EXAMPLES
.SS A step\-by\-step example
.INDENT 0.0
.IP 1. 3
Before a backup can be made a repository has to be initialized:
.INDENT 3.0
.INDENT 3.5
.sp
.nf
.ft C
$ borg init \-\-encryption=repokey /path/to/repo
.ft P
.fi
.UNINDENT
.UNINDENT
.IP 2. 3
Backup the \fB~/src\fP and \fB~/Documents\fP directories into an archive called
\fIMonday\fP:
.INDENT 3.0
.INDENT 3.5
.sp
.nf
.ft C
$ borg create /path/to/repo::Monday ~/src ~/Documents
.ft P
.fi
.UNINDENT
.UNINDENT
.IP 3. 3
The next day create a new archive called \fITuesday\fP:
.INDENT 3.0
.INDENT 3.5
.sp
.nf
.ft C
$ borg create \-\-stats /path/to/repo::Tuesday ~/src ~/Documents
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This backup will be a lot quicker and a lot smaller since only new never
before seen data is stored. The \fB\-\-stats\fP option causes Borg to
output statistics about the newly created archive such as the amount of unique
data (not shared with other archives):
.INDENT 3.0
.INDENT 3.5
.sp
.nf
.ft C
\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
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
\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
.ft P
.fi
.UNINDENT
.UNINDENT
.IP 4. 3
List all archives in the repository:
.INDENT 3.0
.INDENT 3.5
.sp
.nf
.ft C
$ borg list /path/to/repo
Monday                               Mon, 2016\-02\-15 19:14:44
Tuesday                              Tue, 2016\-02\-16 19:15:11
.ft P
.fi
.UNINDENT
.UNINDENT
.IP 5. 3
List the contents of the \fIMonday\fP archive:
.INDENT 3.0
.INDENT 3.5
.sp
.nf
.ft C
$ 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
\&...
.ft P
.fi
.UNINDENT
.UNINDENT
.IP 6. 3
Restore the \fIMonday\fP archive by extracting the files relative to the current directory:
.INDENT 3.0
.INDENT 3.5
.sp
.nf
.ft C
$ borg extract /path/to/repo::Monday
.ft P
.fi
.UNINDENT
.UNINDENT
.IP 7. 3
Delete the \fIMonday\fP archive (please note that this does \fBnot\fP free repo disk space):
.INDENT 3.0
.INDENT 3.5
.sp
.nf
.ft C
$ borg delete /path/to/repo::Monday
.ft P
.fi
.UNINDENT
.UNINDENT
.IP 8. 3
Recover disk space by compacting the segment files in the repo:
.INDENT 3.0
.INDENT 3.5
.sp
.nf
.ft C
$ borg compact /path/to/repo
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
Borg is quiet by default (it works on WARNING log level).
You can use options like \fB\-\-progress\fP or \fB\-\-list\fP to get specific
reports during command execution.  You can also add the \fB\-v\fP (or
\fB\-\-verbose\fP or \fB\-\-info\fP) option to adjust the log level to INFO to
get other informational messages.
.UNINDENT
.UNINDENT
.SH NOTES
.SS Positional Arguments and Options: Order matters
.sp
Borg only supports taking options (\fB\-s\fP and \fB\-\-progress\fP in the example)
to the left or right of all positional arguments (\fBrepo::archive\fP and \fBpath\fP
in the example), but not in between them:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
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
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This is due to a problem in the argparse module: \fI\%https://bugs.python.org/issue15112\fP
.SS Repository URLs
.sp
\fBLocal filesystem\fP (or locally mounted network filesystem):
.sp
\fB/path/to/repo\fP \- filesystem path to repo directory, absolute path
.sp
\fBpath/to/repo\fP \- filesystem path to repo directory, relative path
.sp
Also, stuff like \fB~/path/to/repo\fP or \fB~other/path/to/repo\fP works (this is
expanded by your shell).
.sp
Note: you may also prepend a \fBfile://\fP to a filesystem path to get URL style.
.sp
\fBRemote repositories\fP accessed via ssh \fI\%user@host\fP:
.sp
\fBuser@host:/path/to/repo\fP \- remote repo, absolute path
.sp
\fBssh://user@host:port/path/to/repo\fP \- same, alternative syntax, port can be given
.sp
\fBRemote repositories with relative paths\fP can be given using this syntax:
.sp
\fBuser@host:path/to/repo\fP \- path relative to current directory
.sp
\fBuser@host:~/path/to/repo\fP \- path relative to user\(aqs home directory
.sp
\fBuser@host:~other/path/to/repo\fP \- path relative to other\(aqs home directory
.sp
Note: giving \fBuser@host:/./path/to/repo\fP or \fBuser@host:/~/path/to/repo\fP or
\fBuser@host:/~other/path/to/repo\fP is also supported, but not required here.
.sp
\fBRemote repositories with relative paths, alternative syntax with port\fP:
.sp
\fBssh://user@host:port/./path/to/repo\fP \- path relative to current directory
.sp
\fBssh://user@host:port/~/path/to/repo\fP \- path relative to user\(aqs home directory
.sp
\fBssh://user@host:port/~other/path/to/repo\fP \- path relative to other\(aqs home directory
.sp
If you frequently need the same repo URL, it is a good idea to set the
\fBBORG_REPO\fP environment variable to set a default for the repo URL:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
export BORG_REPO=\(aqssh://user@host:port/path/to/repo\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
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.
.sp
Use \fB::\fP syntax to give the repo URL when syntax requires giving a positional
argument for the repo (e.g. \fBborg mount :: /mnt\fP).
.SS Repository / Archive Locations
.sp
Many commands want either a repository (just give the repo URL, see above) or
an archive location, which is a repo URL followed by \fB::archive_name\fP\&.
.sp
Archive names must not contain the \fB/\fP (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).
.sp
If you have set BORG_REPO (see above) and an archive location is needed, use
\fB::archive_name\fP \- the repo URL part is then read from BORG_REPO.
.SS Logging
.sp
Borg writes all log output to stderr by default. But please note that something
showing up on stderr does \fInot\fP 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.
.sp
If you want to capture the log output to a file, just redirect it:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
borg create repo::archive myfiles 2>> logfile
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Custom logging configurations can be implemented via BORG_LOGGING_CONF.
.sp
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. \fB\-\-list\fP or \fB\-\-progress\fP).
.sp
Log levels: DEBUG < INFO < WARNING < ERROR < CRITICAL
.sp
Use \fB\-\-debug\fP to set DEBUG log level \-
to get debug, info, warning, error and critical level output.
.sp
Use \fB\-\-info\fP (or \fB\-v\fP or \fB\-\-verbose\fP) to set INFO log level \-
to get info, warning, error and critical level output.
.sp
Use \fB\-\-warning\fP (default) to set WARNING log level \-
to get warning, error and critical level output.
.sp
Use \fB\-\-error\fP to set ERROR log level \-
to get error and critical level output.
.sp
Use \fB\-\-critical\fP to set CRITICAL log level \-
to get critical level output.
.sp
While you can set misc. log levels, do not expect that every command will
give different output on different log levels \- it\(aqs just a possibility.
.sp
\fBWARNING:\fP
.INDENT 0