Package: jw.grbackup
NoteThis project is superceded byjw.backupand is no longer maintained.IntroductionThis is a simple backup script for use exclusively under Gentoo Linux. It uses the repository of system-installed files
to automatically exclude them from backup because those files can (and should) be reinstalled easily with theportagepackage manager.ConfigurationGrbackup uses a configuration file (~/.local/etc/grbackupif not overridden on the command line) for its required
information in order to be run with a simple command for daily use. The configuration file is in theYAMLformat. The format is simple enough to be described by an example:roots:
    - /
prune:
    - /tmp
    - /proc
    - /sys
    - /dev
    - /mnt
    - /var/tmp
    - /var/run
    - /var/cache
    - /run
    - /lost+found
destination:
    user: backup
    host: backuphost
    port: 22
    directory: /backup/{HOSTNAME}/rsync-backup
    generations: 7There are three sections (root,pruneanddestination). In therootsection, a list of directories to be
included in the backup are stated. Each list element is on a separate line and begins with “- “ (the space after the
dash is required).Theprunesection contains a list of directories to be excluded from the backup. If it is missing, the following directories
are excluded: /tmp, /proc, /sys, /dev, /mnt, /var/tmp, /var/run, /var/cache, /run, /lost+found.In thedestinationsection, a couple of parameters specify where the backup has to be written to. Sincersyncis
capable of writing to remote hosts through the use ofssh, three parameters,user,hostandportspecify the
necessary information for reaching a remote host. As of version 0.9, thehostparameter is required, meaning only
remote backups are possible. This will change in later versions, allowing local backups. The parameterdirectoryspecifies the base destination directory on the remote host. Parameterporthas a default of 22. As you can see in the
example, there can be variable substitution expressions in the form of{VARIABLE}. The expression will be replaced by the
respective environment variable. The parametergenerationsspecifies how many generations of old backups are to be retained
before they are removed. The default is 30. If a private key is required to log in to the remote host, it can be specified
with akey:key-fileentry in thedestinationsection.Backup organisationTo enable differential backups, the backup is stored under a subdirectory of the destination directory specified in thedestinationsection of the configuration. This subdirectory has a name resembling a time stamp with date and time,
like2014-02-12-03:12:26where the first three numbers are the date in ISO-format and the last three numbers are the
time in 24-hour-format.The new backup is stored in reference to the last backup. All changed files are stored normally. Files which have
not changed since the last backup are simply hard-linked to the corresponding file in the old backup. This way they
don’t take any addition space on the backup medium (apart from the directory entry). This is done byrsyncby the
use of the--link-destoption.UsageThe program is intended to be run by the simple command:grbackupThere are some options for testing and one-time use:-h,--helpshows a help message and exits--configfile,-cfileto specify the path to an alternative configuration file (default: ~/.grbackup)--version,-Vdisplays the program version--log-levellevel,-Llevelto set the log level. Level is one of DEBUG, INFO, WARNING, ERROR, or
CRITICAL. DEBUG shows the most detail while CRITICAL shows almost nothing.
(default: INFO)--log-filefile,-lfileto set log file (default: /var/log/grbackup)Per-directory exclusionTo exclude a directory from backup, simply create a file named.no-backupin it.InstallationThe software can be installed easily from the Python software repository, either on the command line or by downloading
the package and installing it explicitly.NotePython packagesmust notbe installed usingpiporeasy_installglobally in the system environment under
Gentoo Linux. There is a carefully crafted system to make system-provided Python scripts available under Python 2 as
well as Python 3 which is disturbed by packagages deliberately installed bypiporeasy_install. Since
backups are done almost always byroot, the software should be installed inroot’s home directory,/root.
This is done withpip’s--userswitch. Another way is to usepip’s--rootoption and adjustPYTHONPATH.Installation usingpipOn the command line, type:pip install --user jw.grbackupExplicit Installation from a downloaded packageDownload the package fromhttps://pypi.python.org/pypi/jw.grbackup. Unpack it,cdinto the unpacked directory and
type the command:python setup.py install --userInstallation problemsIf you have never installed a Python package before, chances are your version ofsetuptoolsis outdated. Normally,
packages and their dependencies are updated automatically, but not in the case ofsetuptools, because this is the very
package doing the installation and it can’t update itself while it is running, so this needs to be done manually. If
something like the following is displayed when the installation is running:The required version of setuptools (>=*something*) is not available,
and can't be installed while this script is running. Please
install a more recent version first, using
'easy_install -U setuptools'.then just type the command (don’t miss to include the--userflag, it’s not mentioned in the error text):easy_install --user -U setuptoolsThis will install a current version ofsetuptoolsinto your user environment. After that, retry your installation.Bug reportsPlease report bugs and enhancement requests tohttps://bitbucket.org/JohnnyWezel/jw.grbackup/issues.