NAME
SYNOPSIS
DESCRIPTION
OPTIONS
CONFIGURATION FILES
EXIT CODES
AUTHOR
COPYRIGHT
IDENTITIES OF AUTHORS
borgit - Write your Borg backup jobs with sourced bash configuration files
|
borgit |
[-s|--archive-suffix
archiveSuffix]
[--]
configurationFile [configurationFile...]
borgit --help
borgit --version
Run a single Borg backup job according to the given command line options and configuration files
Performs a single "borg create" call according to the parameters specified in the given configuration files.
Typically two
configuration files are given, a repository configuration
file and a backup job configuration file.
The repository configuration file determines the target Borg
repository, and the job configuration file sets the Borg
archive name and the paths that should be backed up.
Example:
borgit -- repos/system-online jobs/ftp-server
Usually
borgit is not called directly. Rather, multiple
backup jobs are run against the same repository with
borgit’s companion application, borgem.
See manual page borgem(1) for more information about
borgem.
-s|--archive-suffix archiveSuffix
A suffix that is appended to a
backup job’s archive prefix, to form the Borg archive
name that should be created in the repository.
For example, if the job configuration declares an archive
prefix "ftp-server" and ".2019-12-06" is
given as archive suffix, the archive name will be
"ftp-server.2019-12-06".
The default archive suffix is the current UTC date in ISO
8601 format with a leading dot (.yyyy-MM-dd), as shown in
the example.
|
--help |
Print a short information text to STDOUT and exit with code 0. |
--version
Print the version string to STDOUT and exit with code 0.
Insofar as they exist borgit reads these global configuration files, in this order, wildcards expanded alphabetically:
•
/usr/lib/borgit/borgit.d/*.conf
• /usr/lib/borgit/borgit.conf
• /etc/borgit/borgit.d/*.conf
• /etc/borgit/borgit.conf
• /run/borgit/borgit.d/*.conf
• /run/borgit/borgit.conf
First the global configuration files are sourced, and then the ones given as trailing arguments.
Any option may
be specified in any configuration file, but if you intend to
use borgem to run multiple backup jobs against the
same repository you need to put job-specific options into
separate configuration files, one configuration file per
job.
You typically have global, repository-specific and
job-specific options.
The configuration files must
• set: repo
Default: Not set
Typically set in configuration: Repository
The Borg repository to back up to (repository only, without
archive)
Example:
repo="backup-user@backup-system:/data/backups/borg/my-system"
• set: archivePrefix
Default: Not set
Typically set in configuration: Job
A job-specific Borg archive prefix (typically, backup job
name) to which the archive suffix will be appended, yielding
the repository archive
Example:
archivePrefix="ftp-server"
Example that uses the configuration file’s name as archive prefix:
archivePrefix="$(basename "${BASH_SOURCE[0]}")"
• set, or append to: paths (indexed array)
Default: paths=()
Typically set in configuration: Job
The paths to be backed up, which are given to Borg as
trailing arguments; they must all exist or else the backup
will not be attempted; this is checked in beforeBackup()
Example:
paths+=(
"/etc/proftpd.conf" )
paths+=( "/data/ftp/share" )
The configuration files may
• set, or append to: borgCreate (indexed array)
Default: borgCreate=( create )
Typically set in configuration: Global, job
The argument(s) for the "borg create" call of the
borg execuable
Global configuration example:
borgCreate=( --progress create )
Job configuration example:
borgCreate+=( --exclude "pp:/data/ftp/share/bind-mount" )
• set, or append to: services (indexed array)
Default: services=()
Typically set in configuration: Job
The systemd services or timers to be stopped and restarted
by the beforeBackup() and afterBackup() functions,
respectively
Example:
services+=( proftpd.service )
• export: Borg environment variables
Such as BORG_PASSCOMMAND
Typically set in configuration: Repository
Example:
export BORG_PASSCOMMAND="cat /path/to/secret.passphrase"
Example for a passphrase file having the same path as the file that is being sourced, but with an appended suffix ".passphrase":
export BORG_PASSCOMMAND="cat \"$(realpath -m "${BASH_SOURCE[0]}").passphrase\""
The configuration files may declare these functions:
• beforeBackupCustom()
Typically set in configuration:
Job
A function that will be called instead of
beforeBackup(), to implement actions that go beyond
validating the paths and stopping systemd units
• afterBackupCustom()
Typically set in configuration:
Job
A function that will be registered as trap function (for
EXIT, HUP, INT, and TERM) instead of afterBackup(),
to implement actions that go beyond restarting systemd
units
borgit runs with these bash options:
set -o nounset
set -o noclobber
set -o errexit
shopt -qs inherit_errexit
Keep this in mind if you intend to write more complex code than setting variables or appending to arrays.
Example:
Global configuration
E.g. in "/etc/borgit/borgit.conf"
borgCreate=( --progress create )
Example:
Repository configuration "system-online"
E.g. in "/root/borgit/repos/system-online", with
the passphrase in
"/root/borgit/repos/system-online.passphrase"
repo="backup-user@backup-system:/data/backups/borg/my-system"
export BORG_PASSCOMMAND="cat \"$(realpath -m
"${BASH_SOURCE[0]}").passphrase\""
Example:
Job configuration "ftp-server"
E.g. in "/root/borgit/jobs/ftp-server"
archivePrefix="$(basename
"${BASH_SOURCE[0]}")"
paths+=( "/etc/proftpd.conf" )
paths+=( "/data/ftp/share" )
borgCreate+=( --exclude
"pp:/data/ftp/share/bind-mount" )
services+=( proftpd.service )
As a fringe benefit you can source a repository configuration file into your interactive bash shell and comfortably manipulate the repository with borg directly, like this:
# source repos/system-online
# borg list "$repo"
# borg delete "$repo::ftp-server.2019-11-02"
# borg prune -y 10 -m 12 -w 50 -d 35 "$repo"
borgit returns with the exit code of its "borg create" call.
eomanis
E-Mail: eomanis@web.de
PGP key fingerprint: F576 37E9 E5C2 8F91 EE64 277B 603E EF8F
E0A9 9498
Copyright 2019, 2020 eomanis
borgit is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License version 3 as published by the Free Software Foundation.
borgit is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with borgit. If not, see <http://www.gnu.org/licenses/>.
Should it be required to ascertain the identity of an author, the person who can prove to be in possession of the secret master key of an author’s PGP key is to be considered the respective author.
In case an author’s PGP key has been replaced by another PGP key, the person who can prove the key supersession in the most convincing manner is to be considered the respective author. For example, an author may document the existence of a properly signed key supersession declaration at a certain point in time in a provably tamper-proof way, such as embedding the declaration or a cryptographically secure hash of it in an irreversible blockchain.