Butterfly-Backup

Butterfly Backup

Introduction

Butterfly Backup is a modern backup program that can back up your files:

• from Linux, BSD, Mac and Windows (through cygwin)
• easily, being a single executable that you can run without a server or complex setup
• effectively, only transferring the parts that actually changed in the files you back up, in four mode (full, incremental, differential and mirror)
• verifiably, store all backup in a readable catalog also through file system
• speedly, parallelizing all backup, restore and export operations
• securely, exporting, archiving and applying retention
• freely - entirely free to use and completely open source

Test

If you want to try or test Butterfly Backup before installing it, run the test:

$ git clone https://github.com/MatteoGuadrini/Butterfly-Backup.git
$ cd Butterfly-Backup
$ bash test_bb.py
...
[92512a6e-506e-11eb-b747-2ba55b805ea5]
type = full
path = /tmp/bb_repo/localhost/2024_01_06__23_28
name = localhost
os = unix
timestamp = 2024-01-06 23:28:59
start = 2024-01-06 23:28:59
end = 2024-01-06 23:29:04
status = 0

Installation

Install Butterfly Backup is very simple; run this:

git clone https://github.com/MatteoGuadrini/Butterfly-Backup.git
cd Butterfly-Backup
sudo python3 setup.py install -f # -f is for upgrade
# or
sudo pip install . --upgrade
bb --help

git clone https://github.com/MatteoGuadrini/Butterfly-Backup.git
cd Butterfly-Backup
# Use a virtual environment
python3 -m venv venv && . venv/bin/activate && pip install .
# Use user-space
pip install --user .
# Use external tools like pipx(https://pipx.pypa.io/stable/) and/or uv(https://docs.astral.sh/uv/) (they create virtual environments for you); upgrading is done via a specific subcommand
pipx install . && pipx upgrade-all
uv pip install . --upgrade
# Deactivate the externally managed file, temporarily or permanently
pip install . --break-system-packages || python3 -m pip config set global.break-system-packages true

Quickstart

A short demo of Butterfly Backup:

bb backup --computer host1 --destination /nas/mybackup --data user config --type macos --mode full

or with short option:

bb backup -c host1 -d /nas/mybackup -D user config -t macos -m full

So we created a first full backup, on a macos machine, considering the folders User -> /Users and Config -> /private/etc in the destination /nas/mybackup

[!NOTE]
If you do not specify the user, Butterfly Backup will assume that the source and the destination know the same user; for example, I start the backup with the above command and my user is calling arthur, he will use the latter to log in to host1.

Now that we have our first full backup, we can run incremental for the next few times.

bb backup --computer host1 --destination /nas/mybackup --data user config --type macos

or with short option:

bb backup -c host1 -d /nas/mybackup -D user config -t macos

[!NOTE]
Incremental mode performs a full backup when they have not been done before.

Before starting any restore, you need to understand what kind of data and in what time period you have to start. So, let’s start checking our backups into the catalog, with this command:

bb list --catalog /nas/mybackup

The result will be the following:

BUTTERFLY BACKUP CATALOG

Backup id: f65e5afe-9734-11e8-b0bb-005056a664e0
Hostname or ip: host1
Timestamp: 2024-08-03 17:50:36

Backup id: 4f2b5f6e-9939-11e8-9ab6-005056a664e0
Hostname or ip: host1
Timestamp: 2024-08-06 07:26:46

Backup id: cc6e2744-9944-11e8-b82a-005056a664e0
Hostname or ip: host1
Timestamp: 2024-08-06 08:49:00

Select (copy) Backup id when you want restore a backup. For exit, press q.

Now, run this command for more detail (for example, try the first):

bb list --catalog /nas/mybackup --backup-id f65e5afe-9734-11e8-b0bb-005056a664e0

The result will be the following:

Backup id: f65e5afe-9734-11e8-b0bb-005056a664e0
Hostname or ip: host1
Type: full
Timestamp: 2024-08-03 17:50:36
Start: 2024-08-03 17:50:36
Finish: 2024-08-03 18:02:32
OS: macos
ExitCode: 0
Path: /nas/mybackup/host1/2024_08_03__17_50
List: etc
Users

Now that we are sure that the selected backup is what we want (both in data and on date), run this command:

bb restore --computer host1 --catalog /nas/mybackup --backup-id f65e5afe-9734-11e8-b0bb-005056a664e0

So we have restored the data saved on the date indicated in our host1.

Web interface: Butterfly-Backup-Web

In this repository you find a simple web interface of Butterfly Backup.

Copy this snippet for a rapid start

# Installation
git clone https://github.com/MatteoGuadrini/butterfly-backup-web.git
cd butterfly-backup-web
pip install . --upgrade

# Modify this variable for your catalog path
export BB_CATALOG_PATH=/backup

# Use bbweb command line
bbweb migrate
bbweb createsuperuser
bbweb runserver 0.0.0.0:80

3-2-1 rule

With Butterfly Backup you can apply 3-2-1 rule (Keep three copies of your data on two different types of media, with one copy offsite) in only 4 lines:

CATALOG="/nas/mybackup"
bb backup --computer host1 --destination $CATALOG --data user config --type macos; BCKID="$(bb list --catalog $CATALOG --last --computer host1 --only-id)"
bb export --catalog $CATALOG --backup-id "$BCKID" --destination /mnt/other_backup/
# attach you USB drive on your host1...
bb restore --computer host1 --catalog $CATALOG --backup-id "$BCKID" --root-dir /usb/path   # on Windows /cygdrive/d/

Schedule on your own this script in your backup server and you have applied the rule.

Documentation

Manual of Butterfly Backup or run help:

bb --help

Licence

This package is Treeware. If you use it in production, then we ask that you buy the world a tree to thank us for our work. By contributing to the Treeware forest you’ll be creating employment for local families and restoring wildlife habitats.

Open source

Butterfly Backup is a open source project. Any contribute, It’s welcome.

A great thanks.

For donations, press this

For me

For Telethon

The Telethon Foundation is a non-profit organization recognized by the Ministry of University and Scientific and Technological Research. They were born in 1990 to respond to the appeal of patients suffering from rare diseases. Come today, we are organized to dare to listen to them and answers, every day of the year.

Adopt the future

Acknowledgments

Thanks to Mark Lutz for writing the Learning Python and Programming Python books that make up my python foundation.

Thanks to Kenneth Reitz and Tanya Schlusser for writing the The Hitchhiker’s Guide to Python books.

Thanks to Dane Hillard for writing the Practices of the Python Pro books.

Special thanks go to my wife, who understood the hours of absence for this development. Thanks to my children, for the daily inspiration they give me and to make me realize, that life must be simple.

Thanks Python!