diff --git a/.usage.gif b/.usage.gif new file mode 100644 index 0000000..38cc354 Binary files /dev/null and b/.usage.gif differ diff --git a/README.md b/README.md index bc9ac43..bb99214 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,121 @@ -# backup.py +
+

backup.py

+
Modular and lightweight backup utility to save, encrypt and verify your personal data.
+ +
-Work in progress +`backup.py` is a CLI utility written in Python designed to backup small-scale UNIX environments +such as VPS, personal servers and workstations. It relies on `tar`, `gpg` and Python builtin +modules to copy, compress and encrypt your files. + +## Overview +`backup.py` supports two major options: `--backup`, to create a new backup and `--extract` +to extract an existing backup archive. + +In order to create a backup file, you first need to create a *"sources file"* to specify +the absolute paths to backup. For instance: + +```ini +# directories end with a slash... +photos=/home/marco/Pictures/ +documents=/home/marco/Documents/ +# while individual files do not +wireguard=/etc/wireguard/wg0.conf +``` + +Then, you can start the backup with the following command: + +```sh +$ sudo ./backup.py -V --checksum --backup sources.ini /home/marco "very_bad_pw" +Copying photos (1/3) +Computing checksums...DONE +└──Computing checksums... [██████████████████████████████] 100.0% (2/2) - (processing 'wallpaper2.jpg') +Copying documents (2/3) +Computing checksums...DONE +└──Computing checksums... [██████████████████████████████] 100.0% (7844/7844) - (processing '__init__.cpython-313.pyc') +Copying wireguard (3/3) +Computing checksums...DONE +└──Computing checksums... [██████████████████████████████] 100.0% (1/1) - (processing 'wg0.conf') +Compressing backup...DONE +└──Compressing backup... [██████████████████████████████] 100.0% (9062/9061) - (processing 'wg0.conf') +Encrypting backup...DONE +File name: '/home/marco/backup-wood-20260122.tar.gz.enc' +Checksums file: '/home/marco/backup-wood-20260122.sha256' +File size: 5533767184 bytes (5.15 GiB) +Elapsed time: 2 minutes, 10 seconds +``` + +Both the `--checksum` and the `--verbose` (`-V`) flags are optional. The former generates a checksum +file containing the hashes of each single file, the latter enables the *verbose mode*, which renders +the user interface as shown before. + +To extract an existing backup, you can instead proceed as follows: + +```sh +$ ./backup.py -V -c --extract backup-wood-20260122.tar.gz.enc "very_bad_pw" backup-wood-20260122.sha256 +Decrypting backup...DONE +Extracting backup...DONE +└──Extracting backup... [██████████████████████████████] 100.0% (9062/9062) - (processing 'wg0.conf') +Verifying backup...DONE +└──Verifying backup... [██████████████████████████████] 100.0% (7847/7847) - (processing '__init__.cpython-313.pyc') +Backup extracted to: '/home/marco/Projects/backup.py/backup.py.tmp' +Elapsed time: 1 minute, 3 seconds +``` + +This will create a new directory named `backup.py.tmp` on your local path. Just like before, +the `-V` and the `-c` options are optional. + +## Usage +As stated before, `python.py` is built from scratch in modern Python (3.10+) without using +any external dependency except for `tar` and `gpg`. + +The *sources file* follows an INI-like syntax structured using associative records between +labels and absolute paths. In order words: + +```ini +