404 lines
11 KiB
Groff
404 lines
11 KiB
Groff
.\" 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
|