From 173521e26764cf8fb7080ddeae1a4cfdadc6c34e Mon Sep 17 00:00:00 2001 From: parke Date: Fri, 18 Feb 2022 15:36:40 -0800 Subject: [PATCH] Numerous edits to improve clarity and consistency. Added context in several places. --- Home.md | 76 +++++++++++++++++++++++++++++++++------------------------ 1 file changed, 44 insertions(+), 32 deletions(-) diff --git a/Home.md b/Home.md index 6ef4856..c58f387 100644 --- a/Home.md +++ b/Home.md @@ -4,23 +4,27 @@ Look at the [README.md](../blob/master/README.md) for the introduction. ## Installation -You only need to install zfs-autobackup on the side that initiates the backup. The other side doesn't need any extra configration. +zfs-autobackup creates ZFS snapshots on a "source" machine and then replicates those snapshots to a "target" machine via SSH. + +zfs-autobackup may be installed on either the source machine or the target machine. (Installing on both is unnecessary.) + +When installed on the source, zfs-autobackup will push snapshots to the target. When installed on the target, zfs-autobackup will pull snapshots from the source. ### Using pip -The recommended way on most servers is to use [pip](https://pypi.org/project/zfs-autobackup/): +The recommended installation method on most machines is to use [pip](https://pypi.org/project/zfs-autobackup/): ```console [root@server ~]# pip install --upgrade zfs-autobackup ``` -This can also be used to upgrade zfs-autobackup to the newest stable version. +The above command can also be used to upgrade zfs-autobackup to the newest stable version. To install the latest beta version add the `--pre` option. ### Using easy_install -On older servers you might have to use easy_install +On older machines you might have to use easy_install: ```console [root@server ~]# easy_install zfs-autobackup @@ -28,15 +32,15 @@ On older servers you might have to use easy_install ## Example -In this example we're going to backup a machine called `pve01` to a machine called `backup`. +In this example, a machine called `backup` is going to create and pull backup snapshots from a machine called `pve01`. ### Setup SSH login -zfs-autobackup needs passwordless login via ssh. This means generating an ssh key and copying it to the remote server. +As zfs-autobackup will perform numerous remote commands via ssh, we strongly recommend setting up passwordless login via ssh. This means generating an ssh key on target machine (`backup`) and copying the public ssh key to the source machine (`pve01`). -#### Generate SSH key on `backup` +#### Generate an SSH key on `backup` -On the backup-server that runs zfs-autobackup you need to create an SSH key. You only need to do this once. +Create an SSH key on the backup machine that runs zfs-autobackup. You only need to do this once. Use the `ssh-keygen` command and leave the passphrase empty: @@ -50,7 +54,7 @@ Enter same passphrase again: root@backup:~# ``` -#### Copy SSH key to `pve01` +#### Copy the SSH key to `pve01` Now you need to copy the public part of the key to `pve01` @@ -66,13 +70,17 @@ Number of key(s) added: 1 root@backup:~# ``` -This allows the backup-server to login to `pve01` as root without password. +This allows the backup machine to login to `pve01` as root without password. ### Select filesystems to backup -Its important to choose a unique and consistent backup name. In this case we name our backup: `offsite1`. +Next, we specify the filesystems we want to snapshot and replicate by assigning a unique group name to those filesystems. -On the source zfs system set the ```autobackup:offsite1``` zfs property to true: +Its important to choose a unique group name and to use the name consistently. (Advanced tip: If you have multiple sets of filesystems that you wish to backup differently, you may do this by creating multiple group names.) + +In this example, we assign the group name `offsite1` to the filesystems we want to backup. + +On the source machine, we set the ```autobackup:offsite1``` zfs property to ```true```, as follows: ```console [root@pve01 ~]# zfs set autobackup:offsite1=true rpool @@ -87,9 +95,9 @@ rpool/data/vm-101-disk-0 autobackup:offsite1 true inherited fr rpool/tmp autobackup:offsite1 true inherited from rpool ``` -ZFS properties are ```inherited``` by child datasets. Since we've set the property on the highest dataset, we're essentially backupping the whole pool. +ZFS properties are ```inherited``` by child datasets. Since we've set the property on the highest dataset, we're essentially backing up the whole pool. -Because we don't want to backup everything, we can exclude certain filesystem by setting the property to false: +If we don't want to backup everything, we can exclude certain filesystem by setting the property to ```false```: ```console [root@pve01 ~]# zfs set autobackup:offsite1=false rpool/tmp @@ -104,16 +112,16 @@ rpool/data/vm-101-disk-0 autobackup:offsite1 true inherited fr rpool/tmp autobackup:offsite1 false local ``` -The autobackup-property can have 3 values: - * ```true```: Backup the dataset and all its children - * ```false```: Dont backup the dataset and all its children. (used to exclude certain datasets) +The ```autobackup``` property can have 3 values: + * ```true```: Backup the dataset and all its children . + * ```false```: Don't backup the dataset and all its children. (Used to exclude certain datasets.) * ```child```: Only backup the children off the dataset, not the dataset itself. -(Only use the zfs-command to set these properties, not the zpool command.) +(Note: Only use the ```zfs``` command to set these properties. Do not use the ```zpool``` command.) ### Running zfs-autobackup -Run the script on the backup server and pull the data from the server specified by --ssh-source. +Run the script on the backup machine and pull the data from the source machine specified by ```--ssh-source```. ```console [root@backup ~]# zfs-autobackup -v --ssh-source pve01 offsite1 data/backup/pve01 @@ -161,9 +169,15 @@ Run the script on the backup server and pull the data from the server specified #### All operations completed successfully ``` -Note that this is called a "pull" backup: The backup server pulls the backup from the server. This is usually the preferred way. +Note that this is called a "pull" backup. The backup (target) machine pulls the backup from the source machine. This is usually the preferred way. -Its also possible to let a server push its backup to the backup-server. However this has security implications. In that case you would setup the SSH keys the other way around and use the --ssh-target parameter on the server. +It is also possible to let a source machine push its backup to the target machine. There are security implications to both approaches, as follows: + +With a pull backup, the target machine will have root access to the source machine. + +With a push backup, the source machine will have root access to the target machine. + +If you wish to do a push backup, then you would setup the SSH keys the other way around and use the `--ssh-target` parameter on the source machine. ### Automatic backups @@ -177,17 +191,17 @@ Or just create a script and run it manually when you need it. ### Monitoring -Dont forget to monitor the results of your backups, look at [Monitoring](Monitoring) for more info. +Don't forget to monitor the results of your backups, look at [Monitoring](Monitoring) for more info. ### Splitting up snapshot and backup job You might want to make snapshots during the week, and only transfer data during the weekends. -In this case you would run this every day: +In this case you would run this each weekday: > zfs-autobackup -v --ssh-source pve01 offsite1 data/backup/pve01 --no-send -And this in the weekends: +And this on weekend days: > zfs-autobackup -v --ssh-source pve01 offsite1 data/backup/pve01 @@ -195,11 +209,11 @@ And this in the weekends: You can use zfs-autobackup as a standalone snapshot tool. -Just dont specify the target-path: +To do this, simply omit the target-path, as follows: > zfs-autobackup -v --ssh-source pve01 offsite1 -Only use this if you dont want to make any backup at all or if a target isn't reachable during the snapshotting phase. +Only use this if you don't want to make any backup at all, or if a target isn't reachable during the snapshotting phase. ### Specifying ssh port or options @@ -214,15 +228,15 @@ Host smartos04 This way you can just specify "smartos04" as host. -Look in man ssh_config for many more options. +Look in ```man ssh_config``` for many more options. ## Tips * Use ```--debug``` if something goes wrong and you want to see the commands that are executed. This will also stop at the first error. * You can split up the snapshotting and sending tasks by creating two cronjobs. Create a separate snapshotter-cronjob by just omitting target-path. -* Set the ```readonly``` property of the target filesystem to ```on```. This prevents changes on the target side. (Normally, if there are changes the next backup will fail and will require a zfs rollback.) Note that readonly means you cant change the CONTENTS of the dataset directly. Its still possible to receive new datasets and manipulate properties etc. -* Use ```--clear-refreservation``` to save space on your backup server. -* Use ```--clear-mountpoint``` to prevent the target server from mounting the backupped filesystem in the wrong place during a reboot. +* Set the ```readonly``` property of the target filesystem to ```on```. This prevents changes on the target side. (Due to the nature of ZFS itself, if any changes are made to a dataset on the target machine, then the next backup to that target machine will probably fail. Such a failure can probably be resolved by perfroming a target-side zfs rollback of the affected dataset.) Note that ```readonly``` prevents changes to the CONTENTS of the dataset directly. Its still possible to receive new datasets and manipulate properties etc. +* Use ```--clear-refreservation``` to save space on your backup machine. +* Use ```--clear-mountpoint``` to prevent the target machine from mounting the backupped filesystem in the wrong place during a reboot. ## Restore example @@ -325,5 +339,3 @@ optional arguments: Full manual at: https://github.com/psy0rz/zfs_autobackup ``` - -