From 8d0ddfee09b36ff28380f8302f512871f33e05af Mon Sep 17 00:00:00 2001
From: Marco Cetica <ceticamarco@gmail.com>
Date: Mon, 13 Mar 2023 17:11:32 +0100
Subject: [PATCH] Added some documentation and 'backup_sources.bk'

---
 README.md         | 128 ++++++++++++++++++++++++++++++++++++++++++++++
 backup.sh         |  13 ++---
 backup_sources.bk |   4 ++
 3 files changed, 139 insertions(+), 6 deletions(-)
 create mode 100644 README.md
 create mode 100644 backup_sources.bk

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..19e62b1
--- /dev/null
+++ b/README.md
@@ -0,0 +1,128 @@
+# backup.sh
+`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](https://linux.die.net/man/1/rsync), [tar](https://linux.die.net/man/1/tar)
+and [openssl](https://linux.die.net/man/1/openssl) to copy, compress and encrypt the backup. 
+
+## Installation
+`backup.sh` consists in a single source file, to install it you can copy the script wherever you want.
+Alternatively, you can install the script, the default sources file and the man file using the following command:
+```sh
+$> 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`.
+
+At this point you still need to install the dependencies:
+- `rsync`
+- `tar`
+- `openssl`
+
+## Usage
+To show the available options, you can run `backup.sh --help`, which will print out the following message:
+```text
+backup.sh - POSIX compliant, modular and lightweight backup utility.
+
+Syntax: ./backup.sh [-b|-e|-h]
+options:
+-b|--backup  SOURCES USER PASS  Backup folders from SOURCES file.
+-e|--extract ARCHIVE PASS       Extract ARCHIVE using PASS.
+-h|--help                       Show this helper.
+```
+
+As you can see, `backup.sh` supports two options: **backup creation** and **archive 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 called
+defined in a text file(called _sources file_) with the following syntax:
+
+```text
+<LABEL>=<PATH>
+```
+
+Where `<LABEL>` is the name of the backup and `<PATH>` is its path. For example,
+if you want you back up `/etc/nginx` and `/etc/ssh`, add the following entries to the _sources file_:
+
+```text
+nginx=/etc/nginx/
+ssh=/etc/ssh/
+```
+
+`backup.sh` will create two folders inside the backup archive with the following syntax:
+```text
+backup-<LABEL>-<YYYYMMDD>
+```
+
+In the previous example, this would be:
+```text
+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:
+```sh
+$> sudo ./backup.sh --backup <SOURCES_FILE> <USER> <ENCRYPTION_PASSWORD>
+```
+
+Where `<SOURCES_FILE>` is the _sources file_, `<USER>` is the home directory where you want the final backup
+and `<ENCRYPTION_PASSWORD>` is the password to encrypt the compressed archive.
+
+In the previous example, this would be:
+```sh
+$> sudo ./backup.sh --backup sources.bk john badpw1234
+```
+
+The backup utility will begin to copy the files defined in the _sources file_:
+```text
+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`.
+
+### Archive extraction
+`backup.sh` can also extract the encrypted backup archive using the following syntax:
+
+```sh
+$> ./backup.sh --extract <ENCRYPTED_ARCHIVE> <ARCHIVE_PASSWORD>
+```
+
+where `<ENCRYPTED_ARCHIVE>` is the encrypted backup and `<ARCHIVE_PASSWORD>` is the backup password.
+
+For instance:
+
+```sh
+$> ./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:
+```text
+backup-nginx-<YYYYMMDD>
+backup-ssh-<YYYYMMDD>
+```
+
+
+## How does backup.sh work
+TODO: explain backend(rsync) parameters.
+### Backup flow
+Graph with:
+1. loop through sources;
+2. Copy each source in tmp dir;
+3. Compress the archive and encrypt it.
+### Encryption
+TODO: show `file` output of the backup
+
+## Unit tests
+## License
diff --git a/backup.sh b/backup.sh
index e0ebd5d..1a3d4c8 100755
--- a/backup.sh
+++ b/backup.sh
@@ -1,9 +1,10 @@
 #!/bin/bash
-# backup.sh - Make an encryption backup of your files.
-# This POSIX compliant script uses rsync and openssl
-# to make a backup of your files. To specify the source
-# directories to backup, create a text file with the following
-# syntax:
+# backup.sh - Backup and encrypt your files.
+# backup.sh is a POSIX compliant, modular and lightweight
+# backup utility to save and encrypt your files.
+#
+# To specify the source directories to backup,
+# create a text file with the following syntax:
 #
 # <LABEL>=<PATH>
 #
@@ -118,7 +119,7 @@ helper() {
     CLI_NAME="$1"
 
     cat <<EOF
-backup.sh - Make an encryption backup of your files.
+backup.sh - POSIX compliant, modular and lightweight backup utility.
 
 Syntax: $CLI_NAME [-b|-e|-h]
 options:
diff --git a/backup_sources.bk b/backup_sources.bk
new file mode 100644
index 0000000..b246e32
--- /dev/null
+++ b/backup_sources.bk
@@ -0,0 +1,4 @@
+ssh=/etc/ssh/
+nginx=/etc/nginx/
+logs=/var/log/
+web_root=/var/www/