docs: initial commit

docs/content/configuration/_index.md

@@ -0,0 +1,6 @@
++++
+title = "Configuration"
+alwaysopen = true
++++
+
+{{% children description="true" %}}

docs/content/configuration/example_pull_backup.md

@@ -0,0 +1,9 @@
++++
+title = "Example: Pull Backup"
+description = "Example configuration for a typical pull-backup scenario, e.g. server to server"
++++
+
+Example configuration for a typical pull-backup scenario, e.g. server to server
+
+{{% alert theme="warning"%}}TBD{{% /alert %}}
+

docs/content/configuration/example_push_backup.md

@@ -0,0 +1,8 @@
++++
+title = "Example: Push Backup"
+description = "Example configuration for a typical push-backup scenario, e.g. laptop to NAS"
++++
+
+Example configuration for a typical push-backup scenario, e.g. laptop to NAS
+
+{{% alert theme="warning"%}}TBD{{% /alert %}}

docs/content/configuration/overview.md

@@ -0,0 +1,144 @@
++++
+title = "Overview"
+weight = 100
+description = "Configuration format, SSH authentication, etc."
++++
+
+{{% panel header="Recommendation" %}}
+Keep the [sample configuration file](https://github.com/zrepl/zrepl/blob/master/cmd/sampleconf/zrepl.yml) open on the side while reading this document!
+{{% / panel %}}
+
+All configuration is managed in a single YAML file.<br />
+It is structured by sections roughly corresponding to `zrepl` subcommands:
+
+```yaml
+# REPLICATION
+# Remote zrepl instances where pull and push jobs connect to
+remotes: 
+  name_of_remote: #...
+# Push jobs (replication from local to remote)
+pushs: 
+  name_of_push_job: #...
+  name_of_other_push_job: #...
+# pull jobs (replication from remote to local & local to local)
+pulls: 
+  name_of_pull_job: #...
+# mapping incoming pushs to local datasets
+sinks: 
+  client_identity: #...
+# access control for remote pull jobs
+pull_acls: 
+  client_identity: #...
+
+# SNAPSHOT MANAGEMENT
+# Automatic snapshotting of filesystems
+autosnap:
+  name_of_autosnap_job: #... 
+# Automatic pruning of snapshots based on creation date
+prune:
+  name_of_prune_job: #... 
+```
+
+When using `zrepl(8)`, a *subcommand* is passed the *job name* as a positional argument:
+
+```yaml
+autosnap: # subcommand
+  db: # job name
+    prefix: zrepl_ 
+    interval: 10m
+    dataset_filter: {
+      "tank/db<": ok
+    }
+```
+```bash
+$ zrepl autosnap --config zrepl.yml db
+```
+
+Run `zrepl --help` for a list of subcommands and options.
+
+## Mapping & Filter Syntax
+
+For various job types, a filesystem `mapping` or `filter` needs to be
+specified. Both have in common that they return a result for a given filesystem
+path (in the ZFS filesystem hierarchy).
+
+A mapping returns a *target filesystem*, a filter returns a *filter result*.
+The matching syntax & rules are the same for mappings and filters.
+
+#### Matching Rules
+
+Given a mapping / filter with a list of patterns and results, which result depends on the following rules:
+
+* More specific path patterns win over less specific ones
+* Direct mappings win over *subtree wildcards* (`<` at end of pattern)
+
+{{% panel %}}
+The **subtree wildcard** `<` means "*the dataset left of `<` and all its children*".
+{{% / panel %}}
+
+##### Example
+
+```
+# Rule number and its pattern
+1: tank<
+2: tank/foo/bar
+3: tank/foo<
+
+# Which rule applies to given path?
+tank/foo/bar/loo => 3
+tank/bar         => 1
+tank/foo/bar     => 2
+zroot            => NO MATCH
+tank/var/log     => 1
+```
+
+#### Mappings
+
+The example below shows a pull job that would pull remote datasets to the given local paths.<br />
+If there exists no mapping (`NO MATCH`), the filesystem will not be pulled.
+
+```yaml
+pull:
+  app01.example.com: # client identity
+    from: app01.example.com
+    mapping: { 
+      "tank/var/db<":    "zroot/backups/app01/tank/var/db",
+      "tank/var/www<":   "zroot/backups/app01/tank/var/www",
+      "tank/var/log":    "zroot/logbackup/app01",
+    }
+```
+
+```
+tank/var/db`          => zroot/backups/app01/tank/var/db
+tank/var/db/a/child   => zroot/backups/app01/tank/var/db/a/child
+...
+tank/var/www          => zroot/backups/app01/tank/var/www
+tank/var/www/a/child  => zroot/backups/app01/tank/var/www/a/child
+...
+tank/var/log          => zroot/logbackup/app01
+tank/var/log/foo      => NOT MAPPED
+```
+
+#### Filters
+
+Valid filter results: `ok` or `omit`.
+
+The example below shows a pull ACL that allows access to the user homes but not
+to the rest of the system's datasets.
+
+```
+# Example for filter syntax
+pull_acls:
+  backups.example.com: # client identity
+    filter: {
+      "<":              omit,
+      "tank/usr/home<": ok,
+    }
+```
+
+## Next up
+
+* [Automating snapshot creation & pruning]({{< ref "configuration/snapshots.md" >}})
+
+* [Replicating filesystems]({{< ref "configuration/replication.md" >}})
+

docs/content/configuration/replication.md

@@ -0,0 +1,40 @@
++++
+title = "Filesystem Replication"
+description = "Replicating filesystems with existing bookmarks & snapshots"
+weight = 300
++++
+
+{{% alert theme="warning"%}}Under Construction{{% /alert %}}
+
+### Remotes
+
+The `remotes` section specifies remote `zrepl` instances from which to pull from / push backups to:
+
+```yaml
+remotes:
+  offsite_backups:
+    transport:
+      ssh:
+        host: 192.168.122.6
+        user: root
+        port: 22
+        identity_file: /etc/zrepl/identities/offsite_backups
+```
+
+#### SSH Transport
+
+The SSH transport connects to the remote server using the SSH binary in
+`$PATH` and the parameters specified in the `zrepl` config file.
+
+However, instead of a traditional interactive SSH session, `zrepl` expects
+another instance of `zrepl` on the other side of the connection; You may be
+familiar with this concept from [git shell](https://git-scm.com/docs/git-shell)
+or [Borg Backup](https://borgbackup.readthedocs.io/en/stable/deployment.html).
+
+Check the examples for instructions on how to set this up on your machines! 
+
+{{% panel %}}
+The environment variables of the underlying SSH process are cleared. `$SSH_AUTH_SOCK` will not be available. We suggest creating a separate, unencrypted SSH key.
+{{% / panel %}}
+
+

docs/content/configuration/snapshots.md

@@ -0,0 +1,7 @@
++++
+title = "Snapshot Management"
+description = "Automated snapshot creation & pruning"
+weight = 200
++++
+
+{{% alert theme="warning"%}}TBD{{% /alert %}}