From 8ade82838d1bf6a86a92d1db9a595a1629c56fa5 Mon Sep 17 00:00:00 2001
From: "Hahn Axel (hahn)" <axel.hahn@iml.unibe.ch>
Date: Tue, 20 Sep 2022 12:07:24 +0200
Subject: [PATCH] update docs
---
docs/10_Installation.md | 34 ++++++++
docs/20_Config.md | 44 ++++++++++
docs/30_Scripts.md | 125 ++++++++++++++++++++++++++++
docs/_index.md | 13 +++
docs/config.json | 25 ++++++
docs/style.css | 176 ++++++++++++++++++++++++++++++++++++++++
readme.md | 13 +++
7 files changed, 430 insertions(+)
create mode 100644 docs/10_Installation.md
create mode 100644 docs/20_Config.md
create mode 100644 docs/30_Scripts.md
create mode 100644 docs/_index.md
create mode 100644 docs/config.json
create mode 100644 docs/style.css
create mode 100644 readme.md
diff --git a/docs/10_Installation.md b/docs/10_Installation.md
new file mode 100644
index 0000000..ba3c73e
--- /dev/null
+++ b/docs/10_Installation.md
@@ -0,0 +1,34 @@
+# Backup target host
+
+Setup a backup target host.
+
+* define a working dir, eg. `/opt/imlbackup/server` - only some smaller logfiles will be generated there
+* get sources as root
+ * extract the files in the repo <https://git-repo.iml.unibe.ch/iml-open-source/iml-backup-server> OR
+ * use git clone: \
+ `cd /var` \
+ `git clone https://git-repo.iml.unibe.ch/iml-open-source/iml-backup-server.git imlbackup`
+* add a non privileged user with a login shell; e.g "imlbackup". Set the home directory to `/opt/imlbackup/server`
+* Set owner on working dir: `chown -R imlbackup /opt/imlbackup/server`
+* Set permissions: `chmod 0700 imlbackup /opt/imlbackup/server`
+* create a ssh keypair for the backup user using `ssh-keygen`
+* It needs diskspace capacity for all your systems you want to backup or you mount a storage
+* define an backup endpoint, eg. `/netshare/backup/` and set the owner to the backup user:
+ * `mkdir /netshare/backup/`
+ * `chown imlbackup: /netshare/backup/`
+ * `chmod 0700 /netshare/backup/`
+
+# Prepare backup client
+
+TODO
+
+* Put the ssh private key to all your devices you want to backup into `[installdir]/keys/imlbackup@targethost`
+* Setup SSH connection for restic
+ * Host: backup-host
+ * User: imlbackup
+ * key: [installdir]/keys/imlbackup@targethost
+ * target dir: /netshare/backup/
+ * enable register functionality: storage_helper.sh
+
+Test: as root
+`ssh -i [installdir]/keys/imlbackup@targethost imlbackup@backup-host`
diff --git a/docs/20_Config.md b/docs/20_Config.md
new file mode 100644
index 0000000..df6e428
--- /dev/null
+++ b/docs/20_Config.md
@@ -0,0 +1,44 @@
+# Config
+
+copy the .dist file to `inc_config.sh`.
+
+```shell
+# ======================================================================
+#
+# IML BACKUP STORAGE HELPER :: CONFIG
+#
+# ======================================================================
+
+ # max count of simultanous connections; 0 is unlimited
+ typeset -i iMaxConnections=10
+ typeset -i iConnections
+ sSelfdir="$( dirname $0 )"
+
+ # directory with backup data
+ # sublevel 1 is a name of backup tool
+ # sublevel 2 is a fqdn of a backed up server
+ # i.e. /netshare/restic-backup/server.example.com
+
+ sBackupBasedir="/netshare"
+ # where to store current connections
+ # sConncectionDir="${sBackupBasedir}/_active"
+ sConncectionDir="${sSelfdir}/_active_connections"
+
+ # where to store last backup status
+ sStatusDir="${sSelfdir}/_last_backup"
+
+ # log
+ sLogdir="${sSelfdir}/log"
+ sLogfile="$sLogdir/connections.log"
+
+# ----------------------------------------------------------------------
+```
+
+You MUST verify:
+
+* `BackupBasedir="/netshare"` - the target dir for backups
+
+You optionally CAN change
+
+* `typeset -i iMaxConnections=10` - the count of allowed parrallel backup connections (backup clients will wait until they get a free slot)
+* `sLogdir="${sSelfdir}/log"` - to write sone small logs somewhere else
\ No newline at end of file
diff --git a/docs/30_Scripts.md b/docs/30_Scripts.md
new file mode 100644
index 0000000..da5497b
--- /dev/null
+++ b/docs/30_Scripts.md
@@ -0,0 +1,125 @@
+# storage_helper.sh
+
+The script should be alwys started with the non privileged user (imlbackup).
+
+Without a parameter you get a help:
+
+```txt
+imlbackup@backup-host:~$ ./storage_helper.sh
+
+---------- :: STORAGE :: storage-connector :: ----------
+
+SYNTAX:
+storage_helper.sh [function]
+
+ backupstatus
+ show all servers and their backup times
+
+ register [hostname]
+ add a slot for a backup client
+
+ unregister [hostname] [statuscode]
+ remove slot for a backup client.
+ The statuscode is an integer of the return code.
+
+ setactive
+ Reactivate an inctave backup repo.
+
+ setinactive
+ Mark a backup repo as inactive.
+ This prevents errors of missing backup data
+ if a host is obsolete and was shut down.
+
+ status
+ show current reserved slots
+
+ usage [full|[filter to hostname]] - DEPRECATED
+ show used diskspace
+ you can set a string to show additionally details if these hosts
+ if you add "full" then details of all hosts will be shown
+```
+
+## What backup clients do
+
+Before a backup client send its data it wants to register.
+`./storage_helper.sh register [hostname]`
+
+The exitcode is 0 if it got a free slot. And non-zero if all slots are in use (see iMaxConnections in config). The backup client will wait a random time until it gets a free slot to write its data.
+
+If the backup is finished it sends
+`./storage_helper.sh unregister [hostname]`
+
+## Admin tasks
+
+### See current activity
+
+```txt
+$ ./storage_helper.sh status
+
+---------- :: STORAGE :: storage-connector :: ----------
+
+STATUS: 0 existing connection(s). Allowed maximum is 10.
+
+```
+
+### Backup status
+
+You get a table of all servers that sent backup data.
+There are listed
+
+* last backup with start time, end time, duration, existcode
+* age of the last backup (to see if a system does not send data anymore)
+* size of backup data
+* Each line per server is colored depending on backup status or time of last sent data
+
+```txt
+$ ./storage_helper.sh backupstatus
+
+---------- :: STORAGE :: storage-connector :: ----------
+
+STATUS: 0 existing connection(s). Allowed maximum is 10.
+
+This table shows the time and duration [s] of the last backup for each server.
+
+ server | start | end | duration | rc | age [h] | size
+-----------------------------------------------------------------------------------------------------------------------------
+. srv1.example.com | 2022-09-19 23:04:14 | 2022-09-19 23:17:52 | 818 | 0 | 12 | 951G /netshare/restic-backup/srv1.example.com
+. srv2.example.com | 2022-09-19 23:03:06 | 2022-09-19 23:18:28 | 922 | 0 | 12 | 955G /netshare/restic-backup/srv2.example.com
+...
+
+Legend
+. OK | ? not started | R running | D disabled | E error
+
+total : 26 servers
+errors: 0
+
+rc=0
+```
+
+### deactivate a backup folder
+
+If you delete a host but must keep its backup data then you can set it inactive. Then you don't get an error because of missing incoming data.
+
+
+To disable a backup target:
+
+```txt
+$ ./storage_helper.sh setinactive
+
+---------- :: STORAGE :: storage-connector :: ----------
+
+--- list of backup repositories
+/netshare/restic-backup/srv1.example.com (active)
+/netshare/restic-backup/srv1.example.com (active)
+...
+Repo to deactivate >
+```
+
+Enter the full path here, eg. `/netshare/restic-backup/srv1.example.com` and Return.
+Then comes an optional input for a hint - that is just for you and your team. Leave a message if the host is deprecated, the application was moved etc.
+
+In the backup status the deactivated target is listed with D = Disabled and is gray.
+
+BTW: the opposite way is possible to:
+
+`./storage_helper.sh setactive`
diff --git a/docs/_index.md b/docs/_index.md
new file mode 100644
index 0000000..bfe1e91
--- /dev/null
+++ b/docs/_index.md
@@ -0,0 +1,13 @@
+# IML Backup server
+
+Bash scripts of an SSH target for IML Backup clients (those use Restic).
+
+Runs on Linux.
+
+📄 Source: https://git-repo.iml.unibe.ch/iml-open-source/iml-backup-server/ \
+📜 License: GNU GPL 3.0 \
+📗 Docs: see docs folder or online https://os-docs.iml.unibe.ch/iml-backup-server/
+
+Related projects:
+
+* IML backup client: https://os-docs.iml.unibe.ch/iml-backup/
\ No newline at end of file
diff --git a/docs/config.json b/docs/config.json
new file mode 100644
index 0000000..7e15cc9
--- /dev/null
+++ b/docs/config.json
@@ -0,0 +1,25 @@
+{
+ "title": "IML Backup server",
+ "author": "Axel Hahn",
+ "tagline": "SSH Target for IML Backup clients",
+ "ignore": {
+ "files": ["30_PHP-client/Plugins/Checks/_skeleton.md"],
+ "folders": ["99_Not_Ready"]
+ },
+ "html": {
+ "auto_toc": true,
+ "auto_landing": false,
+ "date_modified": false,
+ "jump_buttons": true,
+ "edit_on_github_": "iml-it/__PROJECT__/tree/master/docs",
+ "edit_on_": {
+ "name": "Gitlab",
+ "basepath": "https://git-repo.iml.unibe.ch/iml-open-source/iml-backup-server/tree/master/docs"
+ },
+ "links": {
+ "Git Repo": "https://git-repo.iml.unibe.ch/iml-open-source/iml-backup-server"
+ },
+ "theme": "daux-blue",
+ "search": true
+ }
+}
\ No newline at end of file
diff --git a/docs/style.css b/docs/style.css
new file mode 100644
index 0000000..909562c
--- /dev/null
+++ b/docs/style.css
@@ -0,0 +1,176 @@
+/*
+
+ patch css elements of daux.io blue theme
+ version 2022-05-13
+
+*/
+
+
+/* ---------- vars ---------- */
+
+:root{
+
+ /* background colors */
+ --bg:none;
+ --bg-body: #fff;
+ --bg-navlinkactive:#f4f4f4;
+ --bg-navlinkactive: linear-gradient(-90deg,rgba(0,0,0,0), rgba(40,60,80,0.05) 30%);
+ --bg-pre:#f8f8f8;
+ --bg-toc: #fff;
+
+ /* foreground colors */
+ --color: #234;
+ --navlinkactive:#f33;
+ --title: #aaa;
+
+ --link:#12a;
+ --toclink:rgba(40,60,80,0.8);
+
+ --h1: rgba(40,60,80,0.8);
+ --h1-bottom: 1px solid rgba(40,60,80,0.1);
+ --h2: #468;
+ --h3: #579;
+
+}
+
+/* ---------- tags ---------- */
+
+a.Brand::before {
+ background: rgb(255,0,51);
+ color: #fff;
+ font-family: arial;
+ font-weight: bold;
+ padding: 0.5em 0.3em;
+ content: 'IML';
+ margin-right: 0.4em;
+}
+
+body, *{color: var(--color);}
+body{background: var(--bg-body);}
+
+
+a{color: var(--link);}
+a:hover{opacity: 0.7;}
+
+h1>a{ color:var(--title);}
+_h1:nth-child(1){position: fixed; background: var(--bg); box-shadow: 0 0 1em #ccc; padding: 0 1em}
+h1:nth-child(1)>a{ color:var(--navlinkactive); }
+
+.s-content h1{color: var(--h1); font-size: 200%; font-weight:bold; margin-top: 2em; border-bottom: var(--h1-bottom);}
+.s-content h2{color: var(--h2); font-size: 160%; }
+.s-content h3{color: var(--h3); font-size: 140%; }
+.s-content h4{margin: 0; font-size: 100%; text-align: center; background-color: rgba(0,0,0,0.05);padding: 0.3em;}
+
+.s-content pre{
+ background: var(--bg-pre);
+}
+
+/* ---------- classes ---------- */
+
+.required{color:#a42;}
+.optional{color:#888;}
+
+
+/* ----- top left */
+.Brand,
+.Columns__left {
+ background: var(--bg);
+ border-right: 0px solid #e7e7e9;
+ color: var(--color);
+}
+.Brand{font-size: 200%;
+ background_: linear-gradient(-10deg,#fff 50%, #ddd);
+ background: var(--bg);
+}
+.Columns__right__content {
+ background: var(--bg);
+}
+
+/* ----- Navi left */
+
+.Nav a:hover{
+ background: none;
+ color: var(--navlinkactive) !important;
+}
+
+.Nav__item--active {
+ border-right_: 0.3em solid var(--navlinkactive);
+}
+.Nav__item--active > a{
+ background: var(--bg-navlinkactive);
+ color: var(--navlinkactive);
+}
+.Nav .Nav .Nav__item--active a {
+ color: var(--navlinkactive);
+}
+.Nav .Nav .Nav__item a {
+ opacity: 1;
+}
+.Nav__item--open > a {
+ background-color: var(--bg);
+}
+
+.Nav a[href*="__Welcome"]{
+ background: url("/icons/house.png") no-repeat 10px 4px ;
+ padding-left: 40px;
+}
+.Nav a[href*="__How_does_it_work"]{
+ background: url("/icons/light-bulb.png") no-repeat 10px 4px ;
+ padding-left: 40px;
+}
+
+
+
+
+/* ---------- classes ---------- */
+
+/* FIX smaller fnt size in tables */
+.s-content table {
+ font-size: 1em;
+}
+
+
+/* TOC */
+@media(min-width:1700px){
+ .TableOfContentsContainer{
+ position: fixed;
+ right: 2em;
+ top: 1em;
+ }
+}
+
+.TableOfContentsContainer{
+ border-top-left-radius: 1em;
+ background-color: var(--bg-toc);
+ border-left: 2px solid rgba(0,0,0,0.05);
+ padding: 0em;
+}
+.TableOfContentsContainer__content {
+
+ border: none;
+ font-size: 0.5em;
+
+}
+ul.TableOfContents ul{
+ list-style-type: none;
+ padding-left: 1em;
+}
+.TableOfContentsContainer a{ color:var(--toclink);}
+
+.TableOfContentsContainer__content > .TableOfContents > li + li {
+ border-top: none;
+}
+.TableOfContentsContainer__content > .TableOfContents > li {
+ border-bottom: 1px dashed #ddd;
+}
+
+/* pager - prev .. next */
+.s-content{
+ margin-bottom: 6em;
+}
+.Pager{
+ border-top: 1px dashed #aaa; margin: 0; padding: 1em;
+}
+.Pager a{
+ color:var(--navlinkactive);
+}
diff --git a/readme.md b/readme.md
new file mode 100644
index 0000000..bfe1e91
--- /dev/null
+++ b/readme.md
@@ -0,0 +1,13 @@
+# IML Backup server
+
+Bash scripts of an SSH target for IML Backup clients (those use Restic).
+
+Runs on Linux.
+
+📄 Source: https://git-repo.iml.unibe.ch/iml-open-source/iml-backup-server/ \
+📜 License: GNU GPL 3.0 \
+📗 Docs: see docs folder or online https://os-docs.iml.unibe.ch/iml-backup-server/
+
+Related projects:
+
+* IML backup client: https://os-docs.iml.unibe.ch/iml-backup/
\ No newline at end of file
--
GitLab