Merge branch 'more-docs' into 'master'

More docs

See merge request !24

docs/20_Features.md → docs/10_Features.md

@@ -18,6 +18,14 @@ Limited support:
 
 # Backup tools #
 
+## Restic ##
+
+* creates one initial full backup - and then never again.
+* encrypts data
+* deduplicates files
+* delete backups by rules to keep a count of hourly, daily, weekly, mothly, yearly backups
+* several backup targets (currently supported protocols: sftp:// https:// and file://)
+
 ## Duplicity ##
 
 * Incremental and full backups
@@ -26,14 +34,6 @@ Limited support:
 * delete old backups by a given time limit
 * several backup targets (currently supported protocols: scp:// rsync:// and file://)
 
-## Restic ##
-
-* creates an initial full backup - and then never again.
-* encrypts data
-* deduplicates files
-* delete backups by rules to keep a count of hourly, daily, weekly, mothly, yearly backups
-* several backup targets (currently supported protocols: sftp:// https:// and file://)
-
 # Limit simoultanous backups #
 
 As an optional feature you can control the count simultanous written backups.

docs/20_Installation.md

+
+# Installation #
+
+- Uncompress / clone the client to a local directory
+- go to jobs directory to copy the *.job.dist files to *.job
+- configure *.job files
+- manual test run
+- create a cronjob
+
+## Uncompress client ##
+
+To put all files into a directory i.e.
+
+    /opt/imlbackup/client
+
+then use the **root** user and follow these steps:
+
+```
+# Create the directory level above
+mdir -p /opt/imlbackup/
+
+# download
+cd /opt/imlbackup/
+wget https://git-repo.iml.unibe.ch/iml-open-source/iml-backup/-/archive/master/iml-backup-master.tar.gz
+
+# extract
+tar -xzf iml-backup-master.tar.gz
+mv iml-backup-master client
+
+# remove downloaded file
+rm -f iml-backup-master.tar.gz
+
+# to set pwd to /opt/imlbackup/client:
+cd client
+```

docs/30_Configuration/10_Database.md

+
+# Basic settings #
+
+There are 2 defaults:
+
+```
+dir-localdumps = /var/iml-backup
+keep-days = 7
+```
+
+## dir-localdumps ##
+
+{string}
+
+The target directory for local dumps. It is used by 
+
+* the database dump scripts
+* the transfer script to store the client backups
+* the restore script
+
+Below that one a directory for the service will be generated; inside that one the database dumbs with scheme name and timestamp, i.e.
+
+    /var/iml-backup/mysql/mydatabase__20190827-2300.sql.gz
+
+## keep-days ##
+
+{integer}
+
+The number of days how long to keep dumps locally.
+
+Remark:
+To make a database restore its dump must be located at this directory. To restore an older database you need to restore the dump from duplicity first.
+
+If you have local Mysql daemon or Pgsql you can test it by starting 
+
+```
+# dump all databases
+sudo ./localdump.sh
+```
+
+
+```
+# show written files
+find /var/iml-backup
+```
+

docs/30_Configuration/10_backup.job.md

+# dist file #
+
+```
+# ----------------------------------------------------------------------
+#
+# jobfile backup.job for scheduling
+#
+# ----------------------------------------------------------------------
+#
+# SYNTAX: 
+# [variable] = [value]
+#
+# - variable must start in first column
+# - char "=" must be surrounded by space
+# - value - any string; no " needed
+#
+# ----------------------------------------------------------------------
+
+# type = inc
+type = auto
+
+lang = en_us
+
+# ----------------------------------------------------------------------
+# scheduling for incremental backup and full backup
+# for inc and full you can set
+#   DOM:06,22        - days of month
+#   DOW:Mon,Fri      - weekdays
+#   WDM:1st Fri      - nth weekday in month
+# ----------------------------------------------------------------------
+
+inc = DOW:Mon,Tue,Wed,Thu,Fri,Sat,Sun
+
+# full backups for type = inc
+full = WDM:3rd Fri
+
+# full backups for type = auto
+# auto = <time> i.e. 1M 
+auto = 1M
+
+# --- when to start every day?
+
+# incremental jobs
+#   time HHMM ... multiple values with separated with "," and sorted
+#   10:00,12:00,14:00,16:00,18:00
+start-time-inc = 20:00
+start-time-full = 20:00
+
+
+# ----------------------------------------------------------------------
+# local dumps; each service has its own subdir there
+# this entry is mapped to BACKUP_TARGETDIR in "localdump.sh"
+# ----------------------------------------------------------------------
+dir-localdumps = /var/localdumps/backup
+keep-days = 7
+
+# archive databases (to keep deleted schemes or databases that 
+# are not backupped anymore; couchdb2 feature)
+dir-dbarchive = /var/localdumps/archive
+
+# ----------------------------------------------------------------------
+```
+
+# Description #
+
+## auto ##
+
+Define when to make full backups for `type = auto`. It starts incremental backups
+only as long the last full backup is not older than the given range.
+
+It is used for Duplicity only and forces the parameter `--full-if-older-than [value]`.
+
+Values are a number followed by a single letter for the time:
+s, m, h, D, W, M, or Y (indicating seconds, minutes, hours, days, weeks, months, or years respectively)
+
+`auto = 1M`
+
+## dir-dbarchive ##
+
+Target dir for database archives (to keep deleted schemes or databases that are not backupped anymore; couchdb2 feature)
+
+`dir-dbarchive = /var/localdumps/archive`
+
+## dir-localdumps ##
+
+Target dir for database backups of all types. 
+Below that directory a subdir for the database type will be created (i.e. mysql or pgsql).
+
+`dir-localdumps = /var/localdumps/backup`
+
+see also **keep-days**
+
+## keep-days ##
+
+How many days to keep database dumps locally in `dir-localdumps = ...`
+
+`keep-days = 7`
+
+see also **dir-localdumps**
+
+## full ##
+
+Scheduling days for full backup
+For inc and full you can set
+
+* day of month: DOM
+* weekday: DOW
+* nth weekday in a month: WDM
+
+It is followes by a `:` and a single value - or multiple values delimited by `,`.
+
+* Day of month is always a 2 digit value (01..31).
+* Keywords for weekdays are Mon, Tue, Wed, Thu, Fri, Sat, Sun.
+* Valid numbers of day are 1st, 2nd, 3rd, 4th, 5th followes by space and a weekday
+
+Examples:
+
+* DOM:06,22        - days of month
+* DOW:Mon,Fri      - weekdays
+* WDM:1st Fri      - nth weekday in month
+
+`full = WDM:3rd Fri`
+
+See also: **inc**, **start-time-full**
+
+## inc ##
+
+Scheduling days for incremental backup.
+For valid values see description for **full**
+
+`inc = DOW:Mon,Tue,Wed,Thu,Fri,Sat,Sun`
+
+See also: **full**, **start-time-inc**
+
+## lang ##
+
+Language of the shell. Do not change to keep documented keywords for date and time.
+
+## start-time-full ##
+
+Time when to start an incrmental backup. This value will be handled
+if a day matches **full** only.
+
+Values are HHMM ... multiple values with separated with `,` and must be sorted.
+
+If a full time matches an incremental time then full has priority.
+
+`start-time-full= 22:00`
+
+see also **full**
+
+## start-time-inc ##
+
+Time when to start an incrmental backup. This value will be handled
+if a day matches **inc** only.
+
+Values are HHMM ... multiple values with separated with `,` and must be sorted
+
+If a full time matches an incremental time then full has priority.
+
+`start-time-inc = 10:00,12:00,14:00,16:00,18:00`
+
+see also **inc**
+
+## type ##
+
+Type of backup.
+
+Restic:
+
+* set to "auto"
+
+Duplicity:
+
+* "inc" - make full and incremental backups defined times. You need more values:
+  * full = WDM:3rd Fri
+  * inc = DOW:Mon,Tue,Wed,Thu,Fri,Sat,Sun
+  * start-time-full = 20:00
+
+* "auto" - starts incremental backups as long last full backup is not older value in
+  * auto = 1M
+
+`type = auto`
+

docs/30_Configuration/_index.md

+The next pages describe the configuration.
+
+You can create a config by copying the delivered .dist file in the
+folder `./jobs/`.
+
+Example:
+
+```bash
+cd jobs
+cp backup.job.dist backup.job
+```

docs/10_Welcome.md → docs/_index.md

@@ -7,7 +7,7 @@ Runs on Linux: CentOS, Debian, Manjaro, Ubuntu.
 * Free software. GNU GPL 3.0
 * Source: <https://git-repo.iml.unibe.ch/iml-open-source/iml-backup/>
 * Restic: <https://restic.net/>
-* Duplicity: <http://duplicity.nongnu.org/>
+* Duplicity: <https://duplicity.gitlab.io/duplicity-web/>
 
 # Why #
 

docs/config.json

 {
     "title": "IML Backup",
     "author": "Axel Hahn",
+    "tagline": "Automatic decentral server backups.",
     "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/appmonitor/tree/master/docs",

jobs/backup.job.dist

@@ -47,7 +47,6 @@ start-time-full = 20:00
 # ----------------------------------------------------------------------
 # local dumps; each service has its own subdir there
 # this entry is mapped to BACKUP_TARGETDIR in "localdump.sh"
-# dir is set by puppet
 # ----------------------------------------------------------------------
 dir-localdumps = /var/localdumps/backup
 keep-days = 7