.\" Automatically generated by Pandoc 2.17.1.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" "April 4, 2024" "Marco Cetica" "General Commands Manual"
.hy
.SH NAME
.PP
\f[B]backup.sh\f[R] - POSIX compliant, modular and lightweight backup
utility to save and encrypt your files.
.SH SYNOPSIS
.IP
.nf
\f[C]
Syntax: ./backup.sh [-b|-c|-e|-h]
options:
-b|--backup   SOURCES DEST PASS  Backup folders from SOURCES file.
-c|--checksum                    Generate/check SHA256 of a backup.
-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],
\f[I]sha256sum\f[R] and \f[I]gpg\f[R] to copy, compress, verify and
encrypt the backup.
.SH OPTIONS
.PP
\f[B]backup.sh\f[R] supports three options: \f[B]backup creation\f[R],
\f[B]backup extraction\f[R] and \f[B]checksum\f[R] to verify the
integrity of a backup.
The first option requires root permissions, while the second one does
not.
The checksum option must be used in combination of one of the previous
options.
.SS Backup creation
.PP
To specify the directories to back up, \f[V]backup.sh\f[R] uses an
associative array defined in a text file(called \f[I]sources file\f[R])
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[V]/etc/nginx\f[R] and
\f[V]/etc/ssh\f[R], add the following entries to the \f[I]sources
file\f[R]:
.IP
.nf
\f[C]
nginx=/etc/nginx/
ssh=/etc/ssh/
\f[R]
.fi
.PP
\f[V]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 \f[I]sources file\f[R], \f[B]should not\f[R] include:
- Spaces between the label and the equal sign;
.PD 0
.P
.PD
- Empty lines;
.PD 0
.P
.PD
- Comments.
.PP
You can find a sample \f[I]sources file\f[R] at \f[V]sources.bk\f[R](or
at \f[V]/usr/local/etc/sources.bk\f[R]).
.PP
After having defined the \f[I]sources file\f[R], you can invoke
\f[V]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[B]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
You can also tell \f[V]backup.sh\f[R] to generate a SHA256 file
containing the hash of each file using the \f[V]-c\f[R] option.
In the previous example, this would be:
.IP
.nf
\f[C]
$> sudo ./backup.sh --checksum --backup sources.bk /home/john badpw1234
\f[R]
.fi
.PP
The backup utility will begin to copy the files defined in the
\f[I]sources file\f[R]:
.IP
.nf
\f[C]
Copying nginx(1/2)
Copying ssh(2/2)
Compressing backup...
Encrypting backup...
File name: /home/john/backup-<HOSTNAME>-<YYYYMMDD>.tar.gz.enc
Checksum file: /home/john/backup-<HOSTNAME>-<YYYYMMDD>.sha256
File size: 7336400696(6.9G)
Elapsed time: 259 seconds.
\f[R]
.fi
.PP
After that, you will find the backup archive and the checksum file in
\f[V]/home/john/backup-<HOSTNAME>-<YYYYMMDD>.tar.gz.enc\f[R] and
\f[V]/home/john/backup-<HOSTNAME>-<YYYYMMDD>.sha256\f[R], respectively.
.PP
You can also use \f[V]backup.sh\f[R] from a crontab rule:
.IP
.nf
\f[C]
$> sudo crontab -e
30 03 * * 6 EKEY=$(cat /home/john/.ekey) bash -c \[aq]/usr/local/bin/backup.sh -b /usr/local/etc/sources.bk /home/john $EKEY\[aq] > /dev/null 2>&1
\f[R]
.fi
.PP
This will automatically run \f[V]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 be used to extract and to verify the
encrypted backup.
To do so, use the following commands:
.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>-<YYYYMMDD>.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 with the following content:
.IP
.nf
\f[C]
backup-nginx-<YYYYMMDD>
backup-ssh-<YYYYMMDD>
\f[R]
.fi
.PP
\f[B]note\f[R]: be sure to rename any directory with that name to avoid
collisions.
.PP
If you also want to verify the integrity of the backup data, use the
following commands:
.IP
.nf
\f[C]
$> ./backup.sh --checksum --extract <ENCRYPTED_ARCHIVE> <ARCHIVE_PASSWORD> <CHECKSUM_ABSOLUTE_PATH>
\f[R]
.fi
.PP
For instance:
.IP
.nf
\f[C]
$> ./backup.sh --checksum --extract backup-<hostname>-<YYYYMMDD>.tar.gz.enc badpw1234 backup-<hostname>-<YYYYMMDD>.sha256
\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, \f[I]gpg\f[R] to encrypt it and
\f[I]sha256sum\f[R] to verify 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
If specified(\f[V]--checksum\f[R] option), \f[V]backup.sh\f[R] can also
generate the checksum of each file of the backup.
To do so, it uses \f[V]sha256sum(1)\f[R] to compute the hash of every
single file using the SHA256 hashing algorithm.
The checksum file contains nothing but the checksums of the files, no
other information about the files stored on the backup archive is
exposed on the unencrypted checksum file.
This may be an issue if you want plausible deniability(see privacy
section for more information).
.PP
After that the backup folder is being encrypted using gpg.
By default, it is used with the following parameters:
.IP
.nf
\f[C]
$> gpg -a \[rs]
        --symmetric \[rs]
        --cipher-algo=AES256 \[rs]
        --no-symkey-cache \[rs]
        --pinentry-mode=loopback \[rs]
        --batch --passphrase \[dq]$PASSWORD\[dq] \[rs]
        --output \[dq]$OUTPUT\[dq] \[rs]
        \[dq]$INPUT\[dq]
\f[R]
.fi
.PP
This command encrypts the backup using the AES-256 symmetric encryption
algorithm with a 256bit key.
Here is what each flag do: - \f[V]--symmetric\f[R]: Use symmetric
encryption;
.PD 0
.P
.PD
- \f[V]--cipher-algo=AES256\f[R]: Use AES256 algorithm;
.PD 0
.P
.PD
- \f[V]--no-symkey-cache\f[R]: Do not save password on GPG\[cq]s cache;
.PD 0
.P
.PD
- \f[V]--pinentry-mode=loopback --batch\f[R]: Do not prompt the user;
.PD 0
.P
.PD
- \f[V]--passphrase-fd 3 3<< \[dq]$PASSWORD\[dq]\f[R]: Read password
without revealing it on \f[V]ps\f[R];
.PD 0
.P
.PD
- \f[V]--output\f[R]: Specify output file;
.PD 0
.P
.PD
- \f[V]$INPUT\f[R]: Specify input file.
.SS Plausible Deniability
.PP
While \f[V]backup.sh\f[R] provide some pretty strong security against
bruteforce attack(assuming a strong passphrase is being used) it should
by no means considered a viable tool against a cryptanalysis
investigation.
Many of the copying, compressing and encrypting operations made by
\f[V]backup.sh\f[R] during the backup process can be used to invalidate
plausible deniability.
In particular, you should pay attention to the following details:
.IP "1." 3
The \f[V]--checksum\f[R] option generates an \f[B]UNENCRYPTED\f[R]
checksum file containing the \f[I]digests\f[R] of \f[B]EVERY\f[R] file
in your backup archive.
If your files are known to your adversary(e.g., a banned book), they may
use a rainbow table attack to determine whether you own a given file,
voiding your plausible deniability;
.PD 0
.P
.PD
.IP "2." 3
Since \f[V]backup.sh\f[R] is essentially a set of shell commands, an
eavesdropper could monitor the whole backup process to extract the name
of the files or the encryption password.
.SH EXAMPLES
.PP
Below there are some examples that demonstrate \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
an 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
.IP "3." 3
Extract the content of a backup made on 2018-04-25 using the password in
\f[V]/home/john/.pw\f[R]
.PP
This example is very similar to the previous one, we just need to read
the password from the text file:
.IP
.nf
\f[C]
$> backup.sh --extract backup-af9a8e6bfe15-20180425.tar.gz.enc \[dq]$(cat /home/john/.pw)\[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