From 2c69aff8f793c5aeebad9de4e68ccd63d70ce3f8 Mon Sep 17 00:00:00 2001 From: David Runge Date: Sun, 25 Oct 2015 00:16:10 +0200 Subject: README.rst: Reformatting README to ReStructuredText. --- README.rst | 204 ++++++++++++++++++++++++++++++++++++++++--------------------- 1 file changed, 135 insertions(+), 69 deletions(-) diff --git a/README.rst b/README.rst index 2653ece..b9c1536 100644 --- a/README.rst +++ b/README.rst @@ -1,96 +1,162 @@ -# Crypted backups - -## About -This collection of services, timers and scripts enables a precise - gpg encrypted - backup of certain configuration data. -System-wide and user-specific backups are possible. -Crypted-backups by default uses volatile file-systems (*tmpfs*) as a working space. -**Note:** *Depending on the size of your (singular) backups and available RAM you might want to consider moving this working space somewhere else.* - -## Features -Backups of the following program settings/profiles/folders are possible: - -### System -* aura -* bitlbee -* git -* mail & mailman -* mariadb -* /var/log -* /var/log/journal -* websites - -### User -* firefox -* thunderbird - -### Compression -At the moment crypted-backups only supports [xz](http://tukaani.org/xz/) compression. - -## Requirements -* xz -* gnupg - -## Configuration -Two forms of configuration files are used: One for system-wide services and one for user services. -Both are documented and show examples on how to setup the variables. - -### System -The configuration file for system services can be found in **/etc/crypted-backups**. - -### User -The configuration file for user services is read first from **$HOME/.crypted-backups** followed by **$HOME/.config/crypted-backups**. Environment variables set in the first file will be replaced by the ones set in the latter, if present. -Make sure to copy and modify a plain one from your system skeleton folder (**/etc/skel/.crypted-backups**). - -## Usage -Crypted-backups is made available through systemd services and timers. -### Example 1: Activating a system backup with the help of a timer -In this example the system backup for the bitlbee configuration will be started by a timer. -This timer unit has the same name as its service. +crypted backups +=============== + +| *crypted backups* enables for |xz|-compressed and |gnupg| encrypted backups of certain configuration data by the use of |systemd| |systemd.service| and |systemd.timer|. +| System-wide and user-specific backups are possible. The script and all of its components are licensed under the GPLv3. + +| **Note:** Most of *crypted backups* was designed with a headless system in mind. +| **Note:** By default the script uses volatile file-systems (*tmpfs*) as a working space! Depending on the size of your (singular) backups and available RAM you might want to consider moving this working space somewhere else. +| **Note:** Due to systemd's architecture you can copy/paste and modify given default timers from **/usr/lib/systemd/{systemd,user}/** and put them to **/etc/systemd/{system,user}**. The latter will always have precedence over the former. Same counts for services! +| **Note:** To minimize the size of your user backups, you might want to consider using tools like |profile-cleaner| to shrink the size of your program profiles.* + +Requirements +------------ + +* |xz| +* |gnupg| + +System backups +-------------- +| The configuration file for system services can be found in **/etc/crypted-backups**. +| Here you can set the public key to encrypt with, source and destination folder for backups and cleanup policy. +| The following backups are possible (have a look at the default settings in the configuration, to get an idea, about what does what). + +* |aura| package states +* |bitlbee| configuration +* |git| repositories +* |maildir| & |mailman| configuration +* |mariadb| databases +* /var/log folder +* /var/log/journal folder +* websites folder + +Example +_______ +| In this example the system backup for the bitlbee configuration will be started by a timer. +| This timer unit has the same name as its service. + + .. code:: bash /usr/lib/systemd/system/backup-bitlbee.service /usr/lib/systemd/system/backup-bitlbee.timer -Using *systemctl* one can easily start and stop timer units belonging to a service. As root: + +| Using **systemctl** one can easily start and stop timer units belonging to a service. As root: + + .. code:: bash systemctl start backup-bitlbee.timer systemctl stop backup-bitlbee.timer -To make the system boot with this timer started, enable it. Again, as root: + +To make the system boot with this timer started, enable it. Again, as root: + + .. code:: bash systemctl enable backup-bitlbee.timer systemctl disable backup-bitlbee.timer -When the timer's conditions are met, the service *backup-bitlbee.service* is started automatically. Much like cron. -Unlike cron, you can also start and stop the service separately: + +| When the timer's conditions are met, the service **backup-bitlbee.service** is started automatically. Much like cron. +| Unlike cron, you can also start and stop the service separately: + + .. code:: bash systemctl start backup-bitlbee.service systemctl stop backup-bitlbee.service -**Note:** *Due to systemd's architecture you can copy/paste and modify the given timer from **/usr/lib/systemd/system/** and put it to **/etc/systemd/system**. The latter will always have precedence over the former. Same counts for services!* -### Example 2: Activating a user backup with the help of a timer -In this example the user backup for a user's firefox profile will be started by a timer (like in the example above). -The user service and timer units reside in a different location: +User backups +------------ +| The configuration file for user services is read first from **$HOME/.crypted-backups** followed by **$HOME/.config/crypted-backups**. Environment variables set in the first file will be replaced by the ones set in the latter, if present. +| Take a look at the example file in **/usr/share/doc/crypted-backups/crypted-backups.conf.example** to get an idea of how to use the services. +| Here you can set the public key to encrypt with, source and destination folder for backups and cleanup policy. +| The following pbackups + +* |firefox| profile backup +* |thunderbird| profile backup + +Example +_______ +| In this example the user backup for a user's |firefox| profile will be started by a timer (like in the example above). + + .. code:: bash /usr/lib/systemd/user/backup-firefox.service /usr/lib/systemd/user/backup-firefox.timer -Using *systemctl* one can easily start and stop timer units belonging to a service. This time, as your user: + +| Using **systemctl** one can easily start and stop timer units belonging to a service. This time, as your user: + + .. code:: bash systemctl --user start backup-firefox.timer systemctl --user stop backup-firefox.timer -To make your user environment start with this timer started, enable it. Again, as your user: +| To make your user environment start with this timer started, enable it. Again, as your user: + + .. code:: bash systemctl --user enable backup-firefox.timer systemctl --user disable backup-firefox.timer -When the timer's conditions are met, the service *backup-firefox.service* is started (as your user) automatically. -This service can of course also just be started and stopped separately from the timer: + +| When the timer's conditions are met, the service **backup-firefox.service** is started (as your user) automatically. +| This service can of course also just be started and stopped separately from the timer: + + .. code:: bash systemctl --user start backup-firefox.service systemctl --user stop backup-firefox.service -**Note:** *Due to systemd's architecture you can copy/paste and modify the given timer from **/usr/lib/systemd/user/** and put it to **/etc/systemd/user**. The latter will always have precedence over the former. Same counts for services!* -**Note:** *To minimize the size of your backups, you might want to consider using tools like [profile-cleaner](https://github.com/graysky2/profile-cleaner) to shrink the size of your program profiles.* -## TODO -* Unifying scripts for simplicity -* Using [pixz](https://github.com/vasi/pixz) -* Using [rsync](https://rsync.samba.org/) for backup mirroring -* Auto-adding of key, if not in keyring -## License -Crypted-backups is licensed under the GPLv3. +.. |xz| raw:: html + + xz + +.. |gnupg| raw:: html + + GnuPG + +.. |systemd| raw:: html + + systemd + +.. |systemd.service| raw:: html + + services + +.. |systemd.timer| raw:: html + + timers + +.. |profile-cleaner| raw:: html + + profile-cleaner + +.. |aura| raw:: html + + aura + +.. |bitlbee| raw:: html + + bitlbee + +.. |git| raw:: html + + git + +.. |maildir| raw:: html + + Maildir + +.. |mailman| raw:: html + + mailman + +.. |mariadb| raw:: html + + MariaDB + +.. |firefox| raw:: html + + Firefox + +.. |thunderbird| raw:: html + + Thunderbird + + -- cgit v1.2.3-54-g00ecf