Metadata-Version: 1.1
Name: jw.backup
Version: 1.0.6
Summary: A simple differential backup script for systems maintained bypackage managers with single-file manifests
Home-page: https://pypi.python.org/pypi/jw.backup
Author: Johnny Wezel
Author-email: dev-jay@wezel.name
License: GPL
Download-URL: https://pypi.python.org/packages/source/j/jw.backup/jw.backup-1.0.6.tar.gz
Description: backup
        ======
        
        Introduction
        ------------
        
        This is a simple backup script for systems maintained by package management software providing a detailed manifest
        about installed files. It uses the repository of system-installed files to automatically exclude them from backup
        because those files can (and should) be reinstalled easily with the package manager. The program detects the package
        manager automatically and makes use of its manifest of installed files. At the moment, *portage* (on *Gentoo Linux*
        systems and derivations) and *dpkg* (*Debian* and derivations) are supported. More systems can be supported with
        plugins.
        
        Configuration
        -------------
        
        Backup uses a configuration file (``~/.local/etc/backup`` if 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 the
        `YAML <http://www.yaml.org>`_ format. 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
                password: hj983sh34
                host: backuphost
                port: 22
                directory: /backup/{HOSTNAME}/rsync-backup
                generations: 7
        
        There are three sections (*root*, *prune* and *destination*). In the *root* section, 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).
        
        The *prune* section contains a list of directories to be excluded from the backup. If it is missing, the following
        directories are excluded by default: /tmp, /proc, /sys, /dev, /mnt, /var/tmp, /var/run, /var/cache, /run, /lost+found.
        
        In the *destination* section, a couple of parameters specify where the backup has to be written to. Since *rsync* is
        capable of writing to remote hosts through the use of *ssh*, three parameters, *user*, *host* and *port* specify the
        necessary information for reaching a remote host. As of version 0.9, the *host* parameter is required, meaning only
        remote backups are possible. This will change in later versions, allowing local backups. The parameter *directory*
        specifies the base destination directory on the remote host. Parameter *port* has 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 parameter *generations* specifies 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 a ``key: key-file`` entry in the *destination* section.
        
        Backup organisation
        -------------------
        
        To enable differential backups, the backup is stored under a subdirectory of the destination directory specified in the
        *destination* section of the configuration. This subdirectory has a name resembling a time stamp with date and time,
        like ``2014-02-12-03:12:26`` where 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 by *rsync* by the
        use of the ``--link-dest`` option.
        
        Usage
        -----
        
        The program is intended to be run by the simple command::
        
            backup
        
        There are some options for testing and one-time use:
        
        
            -h, --help                      shows a help message and exits
            --config file, -c file          to specify the path to an alternative configuration file (default: ~/.backup)
            --version, -V                   displays the program version
            --log-level level, -L level     to 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-file file, -l file        to set log file (default: /var/log/backup)
        
        Per-directory exclusion
        -----------------------
        
        To exclude a directory from backup, simply create a file named ``.no-backup`` in it.
        
        Installation
        ------------
        
        The software can be installed easily from the Python software repository, either on the command line or by downloading
        the package and installing it explicitly.
        
        .. note::
        
           Python packages should not be installed using *pip* or *easy_install* globally 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 by *pip* or *easy_install*. Since
           backups are done almost always by *root*, the software should be installed in *root*'s home directory, ``/root``.
           This is done with *pip*'s ``--user`` switch. Another way is to use *pip*'s ``--root`` option and adjust
           ``PYTHONPATH``.
        
        Installation using *pip*
        ~~~~~~~~~~~~~~~~~~~~~~~~
        
        On the command line, type::
        
            pip install --user jw.backup
        
        Explicit Installation from a downloaded package
        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
        
        Download the package from https://pypi.python.org/pypi/jw.backup. Unpack it, ``cd`` into the unpacked directory and
        type the command::
        
            python setup.py install --user
        
        Bug reports
        -----------
        
        Please report bugs and enhancement requests to https://bitbucket.org/JohnnyWezel/jw.backup/issues.
Keywords: backup,utility
Platform: POSIX
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
Classifier: Natural Language :: English
Classifier: Operating System :: POSIX
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.4
Classifier: Topic :: System :: Archiving :: Backup
Classifier: Topic :: System :: Archiving :: Mirroring
Classifier: Topic :: Utilities
