From 3e2a7949820d0110f84962ed2ed7cfd76758e939 Mon Sep 17 00:00:00 2001
From: "Hahn Axel (hahn)" <axel.hahn@iml.unibe.ch>
Date: Wed, 26 Jan 2022 17:38:53 +0100
Subject: [PATCH] update docs
---
docs/20_Installation.md | 58 ++++++++++++++--
docs/30_Configuration/20_Filetransfer.md | 84 ++++++++++++++++++++++++
docs/config.json | 2 +-
3 files changed, 136 insertions(+), 8 deletions(-)
diff --git a/docs/20_Installation.md b/docs/20_Installation.md
index e631f8c..69dcc30 100644
--- a/docs/20_Installation.md
+++ b/docs/20_Installation.md
@@ -1,21 +1,23 @@
-
-# Installation #
+# Installation
- Uncompress / clone the client to a local directory
-- go to jobs directory to copy the *.job.dist files to *.job
+- create a backup target (once for all systems that write their backup there)
+- go to jobs directory to copy the *.job.dist files to*.job
- configure *.job files
- manual test run
- create a cronjob
-## Uncompress client ##
+## Uncompress client
To put all files into a directory i.e.
- /opt/imlbackup/client
+```text
+/opt/imlbackup/client
+```
then use the **root** user and follow these steps:
-```
+```shell
# Create the directory level above
mdir -p /opt/imlbackup/
@@ -30,6 +32,48 @@ mv iml-backup-master client
# remove downloaded file
rm -f iml-backup-master.tar.gz
-# to set pwd to /opt/imlbackup/client:
+# to set working directory to /opt/imlbackup/client:
cd client
```
+
+## Create backup target
+
+My scenario is a backup target within my company network.
+
+To store all backup data you need diskspace that is mounted on a server (=backup target server).
+Maybe you mount a volume of a Ceph cluster or mount an NFS share of a storage system.
+
+The size depends on the count of systems and how many backup sets you want to store.
+
+Restic and Duplicity support several backends.
+
+### Initialize server backup via SSH/ SFTP/ RSync
+
+The backup target server needs a running ssh service.
+
+- As root:
+ - create an unprivileged user "imlbackup".
+ - allow write permissions for "imlbackup" on /mnt/backupdata
+ - Test write permissions:
+
+```shell
+su - imlbackup
+touch /mnt/backupdata/hello && echo OK
+rm -f /mnt/backupdata/hello
+```
+
+* Create an SSH keypair for user "imlbackup"
+
+```
+ssh-keygen
+```
+
+Now it is time to test access from another system
+
+* copy the created private key (~imlbackup/.ssh/id_rsa) on backup target server to /opt/imlbackup/client/keys/imlbackup@backup-target.example.com
+* Open ssh shell with referencing that key
+
+```
+ssh -i keys/imlbackup@backup-target.example.com imlbackup@backup-target.example.com
+```
+
diff --git a/docs/30_Configuration/20_Filetransfer.md b/docs/30_Configuration/20_Filetransfer.md
index e69de29..e8b4b98 100644
--- a/docs/30_Configuration/20_Filetransfer.md
+++ b/docs/30_Configuration/20_Filetransfer.md
@@ -0,0 +1,84 @@
+The file transfer describes how local directories will be backed up
+
+* choose backup tool
+* where to write data (backup target)
+* incremental or full backup
+* how to delete backup data
+
+Details to the the given config entries you find in the description for
+[transfer.job](50_File_transfer.job.md).
+
+## Backup tool ##
+
+You can decide between Restic (Default) and Duplicity.
+
+`bin = ...`
+
+```text
+bin = restic
+type = auto
+```
+
+If you use Duplicity for servers it is suggested to run (daily) incremental
+backups and full backups on a specific day.
+
+```text
+bin = duplicity
+type = inc
+full = WDM:3rd Fri
+start-time-full = 23:0.
+```
+
+If you use Duplicity on a desktop client you maybe want to run incremental backups
+and a full backup if the last one is older than a wanted time.
+
+```text
+bin = duplicity
+type = auto
+auto = 1M
+```
+
+## Backup target ##
+
+The definition of a backup target depends on the used backup tool (restic|duplicity).
+You need a bit knowledge about these tools.
+
+We have tested the following targets
+
+* local directory/ mounted filesystem i.e. Samba share
+ * Restic: `/mnt/mounted_directory`
+ * Duplicity: `file:///mnt/mounted_directory`
+* ssh target (scp or rsync)
+ * Restic: `sftp:imlbackup@backup-target.example.com:/mnt/backupdata`
+ * Duplicity: `rsync://imlbackup@backup-target.example.com//mnt/backupdata`
+ * Duplicity: `scp://imlbackup@backup-target.example.com//mnt/backupdata`
+* https
+ * Restic: `rest:https://user:pass@backup-target.example.com:8000/user/`
+
+Set your value in `storage = ...`
+
+Example for Restic with SFTP transfer
+
+`storage = sftp:imlbackup@backup-target.example.com:/mnt/backupdata`
+
+## Local encryption ##
+
+Restic an Duplicity encrypt local data with a password before transferring them.
+
+Deploy a host specific password with an orchestration tool (Ansible, Puppet, ...)
+or on a manual installation keep a copy of it on a safe place. Without the password
+you cannot decrypt backup data after a filesystem crash.
+
+`passphrase = EnterYourSecretHere`
+
+## More options ##
+
+Automatic backup of samba shares - it works only if samba shares were detected.
+If no samba config is available it has no effect and shows no error.
+
+`sambashares = 1`
+
+When restoring data ... this is the path for restored files:
+
+`restore-path = /restore`
+
diff --git a/docs/config.json b/docs/config.json
index 4df2ac7..e71b253 100644
--- a/docs/config.json
+++ b/docs/config.json
@@ -1,7 +1,7 @@
{
"title": "IML Backup",
"author": "Axel Hahn",
- "tagline": "Automatic decentral linux backups.",
+ "tagline": "Automatic decentral backups.",
"ignore": {
"files": ["30_PHP-client/Plugins/Checks/_skeleton.md"],
"folders": ["99_Not_Ready"]
--
GitLab