]> borgit

borgit

NAME
SYNOPSIS
DESCRIPTION
OPTIONS
CONFIGURATION FILES
EXIT CODES
AUTHOR
COPYRIGHT
IDENTITIES OF AUTHORS


NAME

borgit − Write your Borg backup jobs with sourced bash configuration files

SYNOPSIS

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

DESCRIPTION

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.

OPTIONS

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

CONFIGURATION FILES

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 \"${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 \"${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"

EXIT CODES

borgit returns with the exit code of its "borg create" call.

AUTHOR

eomanis

E-Mail: eomanis@web.de
PGP key fingerprint: F576 37E9 E5C2 8F91 EE64 277B 603E EF8F E0A9 9498

COPYRIGHT

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

IDENTITIES OF AUTHORS

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.