Metadata-Version: 2.1
Name: btrfs-sxbackup
Version: 0.6.11
Summary: Incremental btrfs snapshot backups with push/pull support via SSH
Home-page: https://github.com/masc3d/btrfs-sxbackup
Author: Marco Schindler
Author-email: masc@disappear.de
License: GNU GPL
Classifier: Environment :: Console
Classifier: Intended Audience :: End Users/Desktop
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: GNU General Public License (GPL)
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: System :: Filesystems
Classifier: Topic :: System :: Archiving :: Backup
Classifier: Topic :: Utilities
License-File: LICENSE

btrfs-sxbackup
**************

Btrfs snapshot backup utility

* Push/pull support via SSH
* Retention
* Email notifications
* Compression of transferred data
* Syslog logging

System dependencies
===================
Required
--------
The following packages have to be available on both source and destination

* bash

* btrfs-progs

The system executing btrfs-backup requires

* python3

Optional
--------
* ssh (for remote push/pull, not required for local operation)
   
  * bash has to be set as the default remote shell for the user running the backup
   
* lzop (for compression support if desired)

* pv (provides progress indication if installed)

* sendmail (for email notifications if desired)

Installation
============
.. code ::

    pip3 install btrfs-sxbackup

Setup
=====
* when using ssh, public/private key authentication should be set up

Known limitations
=================
* the destination filesystem has to be mounted without the subvol option, otherwise an error will occur on btrfs receive prompting you to remount with fs tree

* some commands (like *update*) may not be available for backup jobs created with older versions of btrfs-sxbackup. in this case backup jobs can be recreated using *destroy* and *init*. existing snapshots will be kept as long as *destroy* is **not** invoked with *--purge*.

Usage examples
==============

Initialize
----------

Initialize a backup job pulling snapshots of subvolume **/** on remote host **myhost.org** to local subvolume **/backup/myhost**

.. code ::

    btrfs-sxbackup init ssh://root@myhost.org:/ /backup/myhost

Initialize a backup job pushing snapshots of local subvolume **/** to remote subvolume **/backup/myhost** on host **mybackupserver.org**

.. code ::

    btrfs-sxbackup init / ssh://root@mybackupserver.org:/backup/myhost

Run
---

Run a backup job

.. code ::

    btrfs-sxbackup run /backup/myhost

Cron
----

Cronjob performing a pull backup job

.. code ::

    # /etc/cron.d/btrfs-sxbackup
    PATH="/usr/sbin:/usr/bin:/sbin:/bin"
    30 2    * * *     root     btrfs-sxbackup run /backup/myhost

Synopsis and options
====================

.. code ::

    usage: btrfs-sxbackup [-h] [-q] [--version] [-v]
                          {init,destroy,update,run,info,transfer} ...

    positional arguments:
      {init,destroy,update,run,info,transfer}
        init                initialize backup job
        destroy             destroy backup job
        update              update backup job
        run                 run backup job
        info                backup job info
        purge               purge backups according to retention expressions
        transfer            transfer snapshot

    optional arguments:
      -h, --help            show this help message and exit
      -q, --quiet           do not log to stdout
      --version             show program's version number and exit
      -v                    can be specified multiple times to increase verbosity

init
----

.. code ::

    usage: btrfs-sxbackup init [-h] [-sr SOURCE_RETENTION]
                               [-dr DESTINATION_RETENTION] [-c]
                               source-subvolume destination-subvolume

    positional arguments:
      source-subvolume      source subvolume to backup. local path or ssh url
      destination-subvolume
                            destination subvolume receiving backup snapshots.
                            local path or ssh url

    optional arguments:
      -h, --help            show this help message and exit
      -sr SOURCE_RETENTION, --source-retention SOURCE_RETENTION
                            expression defining which source snapshots to
                            retain/cleanup. can be a static number (of backups) or
                            more complex expression like "1d:4/d, 1w:daily,
                            2m:none" literally translating to: "1 day from now
                            keep 4 backups a day, 1 week from now keep daily
                            backups, 2 months from now keep none"
      -dr DESTINATION_RETENTION, --destination-retention DESTINATION_RETENTION
                            expression defining which destination snapshots to
                            retain/cleanup. can be a static number (of backups) or
                            more complex expression (see --source-retention
                            argument)
      -c, --compress        enables compression during transmission. Requires lzop
                            to be installed on both source and destination

run
---

.. code ::

    usage: btrfs-sxbackup run [-h] [-m [MAIL]] [-li LOG_IDENT]
                              subvolume [subvolume ...]

    positional arguments:
      subvolume             backup job source or destination subvolume. local path
                            or SSH url

    optional arguments:
      -h, --help            show this help message and exit
      -m [MAIL], --mail [MAIL]
                            enables email notifications. If an email address is
                            given, it overrides the default email-recipient
                            setting in /etc/btrfs-sxbackup.conf
      -li LOG_IDENT, --log-ident LOG_IDENT
                            log ident used for syslog logging, defaults to script
                            name

update
------

.. code ::

    usage: btrfs-sxbackup update [-h] [-sr SOURCE_RETENTION]
                                 [-dr DESTINATION_RETENTION] [-c]
                                 subvolume [subvolume ...]

    positional arguments:
      subvolume             backup job source or destination subvolume. local path
                            or SSH url

    optional arguments:
      -h, --help            show this help message and exit
      -sr SOURCE_RETENTION, --source-retention SOURCE_RETENTION
                            expression defining which source snapshots to
                            retain/cleanup. can be a static number (of backups) or
                            more complex expression like "1d:4/d, 1w:daily,
                            2m:none" literally translating to: "1 day from now
                            keep 4 backups a day, 1 week from now keep daily
                            backups, 2 months from now keep none"
      -dr DESTINATION_RETENTION, --destination-retention DESTINATION_RETENTION
                            expression defining which destination snapshots to
                            retain/cleanup. can be a static number (of backups) or
                            more complex expression (see --source-retention
                            argument)
      -c, --compress        enables compression during transmission. Requires lzop
                            to be installed on both source and destination

info
----

.. code ::

    usage: btrfs-sxbackup info [-h] subvolume [subvolume ...]

    positional arguments:
      subvolume   backup job source or destination subvolume. local path or SSH
                  url

    optional arguments:
      -h, --help  show this help message and exit

purge
-----

.. code ::

    usage: btrfs-sxbackup purge [-h] [-sr SOURCE_RETENTION]
                                [-dr DESTINATION_RETENTION]
                                subvolume [subvolume ...]

    positional arguments:
      subvolume             backup job source or destination subvolume. local path
                            or SSH url

    optional arguments:
      -h, --help            show this help message and exit
      -sr SOURCE_RETENTION, --source-retention SOURCE_RETENTION
                            Optionally override expression defining which source
                            snapshots to retain/cleanup. can be a static number
                            (of backups) or more complex expression like "1d:4/d,
                            1w:daily, 2m:none" literally translating to: "1 day
                            from now keep 4 backups a day, 1 week from now keep
                            daily backups, 2 months from now keep none"
      -dr DESTINATION_RETENTION, --destination-retention DESTINATION_RETENTION
                            Optionally override expression defining which
                            destination snapshots to retain/cleanup. can be a
                            static number (of backups) or more complex expression
                            (see --source-retention argument)

destroy
-------

.. code ::

    usage: btrfs-sxbackup destroy [-h] [--purge] subvolume [subvolume ...]

    positional arguments:
      subvolume   backup job source or destination subvolume. local path or SSH
                  url

    optional arguments:
      -h, --help  show this help message and exit
      --purge     removes all backup snapshots from source and destination

transfer
--------

.. code ::

    usage: btrfs-sxbackup transfer [-h] [-c]
                                   source-subvolume destination-subvolume

    positional arguments:
      source-subvolume      source subvolume to transfer. local path or ssh url
      destination-subvolume
                            destination subvolume. local path or ssh url

    optional arguments:
      -h, --help            show this help message and exit
      -c, --compress        enables compression during transmission. Requires lzop
                            to be installed on both source and destination

Changelog
=========

0.6.11
------
* btrfs send/receive should run with idle io prio

0.6.10
------
* FIXED username should be checked for `None` when building ssh url

0.6.9
-----
* RESOLVED #32 regression, always transferring full snapshots

0.6.8
-----
* RESOLVED #31 Error when destination has no snapshots

0.6.7
-----
* FIXED #30: full snapshot warning breaks local jobs (having no destination)
* RESOLVED #29: can't destroy when destination unavailable

0.6.6
-----
* ADDED support for retain timespan multiplier (eg. '1/4m' -> keep 1 in 4 months) and yearly timespan literal ('y'), resolving #28

0.6.5
-----
* RESOLVED #18, improved error output

0.6.4
-----
* ADDED support for falling back to transferring full snapshot if latest snapshot (timestamp) does not match on source/destination

0.6.3
-----
* FIXED exception during exception handling in main method

0.6.2
-----
* FIXED pip installation may fail with bdist/wheel

0.6.1
-----
* README update

0.6.0
-----
* ADDED support for purge command

0.5.9
-----
* ADDED license headers to all source files, no functional changes

0.5.8
-----
* FIXED job won't run due to inconsistent  datetime comparison (offset-naive/aware)

0.5.7
-----
* ADDED local timestamps to info, resolving #14

0.5.6
-----
* Fixed #13 "update" command always activates compression, regardless of -c

0.5.5
-----
* Fixed retention breakage which could occur when first/earliest expression kept 1 backup per interval

0.5.4
-----
* Python 3.3 compatibility fixes

* Added proper support for relative paths passed to init

0.5.0
-----
* New command line interface

* Source container subvolume path is now **.sxbackup** relative to the source subvolume and cannot be customized anylonger

* Backups created with older versions are still supported.
  If you customized the source container subvolume, this will still work, but it's recommended to rename it
  to the new default (**.sxbackup**) and update source and destination configuration files (.btrfs-sxbackup) accordingly

