From f65a87fb309d6ded21b2b42cbf18e1342a83a444 Mon Sep 17 00:00:00 2001
From: Marco Cetica <ceticamarco@gmail.com>
Date: Tue, 14 Mar 2023 16:23:53 +0100
Subject: [PATCH] Added manual page

---
 README.md   |  16 +--
 backup.sh.1 | 298 ++++++++++++++++++++++++++++++++++++++++++++++++++++
 man.md      | 206 ++++++++++++++++++++++++++++++++++++
 3 files changed, 512 insertions(+), 8 deletions(-)
 create mode 100644 backup.sh.1
 create mode 100644 man.md

diff --git a/README.md b/README.md
index 8c99325..520fa3d 100644
--- a/README.md
+++ b/README.md
@@ -11,7 +11,7 @@ Alternatively, you can install the script, the default sources file and the man
 $> sudo make install
 ```
 This will copy `backup.sh` into `/usr/local/bin/backup.sh`, `backup_sources.bk` into `/usr/local/etc/backup_sources.bk` and
-`backup.sh.1` into `/usr/local/share/man/man1`. To uninstall the program along with the sample _sources file_ and the manual page,
+`backup.sh.1` into `/usr/local/share/man/man1/backup.sh.1`. To uninstall the program along with the sample _sources file_ and the manual page,
 you can issue `sudo make uninstall`.
 
 At this point you still need to install the following dependencies:
@@ -31,7 +31,7 @@ options:
 -h|--help                       Show this helper.
 ```
 
-As you can see, `backup.sh` supports two options: **backup creation** and **archive extraction**, the former requires
+As you can see, `backup.sh` supports two options: **backup creation** and **backup extraction**, the former requires
 root permissions, while the latter does not. Let us see them in details.
 
 ### Backup creation
@@ -103,7 +103,7 @@ This will automatically run `backup.sh` every Saturday morning at 03:30 AM. In t
 key is stored in a local file(with fixed permissions) to avoid password leaking in crontab logs. You can also
 adopt this practice while using the `--extract` option to avoid password leaking in shell history.
 
-### Archive extraction
+### Backup extraction
 `backup.sh` can also extract the encrypted backup archive using the following syntax:
 
 ```sh
@@ -135,14 +135,14 @@ $> rsync -aPhrq --delete
 
 That is:
 
-- `-a`: **archive mode**, rsync copies files recursively while preserving as much metadata
+- `-a`: **archive mode**: rsync copies files recursively while preserving as much metadata
 as possible;  
 - `-P`: **progress/partial**, this allows rsync to resume interrupted transfers and to 
 shows progress information;  
-- `-h`: **human readable output**, rsync shows output numbers in a more readable way;  
-- `-r`: **recursive mode**: which forces rsync to copy directories and their content;  
-- `-q`: **quiet mode**: which reduces the amount of information rsync produces;  
-- `--delete`: **delete mode**: which forces rsync to delete any extraneous files at the
+- `-h`: **human readable output**: rsync shows output numbers in a more readable way;  
+- `-r`: **recursive mode**: forces rsync to copy directories and their content;  
+- `-q`: **quiet mode**: reduces the amount of information rsync produces;  
+- `--delete`: **delete mode**: forces rsync to delete any extraneous files at the
 destination dir.
 
 
diff --git a/backup.sh.1 b/backup.sh.1
new file mode 100644
index 0000000..d2e76fd
--- /dev/null
+++ b/backup.sh.1
@@ -0,0 +1,298 @@
+.\" Automatically generated by Pandoc 3.1
+.\"
+.\" Define V font for inline verbatim, using C font in formats
+.\" that render this, and otherwise B font.
+.ie "\f[CB]x\f[]"x" \{\
+. ftr V B
+. ftr VI BI
+. ftr VB B
+. ftr VBI BI
+.\}
+.el \{\
+. ftr V CR
+. ftr VI CI
+. ftr VB CB
+. ftr VBI CBI
+.\}
+.TH "backup.sh" "1" "March 14, 2023" "Marco Cetica" "General Commands Manual"
+.hy
+.SH NAME
+.PP
+\f[B]backup.sh\f[R] is a POSIX compliant, modular and lightweight backup
+utility to save and encrypt your files.
+.SH SYNOPSIS
+.IP
+.nf
+\f[C]
+Syntax: backup.sh [-b|-e|-h]
+options:
+-b|--backup  SOURCES DEST PASS  Backup folders from SOURCES file.
+-e|--extract ARCHIVE PASS       Extract ARCHIVE using PASS.
+-h|--help                       Show this helper.
+\f[R]
+.fi
+.SH DESCRIPTION
+.PP
+\f[B]backup.sh\f[R] is a POSIX compliant, modular and lightweight backup
+utility to save and encrypt your files.
+This tool is intended to be used on small scale UNIX environment such as
+VPS, small servers and workstations.
+\f[B]backup.sh\f[R] uses \f[I]rsync\f[R], \f[I]tar\f[R] and
+\f[I]openssl\f[R] to copy, compress and encrypt the backup.
+.SH OPTIONS
+.PP
+\f[B]backup.sh\f[R] supports two options: \f[I]backup creation\f[R] and
+\f[I]backup extraction\f[R].
+The former requires root permissions, while the latter does not.
+Let us see them in details:
+.SS Backup creation
+.PP
+To specify the directories to backup, \f[B]backup.sh\f[R] uses an
+associative array defined in a text file(called sources file) with the
+following syntax:
+.IP
+.nf
+\f[C]
+<LABEL>=<PATH>
+\f[R]
+.fi
+.PP
+Where \f[V]<LABEL>\f[R] is the name of the backup and \f[V]<PATH>\f[R]
+is its path.
+For example, if you want to back up \f[I]/etc/nginx\f[R] and
+\f[I]/etc/ssh\f[R], add the following entries to the sources file:
+.IP
+.nf
+\f[C]
+nginx=/etc/nginx/
+ssh=/etc/ssh/
+\f[R]
+.fi
+.PP
+\f[B]backup.sh\f[R] will create two folders inside the backup archive
+with the following syntax:
+.IP
+.nf
+\f[C]
+backup-<LABEL>-<YYYYMMDD>
+\f[R]
+.fi
+.PP
+In the previous example, this would be:
+.IP
+.nf
+\f[C]
+backup-nginx-<YYYYMMDD>
+backup-ssh-<YYYYMMDD>
+\f[R]
+.fi
+.PP
+You can add as many entries as you want, just be sure to use the proper
+syntax.
+In particular, the sources file, \f[I]should not\f[R] includes:
+.IP
+.nf
+\f[C]
+- Spaces between the label and the equal sign;  
+- Empty lines;  
+- Comments.  
+\f[R]
+.fi
+.PP
+You can find a sample sources file at \f[V]backup_sources.bk\f[R](or at
+\f[V]/usr/local/etc/backup_sources.bk\f[R]).
+.PP
+After having defined the sources file, you can invoke
+\f[B]backup.sh\f[R] using the following syntax:
+.IP
+.nf
+\f[C]
+$> sudo ./backup.sh --backup <SOURCES_FILE> <DEST> <ENCRYPTION_PASSWORD>
+\f[R]
+.fi
+.PP
+Where \f[V]<SOURCES_FILE>\f[R] is the \f[I]sources file\f[R],
+\f[V]<DEST>\f[R] is the absolute path of the output of the backup
+\f[I]without trailing slashes\f[R] and \f[V]<ENCRYPTION_PASSWORD>\f[R]
+is the password to encrypt the compressed archive.
+.PP
+In the previous example, this would be:
+.IP
+.nf
+\f[C]
+$> sudo ./backup.sh --backup sources.bk /home/john badpw1234
+\f[R]
+.fi
+.PP
+The backup utility will begin to copy the files defined in the sources
+file:
+.IP
+.nf
+\f[C]
+Copying nginx(1/2)
+Copying ssh(2/2)
+Compressing and encrypting backup...
+Elapsed time: 10 seconds.
+\f[R]
+.fi
+.PP
+After that, you will find the final backup archive in
+\f[V]/home/john/backup-<HOSTNAME>-<YYYMMDD>.tar.gz.enc\f[R].
+.PP
+You can also use \f[B]backup.sh\f[R] from a crontab rule:
+.IP
+.nf
+\f[C]
+$> sudo crontab -e
+30 03 * * 6 EKEY=$(cat /home/john/.ekey) /usr/local/bin/backup.sh -b /usr/local/etc/sources.bk /home/john $EKEY
+\f[R]
+.fi
+.PP
+This will automatically run \f[B]backup.sh\f[R] every Saturday morning
+at 03:30 AM.
+In the example above, the encryption key is stored in a local file(with
+fixed permissions) to avoid password leaking in crontab logs.
+You can also adopt this practice while using the \f[V]--extract\f[R]
+option to avoid password leaking in shell history.
+.SS Backup extraction
+.PP
+\f[B]backup.sh\f[R] can also extract the encrypted backup archive using
+the following syntax:
+.IP
+.nf
+\f[C]
+$> ./backup.sh --extract <ENCRYPTED_ARCHIVE> <ARCHIVE_PASSWORD>
+\f[R]
+.fi
+.PP
+Where \f[V]<ENCRYPTED_ARCHIVE>\f[R] is the encrypted backup and
+\f[V]<ARCHIVE_PASSWORD>\f[R] is the backup password.
+.PP
+For instance:
+.IP
+.nf
+\f[C]
+$> ./backup.sh --extract backup-<hostname>-<YYYMMDD>.tar.gz.enc badpw1234
+\f[R]
+.fi
+.PP
+This will create a new folder called \f[V]backup.sh.tmp\f[R] in your
+local directory.
+Be sure to rename any directory with that name to avoid collisions.
+From the previous example, you should have the following directories:
+.IP
+.nf
+\f[C]
+backup-nginx-<YYYYMMDD>
+backup-ssh-<YYYYMMDD>
+\f[R]
+.fi
+.SS How does backup.sh work?
+.PP
+\f[B]backup.sh\f[R] uses \f[I]rsync\f[R] to copy the files,
+\f[I]tar\f[R] to compress the backup and \f[I]openssl\f[R] to encrypt
+it.
+By default, rsync is being used with the following parameters:
+.IP
+.nf
+\f[C]
+$> rsync -aPhrq --delete
+\f[R]
+.fi
+.PP
+That is:
+.IP
+.nf
+\f[C]
+- a: archive mode: rsync copies files recursively while preserving as much metadata as possible;  
+- P: progress/partial: allows rsync to resume interrupted transfers and to shows progress information;  
+- h: human readable output, rsync shows output numbers in a more readable way;  
+- r: recursive mode: forces rsync to copy directories and their content;  
+- q: quiet mode: reduces the amount of information rsync produces;  
+- delete: delete mode: forces rsync to delete any extraneous files at the destination dir.
+\f[R]
+.fi
+.PP
+After that the backup folder is being encrypred using openssl.
+By default, it is used with the following parameters:
+.IP
+.nf
+\f[C]
+$> openssl enc -aes-256-cbc -md sha512 -pbkdf2 -iter 100000 -salt -k \[dq]$PASSWORD\[dq] > file.tar.gz.enc
+\f[R]
+.fi
+.PP
+This command encrypts the backup using the AES-256-CBC symmetric
+encryption algorithm with a 256bit key.
+Here is what each option means:
+.IP
+.nf
+\f[C]
+- enc: encrypt mode: tell openssl to use encryption functionality;  
+- aes-256-cbc: encryption algorithm: this option tells openssl which encryption algorithm to use;  
+- md sh512: hashing algorithm: this option tells openssl which hashing algorithm to use for key derivation,
+    i.e., converting the text-based password(\[ga]$PASSWORD\[ga]) into an encryption key;  
+- pbkdf2: key deriving algorithm: this option tells openssl which key deriving algorithm to use. In this case
+    we use the _password-based key derivation function 2_ algorithm;  
+- iter 100000: number of iterations: this options tells openssl the number of iteration to use for the key derivation
+    function;  
+- salt: enable salting: this option tells openssl to add a random salt to the key derivation process in order to 
+    avoid rainbow table based attacks.
+\f[R]
+.fi
+.SH EXAMPLES
+.PP
+Below there are some examples that demostrate \f[B]backup.sh\f[R]\[cq]s
+usage.
+.IP "1." 3
+Create a backup of \f[V]/etc/ssh\f[R], \f[V]/var/www\f[R] and
+\f[V]/var/log\f[R] inside the \f[V]/tmp\f[R] directory using a password
+stored in \f[V]/home/op1/.backup_pw\f[R]
+.PP
+The first thing to do is to define the source paths inside a
+\f[I]sources file\f[R]:
+.IP
+.nf
+\f[C]
+$> cat sources.bk
+ssh=/etc/ssh
+web_root=/var/www
+logs=/var/log
+\f[R]
+.fi
+.PP
+After that we can load our encryption key from the specified file inside
+a environment variable:
+.IP
+.nf
+\f[C]
+$> ENC_KEY=$(cat /home/op1/.backup_pw)
+\f[R]
+.fi
+.PP
+Finally, we can start the backup process with:
+.IP
+.nf
+\f[C]
+$> sudo backup.sh --backup sources.bk /tmp $ENC_KEY
+\f[R]
+.fi
+.IP "2." 3
+Extract the content of a backup made on 2023-03-14 with the password
+`Ax98f!'
+.PP
+To do this, we can simply issue the following command:
+.IP
+.nf
+\f[C]
+$> backup.sh --extract backup-af9a8e6bfe15-20230314.tar.gz.enc \[dq]Ax98f!\[dq]
+\f[R]
+.fi
+.SH AUTHORS
+.PP
+\f[B]backup.sh\f[R] was written by Marco Cetica on late 2018.
+.SH BUGS
+.PP
+Submit bug reports online at: <email@marcocetica.com> or open an issue
+on the issue tracker of the GitHub page of this project:
+https://github.com/ice-bit/backup.sh
diff --git a/man.md b/man.md
new file mode 100644
index 0000000..7ed8146
--- /dev/null
+++ b/man.md
@@ -0,0 +1,206 @@
+---
+title: backup.sh
+section: 1
+header: General Commands Manual
+footer: Marco Cetica
+date: March 14, 2023
+---
+
+# NAME
+**backup.sh** is a POSIX compliant, modular and lightweight backup utility to save and encrypt your files.
+
+# SYNOPSIS
+```
+Syntax: backup.sh [-b|-e|-h]
+options:
+-b|--backup  SOURCES DEST PASS  Backup folders from SOURCES file.
+-e|--extract ARCHIVE PASS       Extract ARCHIVE using PASS.
+-h|--help                       Show this helper.
+```
+
+# DESCRIPTION
+**backup.sh** is a POSIX compliant, modular and lightweight backup utility to save and encrypt your files. 
+This tool is intended to be used on small scale UNIX environment such as VPS, small servers and workstations. 
+**backup.sh** uses _rsync_, _tar_ and _openssl_ to copy, compress and encrypt the backup.
+
+# OPTIONS
+**backup.sh** supports two options: _backup creation_ and _backup extraction_.
+The former requires root permissions, while the latter does not. Let us see them in details:
+
+## Backup creation
+To specify the directories to backup, **backup.sh** uses an associative array defined in a text file(called sources file) 
+with the following syntax:
+
+```
+<LABEL>=<PATH>
+```
+
+Where `<LABEL>` is the name of the backup and `<PATH>` is its path. 
+For example, if you want to back up _/etc/nginx_ and _/etc/ssh_, add the following entries to the sources file:
+
+```
+nginx=/etc/nginx/
+ssh=/etc/ssh/
+```
+
+**backup.sh** will create two folders inside the backup archive with the following syntax:
+
+```
+backup-<LABEL>-<YYYYMMDD>
+```
+
+In the previous example, this would be:
+
+```
+backup-nginx-<YYYYMMDD>
+backup-ssh-<YYYYMMDD>
+```
+
+You can add as many entries as you want, just be sure to use the proper syntax. 
+In particular, the sources file, _should not_ includes:
+
+    - Spaces between the label and the equal sign;  
+    - Empty lines;  
+    - Comments.  
+
+You can find a sample sources file at `backup_sources.bk`(or at `/usr/local/etc/backup_sources.bk`).
+
+After having defined the sources file, you can invoke **backup.sh** using the following syntax:
+```
+$> sudo ./backup.sh --backup <SOURCES_FILE> <DEST> <ENCRYPTION_PASSWORD>
+```
+
+Where `<SOURCES_FILE>` is the _sources file_, `<DEST>` is the absolute path of the output of the backup _without trailing slashes_ 
+and `<ENCRYPTION_PASSWORD>` is the password to encrypt the compressed archive.
+
+In the previous example, this would be:
+
+```
+$> sudo ./backup.sh --backup sources.bk /home/john badpw1234
+```
+
+The backup utility will begin to copy the files defined in the sources file:
+
+```
+Copying nginx(1/2)
+Copying ssh(2/2)
+Compressing and encrypting backup...
+Elapsed time: 10 seconds.
+```
+
+After that, you will find the final backup archive in `/home/john/backup-<HOSTNAME>-<YYYMMDD>.tar.gz.enc`.
+
+You can also use **backup.sh** from a crontab rule:
+
+```
+$> sudo crontab -e
+30 03 * * 6 EKEY=$(cat /home/john/.ekey) /usr/local/bin/backup.sh -b /usr/local/etc/sources.bk /home/john $EKEY
+```
+
+This will automatically run **backup.sh** every Saturday morning at 03:30 AM. 
+In the example above, the encryption key is stored in a local file(with fixed permissions) to avoid password leaking in crontab logs. 
+You can also adopt this practice while using the `--extract` option to avoid password leaking in shell history.
+
+## Backup extraction
+**backup.sh** can also extract the encrypted backup archive using the following syntax:
+
+```
+$> ./backup.sh --extract <ENCRYPTED_ARCHIVE> <ARCHIVE_PASSWORD>
+```
+
+Where `<ENCRYPTED_ARCHIVE>` is the encrypted backup and `<ARCHIVE_PASSWORD>` is the backup password.
+
+For instance:
+```
+$> ./backup.sh --extract backup-<hostname>-<YYYMMDD>.tar.gz.enc badpw1234
+```
+
+This will create a new folder called `backup.sh.tmp` in your local directory. 
+Be sure to rename any directory with that name to avoid collisions. From the previous example, you should have the following directories:
+
+```
+backup-nginx-<YYYYMMDD>
+backup-ssh-<YYYYMMDD>
+```
+
+## How does backup.sh work?
+**backup.sh** uses _rsync_ to copy the files, _tar_ to compress the backup and _openssl_ to encrypt it. 
+By default, rsync is being used with the following parameters:
+
+```
+$> rsync -aPhrq --delete
+```
+
+That is:
+
+    - a: archive mode: rsync copies files recursively while preserving as much metadata as possible;  
+    - P: progress/partial: allows rsync to resume interrupted transfers and to shows progress information;  
+    - h: human readable output, rsync shows output numbers in a more readable way;  
+    - r: recursive mode: forces rsync to copy directories and their content;  
+    - q: quiet mode: reduces the amount of information rsync produces;  
+    - delete: delete mode: forces rsync to delete any extraneous files at the destination dir.
+
+
+After that the backup folder is being encrypred using openssl. By default, it is used with the following parameters:
+
+
+```
+$> openssl enc -aes-256-cbc -md sha512 -pbkdf2 -iter 100000 -salt -k "$PASSWORD" > file.tar.gz.enc
+```
+
+This command encrypts the backup using the AES-256-CBC symmetric encryption algorithm with a 256bit key. Here is what each option means:
+
+    - enc: encrypt mode: tell openssl to use encryption functionality;  
+    - aes-256-cbc: encryption algorithm: this option tells openssl which encryption algorithm to use;  
+    - md sh512: hashing algorithm: this option tells openssl which hashing algorithm to use for key derivation,
+        i.e., converting the text-based password(`$PASSWORD`) into an encryption key;  
+    - pbkdf2: key deriving algorithm: this option tells openssl which key deriving algorithm to use. In this case
+        we use the _password-based key derivation function 2_ algorithm;  
+    - iter 100000: number of iterations: this options tells openssl the number of iteration to use for the key derivation
+        function;  
+    - salt: enable salting: this option tells openssl to add a random salt to the key derivation process in order to 
+        avoid rainbow table based attacks.
+
+# EXAMPLES
+Below there are some examples that demostrate **backup.sh**'s usage.
+
+1. Create a backup of `/etc/ssh`, `/var/www` and `/var/log` inside the `/tmp` directory using a password
+stored in `/home/op1/.backup_pw`
+
+The first thing to do is to define the source paths inside a _sources file_:
+
+```
+$> cat sources.bk
+ssh=/etc/ssh
+web_root=/var/www
+logs=/var/log
+```
+
+After that we can load our encryption key from the specified file inside a environment variable:
+
+```
+$> ENC_KEY=$(cat /home/op1/.backup_pw)
+```
+
+Finally, we can start the backup process with:
+
+```
+$> sudo backup.sh --backup sources.bk /tmp $ENC_KEY
+```
+
+
+
+2. Extract the content of a backup made on 2023-03-14 with the password 'Ax98f!'
+
+To do this, we can simply issue the following command:
+
+```
+$> backup.sh --extract backup-af9a8e6bfe15-20230314.tar.gz.enc "Ax98f!"
+```
+
+# AUTHORS
+**backup.sh** was written by Marco Cetica on late 2018.
+
+# BUGS
+Submit bug reports online at: <email@marcocetica.com> or open an issue 
+on the issue tracker of the GitHub page of this project: https://github.com/ice-bit/backup.sh