upstream/borgbackup
1
0
Fork 0
mirror of https://github.com/borgbackup/borg.git synced 2026-06-08 16:23:42 -04:00
Code Issues Projects Releases Packages Wiki Activity Actions 3

commit man pages

Browse source
This commit is contained in:
Marian Beermann 2017-02-05 14:22:06 +01:00
parent d6a26ca26d
commit 1d91d2699c
26 changed files with 3143 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

56
docs/man/borg-break-lock.1 Normal file
View file

@ -0,0 +1,56 @@
.\" Man page generated from reStructuredText.
.
.TH BORG-BREAK-LOCK 1 "2017-02-05" "" "borg backup tool"
.SH NAME
borg-break-lock \- Break the repository lock (e.g. in case it was left by a dead borg.
.
.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
..
.SH SYNOPSIS
.sp
borg break\-lock <options> REPOSITORY
.SH DESCRIPTION
.sp
This command breaks the repository and cache locks.
Please use carefully and only while no borg process (on any machine) is
trying to access the Cache or the Repository.
.SH OPTIONS
.sp
See \fIborg\-common(1)\fP for common options of Borg commands.
.SS arguments
.INDENT 0.0
.TP
.B REPOSITORY
repository for which to break the locks
.UNINDENT
.SH SEE ALSO
.sp
\fIborg\-common(1)\fP
.SH AUTHOR
The Borg Collective
.\" Generated by docutils manpage writer.
.

52
docs/man/borg-change-passphrase.1 Normal file
View file

@ -0,0 +1,52 @@
.\" Man page generated from reStructuredText.
.
.TH BORG-CHANGE-PASSPHRASE 1 "2017-02-05" "" "borg backup tool"
.SH NAME
borg-change-passphrase \- Change repository key file passphrase
.
.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
..
.SH SYNOPSIS
.sp
borg change\-passphrase <options> REPOSITORY
.SH DESCRIPTION
.sp
The key files used for repository encryption are optionally passphrase
protected. This command can be used to change this passphrase.
.SH OPTIONS
.sp
See \fIborg\-common(1)\fP for common options of Borg commands.
.SS arguments
.sp
REPOSITORY
.SH SEE ALSO
.sp
\fIborg\-common(1)\fP
.SH AUTHOR
The Borg Collective
.\" Generated by docutils manpage writer.
.

148
docs/man/borg-check.1 Normal file
View file

@ -0,0 +1,148 @@
.\" Man page generated from reStructuredText.
.
.TH BORG-CHECK 1 "2017-02-05" "" "borg backup tool"
.SH NAME
borg-check \- Check repository consistency
.
.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
..
.SH SYNOPSIS
.sp
borg check <options> REPOSITORY_OR_ARCHIVE
.SH DESCRIPTION
.sp
The check command verifies the consistency of a repository and the corresponding archives.
.sp
First, the underlying repository data files are checked:
.INDENT 0.0
.IP \(bu 2
For all segments the segment magic (header) is checked
.IP \(bu 2
For all objects stored in the segments, all metadata (e.g. crc and size) and
all data is read. The read data is checked by size and CRC. Bit rot and other
types of accidental damage can be detected this way.
.IP \(bu 2
If we are in repair mode and a integrity error is detected for a segment,
we try to recover as many objects from the segment as possible.
.IP \(bu 2
In repair mode, it makes sure that the index is consistent with the data
stored in the segments.
.IP \(bu 2
If you use a remote repo server via ssh:, the repo check is executed on the
repo server without causing significant network traffic.
.IP \(bu 2
The repository check can be skipped using the \-\-archives\-only option.
.UNINDENT
.sp
Second, the consistency and correctness of the archive metadata is verified:
.INDENT 0.0
.IP \(bu 2
Is the repo manifest present? If not, it is rebuilt from archive metadata
chunks (this requires reading and decrypting of all metadata and data).
.IP \(bu 2
Check if archive metadata chunk is present. if not, remove archive from
manifest.
.IP \(bu 2
For all files (items) in the archive, for all chunks referenced by these
files, check if chunk is present.
If a chunk is not present and we are in repair mode, replace it with a same\-size
replacement chunk of zeros.
If a previously lost chunk reappears (e.g. via a later backup) and we are in
repair mode, the all\-zero replacement chunk will be replaced by the correct chunk.
This requires reading of archive and file metadata, but not data.
.IP \(bu 2
If we are in repair mode and we checked all the archives: delete orphaned
chunks from the repo.
.IP \(bu 2
if you use a remote repo server via ssh:, the archive check is executed on
the client machine (because if encryption is enabled, the checks will require
decryption and this is always done client\-side, because key access will be
required).
.IP \(bu 2
The archive checks can be time consuming, they can be skipped using the
\-\-repository\-only option.
.UNINDENT
.sp
The \-\-verify\-data option will perform a full integrity verification (as opposed to
checking the CRC32 of the segment) of data, which means reading the data from the
repository, decrypting and decompressing it. This is a cryptographic verification,
which will detect (accidental) corruption. For encrypted repositories it is
tamper\-resistant as well, unless the attacker has access to the keys.
.sp
It is also very slow.
.SH OPTIONS
.sp
See \fIborg\-common(1)\fP for common options of Borg commands.
.SS arguments
.INDENT 0.0
.TP
.B REPOSITORY_OR_ARCHIVE
repository or archive to check consistency of
.UNINDENT
.SS optional arguments
.INDENT 0.0
.TP
.B \-\-repository\-only
only perform repository checks
.TP
.B \-\-archives\-only
only perform archives checks
.TP
.B \-\-verify\-data
perform cryptographic archive data integrity verification (conflicts with \-\-repository\-only)
.TP
.B \-\-repair
attempt to repair any inconsistencies found
.TP
.B \-\-save\-space
work slower, but using less space
.TP
.B \-p\fP,\fB \-\-progress
show progress display while checking
.UNINDENT
.SS filters
.INDENT 0.0
.TP
.B \-P\fP,\fB \-\-prefix
only consider archive names starting with this prefix
.TP
.B \-\-sort\-by
Comma\-separated list of sorting keys; valid keys are: timestamp, name, id; default is: timestamp
.TP
.BI \-\-first \ N
consider first N archives after other filters were applied
.TP
.BI \-\-last \ N
consider last N archives after other filters were applied
.UNINDENT
.SH SEE ALSO
.sp
\fIborg\-common(1)\fP
.SH AUTHOR
The Borg Collective
.\" Generated by docutils manpage writer.
.

87
docs/man/borg-common.1 Normal file
View file

@ -0,0 +1,87 @@
.\" Man page generated from reStructuredText.
.
.TH BORG-COMMON 1 "2017-02-05" "" "borg backup tool"
.SH NAME
borg-common \- Common options of Borg commands
.
.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
..
.SH SYNOPSIS
.INDENT 0.0
.TP
.B \-h\fP,\fB \-\-help
show this help message and exit
.TP
.B \-\-critical
work on log level CRITICAL
.TP
.B \-\-error
work on log level ERROR
.TP
.B \-\-warning
work on log level WARNING (default)
.TP
.B \-\-info\fP,\fB \-v\fP,\fB \-\-verbose
work on log level INFO
.TP
.B \-\-debug
enable debug output, work on log level DEBUG
.TP
.BI \-\-debug\-topic \ TOPIC
enable TOPIC debugging (can be specified multiple times). The logger path is borg.debug.<TOPIC> if TOPIC is not fully qualified.
.TP
.BI \-\-lock\-wait \ N
wait for the lock, but max. N seconds (default: 1).
.TP
.B \-\-show\-version
show/log the borg version
.TP
.B \-\-show\-rc
show/log the return code (rc)
.TP
.B \-\-no\-files\-cache
do not load/update the file metadata cache used to detect unchanged files
.TP
.BI \-\-umask \ M
set umask to M (local and remote, default: 0077)
.TP
.BI \-\-remote\-path \ PATH
set remote path to executable (default: "borg")
.TP
.BI \-\-remote\-ratelimit \ rate
set remote network upload rate limit in kiByte/s (default: 0=unlimited)
.TP
.B \-\-consider\-part\-files
treat part files like normal files (e.g. to list/extract them)
.UNINDENT
.SH SEE ALSO
.sp
\fIborg\-common(1)\fP
.SH AUTHOR
The Borg Collective
.\" Generated by docutils manpage writer.
.

156
docs/man/borg-compression.1 Normal file
View file

@ -0,0 +1,156 @@
.\" Man page generated from reStructuredText.
.
.TH BORG-COMPRESSION 1 "2017-02-05" "" "borg backup tool"
.SH NAME
borg-compression \- Details regarding compression
.
.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
..
.SH DESCRIPTION
.sp
Compression is off by default, if you want some, you have to specify what you want.
.sp
Valid compression specifiers are:
.sp
none
.INDENT 0.0
.INDENT 3.5
Do not compress. (default)
.UNINDENT
.UNINDENT
.sp
lz4
.INDENT 0.0
.INDENT 3.5
Use lz4 compression. High speed, low compression.
.UNINDENT
.UNINDENT
.sp
zlib[,L]
.INDENT 0.0
.INDENT 3.5
Use zlib ("gz") compression. Medium speed, medium compression.
If you do not explicitely give the compression level L (ranging from 0
to 9), it will use level 6.
Giving level 0 (means "no compression", but still has zlib protocol
overhead) is usually pointless, you better use "none" compression.
.UNINDENT
.UNINDENT
.sp
lzma[,L]
.INDENT 0.0
.INDENT 3.5
Use lzma ("xz") compression. Low speed, high compression.
If you do not explicitely give the compression level L (ranging from 0
to 9), it will use level 6.
Giving levels above 6 is pointless and counterproductive because it does
not compress better due to the buffer size used by borg \- but it wastes
lots of CPU cycles and RAM.
.UNINDENT
.UNINDENT
.sp
auto,C[,L]
.INDENT 0.0
.INDENT 3.5
Use a built\-in heuristic to decide per chunk whether to compress or not.
The heuristic tries with lz4 whether the data is compressible.
For incompressible data, it will not use compression (uses "none").
For compressible data, it uses the given C[,L] compression \- with C[,L]
being any valid compression specifier.
.UNINDENT
.UNINDENT
.sp
The decision about which compression to use is done by borg like this:
.INDENT 0.0
.IP 1. 3
find a compression specifier (per file):
match the path/filename against all patterns in all \-\-compression\-from
files (if any). If a pattern matches, use the compression spec given for
that pattern. If no pattern matches (and also if you do not give any
\-\-compression\-from option), default to the compression spec given by
\-\-compression. See docs/misc/compression.conf for an example config.
.IP 2. 3
if the found compression spec is not "auto", the decision is taken:
use the found compression spec.
.IP 3. 3
if the found compression spec is "auto", test compressibility of each
chunk using lz4.
If it is compressible, use the C,[L] compression spec given within the
"auto" specifier. If it is not compressible, use no compression.
.UNINDENT
.sp
Examples:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
borg create \-\-compression lz4 REPO::ARCHIVE data
borg create \-\-compression zlib REPO::ARCHIVE data
borg create \-\-compression zlib,1 REPO::ARCHIVE data
borg create \-\-compression auto,lzma,6 REPO::ARCHIVE data
borg create \-\-compression\-from compression.conf \-\-compression auto,lzma ...
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
compression.conf has entries like:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# example config file for \-\-compression\-from option
#
# Format of non\-comment / non\-empty lines:
# <compression\-spec>:<path/filename pattern>
# compression\-spec is same format as for \-\-compression option
# path/filename pattern is same format as for \-\-exclude option
none:*.gz
none:*.zip
none:*.mp3
none:*.ogg
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
General remarks:
.sp
It is no problem to mix different compression methods in one repo,
deduplication is done on the source data chunks (not on the compressed
or encrypted data).
.sp
If some specific chunk was once compressed and stored into the repo, creating
another backup that also uses this chunk will not change the stored chunk.
So if you use different compression specs for the backups, whichever stores a
chunk first determines its compression. See also borg recreate.
.SH AUTHOR
The Borg Collective
.\" Generated by docutils manpage writer.
.

233
docs/man/borg-create.1 Normal file
View file

@ -0,0 +1,233 @@
.\" Man page generated from reStructuredText.
.
.TH BORG-CREATE 1 "2017-02-05" "" "borg backup tool"
.SH NAME
borg-create \- Create new archive
.
.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
..
.SH SYNOPSIS
.sp
borg create <options> ARCHIVE PATH
.SH DESCRIPTION
.sp
This command creates a backup archive containing all files found while recursively
traversing all paths specified. When giving \(aq\-\(aq as path, borg will read data
from standard input and create a file \(aqstdin\(aq in the created archive from that
data.
.sp
The archive will consume almost no disk space for files or parts of files that
have already been stored in other archives.
.sp
The archive name needs to be unique. It must not end in \(aq.checkpoint\(aq or
\(aq.checkpoint.N\(aq (with N being a number), because these names are used for
checkpoints and treated in special ways.
.sp
In the archive name, you may use the following placeholders:
{now}, {utcnow}, {fqdn}, {hostname}, {user} and some others.
.sp
To speed up pulling backups over sshfs and similar network file systems which do
not provide correct inode information the \-\-ignore\-inode flag can be used. This
potentially decreases reliability of change detection, while avoiding always reading
all files on these file systems.
.sp
See the output of the "borg help patterns" command for more help on exclude patterns.
See the output of the "borg help placeholders" command for more help on placeholders.
.SH OPTIONS
.sp
See \fIborg\-common(1)\fP for common options of Borg commands.
.SS arguments
.INDENT 0.0
.TP
.B ARCHIVE
name of archive to create (must be also a valid directory name)
.TP
.B PATH
paths to archive
.UNINDENT
.SS optional arguments
.INDENT 0.0
.TP
.B \-n\fP,\fB \-\-dry\-run
do not create a backup archive
.TP
.B \-s\fP,\fB \-\-stats
print statistics for the created archive
.TP
.B \-p\fP,\fB \-\-progress
show progress display while creating the archive, showing Original, Compressed and Deduplicated sizes, followed by the Number of files seen and the path being processed, default: False
.TP
.B \-\-list
output verbose list of items (files, dirs, ...)
.TP
.BI \-\-filter \ STATUSCHARS
only display items with the given status characters
.UNINDENT
.SS Exclusion options
.INDENT 0.0
.TP
.BI \-e \ PATTERN\fP,\fB \ \-\-exclude \ PATTERN
exclude paths matching PATTERN
.TP
.BI \-\-exclude\-from \ EXCLUDEFILE
read exclude patterns from EXCLUDEFILE, one per line
.TP
.B \-\-exclude\-caches
exclude directories that contain a CACHEDIR.TAG file (\fI\%http://www.brynosaurus.com/cachedir/spec.html\fP)
.TP
.BI \-\-exclude\-if\-present \ NAME
exclude directories that are tagged by containing a filesystem object with the given NAME
.TP
.B \-\-keep\-exclude\-tags\fP,\fB \-\-keep\-tag\-files
keep tag objects (i.e.: arguments to \-\-exclude\-if\-present) in otherwise excluded caches/directories
.UNINDENT
.SS Filesystem options
.INDENT 0.0
.TP
.B \-x\fP,\fB \-\-one\-file\-system
stay in same file system, do not cross mount points
.TP
.B \-\-numeric\-owner
only store numeric user and group identifiers
.TP
.B \-\-noatime
do not store atime into archive
.TP
.B \-\-noctime
do not store ctime into archive
.TP
.B \-\-ignore\-inode
ignore inode data in the file metadata cache used to detect unchanged files.
.TP
.B \-\-read\-special
open and read block and char device files as well as FIFOs as if they were regular files. Also follows symlinks pointing to these kinds of files.
.UNINDENT
.SS Archive options
.INDENT 0.0
.TP
.BI \-\-comment \ COMMENT
add a comment text to the archive
.TP
.BI \-\-timestamp \ TIMESTAMP
manually specify the archive creation date/time (UTC, yyyy\-mm\-ddThh:mm:ss format). alternatively, give a reference file/directory.
.TP
.BI \-c \ SECONDS\fP,\fB \ \-\-checkpoint\-interval \ SECONDS
write checkpoint every SECONDS seconds (Default: 1800)
.TP
.BI \-\-chunker\-params \ PARAMS
specify the chunker parameters (CHUNK_MIN_EXP, CHUNK_MAX_EXP, HASH_MASK_BITS, HASH_WINDOW_SIZE). default: 19,23,21,4095
.TP
.BI \-C \ COMPRESSION\fP,\fB \ \-\-compression \ COMPRESSION
select compression algorithm, see the output of the "borg help compression" command for details.
.TP
.BI \-\-compression\-from \ COMPRESSIONCONFIG
read compression patterns from COMPRESSIONCONFIG, see the output of the "borg help compression" command for details.
.UNINDENT
.SH EXAMPLES
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# Backup ~/Documents into an archive named "my\-documents"
$ borg create /path/to/repo::my\-documents ~/Documents
# same, but list all files as we process them
$ borg create \-\-list /path/to/repo::my\-documents ~/Documents
# Backup ~/Documents and ~/src but exclude pyc files
$ borg create /path/to/repo::my\-files \e
~/Documents \e
~/src \e
\-\-exclude \(aq*.pyc\(aq
# Backup home directories excluding image thumbnails (i.e. only
# /home/*/.thumbnails is excluded, not /home/*/*/.thumbnails)
$ borg create /path/to/repo::my\-files /home \e
\-\-exclude \(aqre:^/home/[^/]+/\e.thumbnails/\(aq
# Do the same using a shell\-style pattern
$ borg create /path/to/repo::my\-files /home \e
\-\-exclude \(aqsh:/home/*/.thumbnails\(aq
# Backup the root filesystem into an archive named "root\-YYYY\-MM\-DD"
# use zlib compression (good, but slow) \- default is no compression
$ borg create \-C zlib,6 /path/to/repo::root\-{now:%Y\-%m\-%d} / \-\-one\-file\-system
# Backup a remote host locally ("pull" style) using sshfs
$ mkdir sshfs\-mount
$ sshfs root@example.com:/ sshfs\-mount
$ cd sshfs\-mount
$ borg create /path/to/repo::example.com\-root\-{now:%Y\-%m\-%d} .
$ cd ..
$ fusermount \-u sshfs\-mount
# Make a big effort in fine granular deduplication (big chunk management
# overhead, needs a lot of RAM and disk space, see formula in internals
# docs \- same parameters as borg < 1.0 or attic):
$ borg create \-\-chunker\-params 10,23,16,4095 /path/to/repo::small /smallstuff
# Backup a raw device (must not be active/in use/mounted at that time)
$ dd if=/dev/sdx bs=10M | borg create /path/to/repo::my\-sdx \-
# No compression (default)
$ borg create /path/to/repo::arch ~
# Super fast, low compression
$ borg create \-\-compression lz4 /path/to/repo::arch ~
# Less fast, higher compression (N = 0..9)
$ borg create \-\-compression zlib,N /path/to/repo::arch ~
# Even slower, even higher compression (N = 0..9)
$ borg create \-\-compression lzma,N /path/to/repo::arch ~
# Use short hostname, user name and current time in archive name
$ borg create /path/to/repo::{hostname}\-{user}\-{now} ~
# Similar, use the same datetime format as borg 1.1 will have as default
$ borg create /path/to/repo::{hostname}\-{user}\-{now:%Y\-%m\-%dT%H:%M:%S} ~
# As above, but add nanoseconds
$ borg create /path/to/repo::{hostname}\-{user}\-{now:%Y\-%m\-%dT%H:%M:%S.%f} ~
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Notes
.INDENT 0.0
.IP \(bu 2
the \-\-exclude patterns are not like tar. In tar \-\-exclude .bundler/gems will
exclude foo/.bundler/gems. In borg it will not, you need to use \-\-exclude
\(aq*/.bundler/gems\(aq to get the same effect. See \fBborg help patterns\fP for
more information.
.UNINDENT
.SH SEE ALSO
.sp
\fIborg\-common(1)\fP, \fIborg\-delete(1)\fP, \fIborg\-prune(1)\fP, \fIborg\-check(1)\fP, \fIborg\-patterns(1)\fP, \fIborg\-placeholders(1)\fP, \fIborg\-compression(1)\fP
.SH AUTHOR
The Borg Collective
.\" Generated by docutils manpage writer.
.

109
docs/man/borg-delete.1 Normal file
View file

@ -0,0 +1,109 @@
.\" Man page generated from reStructuredText.
.
.TH BORG-DELETE 1 "2017-02-05" "" "borg backup tool"
.SH NAME
borg-delete \- Delete an existing repository or archives
.
.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
..
.SH SYNOPSIS
.sp
borg delete <options> TARGET
.SH DESCRIPTION
.sp
This command deletes an archive from the repository or the complete repository.
Disk space is reclaimed accordingly. If you delete the complete repository, the
local cache for it (if any) is also deleted.
.SH OPTIONS
.sp
See \fIborg\-common(1)\fP for common options of Borg commands.
.SS arguments
.INDENT 0.0
.TP
.B TARGET
archive or repository to delete
.UNINDENT
.SS optional arguments
.INDENT 0.0
.TP
.B \-p\fP,\fB \-\-progress
show progress display while deleting a single archive
.TP
.B \-s\fP,\fB \-\-stats
print statistics for the deleted archive
.TP
.B \-c\fP,\fB \-\-cache\-only
delete only the local cache for the given repository
.TP
.B \-\-force
force deletion of corrupted archives
.TP
.B \-\-save\-space
work slower, but using less space
.UNINDENT
.SS filters
.INDENT 0.0
.TP
.B \-P\fP,\fB \-\-prefix
only consider archive names starting with this prefix
.TP
.B \-\-sort\-by
Comma\-separated list of sorting keys; valid keys are: timestamp, name, id; default is: timestamp
.TP
.BI \-\-first \ N
consider first N archives after other filters were applied
.TP
.BI \-\-last \ N
consider last N archives after other filters were applied
.UNINDENT
.SH EXAMPLES
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# delete a single backup archive:
$ borg delete /path/to/repo::Monday
# delete the whole repository and the related local cache:
$ borg delete /path/to/repo
You requested to completely DELETE the repository *including* all archives it contains:
repo Mon, 2016\-02\-15 19:26:54
root\-2016\-02\-15 Mon, 2016\-02\-15 19:36:29
newname Mon, 2016\-02\-15 19:50:19
Type \(aqYES\(aq if you understand this and want to continue: YES
.ft P
.fi
.UNINDENT
.UNINDENT
.SH SEE ALSO
.sp
\fIborg\-common(1)\fP
.SH AUTHOR
The Borg Collective
.\" Generated by docutils manpage writer.
.

133
docs/man/borg-diff.1 Normal file
View file

@ -0,0 +1,133 @@
.\" Man page generated from reStructuredText.
.
.TH BORG-DIFF 1 "2017-02-05" "" "borg backup tool"
.SH NAME
borg-diff \- Diff contents of two archives
.
.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
..
.SH SYNOPSIS
.sp
borg diff <options> REPO_ARCHIVE1 ARCHIVE2 PATH
.SH DESCRIPTION
.sp
This command finds differences (file contents, user/group/mode) between archives.
.sp
A repository location and an archive name must be specified for REPO_ARCHIVE1.
ARCHIVE2 is just another archive name in same repository (no repository location
allowed).
.sp
For archives created with Borg 1.1 or newer diff automatically detects whether
the archives are created with the same chunker params. If so, only chunk IDs
are compared, which is very fast.
.sp
For archives prior to Borg 1.1 chunk contents are compared by default.
If you did not create the archives with different chunker params,
pass \-\-same\-chunker\-params.
Note that the chunker params changed from Borg 0.xx to 1.0.
.sp
See the output of the "borg help patterns" command for more help on exclude patterns.
.SH OPTIONS
.sp
See \fIborg\-common(1)\fP for common options of Borg commands.
.SS arguments
.INDENT 0.0
.TP
.B REPO_ARCHIVE1
repository location and ARCHIVE1 name
.TP
.B ARCHIVE2
ARCHIVE2 name (no repository location allowed)
.TP
.B PATH
paths of items inside the archives to compare; patterns are supported
.UNINDENT
.SS optional arguments
.INDENT 0.0
.TP
.BI \-e \ PATTERN\fP,\fB \ \-\-exclude \ PATTERN
exclude paths matching PATTERN
.TP
.BI \-\-exclude\-from \ EXCLUDEFILE
read exclude patterns from EXCLUDEFILE, one per line
.TP
.B \-\-numeric\-owner
only consider numeric user and group identifiers
.TP
.B \-\-same\-chunker\-params
Override check of chunker parameters.
.TP
.B \-\-sort
Sort the output lines by file path.
.UNINDENT
.SH EXAMPLES
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ borg init \-e=none testrepo
$ mkdir testdir
$ cd testdir
$ echo asdf > file1
$ dd if=/dev/urandom bs=1M count=4 > file2
$ touch file3
$ borg create ../testrepo::archive1 .
$ chmod a+x file1
$ echo "something" >> file2
$ borg create ../testrepo::archive2 .
$ rm file3
$ touch file4
$ borg create ../testrepo::archive3 .
$ cd ..
$ borg diff testrepo::archive1 archive2
[\-rw\-r\-\-r\-\- \-> \-rwxr\-xr\-x] file1
+135 B \-252 B file2
$ borg diff testrepo::archive2 archive3
added 0 B file4
removed 0 B file3
$ borg diff testrepo::archive1 archive3
[\-rw\-r\-\-r\-\- \-> \-rwxr\-xr\-x] file1
+135 B \-252 B file2
added 0 B file4
removed 0 B file3
.ft P
.fi
.UNINDENT
.UNINDENT
.SH SEE ALSO
.sp
\fIborg\-common(1)\fP
.SH AUTHOR
The Borg Collective
.\" Generated by docutils manpage writer.
.

131
docs/man/borg-extract.1 Normal file
View file

@ -0,0 +1,131 @@
.\" Man page generated from reStructuredText.
.
.TH BORG-EXTRACT 1 "2017-02-05" "" "borg backup tool"
.SH NAME
borg-extract \- Extract archive contents
.
.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
..
.SH SYNOPSIS
.sp
borg extract <options> ARCHIVE PATH
.SH DESCRIPTION
.sp
This command extracts the contents of an archive. By default the entire
archive is extracted but a subset of files and directories can be selected
by passing a list of \fBPATHs\fP as arguments. The file selection can further
be restricted by using the \fB\-\-exclude\fP option.
.sp
See the output of the "borg help patterns" command for more help on exclude patterns.
.sp
By using \fB\-\-dry\-run\fP, you can do all extraction steps except actually writing the
output data: reading metadata and data chunks from the repo, checking the hash/hmac,
decrypting, decompressing.
.SH OPTIONS
.sp
See \fIborg\-common(1)\fP for common options of Borg commands.
.SS arguments
.INDENT 0.0
.TP
.B ARCHIVE
archive to extract
.TP
.B PATH
paths to extract; patterns are supported
.UNINDENT
.SS optional arguments
.INDENT 0.0
.TP
.B \-p\fP,\fB \-\-progress
show progress while extracting (may be slower)
.TP
.B \-\-list
output verbose list of items (files, dirs, ...)
.TP
.B \-n\fP,\fB \-\-dry\-run
do not actually change any files
.TP
.BI \-e \ PATTERN\fP,\fB \ \-\-exclude \ PATTERN
exclude paths matching PATTERN
.TP
.BI \-\-exclude\-from \ EXCLUDEFILE
read exclude patterns from EXCLUDEFILE, one per line
.TP
.B \-\-numeric\-owner
only obey numeric user and group identifiers
.TP
.BI \-\-strip\-components \ NUMBER
Remove the specified number of leading path elements. Pathnames with fewer elements will be silently skipped.
.TP
.B \-\-stdout
write all extracted data to stdout
.TP
.B \-\-sparse
create holes in output sparse file from all\-zero chunks
.UNINDENT
.SH EXAMPLES
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# Extract entire archive
$ borg extract /path/to/repo::my\-files
# Extract entire archive and list files while processing
$ borg extract \-\-list /path/to/repo::my\-files
# Verify whether an archive could be successfully extracted, but do not write files to disk
$ borg extract \-\-dry\-run /path/to/repo::my\-files
# Extract the "src" directory
$ borg extract /path/to/repo::my\-files home/USERNAME/src
# Extract the "src" directory but exclude object files
$ borg extract /path/to/repo::my\-files home/USERNAME/src \-\-exclude \(aq*.o\(aq
# Restore a raw device (must not be active/in use/mounted at that time)
$ borg extract \-\-stdout /path/to/repo::my\-sdx | dd of=/dev/sdx bs=10M
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
Currently, extract always writes into the current working directory ("."),
so make sure you \fBcd\fP to the right place before calling \fBborg extract\fP\&.
.UNINDENT
.UNINDENT
.SH SEE ALSO
.sp
\fIborg\-common(1)\fP, \fIborg\-mount(1)\fP
.SH AUTHOR
The Borg Collective
.\" Generated by docutils manpage writer.
.

107
docs/man/borg-info.1 Normal file
View file

@ -0,0 +1,107 @@
.\" Man page generated from reStructuredText.
.
.TH BORG-INFO 1 "2017-02-05" "" "borg backup tool"
.SH NAME
borg-info \- Show archive details such as disk space used
.
.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
..
.SH SYNOPSIS
.sp
borg info <options> REPOSITORY_OR_ARCHIVE
.SH DESCRIPTION
.sp
This command displays detailed information about the specified archive or repository.
.sp
Please note that the deduplicated sizes of the individual archives do not add
up to the deduplicated size of the repository ("all archives"), because the two
are meaning different things:
.INDENT 0.0
.TP
.B This archive / deduplicated size = amount of data stored ONLY for this archive
= unique chunks of this archive.
.TP
.B All archives / deduplicated size = amount of data stored in the repo
= all chunks in the repository.
.UNINDENT
.SH OPTIONS
.sp
See \fIborg\-common(1)\fP for common options of Borg commands.
.SS arguments
.INDENT 0.0
.TP
.B REPOSITORY_OR_ARCHIVE
archive or repository to display information about
.UNINDENT
.SS filters
.INDENT 0.0
.TP
.B \-P\fP,\fB \-\-prefix
only consider archive names starting with this prefix
.TP
.B \-\-sort\-by
Comma\-separated list of sorting keys; valid keys are: timestamp, name, id; default is: timestamp
.TP
.BI \-\-first \ N
consider first N archives after other filters were applied
.TP
.BI \-\-last \ N
consider last N archives after other filters were applied
.UNINDENT
.SH EXAMPLES
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ borg info /path/to/repo::root\-2016\-02\-15
Name: root\-2016\-02\-15
Fingerprint: 57c827621f21b000a8d363c1e163cc55983822b3afff3a96df595077a660be50
Hostname: myhostname
Username: root
Time (start): Mon, 2016\-02\-15 19:36:29
Time (end): Mon, 2016\-02\-15 19:39:26
Command line: /usr/local/bin/borg create \-\-list \-C zlib,6 /path/to/repo::root\-2016\-02\-15 / \-\-one\-file\-system
Number of files: 38100
Original size Compressed size Deduplicated size
This archive: 1.33 GB 613.25 MB 571.64 MB
All archives: 1.63 GB 853.66 MB 584.12 MB
Unique chunks Total chunks
Chunk index: 36858 48844
.ft P
.fi
.UNINDENT
.UNINDENT
.SH SEE ALSO
.sp
\fIborg\-common(1)\fP, \fIborg\-list(1)\fP, \fIborg\-diff(1)\fP
.SH AUTHOR
The Borg Collective
.\" Generated by docutils manpage writer.
.

157
docs/man/borg-init.1 Normal file
View file

@ -0,0 +1,157 @@
.\" Man page generated from reStructuredText.
.
.TH BORG-INIT 1 "2017-02-05" "" "borg backup tool"
.SH NAME
borg-init \- Initialize an empty repository
.
.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
..
.SH SYNOPSIS
.sp
borg init <options> REPOSITORY
.SH DESCRIPTION
.sp
This command initializes an empty repository. A repository is a filesystem
directory containing the deduplicated data from zero or more archives.
.sp
Encryption can be enabled at repository init time.
.sp
It is not recommended to work without encryption. Repository encryption protects
you e.g. against the case that an attacker has access to your backup repository.
.sp
But be careful with the key / the passphrase:
.sp
If you want "passphrase\-only" security, use one of the repokey modes. The
key will be stored inside the repository (in its "config" file). In above
mentioned attack scenario, the attacker will have the key (but not the
passphrase).
.sp
If you want "passphrase and having\-the\-key" security, use one of the keyfile
modes. The key will be stored in your home directory (in .config/borg/keys).
In the attack scenario, the attacker who has just access to your repo won\(aqt
have the key (and also not the passphrase).
.sp
Make a backup copy of the key file (keyfile mode) or repo config file
(repokey mode) and keep it at a safe place, so you still have the key in
case it gets corrupted or lost. Also keep the passphrase at a safe place.
The backup that is encrypted with that key won\(aqt help you with that, of course.
.sp
Make sure you use a good passphrase. Not too short, not too simple. The real
encryption / decryption key is encrypted with / locked by your passphrase.
If an attacker gets your key, he can\(aqt unlock and use it without knowing the
passphrase.
.sp
Be careful with special or non\-ascii characters in your passphrase:
.INDENT 0.0
.IP \(bu 2
Borg processes the passphrase as unicode (and encodes it as utf\-8),
so it does not have problems dealing with even the strangest characters.
.IP \(bu 2
BUT: that does not necessarily apply to your OS / VM / keyboard configuration.
.UNINDENT
.sp
So better use a long passphrase made from simple ascii chars than one that
includes non\-ascii stuff or characters that are hard/impossible to enter on
a different keyboard layout.
.sp
You can change your passphrase for existing repos at any time, it won\(aqt affect
the encryption/decryption key or other secrets.
.SS Encryption modes
.sp
repokey and keyfile use AES\-CTR\-256 for encryption and HMAC\-SHA256 for
authentication in an encrypt\-then\-MAC (EtM) construction. The chunk ID hash
is HMAC\-SHA256 as well (with a separate key).
These modes are compatible with borg 1.0.x.
.sp
repokey\-blake2 and keyfile\-blake2 are also authenticated encryption modes,
but use BLAKE2b\-256 instead of HMAC\-SHA256 for authentication. The chunk ID
hash is a keyed BLAKE2b\-256 hash.
These modes are new and not compatible with borg 1.0.x.
.sp
"authenticated" mode uses no encryption, but authenticates repository contents
through the same keyed BLAKE2b\-256 hash as the other blake2 modes (it uses it
as chunk ID hash). The key is stored like repokey.
This mode is new and not compatible with borg 1.0.x.
.sp
"none" mode uses no encryption and no authentication. It uses sha256 as chunk
ID hash. Not recommended, rather consider using an authenticated or
authenticated/encrypted mode.
This mode is compatible with borg 1.0.x.
.sp
Hardware acceleration will be used automatically.
.sp
On modern Intel/AMD CPUs (except very cheap ones), AES is usually hw
accelerated. BLAKE2b is faster than sha256 on Intel/AMD 64bit CPUs.
.sp
On modern ARM CPUs, NEON provides hw acceleration for sha256 making it faster
than BLAKE2b\-256 there.
.SH OPTIONS
.sp
See \fIborg\-common(1)\fP for common options of Borg commands.
.SS arguments
.INDENT 0.0
.TP
.B REPOSITORY
repository to create
.UNINDENT
.SS optional arguments
.INDENT 0.0
.TP
.B \-e\fP,\fB \-\-encryption
select encryption key mode (default: "None")
.TP
.B \-a\fP,\fB \-\-append\-only
create an append\-only mode repository
.UNINDENT
.SH EXAMPLES
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# Local repository, repokey encryption, BLAKE2b (often faster, since Borg 1.1)
$ borg init \-\-encryption=repokey\-blake2 /path/to/repo
# Local repository (no encryption)
$ borg init \-\-encryption=none /path/to/repo
# Remote repository (accesses a remote borg via ssh)
$ borg init \-\-encryption=repokey\-blake2 user@hostname:backup
# Remote repository (store the key your home dir)
$ borg init \-\-encryption=keyfile user@hostname:backup
.ft P
.fi
.UNINDENT
.UNINDENT
.SH SEE ALSO
.sp
\fIborg\-common(1)\fP, \fIborg\-create(1)\fP, \fIborg\-delete(1)\fP, \fIborg\-check(1)\fP, \fIborg\-list(1)\fP, \fIborg\-key\-import(1)\fP, \fIborg\-key\-export(1)\fP, \fIborg\-key\-change\-passphrase(1)\fP
.SH AUTHOR
The Borg Collective
.\" Generated by docutils manpage writer.
.

52
docs/man/borg-key-change-passphrase.1 Normal file
View file

@ -0,0 +1,52 @@
.\" Man page generated from reStructuredText.
.
.TH BORG-KEY-CHANGE-PASSPHRASE 1 "2017-02-05" "" "borg backup tool"
.SH NAME
borg-key-change-passphrase \- Change repository key file passphrase
.
.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
..
.SH SYNOPSIS
.sp
borg key change\-passphrase <options> REPOSITORY
.SH DESCRIPTION
.sp
The key files used for repository encryption are optionally passphrase
protected. This command can be used to change this passphrase.
.SH OPTIONS
.sp
See \fIborg\-common(1)\fP for common options of Borg commands.
.SS arguments
.sp
REPOSITORY
.SH SEE ALSO
.sp
\fIborg\-common(1)\fP
.SH AUTHOR
The Borg Collective
.\" Generated by docutils manpage writer.
.

78
docs/man/borg-key-export.1 Normal file
View file

@ -0,0 +1,78 @@
.\" Man page generated from reStructuredText.
.
.TH BORG-KEY-EXPORT 1 "2017-02-05" "" "borg backup tool"
.SH NAME
borg-key-export \- Export the repository key for backup
.
.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
..
.SH SYNOPSIS
.sp
borg key export <options> REPOSITORY PATH
.SH DESCRIPTION
.sp
If repository encryption is used, the repository is inaccessible
without the key. This command allows to backup this essential key.
.sp
There are two backup formats. The normal backup format is suitable for
digital storage as a file. The \fB\-\-paper\fP backup format is optimized
for printing and typing in while importing, with per line checks to
reduce problems with manual input.
.sp
For repositories using keyfile encryption the key is saved locally
on the system that is capable of doing backups. To guard against loss
of this key, the key needs to be backed up independently of the main
data backup.
.sp
For repositories using the repokey encryption the key is saved in the
repository in the config file. A backup is thus not strictly needed,
but guards against the repository becoming inaccessible if the file
is damaged for some reason.
.SH OPTIONS
.sp
See \fIborg\-common(1)\fP for common options of Borg commands.
.SS arguments
.sp
REPOSITORY
.INDENT 0.0
.TP
.B PATH
where to store the backup
.UNINDENT
.SS optional arguments
.INDENT 0.0
.TP
.B \-\-paper
Create an export suitable for printing and later type\-in
.UNINDENT
.SH SEE ALSO
.sp
\fIborg\-common(1)\fP, \fIborg\-key\-import(1)\fP
.SH AUTHOR
The Borg Collective
.\" Generated by docutils manpage writer.
.

67
docs/man/borg-key-import.1 Normal file
View file

@ -0,0 +1,67 @@
.\" Man page generated from reStructuredText.
.
.TH BORG-KEY-IMPORT 1 "2017-02-05" "" "borg backup tool"
.SH NAME
borg-key-import \- Import the repository key from backup
.
.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
..
.SH SYNOPSIS
.sp
borg key import <options> REPOSITORY PATH
.SH DESCRIPTION
.sp
This command allows to restore a key previously backed up with the
export command.
.sp
If the \fB\-\-paper\fP option is given, the import will be an interactive
process in which each line is checked for plausibility before
proceeding to the next line. For this format PATH must not be given.
.SH OPTIONS
.sp
See \fIborg\-common(1)\fP for common options of Borg commands.
.SS arguments
.sp
REPOSITORY
.INDENT 0.0
.TP
.B PATH
path to the backup
.UNINDENT
.SS optional arguments
.INDENT 0.0
.TP
.B \-\-paper
interactively import from a backup done with \-\-paper
.UNINDENT
.SH SEE ALSO
.sp
\fIborg\-common(1)\fP, \fIborg\-key\-export(1)\fP
.SH AUTHOR
The Borg Collective
.\" Generated by docutils manpage writer.
.

66
docs/man/borg-key-migrate-to-repokey.1 Normal file
View file

@ -0,0 +1,66 @@
.\" Man page generated from reStructuredText.
.
.TH BORG-KEY-MIGRATE-TO-REPOKEY 1 "2017-02-05" "" "borg backup tool"
.SH NAME
borg-key-migrate-to-repokey \- Migrate passphrase -> repokey
.
.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
..
.SH SYNOPSIS
.sp
borg key migrate\-to\-repokey <options> REPOSITORY
.SH DESCRIPTION
.sp
This command migrates a repository from passphrase mode (removed in Borg 1.0)
to repokey mode.
.sp
You will be first asked for the repository passphrase (to open it in passphrase
mode). This is the same passphrase as you used to use for this repo before 1.0.
.sp
It will then derive the different secrets from this passphrase.
.sp
Then you will be asked for a new passphrase (twice, for safety). This
passphrase will be used to protect the repokey (which contains these same
secrets in encrypted form). You may use the same passphrase as you used to
use, but you may also use a different one.
.sp
After migrating to repokey mode, you can change the passphrase at any time.
But please note: the secrets will always stay the same and they could always
be derived from your (old) passphrase\-mode passphrase.
.SH OPTIONS
.sp
See \fIborg\-common(1)\fP for common options of Borg commands.
.SS arguments
.sp
REPOSITORY
.SH SEE ALSO
.sp
\fIborg\-common(1)\fP
.SH AUTHOR
The Borg Collective
.\" Generated by docutils manpage writer.
.

245
docs/man/borg-list.1 Normal file
View file

@ -0,0 +1,245 @@
.\" Man page generated from reStructuredText.
.
.TH BORG-LIST 1 "2017-02-05" "" "borg backup tool"
.SH NAME
borg-list \- List archive or repository contents
.
.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
..
.SH SYNOPSIS
.sp
borg list <options> REPOSITORY_OR_ARCHIVE PATH
.SH DESCRIPTION
.sp
This command lists the contents of a repository or an archive.
.sp
See the "borg help patterns" command for more help on exclude patterns.
.sp
The following keys are available for \-\-format:
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.IP \(bu 2
NEWLINE: OS dependent line separator
.IP \(bu 2
NL: alias of NEWLINE
.IP \(bu 2
NUL: NUL character for creating print0 / xargs \-0 like output, see barchive/bpath
.IP \(bu 2
SPACE
.IP \(bu 2
TAB
.IP \(bu 2
CR
.IP \(bu 2
LF
.UNINDENT
.UNINDENT
.UNINDENT
.sp
Keys for listing repository archives:
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.IP \(bu 2
archive: archive name interpreted as text (might be missing non\-text characters, see barchive)
.IP \(bu 2
barchive: verbatim archive name, can contain any character except NUL
.IP \(bu 2
time: time of creation of the archive
.IP \(bu 2
id: internal ID of the archive
.UNINDENT
.UNINDENT
.UNINDENT
.sp
Keys for listing archive files:
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.IP \(bu 2
type
.IP \(bu 2
mode
.IP \(bu 2
uid
.IP \(bu 2
gid
.IP \(bu 2
user
.IP \(bu 2
group
.IP \(bu 2
path: path interpreted as text (might be missing non\-text characters, see bpath)
.IP \(bu 2
bpath: verbatim POSIX path, can contain any character except NUL
.IP \(bu 2
source: link target for links (identical to linktarget)
.IP \(bu 2
linktarget
.IP \(bu 2
flags
.IP \(bu 2
size
.IP \(bu 2
csize: compressed size
.IP \(bu 2
num_chunks: number of chunks in this file
.IP \(bu 2
unique_chunks: number of unique chunks in this file
.IP \(bu 2
mtime
.IP \(bu 2
ctime
.IP \(bu 2
atime
.IP \(bu 2
isomtime
.IP \(bu 2
isoctime
.IP \(bu 2
isoatime
.IP \(bu 2
blake2b
.IP \(bu 2
blake2s
.IP \(bu 2
md5
.IP \(bu 2
sha1
.IP \(bu 2
sha224
.IP \(bu 2
sha256
.IP \(bu 2
sha384
.IP \(bu 2
sha3_224
.IP \(bu 2
sha3_256
.IP \(bu 2
sha3_384
.IP \(bu 2
sha3_512
.IP \(bu 2
sha512
.IP \(bu 2
shake_128
.IP \(bu 2
shake_256
.IP \(bu 2
archiveid
.IP \(bu 2
archivename
.IP \(bu 2
extra: prepends {source} with " \-> " for soft links and " link to " for hard links
.IP \(bu 2
health: either "healthy" (file ok) or "broken" (if file has all\-zero replacement chunks)
.UNINDENT
.UNINDENT
.UNINDENT
.SH OPTIONS
.sp
See \fIborg\-common(1)\fP for common options of Borg commands.
.SS arguments
.INDENT 0.0
.TP
.B REPOSITORY_OR_ARCHIVE
repository/archive to list contents of
.TP
.B PATH
paths to list; patterns are supported
.UNINDENT
.SS optional arguments
.INDENT 0.0
.TP
.B \-\-short
only print file/directory names, nothing else
.TP
.B \-\-format\fP,\fB \-\-list\-format
specify format for file listing
(default: "{mode} {user:6} {group:6} {size:8d} {isomtime} {path}{extra}{NL}")
.TP
.BI \-e \ PATTERN\fP,\fB \ \-\-exclude \ PATTERN
exclude paths matching PATTERN
.TP
.BI \-\-exclude\-from \ EXCLUDEFILE
read exclude patterns from EXCLUDEFILE, one per line
.UNINDENT
.SS filters
.INDENT 0.0
.TP
.B \-P\fP,\fB \-\-prefix
only consider archive names starting with this prefix
.TP
.B \-\-sort\-by
Comma\-separated list of sorting keys; valid keys are: timestamp, name, id; default is: timestamp
.TP
.BI \-\-first \ N
consider first N archives after other filters were applied
.TP
.BI \-\-last \ N
consider last N archives after other filters were applied
.UNINDENT
.SH EXAMPLES
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ borg list /path/to/repo
Monday Mon, 2016\-02\-15 19:15:11
repo Mon, 2016\-02\-15 19:26:54
root\-2016\-02\-15 Mon, 2016\-02\-15 19:36:29
newname Mon, 2016\-02\-15 19:50:19
\&...
$ borg list /path/to/repo::root\-2016\-02\-15
drwxr\-xr\-x root root 0 Mon, 2016\-02\-15 17:44:27 .
drwxrwxr\-x root root 0 Mon, 2016\-02\-15 19:04:49 bin
\-rwxr\-xr\-x root root 1029624 Thu, 2014\-11\-13 00:08:51 bin/bash
lrwxrwxrwx root root 0 Fri, 2015\-03\-27 20:24:26 bin/bzcmp \-> bzdiff
\-rwxr\-xr\-x root root 2140 Fri, 2015\-03\-27 20:24:22 bin/bzdiff
\&...
$ borg list /path/to/repo::archiveA \-\-list\-format="{mode} {user:6} {group:6} {size:8d} {isomtime} {path}{extra}{NEWLINE}"
drwxrwxr\-x user user 0 Sun, 2015\-02\-01 11:00:00 .
drwxrwxr\-x user user 0 Sun, 2015\-02\-01 11:00:00 code
drwxrwxr\-x user user 0 Sun, 2015\-02\-01 11:00:00 code/myproject
\-rw\-rw\-r\-\- user user 1416192 Sun, 2015\-02\-01 11:00:00 code/myproject/file.ext
\&...
.ft P
.fi
.UNINDENT
.UNINDENT
.SH SEE ALSO
.sp
\fIborg\-common(1)\fP, \fIborg\-info(1)\fP, \fIborg\-diff(1)\fP, \fIborg\-prune(1)\fP, \fIborg\-patterns(1)\fP
.SH AUTHOR
The Borg Collective
.\" Generated by docutils manpage writer.
.

115
docs/man/borg-mount.1 Normal file
View file

@ -0,0 +1,115 @@
.\" Man page generated from reStructuredText.
.
.TH BORG-MOUNT 1 "2017-02-05" "" "borg backup tool"
.SH NAME
borg-mount \- Mount archive or an entire repository as a FUSE filesystem
.
.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
..
.SH SYNOPSIS
.sp
borg mount <options> REPOSITORY_OR_ARCHIVE MOUNTPOINT
.SH DESCRIPTION
.sp
This command mounts an archive as a FUSE filesystem. This can be useful for
browsing an archive or restoring individual files. Unless the \fB\-\-foreground\fP
option is given the command will run in the background until the filesystem
is \fBumounted\fP\&.
.sp
The command \fBborgfs\fP provides a wrapper for \fBborg mount\fP\&. This can also be
used in fstab entries:
\fB/path/to/repo /mnt/point fuse.borgfs defaults,noauto 0 0\fP
.sp
To allow a regular user to use fstab entries, add the \fBuser\fP option:
\fB/path/to/repo /mnt/point fuse.borgfs defaults,noauto,user 0 0\fP
.sp
For mount options, see the fuse(8) manual page. Additional mount options
supported by borg:
.INDENT 0.0
.IP \(bu 2
versions: when used with a repository mount, this gives a merged, versioned
view of the files in the archives. EXPERIMENTAL, layout may change in future.
.IP \(bu 2
allow_damaged_files: by default damaged files (where missing chunks were
replaced with runs of zeros by borg check \-\-repair) are not readable and
return EIO (I/O error). Set this option to read such files.
.UNINDENT
.sp
The BORG_MOUNT_DATA_CACHE_ENTRIES environment variable is meant for advanced users
to tweak the performance. It sets the number of cached data chunks; additional
memory usage can be up to ~8 MiB times this number. The default is the number
of CPU cores.
.sp
When the daemonized process receives a signal or crashes, it does not unmount.
Unmounting in these cases could cause an active rsync or similar process
to unintentionally delete data.
.sp
When running in the foreground ^C/SIGINT unmounts cleanly, but other
signals or crashes do not.
.SH OPTIONS
.sp
See \fIborg\-common(1)\fP for common options of Borg commands.
.SS arguments
.INDENT 0.0
.TP
.B REPOSITORY_OR_ARCHIVE
repository/archive to mount
.TP
.B MOUNTPOINT
where to mount filesystem
.UNINDENT
.SS optional arguments
.INDENT 0.0
.TP
.B \-f\fP,\fB \-\-foreground
stay in foreground, do not daemonize
.TP
.B \-o
Extra mount options
.UNINDENT
.SS filters
.INDENT 0.0
.TP
.B \-P\fP,\fB \-\-prefix
only consider archive names starting with this prefix
.TP
.B \-\-sort\-by
Comma\-separated list of sorting keys; valid keys are: timestamp, name, id; default is: timestamp
.TP
.BI \-\-first \ N
consider first N archives after other filters were applied
.TP
.BI \-\-last \ N
consider last N archives after other filters were applied
.UNINDENT
.SH SEE ALSO
.sp
\fIborg\-common(1)\fP, \fIborg\-umount(1)\fP, \fIborg\-extract(1)\fP
.SH AUTHOR
The Borg Collective
.\" Generated by docutils manpage writer.
.

144
docs/man/borg-patterns.1 Normal file
View file

@ -0,0 +1,144 @@
.\" Man page generated from reStructuredText.
.
.TH BORG-PATTERNS 1 "2017-02-05" "" "borg backup tool"
.SH NAME
borg-patterns \- Details regarding patterns
.
.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
..
.SH DESCRIPTION
.sp
Exclusion patterns support four separate styles, fnmatch, shell, regular
expressions and path prefixes. By default, fnmatch is used. If followed
by a colon (\(aq:\(aq) the first two characters of a pattern are used as a
style selector. Explicit style selection is necessary when a
non\-default style is desired or when the desired pattern starts with
two alphanumeric characters followed by a colon (i.e. \fIaa:something/*\fP).
.sp
\fI\%Fnmatch\fP, selector \fIfm:\fP
.INDENT 0.0
.INDENT 3.5
This is the default style. These patterns use a variant of shell
pattern syntax, with \(aq*\(aq matching any number of characters, \(aq?\(aq
matching any single character, \(aq[...]\(aq matching any single
character specified, including ranges, and \(aq[!...]\(aq matching any
character not specified. For the purpose of these patterns, the
path separator (\(aq\(aq for Windows and \(aq/\(aq on other systems) is not
treated specially. Wrap meta\-characters in brackets for a literal
match (i.e. \fI[?]\fP to match the literal character \fI?\fP). For a path
to match a pattern, it must completely match from start to end, or
must match from the start to just before a path separator. Except
for the root path, paths will never end in the path separator when
matching is attempted. Thus, if a given pattern ends in a path
separator, a \(aq*\(aq is appended before matching is attempted.
.UNINDENT
.UNINDENT
.sp
Shell\-style patterns, selector \fIsh:\fP
.INDENT 0.0
.INDENT 3.5
Like fnmatch patterns these are similar to shell patterns. The difference
is that the pattern may include \fI**/\fP for matching zero or more directory
levels, \fI*\fP for matching zero or more arbitrary characters with the
exception of any path separator.
.UNINDENT
.UNINDENT
.sp
Regular expressions, selector \fIre:\fP
.INDENT 0.0
.INDENT 3.5
Regular expressions similar to those found in Perl are supported. Unlike
shell patterns regular expressions are not required to match the complete
path and any substring match is sufficient. It is strongly recommended to
anchor patterns to the start (\(aq^\(aq), to the end (\(aq$\(aq) or both. Path
separators (\(aq\(aq for Windows and \(aq/\(aq on other systems) in paths are
always normalized to a forward slash (\(aq/\(aq) before applying a pattern. The
regular expression syntax is described in the \fI\%Python documentation for
the re module\fP\&.
.UNINDENT
.UNINDENT
.sp
Prefix path, selector \fIpp:\fP
.INDENT 0.0
.INDENT 3.5
This pattern style is useful to match whole sub\-directories. The pattern
\fIpp:/data/bar\fP matches \fI/data/bar\fP and everything therein.
.UNINDENT
.UNINDENT
.sp
Exclusions can be passed via the command line option \fI\-\-exclude\fP\&. When used
from within a shell the patterns should be quoted to protect them from
expansion.
.sp
The \fI\-\-exclude\-from\fP option permits loading exclusion patterns from a text
file with one pattern per line. Lines empty or starting with the number sign
(\(aq#\(aq) after removing whitespace on both ends are ignored. The optional style
selector prefix is also supported for patterns loaded from a file. Due to
whitespace removal paths with whitespace at the beginning or end can only be
excluded using regular expressions.
.sp
Examples:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# Exclude \(aq/home/user/file.o\(aq but not \(aq/home/user/file.odt\(aq:
$ borg create \-e \(aq*.o\(aq backup /
# Exclude \(aq/home/user/junk\(aq and \(aq/home/user/subdir/junk\(aq but
# not \(aq/home/user/importantjunk\(aq or \(aq/etc/junk\(aq:
$ borg create \-e \(aq/home/*/junk\(aq backup /
# Exclude the contents of \(aq/home/user/cache\(aq but not the directory itself:
$ borg create \-e /home/user/cache/ backup /
# The file \(aq/home/user/cache/important\(aq is *not* backed up:
$ borg create \-e /home/user/cache/ backup / /home/user/cache/important
# The contents of directories in \(aq/home\(aq are not backed up when their name
# ends in \(aq.tmp\(aq
$ borg create \-\-exclude \(aqre:^/home/[^/]+\e.tmp/\(aq backup /
# Load exclusions from file
$ cat >exclude.txt <<EOF
# Comment line
/home/*/junk
*.tmp
fm:aa:something/*
re:^/home/[^/]\e.tmp/
sh:/home/*/.thumbnails
EOF
$ borg create \-\-exclude\-from exclude.txt backup /
.ft P
.fi
.UNINDENT
.UNINDENT
.SH AUTHOR
The Borg Collective
.\" Generated by docutils manpage writer.
.

126
docs/man/borg-placeholders.1 Normal file
View file

@ -0,0 +1,126 @@
.\" Man page generated from reStructuredText.
.
.TH BORG-PLACEHOLDERS 1 "2017-02-05" "" "borg backup tool"
.SH NAME
borg-placeholders \- Details regarding placeholders
.
.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
..
.SH DESCRIPTION
.sp
Repository (or Archive) URLs, \-\-prefix and \-\-remote\-path values support these
placeholders:
.sp
{hostname}
.INDENT 0.0
.INDENT 3.5
The (short) hostname of the machine.
.UNINDENT
.UNINDENT
.sp
{fqdn}
.INDENT 0.0
.INDENT 3.5
The full name of the machine.
.UNINDENT
.UNINDENT
.sp
{now}
.INDENT 0.0
.INDENT 3.5
The current local date and time, by default in ISO\-8601 format.
You can also supply your own \fI\%format string\fP, e.g. {now:%Y\-%m\-%d_%H:%M:%S}
.UNINDENT
.UNINDENT
.sp
{utcnow}
.INDENT 0.0
.INDENT 3.5
The current UTC date and time, by default in ISO\-8601 format.
You can also supply your own \fI\%format string\fP, e.g. {utcnow:%Y\-%m\-%d_%H:%M:%S}
.UNINDENT
.UNINDENT
.sp
{user}
.INDENT 0.0
.INDENT 3.5
The user name (or UID, if no name is available) of the user running borg.
.UNINDENT
.UNINDENT
.sp
{pid}
.INDENT 0.0
.INDENT 3.5
The current process ID.
.UNINDENT
.UNINDENT
.sp
{borgversion}
.INDENT 0.0
.INDENT 3.5
The version of borg, e.g.: 1.0.8rc1
.UNINDENT
.UNINDENT
.sp
{borgmajor}
.INDENT 0.0
.INDENT 3.5
The version of borg, only the major version, e.g.: 1
.UNINDENT
.UNINDENT
.sp
{borgminor}
.INDENT 0.0
.INDENT 3.5
The version of borg, only major and minor version, e.g.: 1.0
.UNINDENT
.UNINDENT
.sp
{borgpatch}
.INDENT 0.0
.INDENT 3.5
The version of borg, only major, minor and patch version, e.g.: 1.0.8
.UNINDENT
.UNINDENT
.sp
Examples:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
borg create /path/to/repo::{hostname}\-{user}\-{utcnow} ...
borg create /path/to/repo::{hostname}\-{now:%Y\-%m\-%d_%H:%M:%S} ...
borg prune \-\-prefix \(aq{hostname}\-\(aq ...
.ft P
.fi
.UNINDENT
.UNINDENT
.SH AUTHOR
The Borg Collective
.\" Generated by docutils manpage writer.
.

177
docs/man/borg-prune.1 Normal file
View file

@ -0,0 +1,177 @@
.\" Man page generated from reStructuredText.
.
.TH BORG-PRUNE 1 "2017-02-05" "" "borg backup tool"
.SH NAME
borg-prune \- Prune repository archives according to specified rules
.
.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
..
.SH SYNOPSIS
.sp
borg prune <options> REPOSITORY
.SH DESCRIPTION
.sp
The prune command prunes a repository by deleting all archives not matching
any of the specified retention options. This command is normally used by
automated backup scripts wanting to keep a certain number of historic backups.
.sp
Also, prune automatically removes checkpoint archives (incomplete archives left
behind by interrupted backup runs) except if the checkpoint is the latest
archive (and thus still needed). Checkpoint archives are not considered when
comparing archive counts against the retention limits (\-\-keep\-X).
.sp
If a prefix is set with \-P, then only archives that start with the prefix are
considered for deletion and only those archives count towards the totals
specified by the rules.
Otherwise, \fIall\fP archives in the repository are candidates for deletion!
There is no automatic distinction between archives representing different
contents. These need to be distinguished by specifying matching prefixes.
.sp
If you have multiple sequences of archives with different data sets (e.g.
from different machines) in one shared repository, use one prune call per
data set that matches only the respective archives using the \-P option.
.sp
The "\-\-keep\-within" option takes an argument of the form "<int><char>",
where char is "H", "d", "w", "m", "y". For example, "\-\-keep\-within 2d" means
to keep all archives that were created within the past 48 hours.
"1m" is taken to mean "31d". The archives kept with this option do not
count towards the totals specified by any other options.
.sp
A good procedure is to thin out more and more the older your backups get.
As an example, "\-\-keep\-daily 7" means to keep the latest backup on each day,
up to 7 most recent days with backups (days without backups do not count).
The rules are applied from secondly to yearly, and backups selected by previous
rules do not count towards those of later rules. The time that each backup
starts is used for pruning purposes. Dates and times are interpreted in
the local timezone, and weeks go from Monday to Sunday. Specifying a
negative number of archives to keep means that there is no limit.
.sp
The "\-\-keep\-last N" option is doing the same as "\-\-keep\-secondly N" (and it will
keep the last N archives under the assumption that you do not create more than one
backup archive in the same second).
.SH OPTIONS
.sp
See \fIborg\-common(1)\fP for common options of Borg commands.
.SS arguments
.INDENT 0.0
.TP
.B REPOSITORY
repository to prune
.UNINDENT
.SS optional arguments
.INDENT 0.0
.TP
.B \-n\fP,\fB \-\-dry\-run
do not change repository
.TP
.B \-\-force
force pruning of corrupted archives
.TP
.B \-p\fP,\fB \-\-progress
show progress display while deleting archives
.TP
.B \-s\fP,\fB \-\-stats
print statistics for the deleted archive
.TP
.B \-\-list
output verbose list of archives it keeps/prunes
.TP
.BI \-\-keep\-within \ WITHIN
keep all archives within this time interval
.TP
.B \-\-keep\-last\fP,\fB \-\-keep\-secondly
number of secondly archives to keep
.TP
.B \-\-keep\-minutely
number of minutely archives to keep
.TP
.B \-H\fP,\fB \-\-keep\-hourly
number of hourly archives to keep
.TP
.B \-d\fP,\fB \-\-keep\-daily
number of daily archives to keep
.TP
.B \-w\fP,\fB \-\-keep\-weekly
number of weekly archives to keep
.TP
.B \-m\fP,\fB \-\-keep\-monthly
number of monthly archives to keep
.TP
.B \-y\fP,\fB \-\-keep\-yearly
number of yearly archives to keep
.TP
.B \-P\fP,\fB \-\-prefix
only consider archive names starting with this prefix
.TP
.B \-\-save\-space
work slower, but using less space
.UNINDENT
.SH EXAMPLES
.sp
Be careful, prune is a potentially dangerous command, it will remove backup
archives.
.sp
The default of prune is to apply to \fBall archives in the repository\fP unless
you restrict its operation to a subset of the archives using \fB\-\-prefix\fP\&.
When using \fB\-\-prefix\fP, be careful to choose a good prefix \- e.g. do not use a
prefix "foo" if you do not also want to match "foobar".
.sp
It is strongly recommended to always run \fBprune \-v \-\-list \-\-dry\-run ...\fP
first so you will see what it would do without it actually doing anything.
.sp
There is also a visualized prune example in \fBdocs/misc/prune\-example.txt\fP\&.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# Keep 7 end of day and 4 additional end of week archives.
# Do a dry\-run without actually deleting anything.
$ borg prune \-v \-\-list \-\-dry\-run \-\-keep\-daily=7 \-\-keep\-weekly=4 /path/to/repo
# Same as above but only apply to archive names starting with the hostname
# of the machine followed by a "\-" character:
$ borg prune \-v \-\-list \-\-keep\-daily=7 \-\-keep\-weekly=4 \-\-prefix=\(aq{hostname}\-\(aq /path/to/repo
# Keep 7 end of day, 4 additional end of week archives,
# and an end of month archive for every month:
$ borg prune \-v \-\-list \-\-keep\-daily=7 \-\-keep\-weekly=4 \-\-keep\-monthly=\-1 /path/to/repo
# Keep all backups in the last 10 days, 4 additional end of week archives,
# and an end of month archive for every month:
$ borg prune \-v \-\-list \-\-keep\-within=10d \-\-keep\-weekly=4 \-\-keep\-monthly=\-1 /path/to/repo
.ft P
.fi
.UNINDENT
.UNINDENT
.SH SEE ALSO
.sp
\fIborg\-common(1)\fP
.SH AUTHOR
The Borg Collective
.\" Generated by docutils manpage writer.
.

192
docs/man/borg-recreate.1 Normal file
View file

@ -0,0 +1,192 @@
.\" Man page generated from reStructuredText.
.
.TH BORG-RECREATE 1 "2017-02-05" "" "borg backup tool"
.SH NAME
borg-recreate \- Re-create archives
.
.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
..
.SH SYNOPSIS
.sp
borg recreate <options> REPOSITORY_OR_ARCHIVE PATH
.SH DESCRIPTION
.sp
Recreate the contents of existing archives.
.sp
This is an \fIexperimental\fP feature. Do \fInot\fP use this on your only backup.
.sp
\-\-exclude, \-\-exclude\-from and PATH have the exact same semantics
as in "borg create". If PATHs are specified the resulting archive
will only contain files from these PATHs.
.sp
Note that all paths in an archive are relative, therefore absolute patterns/paths
will \fInot\fP match (\-\-exclude, \-\-exclude\-from, \-\-compression\-from, PATHs).
.sp
\-\-compression: all chunks seen will be stored using the given method.
Due to how Borg stores compressed size information this might display
incorrect information for archives that were not recreated at the same time.
There is no risk of data loss by this.
.sp
\-\-chunker\-params will re\-chunk all files in the archive, this can be
used to have upgraded Borg 0.xx or Attic archives deduplicate with
Borg 1.x archives.
.sp
USE WITH CAUTION.
Depending on the PATHs and patterns given, recreate can be used to permanently
delete files from archives.
When in doubt, use "\-\-dry\-run \-\-verbose \-\-list" to see how patterns/PATHS are
interpreted.
.sp
The archive being recreated is only removed after the operation completes. The
archive that is built during the operation exists at the same time at
"<ARCHIVE>.recreate". The new archive will have a different archive ID.
.sp
With \-\-target the original archive is not replaced, instead a new archive is created.
.sp
When rechunking space usage can be substantial, expect at least the entire
deduplicated size of the archives using the previous chunker params.
When recompressing expect approx. (throughput / checkpoint\-interval) in space usage,
assuming all chunks are recompressed.
.SH OPTIONS
.sp
See \fIborg\-common(1)\fP for common options of Borg commands.
.SS arguments
.INDENT 0.0
.TP
.B REPOSITORY_OR_ARCHIVE
repository/archive to recreate
.TP
.B PATH
paths to recreate; patterns are supported
.UNINDENT
.SS optional arguments
.INDENT 0.0
.TP
.B \-\-list
output verbose list of items (files, dirs, ...)
.TP
.BI \-\-filter \ STATUSCHARS
only display items with the given status characters
.TP
.B \-p\fP,\fB \-\-progress
show progress display while recreating archives
.TP
.B \-n\fP,\fB \-\-dry\-run
do not change anything
.TP
.B \-s\fP,\fB \-\-stats
print statistics at end
.UNINDENT
.SS Exclusion options
.INDENT 0.0
.TP
.BI \-e \ PATTERN\fP,\fB \ \-\-exclude \ PATTERN
exclude paths matching PATTERN
.TP
.BI \-\-exclude\-from \ EXCLUDEFILE
read exclude patterns from EXCLUDEFILE, one per line
.TP
.B \-\-exclude\-caches
exclude directories that contain a CACHEDIR.TAG file (\fI\%http://www.brynosaurus.com/cachedir/spec.html\fP)
.TP
.BI \-\-exclude\-if\-present \ NAME
exclude directories that are tagged by containing a filesystem object with the given NAME
.TP
.B \-\-keep\-exclude\-tags\fP,\fB \-\-keep\-tag\-files
keep tag objects (i.e.: arguments to \-\-exclude\-if\-present) in otherwise excluded caches/directories
.UNINDENT
.SS Archive options
.INDENT 0.0
.TP
.BI \-\-target \ TARGET
create a new archive with the name ARCHIVE, do not replace existing archive (only applies for a single archive)
.TP
.BI \-c \ SECONDS\fP,\fB \ \-\-checkpoint\-interval \ SECONDS
write checkpoint every SECONDS seconds (Default: 1800)
.TP
.BI \-\-comment \ COMMENT
add a comment text to the archive
.TP
.BI \-\-timestamp \ TIMESTAMP
manually specify the archive creation date/time (UTC, yyyy\-mm\-ddThh:mm:ss format). alternatively, give a reference file/directory.
.TP
.BI \-C \ COMPRESSION\fP,\fB \ \-\-compression \ COMPRESSION
select compression algorithm, see the output of the "borg help compression" command for details.
.TP
.B \-\-always\-recompress
always recompress chunks, don\(aqt skip chunks already compressed with the same algorithm.
.TP
.BI \-\-compression\-from \ COMPRESSIONCONFIG
read compression patterns from COMPRESSIONCONFIG, see the output of the "borg help compression" command for details.
.TP
.BI \-\-chunker\-params \ PARAMS
specify the chunker parameters (CHUNK_MIN_EXP, CHUNK_MAX_EXP, HASH_MASK_BITS, HASH_WINDOW_SIZE) or "default" to use the current defaults. default: 19,23,21,4095
.UNINDENT
.SH EXAMPLES
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# Make old (Attic / Borg 0.xx) archives deduplicate with Borg 1.x archives
# Archives created with Borg 1.1+ and the default chunker params are skipped (archive ID stays the same)
$ borg recreate /mnt/backup \-\-chunker\-params default \-\-progress
# Create a backup with little but fast compression
$ borg create /mnt/backup::archive /some/files \-\-compression lz4
# Then compress it \- this might take longer, but the backup has already completed, so no inconsistencies
# from a long\-running backup job.
$ borg recreate /mnt/backup::archive \-\-compression zlib,9
# Remove unwanted files from all archives in a repository
$ borg recreate /mnt/backup \-e /home/icke/Pictures/drunk_photos
# Change archive comment
$ borg create \-\-comment "This is a comment" /mnt/backup::archivename ~
$ borg info /mnt/backup::archivename
Name: archivename
Fingerprint: ...
Comment: This is a comment
\&...
$ borg recreate \-\-comment "This is a better comment" /mnt/backup::archivename
$ borg info /mnt/backup::archivename
Name: archivename
Fingerprint: ...
Comment: This is a better comment
\&...
.ft P
.fi
.UNINDENT
.UNINDENT
.SH SEE ALSO
.sp
\fIborg\-common(1)\fP, \fIborg\-patterns(1)\fP, \fIborg\-placeholders(1)\fP, \fIborg\-compression(1)\fP
.SH AUTHOR
The Borg Collective
.\" Generated by docutils manpage writer.
.

76
docs/man/borg-rename.1 Normal file
View file

@ -0,0 +1,76 @@
.\" Man page generated from reStructuredText.
.
.TH BORG-RENAME 1 "2017-02-05" "" "borg backup tool"
.SH NAME
borg-rename \- Rename an existing archive
.
.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
..
.SH SYNOPSIS
.sp
borg rename <options> ARCHIVE NEWNAME
.SH DESCRIPTION
.sp
This command renames an archive in the repository.
.sp
This results in a different archive ID.
.SH OPTIONS
.sp
See \fIborg\-common(1)\fP for common options of Borg commands.
.SS arguments
.INDENT 0.0
.TP
.B ARCHIVE
archive to rename
.TP
.B NEWNAME
the new archive name to use
.UNINDENT
.SH EXAMPLES
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ borg create /path/to/repo::archivename ~
$ borg list /path/to/repo
archivename Mon, 2016\-02\-15 19:50:19
$ borg rename /path/to/repo::archivename newname
$ borg list /path/to/repo
newname Mon, 2016\-02\-15 19:50:19
.ft P
.fi
.UNINDENT
.UNINDENT
.SH SEE ALSO
.sp
\fIborg\-common(1)\fP
.SH AUTHOR
The Borg Collective
.\" Generated by docutils manpage writer.
.

80
docs/man/borg-serve.1 Normal file
View file

@ -0,0 +1,80 @@
.\" Man page generated from reStructuredText.
.
.TH BORG-SERVE 1 "2017-02-05" "" "borg backup tool"
.SH NAME
borg-serve \- Start in server mode. This command is usually not used manually.
.
.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
..
.SH SYNOPSIS
.sp
borg serve <options>
.SH DESCRIPTION
.sp
This command starts a repository server process. This command is usually not used manually.
.SH OPTIONS
.sp
See \fIborg\-common(1)\fP for common options of Borg commands.
.SS optional arguments
.INDENT 0.0
.TP
.BI \-\-restrict\-to\-path \ PATH
restrict repository access to PATH. Can be specified multiple times to allow the client access to several directories. Access to all sub\-directories is granted implicitly; PATH doesn\(aqt need to directly point to a repository.
.TP
.B \-\-append\-only
only allow appending to repository segment files
.UNINDENT
.SH EXAMPLES
.sp
borg serve has special support for ssh forced commands (see \fBauthorized_keys\fP
example below): it will detect that you use such a forced command and extract
the value of the \fB\-\-restrict\-to\-path\fP option(s).
It will then parse the original command that came from the client, makes sure
that it is also \fBborg serve\fP and enforce path restriction(s) as given by the
forced command. That way, other options given by the client (like \fB\-\-info\fP or
\fB\-\-umask\fP) are preserved (and are not fixed by the forced command).
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# Allow an SSH keypair to only run borg, and only have access to /path/to/repo.
# Use key options to disable unneeded and potentially dangerous SSH functionality.
# This will help to secure an automated remote backup system.
$ cat ~/.ssh/authorized_keys
command="borg serve \-\-restrict\-to\-path /path/to/repo",no\-pty,no\-agent\-forwarding,no\-port\-forwarding,no\-X11\-forwarding,no\-user\-rc ssh\-rsa AAAAB3[...]
.ft P
.fi
.UNINDENT
.UNINDENT
.SH SEE ALSO
.sp
\fIborg\-common(1)\fP
.SH AUTHOR
The Borg Collective
.\" Generated by docutils manpage writer.
.

115
docs/man/borg-umount.1 Normal file
View file

@ -0,0 +1,115 @@
.\" Man page generated from reStructuredText.
.
.TH BORG-UMOUNT 1 "2017-02-05" "" "borg backup tool"
.SH NAME
borg-umount \- un-mount the FUSE filesystem
.
.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
..
.SH SYNOPSIS
.sp
borg umount <options> MOUNTPOINT
.SH DESCRIPTION
.sp
This command un\-mounts a FUSE filesystem that was mounted with \fBborg mount\fP\&.
.sp
This is a convenience wrapper that just calls the platform\-specific shell
command \- usually this is either umount or fusermount \-u.
.SH OPTIONS
.sp
See \fIborg\-common(1)\fP for common options of Borg commands.
.SS arguments
.INDENT 0.0
.TP
.B MOUNTPOINT
mountpoint of the filesystem to umount
.UNINDENT
.SH EXAMPLES
.SS borg mount
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ borg mount /path/to/repo::root\-2016\-02\-15 /tmp/mymountpoint
$ ls /tmp/mymountpoint
bin boot etc home lib lib64 lost+found media mnt opt root sbin srv tmp usr var
$ borg umount /tmp/mymountpoint
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ borg mount \-o versions /path/to/repo /tmp/mymountpoint
$ ls \-l /tmp/mymountpoint/home/user/doc.txt/
total 24
\-rw\-rw\-r\-\- 1 user group 12357 Aug 26 21:19 doc.txt.cda00bc9
\-rw\-rw\-r\-\- 1 user group 12204 Aug 26 21:04 doc.txt.fa760f28
$ fusermount \-u /tmp/mymountpoint
.ft P
.fi
.UNINDENT
.UNINDENT
.SS borgfs
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ echo \(aq/mnt/backup /tmp/myrepo fuse.borgfs defaults,noauto 0 0\(aq >> /etc/fstab
$ echo \(aq/mnt/backup::root\-2016\-02\-15 /tmp/myarchive fuse.borgfs defaults,noauto 0 0\(aq >> /etc/fstab
$ mount /tmp/myrepo
$ mount /tmp/myarchive
$ ls /tmp/myrepo
root\-2016\-02\-01 root\-2016\-02\-2015
$ ls /tmp/myarchive
bin boot etc home lib lib64 lost+found media mnt opt root sbin srv tmp usr var
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
\fBborgfs\fP will be automatically provided if you used a distribution
package, \fBpip\fP or \fBsetup.py\fP to install Borg\&. Users of the
standalone binary will have to manually create a symlink (see
\fIpyinstaller\-binary\fP).
.UNINDENT
.UNINDENT
.SH SEE ALSO
.sp
\fIborg\-common(1)\fP, \fIborg\-mount(1)\fP
.SH AUTHOR
The Borg Collective
.\" Generated by docutils manpage writer.
.

170
docs/man/borg-upgrade.1 Normal file
View file

@ -0,0 +1,170 @@
.\" Man page generated from reStructuredText.
.
.TH BORG-UPGRADE 1 "2017-02-05" "" "borg backup tool"
.SH NAME
borg-upgrade \- upgrade a repository from a previous version
.
.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
..
.SH SYNOPSIS
.sp
borg upgrade <options> REPOSITORY
.SH DESCRIPTION
.sp
Upgrade an existing Borg repository.
.SS Borg 1.x.y upgrades
.sp
Use \fBborg upgrade \-\-tam REPO\fP to require manifest authentication
introduced with Borg 1.0.9 to address security issues. This means
that modifying the repository after doing this with a version prior
to 1.0.9 will raise a validation error, so only perform this upgrade
after updating all clients using the repository to 1.0.9 or newer.
.sp
This upgrade should be done on each client for safety reasons.
.sp
If a repository is accidentally modified with a pre\-1.0.9 client after
this upgrade, use \fBborg upgrade \-\-tam \-\-force REPO\fP to remedy it.
.sp
If you routinely do this you might not want to enable this upgrade
(which will leave you exposed to the security issue). You can
reverse the upgrade by issuing \fBborg upgrade \-\-disable\-tam REPO\fP\&.
.sp
See
\fI\%https://borgbackup.readthedocs.io/en/stable/changes.html#pre\-1\-0\-9\-manifest\-spoofing\-vulnerability\fP
for details.
.SS Attic and Borg 0.xx to Borg 1.x
.sp
This currently supports converting an Attic repository to Borg and also
helps with converting Borg 0.xx to 1.0.
.sp
Currently, only LOCAL repositories can be upgraded (issue #465).
.sp
It will change the magic strings in the repository\(aqs segments
to match the new Borg magic strings. The keyfiles found in
$ATTIC_KEYS_DIR or ~/.attic/keys/ will also be converted and
copied to $BORG_KEYS_DIR or ~/.config/borg/keys.
.sp
The cache files are converted, from $ATTIC_CACHE_DIR or
~/.cache/attic to $BORG_CACHE_DIR or ~/.cache/borg, but the
cache layout between Borg and Attic changed, so it is possible
the first backup after the conversion takes longer than expected
due to the cache resync.
.sp
Upgrade should be able to resume if interrupted, although it
will still iterate over all segments. If you want to start
from scratch, use \fIborg delete\fP over the copied repository to
make sure the cache files are also removed:
.INDENT 0.0
.INDENT 3.5
borg delete borg
.UNINDENT
.UNINDENT
.sp
Unless \fB\-\-inplace\fP is specified, the upgrade process first
creates a backup copy of the repository, in
REPOSITORY.upgrade\-DATETIME, using hardlinks. This takes
longer than in place upgrades, but is much safer and gives
progress information (as opposed to \fBcp \-al\fP). Once you are
satisfied with the conversion, you can safely destroy the
backup copy.
.sp
WARNING: Running the upgrade in place will make the current
copy unusable with older version, with no way of going back
to previous versions. This can PERMANENTLY DAMAGE YOUR
REPOSITORY! Attic CAN NOT READ BORG REPOSITORIES, as the
magic strings have changed. You have been warned.
.SH OPTIONS
.sp
See \fIborg\-common(1)\fP for common options of Borg commands.
.SS arguments
.INDENT 0.0
.TP
.B REPOSITORY
path to the repository to be upgraded
.UNINDENT
.SS optional arguments
.INDENT 0.0
.TP
.B \-p\fP,\fB \-\-progress
show progress display while upgrading the repository
.TP
.B \-n\fP,\fB \-\-dry\-run
do not change repository
.TP
.B \-i\fP,\fB \-\-inplace
rewrite repository in place, with no chance of going back to older
versions of the repository.
.TP
.B \-\-force
Force upgrade
.TP
.B \-\-tam
Enable manifest authentication (in key and cache) (Borg 1.0.9 and later)
.TP
.B \-\-disable\-tam
Disable manifest authentication (in key and cache)
.UNINDENT
.SH EXAMPLES
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# Upgrade the borg repository to the most recent version.
$ borg upgrade \-v /path/to/repo
making a hardlink copy in /path/to/repo.upgrade\-2016\-02\-15\-20:51:55
opening attic repository with borg and converting
no key file found for repository
converting repo index /path/to/repo/index.0
converting 1 segments...
converting borg 0.xx to borg current
no key file found for repository
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Upgrading a passphrase encrypted attic repo
.sp
attic offered a "passphrase" encryption mode, but this was removed in borg 1.0
and replaced by the "repokey" mode (which stores the passphrase\-protected
encryption key into the repository config).
.sp
Thus, to upgrade a "passphrase" attic repo to a "repokey" borg repo, 2 steps
are needed, in this order:
.INDENT 0.0
.IP \(bu 2
borg upgrade repo
.IP \(bu 2
borg key migrate\-to\-repokey repo
.UNINDENT
.SH SEE ALSO
.sp
\fIborg\-common(1)\fP
.SH AUTHOR
The Borg Collective
.\" Generated by docutils manpage writer.
.

71
docs/man/borg-with-lock.1 Normal file
View file

@ -0,0 +1,71 @@
.\" Man page generated from reStructuredText.
.
.TH BORG-WITH-LOCK 1 "2017-02-05" "" "borg backup tool"
.SH NAME
borg-with-lock \- run a user specified command with the repository lock held
.
.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
..
.SH SYNOPSIS
.sp
borg with\-lock <options> REPOSITORY COMMAND ARGS
.SH DESCRIPTION
.sp
This command runs a user\-specified command while the repository lock is held.
.sp
It will first try to acquire the lock (make sure that no other operation is
running in the repo), then execute the given command as a subprocess and wait
for its termination, release the lock and return the user command\(aqs return
code as borg\(aqs return code.
.INDENT 0.0
.TP
.B Note: if you copy a repository with the lock held, the lock will be present in
the copy, obviously. Thus, before using borg on the copy, you need to
use "borg break\-lock" on it.
.UNINDENT
.SH OPTIONS
.sp
See \fIborg\-common(1)\fP for common options of Borg commands.
.SS arguments
.INDENT 0.0
.TP
.B REPOSITORY
repository to lock
.TP
.B COMMAND
command to run
.TP
.B ARGS
command arguments
.UNINDENT
.SH SEE ALSO
.sp
\fIborg\-common(1)\fP
.SH AUTHOR
The Borg Collective
.\" Generated by docutils manpage writer.
.