Merge branch 'master' of github.com:psy0rz/zfs_autobackup.wiki

Home.md

@@ -6,7 +6,7 @@ Look at the [README.md](../blob/master/README.md) for the introduction.
 
 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.)
+zfs-autobackup may be installed on either the source machine or the target machine, installing it 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.
 
@@ -32,7 +32,7 @@ On older machines you might have to use easy_install:
 
 ### Using the sources
 
-If you dont want to install zfs-autobackup, or want to make some changes to the code, look at [Development](Development)
+If you don't want to install zfs-autobackup, or want to make some changes to the code, look at [Development](Development)
 
 ## Example
 
@@ -78,11 +78,27 @@ root@backup:~#
 ```
 This allows the backup machine to login to `pve01` as root without password.
 
+### Running without root
+
+In order to run zfs-autobackup without root permissions, you'll need to set a few ZFS permissions. The permissions required differ for receiving and sending. 
+
+On the machine you want to sync the dataset from, you'll need the send, hold, mount, snapshot, and destroy permissions. You can apply them like so:
+
+```console
+root@source:~# zfs allow -u localuser mount,send,hold,snapshot,destroy rpool
+```
+
+On the receiving side, you will need the compression, mountpoint, create, mount, receive, rollback and destroy permissions:
+
+```console
+root@target:~# zfs allow -u remoteuser compression,mountpoint,create,mount,receive,rollback,destroy tank/backups/rpool
+```
+
 ### Select filesystems to backup
 
 Next, we specify the filesystems we want to snapshot and replicate by assigning a unique group name to those filesystems.
 
-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.)
+It's 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.
 
@@ -183,15 +199,15 @@ Run the script on the backup machine and pull the data from the source machine s
 
 ### The results
 
-As you might notice, zfs-autobackup preserve the whole parent-path of the source.
+As you might notice, zfs-autobackup preserves the whole parent path of the source.
 
 So `rpool/data/vm100-disk-0` ends up as: `data/backup/pve01/rpool/data/vm-100-disk-0`
 
-Since its a backup, its usefull to preserve the original structure of the data like this.
+Since it's a backup, it's useful to preserve the original structure of the data like this.
 
 ### Stripping the path
 
-Since you might think this is ugly, there is the `--strip-path` option. However this can lead to collisions if you 2 source datasets result in the same target paths. Since version 3.1.2 zfs-autobackup will check for this and emit an error. 
+Since you might think this is ugly, there is the `--strip-path` option. However this can lead to collisions if two source datasets result in the same target paths. Since version 3.1.2 zfs-autobackup will check for this and emit an error.
 
 #### Making source and target paths look the same
 
@@ -200,7 +216,15 @@ If you want your source and target structure to look exactly the same, you have
 * Select the whole source-pool. In this case: `zfs set autobackup:offsite1=true rpool`
 * Use `--strip-path=1`
 * Specify target-pool as target-path. In this case: `data`
-* Use the `--force` option the first time to overwrite the existing target pool. (New in v3.1.2)
+* You may need to use `--force` option the first time to overwrite the existing target pool.  It is recommended you try with `--test` and without `--force` first (New in v3.1.2).
+
+This configuration will attempt replicate the entire pool from the source to the target. If you wish to exclude specific datasets from being replicated from the source pool, make sure that you do so by running commands such as:
+
+```console
+[root@pve01 ~]# zfs set autobackup:offsite1=false rpool/tmp
+```
+
+For each dataset you don't want to replicate BEFORE you run zfs-autobackup without `--test` for the first time.
 
 ### Pull or push?
 
@@ -217,9 +241,9 @@ Note that you can always change the ssh source and target parameters at a later
 
 #### Pull+push (zero trust)
 
-It also possible to use a 3rd server that pulls backups from the source and pushes the data to the target server via 1 stream. This way the source and target server wont have to be able to reach each other. If one server gets hacked, they cant access the other server.
+It also possible to use a third server that pulls backups from the source and pushes the data to the target server via one stream. This way the source and target server won't have to be able to reach each other. If one server gets hacked, they can't access the other server.
 
-To do this, you only have to install zfs-autobackup on a 3rd server and use both `--ssh-source` and `--ssh-target` to specify the other source and target servers.
+To do this, you only have to install zfs-autobackup on a third server and use both `--ssh-source` and `--ssh-target` to specify the other source and target servers.
 
 ## Local Usage
 
@@ -239,15 +263,13 @@ Now every time you run the command, zfs-autobackup will create a new snapshot an
 
 Older snapshots will eventually be deleted, depending on the `--keep-source` and `--keep-target` settings. The defaults are shown above under the 'Settings summary'. Look at [Thinner](Thinner) for more info.
 
-Once you've got the correct settings for your situation, you can just store the command in a cronjob.
+Once you've got the correct settings for your situation, you can just store the command in a cronjob or just create a script and run it manually when you need it.
-
-Or just create a script and run it manually when you need it.
 
 ## Monitoring
 
 Don't forget to monitor the results of your backups, look at [Monitoring](Monitoring) for more info.
 
-## Splitting up snapshot and backup job
+## Splitting up snapshot and backup jobs
 
 You might want to make snapshots during the week, and only transfer data during the weekends.
 
@@ -261,7 +283,7 @@ And this on weekend days:
 
 You can also create the snapshots in offline mode by using zfs-autobackup as a snapshot tool on the source side. This way the snapshots will always be created, even if the backup server is offline or unreachable.
 
-## Use as snapshot tool
+## Use as a snapshot tool
 
 You can use zfs-autobackup as a standalone snapshot tool.
 
@@ -273,6 +295,10 @@ Only use this if you don't want to make any backup at all, or if a target isn't
 
 If you have offline backups, checkout [[Common-snapshots-and-holds]]
 
+## Use alongside other snapshot tools
+
+zfs-autobackup can happily co-exist on the same system as other ZFS snapshot tools such as zfs-auto-snapshot if you are already using one. zfs-autobackup will not thin any manually created snapshots or those created by other snapshot tools, it will only thin its own shapshots if you use its `--keep-source` or `--keep-target` options.
+
 ## Specifying ssh port or options
 
 The correct way to do this is by creating ~/.ssh/config:
@@ -298,16 +324,16 @@ You CAN use the same backup name to transfer data to multiple targets. However i
 
 One way to do this is to make adjust the --keep-source option or to make sure the backups run at a close enough interval.
 
-However: To prevent confusion, and to be more flexible, I would advise to always use different and clear to distinguish names. e.g.: autobackup:offsite and autobackup:local for example.
+To prevent confusion, and to be more flexible, I would advise you to always use easily distinguished names e.g.: autobackup:offsite and autobackup:local, for example.
 
 ## Tips
 
 * Use ```--clear-mountpoint``` to prevent all kinds of problems. See [[Mounting]]
 * Use ```--debug``` if something goes wrong and you want to see the commands that are executed. This will also stop at the first error.
-* Use these only one time if needed: `--force` `--destroy-incompatible` `--rollback`. Dont add them to your script. Try to solve the underlying cause if you keep needing them.
+* Use these only one time if needed: `--force` `--destroy-incompatible` `--rollback`. Don't add them to your script. Try to solve the underlying cause if you keep needing them.
-* 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.
+* 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. It's still possible to receive new datasets and manipulate properties etc.
 * Use ```--clear-refreservation``` to save space on your backup machine.
-* zfs-autobackup uses holds by default, so you might get "dataset busy" if you try to destroy a snapshot. (check zfs holds --help)
+* zfs-autobackup uses holds by default, so you might get "dataset busy" if you try to destroy a snapshot. (check zfs holds --help or see [here.](https://github.com/psy0rz/zfs_autobackup/wiki/Problems#dataset-is-busy))
 
 ## Restore example