marco/backup.sh
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Added manual page

Browse Source
This commit is contained in:
Marco Cetica 2023-03-14 16:23:53 +01:00
parent 3df55ee227
commit f65a87fb30
No known key found for this signature in database
GPG Key ID: 0EE8E2CF315D6F8E
3 changed files with 512 additions and 8 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

16
README.md
View File

@ -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.

298
backup.sh.1 Normal file
View File

@ -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

206
man.md Normal file
View File

@ -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