diff --git a/README.md b/README.md index 01f44ba..c02caae 100644 --- a/README.md +++ b/README.md @@ -1,31 +1,119 @@ # vzborg utility -Backup, restore and mantain your Proxmox vzdupms in -- Deduplicated -- Local or remote -- Optionally encrypted +**Deduplicated, encrypted backups for the Proxmox Virtual Environment.** -borg repositories -## Requirements -You need a proxmox 5.x or 6.x, and a suitable borg backup package installed. +Vzborg uses vzdump and borg backup to allow deduplicated, compressed backups of Proxmox guests, in an optionally encrypted repository. -If you are in proxmox 5.x you must enable stretch-backports repository and install it with: +With vzborg, you can backup, restore, delete, list and mantain your backups in a flexible and efficient way. -`apt install -t stretch-backports borgbackup` +Use default retention settings to keep a suitable number of hourly, daily, weekly, monthly and yearly backups of your guest. + +Set up automated backups to remote repositories, simply setting appropriate ssh keys. + +## Requirements +You need a proxmox 5.x or 6.x server with a suitable borg backup package installed. If you are in proxmox 6.x you can just install it with: `apt install borgbackup` +If you are in proxmox 5.x you must enable stretch-backports repository and install it with: + +`apt install -t stretch-backports borgbackup` + +If you want to use a remote repository, you need borg backup installed on it, with the same or a greater version, than the one installed in your proxmox server. If your remote repository is in another proxmox server, you can also install vzborg on it. + ## Installation -ToDo -## Use -`vzborg -c help` +In your proxmox server run as root: + +`wget -O - https://raw.githubusercontent.com/g3492/vzborg/master/install_and_update_vzborg.sh | bash` + +## Usage: +`vzborg [OPTIONS]` + +vzborg only uses options as parameters. Spcecified, but not used options, are ignored. + +### Required option: + +` -c COMMAND` + +Where COMMAND is one of: + +| Command | Description | +|:----------|:-----------------------------------| +| backup |Perform a backup job. | +| delete |Delete a specific backup. | +| discard |Discard all backups of given guests.| +| getdump |Recreate a dump file from a backup. | +| help |Show vzborg help. | +| list |List backups in repository. | +| prune |Prune (purge) repository. | +| restore |Restore backup from repository. | +| version |Show vzborg, borg and pve version. | + + +### Aditional options +| Option | Value | Use |Description | +|:----------------|:-----------|:--------------------------|:-----------------------------------| +|-b (--backup) |BACKUP_NAME |delete/restore |Name of an existing backup (archive)| +|-d (--dry-run) | |backup/prune | Perform simulation| +|-f (--force) | |restore |Force overwrite of existing VM/CT| +|-h (--help)| | |all |Display command help. Requires -c option| +|-i (--ids) |VM_ID |backup/discard |PVE VM/CT ID or list of PVE VM/CT IDs | +|-k (--keep) |RETENTION |prune|List of retention settings | +|-m (--mode) |MODE |backup | vzdump mode (default = snapshot)| +|-r (--repository)|REPOSITORY |backup/getdump/list/restore| Borg repository | +|-s (--storage) |STORAGE |getdump/restore | Proxmox storage (default = local)| + +### Configuration file: + + `/etc/vzborg.conf` + +Edit before using vzborg, to customize defaults parameters. + + +### Examples +`vzborg -c restore -h` + +Show help about restore command. + +`vzborg -c backup -i '101 102 307'` + +Backup guests 101, 102 and 307 with default options. + +`vzborg -c restore -b vzborg-300-2020_03_20-13_11_46.vma -i 1300 -s local_lvm` + +Restore VM from backup with name vzborg-300-2020_03_20-13_11_46.vma as VM with ID 1300 to storage local_lvm. + +`vzborg -c list` + +List all backups in default repository. + +`vzborg -c list -i 303 -r ssh://example.com:22/mnt/remote_borg_repo` + +List all backups of guest with ID 303 existing on remote repository ssh://example.com:22/mnt/remote_borg_repo + +`vzborg -c list -i '1230 1040 2077' -r /mnt/vzborg` + +List all backups of guests with IDs 12030, 1040 and 2077 existing in local repository /mnt/vzborg + + +`vzborg -c getdump -b vzborg-13998-2020_03_20-13_08_35.tar -s backups` + +Recreate from backup name vzborg-13998-2020_03_20-13_08_35.tar an lxc dump file in PVE storage backups (the file will be recreated as the compressed file vzdump-13998-2020_03_20-13_08_35.tar.lzo) + +`vzborg -c prune -i '101 102 307'` + +Prune or purge backups of guests with IDs 101, 102 and 307, on default repository, using default retentions. + +`vzborg -c prune -i '101 102 307' -k '--keep-weekly=4 --keep-monthly=6 --keep-yearly=2'` + +Prune or purge backups of guests with IDs 101, 102 and 307 on default repository, keeping 4 weekly, 6 montly an 2 yearly backups. ## License Licensed under GNU Affero General Public License, version 3. ## Feedback, bug-reports, requests, ... -They are [welcome](https://github.com/g3492/vzborg/issues)! +They are welcome [here](https://github.com/g3492/vzborg/issues)! ## Important note -By now vzborg is alfa software. You can test it at your own risk \ No newline at end of file +vzborg is alfa software under development. Use it at your own risk \ No newline at end of file diff --git a/install_and_update_vzborg.sh b/install_and_update_vzborg.sh new file mode 100755 index 0000000..e5fadca --- /dev/null +++ b/install_and_update_vzborg.sh @@ -0,0 +1,69 @@ +#!/usr/bin/env bash +# Install vzborg with: +# +# wget -O - https://raw.githubusercontent.com/g3492/vzborg/master/install_and_update_vzborg.sh | bash +# +# vim: set filetype=sh : +# Make the script exit when a command fails (set -e). +set -o errexit +# Make the script exit when tries to use undeclared variables (set -u) +set -o nounset +# Exit on pipe fail +set -o pipefail + +say() { + echo -e $1 +} +die() { + say "Error: $1" >&2 + exit 1 +} + +version_greater_equal() { + printf '%s\n%s\n' "$2" "$1" | sort -V -C +} + +# CHECKS + +# Check if running as root. +if [[ $EUID = 0 ]]; then + say "OK. Running as root." +else + die "vzborg installation must be executed as root user." +fi + +# Check PVE version +if [[ -f /usr/bin/pveversion ]]; then + pve_version="$(pveversion | cut -d'/' -f2)" + say 'Checking PVE version' + if version_greater_equal "${pve_version}" 5.0; then + say "OK" + else + die "You need Proxmox virtual environment (PVE) version >= 5.0.0" + fi +else + die "Can not find pveversion. Is this a Proxmox Virtual Environment (PVE) server?" +fi +# Check borg version +if [[ -f /usr/bin/borg ]]; then + borg_version="$(borg -V | cut -d' ' -f2)" + say 'Checking Borg backup version' + if version_greater_equal "${borg_version}" 1.1.0; then + say "OK" + else + die "You need borg backup version >= 1.1.0" + fi +else + die "Can not find borg. Is Borg backup installed?" +fi + +# Install +say "Installing vzborg to /usr/local/bin" +wget -P /usr/local/bin https://raw.githubusercontent.com/g3492/vzborg/master/vzborg +chmod +x /usr/local/bin/vzborg +if [[ -f /etc/vzborg.conf ]]; then + say "Configuration file /etc/vzborg.conf exist." +else + say "Creating default configuration file (/etc/vzborg.conf)" + wget -P /etc https://raw.githubusercontent.com/g3492/vzborg/master/vzborg.conf +fi diff --git a/vzborg.conf b/vzborg.conf index c989d0c..7745684 100644 --- a/vzborg.conf +++ b/vzborg.conf @@ -1,5 +1,6 @@ -# -# VZBORG DEFAULT VARIABLES +############################ +# VZBORG DEFAULT VARIABLES # +############################ # BORG REPOSITORY PATH # @@ -22,16 +23,14 @@ VZBORG_REPO="/var/lib/vz/vzborg/" # # Select your borg encryption mode, for automatic repo creation on first backup # -# Modes avilable for both proxmox 5.x with borg <1.1 and proxmox 6.x with borg >=1.1 -# are < none | repokey | keyfile > -# -# Aditional modes available for proxmox 6.x with borg >=1.1 and not backward compatible -# are < authenticated | authenticated-blake2 | repokey-blake2 | keyfile-blake2 > +# Choose one of: +# < none|repokey|keyfile|authenticated|authenticated-blake2|repokey-blake2|keyfile-blake2 > # # For detailed information about encryption modes see borg documentation: +# # https://borgbackup.readthedocs.io/en/stable/usage/init.html # -ENCRYPTION_MODE=repokey +ENCRYPTION_MODE=repokey-blake2 # ENCRYPTION PASSPHRASE # @@ -41,7 +40,7 @@ ENCRYPTION_MODE=repokey # automatically on first backup VZBORG_PASSPHRASE='MySecretBorgRepositoryPassphrase' -# NOTIFICATION OF BACKUP AND PRUNE JOBS +# NOTIFICATION OF BACKUP JOBS # # who recives the log info NOTIFY_TO="admin@example.com" @@ -60,9 +59,6 @@ DEFAULT_KEEP='--keep-daily=2 --keep-weekly=4 --keep-monthly=12 --keep-yearly=2' # LIST FORMAT # # Set a default list format -# Default list format for borg <1.1 (proxmox 5.x) -#DEFAULT_LIST_FORMAT='{archive} host: {hostname}{NL}' -# Default list format for borg >1.1 (proxmox 6.x) DEFAULT_LIST_FORMAT='{archive} (host: {hostname}) {comment}{NL}' # COMPRESSION