qBackup is a set of scripts to help use borgbackup for regular backups on a Windows machine. Y'know. Because Q introduces Star Fleet to the Borg? ... Moving on. qBackup has two main components: the installer install.ps1
and the actual backup script qbackup.ps1
. The process is designed so that the backup script can be run as e.g. a scheduled task.
qBackup requires a native Cygwin to be installed, i.e. a 64bit Cygwin on 64bit machines. Whenever I refer to Cygwin in this document, I refer to the native version. Currently, qBackup supports only 64bit systems. Feel free to fix this in a PR if you have a 32bit system.
If you do not have Cygwin already installed on your machine, the installer will setup Cygwin at a location of your choice. You can also pass the option -CygwinPath C:\cygwin
to the installer to request installation to C:\cygwin
. If an existing Cygwin installation is found, the installer will still detect it and prompt whether to use it.
The only other changes to your system made by the installer are limited to the directory in which qBackup resides.
To install qBackup, simply run install.ps1
. It will download the Cygwin setup executable and use it to install the following Cygwin packages:
python3
python3-devel
git,openssh
gcc-g++
openssl-devel
liblz4-devel
It will then hand over to Cygwin's bash to do the following:
- generate an SSH keypair in
qbackup.sshkey
andqbackup.sshkey.pub
, no passphrase. - setup a python3 virtual environment in the folder
venv
and activate it. - clone the borgbackup repository into
venv\borg
and (currently) check out version1.1.2
. - install cython from the Python package index.
- install borgbackup from the local directory
venv\borg
.
Note: Currently, it also manually installs the package msgpack-python
version 0.5.1
as a temporary workaround for this problem I had.
You can call qBackup in one of the following ways:
This command outputs the backup encryption passphrase to stdout. It exists so qBackup can set the BORG_PASSCOMMAND
environment variable to qBackup.ps1 -IDDQD
.
The qBackup configuration is stored in a JSON file called qbackup.json
. If the file does not exist or values are missing from it, the following default values are used:
{
"binary": "borg",
"bflags": "--compression zlib,9 --stats --list --filter=ME",
"format": "yyyy-MM-dd_HH-mm-ss",
"pruned": "--keep-daily 30 --keep-weekly 52 --keep-monthly 12 --keep-yearly 20"
}
It also contains the value remote
, which stores the URL to your remote backup location, i.e. a value similar to
ssh://user@backup.server/home/user/backups/
The encryption passphrase for the remote backup is stored as a DPAPI-encrypted string in the field secret
of this json file. Furthermore:
binary
stores the remote path to your borg executable.bflags
are parameters passed to the borg command for each create operation.format
is the format for the remote backup archive name and for the local logfile. The remote backup will have the name::format
while the local log files will have the nameformat.log
.pruned
contains the parameters passed to each prune operation.
The command -Configure
is a (debatably) convenient way to change these settings, but you can also just go ahead and edit the json file, of course. Notably however, the only way to really change the stored encryption key is by calling -Configure
with the -SetSecret
option.
Simply run borg with the specified arguments. The BORG_REPO
, BORG_PASSCOMMAND
, BORG_RSH
and BORG_REMOTE_PATH
environment variables will be set, so you can e.g. simply call qbackup.ps1 -Borg list
to list your remote archives.
When run, qBackup will create a shadow copy of the disk where DIRECTORY
is located, then mount this shadow copy in a temporary folder. If -ACLs
is specified, it will backup the NTFS permissions of all files in the shadow copy of DIRECTORY
to a file called .acls
.
The script will then backup the files from the shadow copy using the create operation of borg. The borg archive name is derived from the current date and time according to the format
setting. All aditional parameters from BORGARGS
as well as those from the bflags
setting will also be passed to this borg
call. If the -Log
option is specified, qBackup will create a logfile containing the output of borg
.
If the -Pruned
option is specified, qBackup will then prune the remote archive according to the pruned
setting.
Finally, the -Init
option has to be set if and only if you run qBackup against a remote for the first time.