.. image:: https://travis-ci.org/ccomb/buttervolume.svg?branch=master
:target: https://travis-ci.org/ccomb/buttervolume
:alt: Travis state
BTRFS Volume plugin for Docker
==============================
**What will Buttervolume allow you to do?**
- Quickly recover recent data after an exploit or failure of your web sites or applications
- Quickly rollback your data to a previous version after a failed upgrade
- Implement automatic upgrade of your applications without fear
- Keep an history of your data
- Make many backups without consuming more disk space than needed
- Build a resilient hosting cluster with data replication
- Quickly move your applications between nodes
- Create preconfigured or templated applications to deploy in seconds
**What can Buttervolume do?**
- Snapshot your Docker volumes
- Restore a snapshot to its original volume or under a new volume
- List and remove existing snapshots of your volumes
- Clone your Docker volumes
- Replicate or Sync your volumes to another host
- Run periodic snapshots, sync or replication of your volumes
- Remove your old snapshots periodically
- Pause or resume the periodic jobs, either individually or globally
**How does it work?**
Buttervolume is a Docker Volume Plugin that stores each Docker volume as a
BTRFS subvolume.
.. contents::
Introduction
************
`BTRFS <https://btrfs.wiki.kernel.org/>`_ is a next-generation copy-on-write
filesystem with subvolume and snapshot support. A BTRFS `subvolume
<https://btrfs.wiki.kernel.org/index.php/SysadminGuide#Subvolumes>`_ can be
seen as an independant file namespace that can live in a directory and can be
mounted as a filesystem and snapshotted individually.
On the other hand, `Docker volumes
<https://docs.docker.com/storage/volumes/>`_ are commonly used
to store persistent data of stateful containers, such as a MySQL/PostgreSQL
database or an upload directory of a CMS. By default, Docker volumes are just
local directories in the host filesystem. A number of `Volume plugins
<https://docs.docker.com/engine/extend/legacy_plugins/#/volume-plugins>`_
already exist for various storage backends, including distributed filesystems,
but small clusters often can't afford to deploy a distributed filesystem.
We believe BTRFS subvolumes are a powerful and lightweight storage solution for
Docker volumes, allowing fast and easy replication (and backup) across several
nodes of a small cluster.
Prerequisites
*************
Make sure the directory ``/var/lib/buttervolume/`` is living in a BTRFS
filesystem. It can be a BTRFS mountpoint or a BTRFS subvolume or both.
You should also create the directories for the config and ssh on the host::
sudo mkdir /var/lib/buttervolume
sudo mkdir /var/lib/buttervolume/config
sudo mkdir /var/lib/buttervolume/ssh
Build and run as a contributor
******************************
If you want to be a contributor, read this chapter. Otherwise jump to the next section.
You first need to create a root filesystem for the plugin, using the provided Dockerfile::
git clone https://github.com/ccomb/buttervolume
./build.sh
By default the plugin is built for the latest commit (HEAD). You can build another version by specifying it like this::
./build.sh 3.7
At this point, you can set the SSH_PORT option for the plugin by running::
docker plugin set ccomb/buttervolume SSH_PORT=1122
Note that this option is only relevant if you use the replication feature between two nodes.
Now you can enable the plugin, which should start buttervolume in the plugin
container::
docker plugin enable ccomb/buttervolume:HEAD
You can check it is responding by running a buttervolume command::
export RUNCROOT=/run/docker/runtime-runc/plugins.moby/ # or /run/docker/plugins/runtime-root/plugins.moby/
alias drunc="sudo runc --root $RUNCROOT"
alias buttervolume="drunc exec -t $(drunc list|tail -n+2|awk '{print $1}') buttervolume"
sudo buttervolume scheduled
Increase the log level by writing a `/var/lib/buttervolume/config/config.ini` file with::
[DEFAULT]
TIMER = 120
Then check the logs with::
sudo journalctl -f -u docker.service
You can also locally install and run the plugin in the foreground with::
python3 -m venv venv
./venv/bin/python setup.py develop
sudo ./venv/bin/buttervolume run
Then you can use the buttervolume CLI that was installed in developer mode in the venv::
./venv/bin/buttervolume --version
Install and run as a user
*************************
If the plugin is already pushed to the image repository, you can install it with::
docker plugin install ccomb/buttervolume
Check it is running::
docker plugin ls
Find your runc root, then define useful aliases::
export RUNCROOT=/run/docker/runtime-runc/plugins.moby/ # or /run/docker/plugins/runtime-root/plugins.moby/
alias drunc="sudo runc --root $RUNCROOT"
alias buttervolume="drunc exec -t $(drunc list|tail -n+2|awk '{print $1}') buttervolume"
And try a buttervolume command::
buttervolume scheduled
Or create a volume with the driver. Note that the name of the driver is the
name of the plugin::
docker volume create -d ccomb/buttervolume:latest myvolume
Note that instead of using aliases, you can also define functions that you
can put in your .bash_profile or .bash_aliases::
function drunc () {
RUNCROOT=/run/docker/runtime-runc/plugins.moby/ # or /run/docker/plugins/runtime-root/plugins.moby/
sudo runc --root $RUNCROOT $@
}
function buttervolume () {
drunc exec -t $(docker plugin ls --no-trunc | grep 'ccomb/buttervolume:latest' | awk '{print $1}') buttervolume $@
}
Upgrade
*******
You must force disable it before reinstalling it (as explained in the docker documentation)::
docker plugin disable -f ccomb/buttervolume
docker plugin rm -f ccomb/buttervolume
docker plugin install ccomb/buttervolume
Configure
*********
You can configure the following variables:
* ``DRIVERNAME``: the full name of the driver (with the tag)
* ``VOLUMES_PATH``: the path where the BTRFS volumes are located
* ``SNAPSHOTS_PATH``: the path where the BTRFS snapshots are located
* ``TEST_REMOTE_PATH``: the path during unit tests where the remote BTRFS snapshots are located
* ``SCHEDULE``: the path of the scheduler configuration
* ``RUNPATH``: the path of the docker run directory (/run/docker)
* ``SOCKET``: the path of the unix socket where buttervolume listens
* ``TIMER``: the number of seconds between two runs of the scheduler jobs
* ``DTFORMAT``: the format of the datetime in the logs
* ``LOGLEVEL``: the Python log level (INFO, DEBUG, etc.)
The configuration can be done in this order of priority:
#. from an environment variable prefixed with ``BUTTERVOLUME_`` (ex: ``BUTTERVOLUME_TIMER=120``)
#. from the [DEFAULT] section of the ``/etc/buttervolume/config.ini`` file
inside the container or ``/var/lib/buttervolume/config/config.ini`` on the
host
Example of ``config.ini`` file::
[DEFAULT]
TIMER = 120
If none of this is configured, the following default values are used:
* ``DRIVERNAME = ccomb/buttervolume:latest``
* ``VOLUMES_PATH = /var/lib/buttervolume/volumes/``
* ``SNAPSHOTS_PATH = /var/lib/buttervolume/snapshots/``
* ``TEST_REMOTE_PATH = /var/lib/buttervolume/received/``
* ``SCHEDULE = /etc/buttervolume/schedule.csv``
* ``RUNPATH = /run/docker``
* ``SOCKET = $RUNPATH/plugins/btrfs.sock`` # only if run manually
* ``TIMER = 60``
* ``DTFORMAT = %Y-%m-%dT%H:%M:%S.%f``
* ``LOGLEVEL = INFO``
Usage
*****
Running the plugin
------------------
The normal way to run it is as a new-style Docker Plugin as described above in
the "Install and run" section, which will start it automatically. This will
create a ``/run/docker/plugins/<uuid>/btrfs.sock`` file to be used by the
Docker daemon. The ``<uuid>`` is the unique identifier of the `runc/OCI`
container running it. This means you can probably run several versions of the
plugin simultaneously but this is currently not recommended unless you keep in
mind the volumes and snapshots are in the same place for the different
versions. Otherwise you can configure a different path for the volumes and
snapshots of each different versions using the ``config.ini`` file.
Then the name of the volume driver is the name of the plugin::
docker volume create -d ccomb/buttervolume:latest myvolume
or::
docker volume create --volume-driver=ccomb/buttervolume:latest
When creating a volume, you can choose to disable copy-on-write on a per-volume
basis. Just use the `-o` or `--opt` option as defined in the `Docker documentation
<https://docs.docker.com/engine/reference/commandline/volume_create/#options>`_ ::
docker volume create -d ccomb/buttervolume -o copyonwrite=false myvolume
Running the plugin locally or in legacy mode
--------------------------------------------
If you installed it locally as a Python distribution, you can also
start it manually with::
sudo buttervolume run
In this case it will create a unix socket in ``/run/docker/plugins/btrfs.sock``
for use by Docker with the legacy plugin system. Then the name of the volume
driver is the name of the socket file::
docker volume create -d btrfs myvolume
or::
docker create --volume-driver=btrfs
When started, the plugin will also start its own scheduler to run periodic jobs
(such as a snapshot, replication, purge or synchronization)
Creating and deleting volumes
-----------------------------
Once the plugin is running, whenever you create a container you can specify the
volume driver with ``docker create --volume-driver=ccomb/buttervolume --name <name>
<image>``. You can also manually create a BTRFS volume with ``docker volume
create -d ccomb/buttervolume``. It also works with docker-compose, by specifying the
``ccomb/buttervolume`` driver in the ``volumes`` section of the compose file.
When you delete the volume with ``docker rm -v <container>`` or ``docker volume
rm <volume>``, the BTRFS subvolume is deleted. If you snapshotted the volume
elsewhere in the meantime, the snapshots won't be deleted.
Managing volumes and snapshots
------------------------------
When buttervolume is installed, it provides a command line tool
``buttervolume``, with the following subcommands::
run Run the plugin in foreground
snapshot Snapshot a volume
snapshots List snapshots
schedule Schedule, unschedule, pause or resume a periodic snapshot, replication, synchronization or purge
scheduled List, pause or resume all the scheduled actions
restore Restore a snapshot (optionally to a different volume)
clone Clone a volume as new volume
send Send a snapshot to another host
sync Synchronise a volume from a remote host volume
rm Delete a snapshot
purge Purge old snapshot using a purge pattern
Create a snapshot
-----------------
You can create a readonly snapshot of the volume with::
buttervolume snapshot <volume>
The volumes are currently expected to live in ``/var/lib/buttervolume/volumes`` and
the snapshot will be created in ``/var/lib/buttervolume/snapshots``, by appending the
datetime to the name of the volume, separated with ``@``.
List the snapshots
------------------
You can list all the snapshots::
buttervolume snapshots
or just the snapshots corresponding to a volume with::
buttervolume snapshots <volume>
``<volume>`` is the name of the volume, not the full path. It is expected
to live in ``/var/lib/buttervolume/volumes``.
Restore a snapshot
------------------
You can restore a snapshot as a volume. The current volume will first
be snapshotted, deleted, then replaced with the snapshot. If you provide a
volume name instead of a snapshot, the **latest snapshot** is restored. So no
data is lost if you do something wrong. Please take care of stopping the
container before restoring a snapshot::
buttervolume restore <snapshot>
``<snapshot>`` is the name of the snapshot, not the full path. It is expected
to live in ``/var/lib/buttervolume/snapshots``.
By default, the volume name corresponds to the volume the snapshot was created
from. But you can optionally restore the snapshot to a different volume name by
adding the target as the second argument::
buttervolume restore <snapshot> <volume>
Clone a volume
------------------
You can clone a volume as a new volume. The current volume will be cloned
as a new volume name given as parameter. Please take care of stopping the
container before cloning a volume::
buttervolume clone <volume> <new_volume>
``<volume>`` is the name of the volume to be cloned, not the full path. It is expected
to live in ``/var/lib/buttervolume/volumes``.
``<new_volume>`` is the name of the new volume to be created as clone of previous one,
not the full path. It is expected to be created in ``/var/lib/buttervolume/volumes``.
Delete a snapshot
-----------------
You can delete a snapshot with::
buttervolume rm <snapshot>
``<snapshot>`` is the name of the snapshot, not the full path. It is expected
to live in ``/var/lib/buttervolume/snapshots``.
Replicate a snapshot to another host
------------------------------------
You can incrementally send snapshots to another host, so that data is
replicated to several machines, allowing to quickly move a stateful docker
container to another host. The first snapshot is first sent as a whole, then
the next snapshots are used to only send the difference between the current one
and the previous one. This allows to replicate snapshots very often without
consuming a lot of bandwith or disk space::
buttervolume send <host> <snapshot>
``<snapshot>`` is the name of the snapshot, not the full path. It is expected
to live in ``/var/lib/buttervolume/snapshots`` and is replicated to the same path on
the remote host.
``<host>`` is the hostname or IP address of the remote host. The snapshot is
currently sent using BTRFS send/receive through ssh, with an ssh server direcly
included in the plugin. This requires that ssh keys be present and already
authorized on the target host (under ``/var/lib/buttervolume/ssh``), and that
the ``StrictHostKeyChecking no`` option be enabled in
``/var/lib/buttervolume/ssh/config`` on local host.
Please note you have to restart you docker daemons each time you change ssh configuration.
The default SSH_PORT of the ssh server included in the plugin is **1122**. You can
change it with `docker plugin set ccomb/buttervolume SSH_PORT=<PORT>` before
enabling the plugin.
Synchronize a volume from another host volume
---------------------------------------------
You can receive data from a remote volume, so in case there is a volume on
the remote host with the **same name**, it will get new and most recent data
from the distant volume and replace in the local volume. Before running the
``rsync`` command a snapshot is made on the local machine to manage recovery::
buttervolume sync <volume> <host1> [<host2>][...]
The intent is to synchronize a volume between multi hosts on running
containers, so you should schedule that action on each nodes from all remote
hosts.
.. note::
As we are pulling data from multiple hosts we never remove data, consider
removing scheduled actions before removing data on each hosts.
.. warning::
Make sure your application is able to handle such synchronisation
Purge old snapshots
-------------------
You can purge old snapshot corresponding to the specified volume, using a retention pattern::
buttervolume purge <pattern> <volume>
If you're unsure whether you retention pattern is correct, you can run the
purge with the ``--dryrun`` option, to inspect what snapshots would be deleted,
without deleting them::
buttervolume purge --dryrun <pattern> <volume>
``<volume>`` is the name of the volume, not the full path. It is expected
to live in ``/var/lib/buttervolume/volumes``.
``<pattern>`` is the snapshot retention pattern. It is a semicolon-separated
list of time length specifiers with a unit. Units can be ``m`` for minutes,
``h`` for hours, ``d`` for days, ``w`` for weeks, ``y`` for years. The pattern
should have at least 2 items.
Here are a few examples of retention patterns:
- ``4h:1d:2w:2y``
Keep all snapshots in the last four hours, then keep only one snapshot
every four hours during the first day, then one snapshot per day during
the first two weeks, then one snapshot every two weeks during the first
two years, then delete everything after two years.
- ``4h:1w``
keep all snapshots during the last four hours, then one snapshot every
four hours during the first week, then delete older snapshots.
- ``2h:2h``
keep all snapshots during the last two hours, then delete older snapshots.
Schedule a job
--------------
You can schedule, pause or resume a periodic job, such as a snapshot, a
replication, a synchronization or a purge. The schedule it self is stored in
``/etc/buttervolume/schedule.csv``.
**Schedule a snapshot** of a volume every 60 minutes::
buttervolume schedule snapshot 60 <volume>
Pause this schedule::
buttervolume schedule snapshot pause <volume>
Resume this schedule::
buttervolume schedule snapshot resume <volume>
Remove this schedule by specifying a timer of 0 min (or `delete`)::
buttervolume schedule snapshot 0 <volume>
**Schedule a replication** of volume ``foovolume`` to ``remote_host``::
buttervolume schedule replicate:remote_host 3600 foovolume
Remove the same schedule::
buttervolume schedule replicate:remote_host 0 foovolume
**Schedule a purge** every hour of the snapshots of volume ``foovolume``, but
keep all the snapshots in the last 4 hours, then only one snapshot every 4
hours during the first week, then one snapshot every week during one year, then
delete all snapshots after one year::
buttervolume schedule purge:4h:1w:1y 60 foovolume
Remove the same schedule::
buttervolume schedule purge:4h:1w:1y 0 foovolume
Using the right combination of snapshot schedule timer, purge schedule timer
and purge retention pattern, you can create you own backup strategy, from the
simplest ones to more elaborate ones. A common one is the following::
buttervolume schedule snapshot 1440 <volume>
buttervolume schedule purge:1d:4w:1y 1440 <volume>
It should create a snapshot every day, then purge snapshots everydays while
keeping all snapshots in the last 24h, then one snapshot per day during one
month, then one snapshot per month during only one year.
**Schedule a syncrhonization** of volume ``foovolume`` from ``remote_host1``
abd ``remote_host2``::
buttervolume schedule synchronize:remote_host1,remote_host2 60 foovolume
Remove the same schedule::
buttervolume schedule synchronize:remote_host1,remote_host2 0 foovolume
List, pause or resume all scheduled jobs
----------------------------------------
You can list all the scheduled job with::
buttervolume scheduled
or::
buttervolume scheduled list
It will display the schedule in the same format used for adding the schedule,
which is convenient to remove an existing schedule or add a similar one.
Pause all the scheduled jobs::
buttervolume scheduled pause
Resume all the scheduled jobs::
buttervolume scheduled resume
The global job pause/resume feature is implemented separately from the
individual job pause/resume. So it will not affect your individual
pause/resume settings.
Copy-on-write
-------------
Copy-On-Write is enabled by default. You can disable it if you really want.
Why disabling copy-on-write? If your docker volume stores databases such as
PostgreSQL or MariaDB, the copy-on-write feature may hurt performance, though
the latest kernels have improved a lot. The good news is that disabling
copy-on-write does not prevent from doing snaphots.
Testing
*******
If your volumes directory is a BTRFS partition or volume, tests can be run
with::
./test.sh
Working without a BTRFS partition
*********************************
If you have no BTRFS partitions or volumes you can setup a virtual partition
in a file as follows (tested on Debian 8):
Setup BTRFS virtual partition::
sudo qemu-img create /var/lib/docker/btrfs.img 10G
sudo mkfs.btrfs /var/lib/docker/btrfs.img
.. note::
you can ignore the error, in fact the new FS is formatted
Mount the partition somewhere temporarily to create 3 new BTRFS subvolumes::
sudo -s
mkdir /tmp/btrfs_mount_point
mount -o loop /var/lib/docker/btrfs.img /tmp/btrfs_mount_point/
btrfs subvolume create /tmp/btrfs_mount_point/snapshots
btrfs subvolume create /tmp/btrfs_mount_point/volumes
btrfs subvolume create /tmp/btrfs_mount_point/received
umount /tmp/btrfs_mount_point/
rm -r /tmp/btrfs_mount_point/
Stop docker, create required mount point and restart docker::
systemctl stop docker
mkdir -p /var/lib/buttervolume/volumes
mkdir -p /var/lib/buttervolume/snapshots
mkdir -p /var/lib/buttervolume/received
mount -o loop,subvol=volumes /var/lib/docker/btrfs.img /var/lib/buttervolume/volumes
mount -o loop,subvol=snapshots /var/lib/docker/btrfs.img /var/lib/buttervolume/snapshots
mount -o loop,subvol=received /var/lib/docker/btrfs.img /var/lib/buttervolume/received
systemctl start docker
Once you are done with your test, you can unmount those volumes and you will
find back your previous docker volumes::
systemctl stop docker
umount /var/lib/buttervolume/volumes
umount /var/lib/buttervolume/snapshots
umount /var/lib/buttervolume/received
systemctl start docker
rm /var/lib/docker/btrfs.img
Migrate to version 3
********************
If you're currently using Buttervolume 1.x or 2.0 in production, you must
carefully follow the guidelines below to migrate to version 3.
First copy the ssh and config files and disable the scheduler::
sudo -s
docker cp buttervolume_plugin_1:/etc/buttervolume /var/lib/buttervolume/config
docker cp buttervolume_plugin_1:/root/.ssh /var/lib/buttervolume/ssh
mv /var/lib/buttervolume/config/schedule.csv /var/lib/buttervolume/config/schedule.csv.disabled
Then stop all your containers, excepted buttervolume
Now snapshot and delete all your volumes::
volumes=$(docker volume ls -f driver=ccomb/buttervolume:latest --format "{{.Name}}")
# or: # volumes=$(docker volume ls -f driver=ccomb/buttervolume:latest|tail -n+2|awk '{print $2}')
echo $volumes
for v in $volumes; do docker exec buttervolume_plugin_1 buttervolume snapshot $v; done
for v in $volumes; do docker volume rm $v; done
Then stop the buttervolume container, **remove the old btrfs.sock file**, and
restart docker::
docker stop buttervolume_plugin_1
docker rm -v buttervolume_plugin_1
rm /run/docker/plugins/btrfs.sock
systemctl stop docker
If you were using Buttervolume 1.x, you must move your snapshots to the new location::
mkdir /var/lib/buttervolume/snapshots
cd /var/lib/docker/snapshots
for i in *; do btrfs subvolume snapshot -r $i /var/lib/buttervolume/snapshots/$i; done
Restore /var/lib/docker/volumes as the original folder::
cd /var/lib/docker
mkdir volumes.new
mv volumes/* volumes.new/
umount volumes # if this was a mounted btrfs subvolume
mv volumes.new/* volumes/
rmdir volumes.new
systemctl start docker
Change your volume configurations (in your compose files) to use the new
``ccomb/buttervolume:latest`` driver name instead of ``btrfs``
Then start the new buttervolume 3.x as a managed plugin and check it is started::
docker plugin install ccomb/buttervolume:latest
docker plugin ls
Then recreate all your volumes with the new driver and restore them from the snapshots::
for v in $volumes; do docker volume create -d ccomb/buttervolume:latest $v; done
export RUNCROOT=/run/docker/runtime-runc/plugins.moby/ # or /run/docker/plugins/runtime-root/plugins.moby/
alias drunc="sudo runc --root $RUNCROOT"
alias buttervolume="drunc exec -t $(drunc list|tail -n+2|awk '{print $1}') buttervolume"
# WARNING : check the the volume you will restore are the correct ones
for v in $volumes; do buttervolume restore $v; done
Then restart your containers, check they are ok with the correct data.
Reenable the schedule::
mv /var/lib/buttervolume/config/schedule.csv.disabled /var/lib/buttervolume/config/schedule.csv
Credits
*******
Thanks to:
- Christophe Combelles
- Pierre Verkest
- Marcelo Ochoa
- Christoph Rist
- Philip Nagler-Frank
- Yoann MOUGNIBAS
CHANGELOG
=========
3.12 (2024-11-05)
*****************
- Updated the Docker image to Debian 12
- changed requests-unixsocket to requests-unixsocket2
3.11 (2024-10-12)
*****************
- updated the doc to link to the new name
- Updated the Docker image
3.10 (2023-04-09)
*****************
- updated dependencies
- fixed bug #45
3.9 (2022-10-11)
****************
- Fixed a crash when option_copyonwrite is not set
- Restored the test suite
- Improved and simplified the build script and test script
3.8 (2022-10-07)
****************
- Switched to copy-on-write by default
- Allow to choose to enable/disable copy-on-write for each volume
- Allow to change the default SSH_PORT in the plugin config
- Updated the base docker image and dependencies
- Added an option to show the version number
- Improved documentation
3.7 (2018-12-13)
****************
- Unpinned urllib3
3.6 (2018-12-11)
****************
- Fixed zombie sshd processes inside the plugin
- Minor documentation change
3.5 (2018-06-07)
****************
- Improved documentation
3.4 (2018-04-27)
****************
- Fix rights at startup so that ssh works
3.3 (2018-04-27)
****************
- Fixed a bug preventing a start in certain conditions
3.2 (2018-04-27)
****************
- Fixed the socket path for startup
3.1 (2018-04-27)
****************
- Fixed a declaration in Python 3.6
- Automatically detects the btrfs.sock path
- Made the runpath and drivername configurable
3.0 (2018-04-24)
****************
- Now use the docker *managed plugin* system
- Stop the scheduler before shutdown to avoid a 5s timeout
- Improved logging
- Improved the migration doc from version 1 or 2
2.0 (2018-03-24)
****************
- BREAKING CHANGE: Please read the migration path from version 1 to version 2:
BTRFS volumes and snapshots are now stored by default in different directories under ``/var/lib/buttervolume``
- Configuration possible through environment variables or a ``config.ini`` file
- implemented ``VolumeDriver.Capabilities`` and just return ``'local'``
- other minor fixes and improvements
1.4 (2018-02-01)
****************
- Add clone command
- replace sync by `btrfs filesystem sync`
1.3.1 (2017-10-22)
******************
- fixed packaging (missing README)
1.3 (2017-07-30)
****************
- fixed the cli for the restore command
1.2 (2017-07-16)
****************
- fixed the purge algorithm
1.1 (2017-07-13)
****************
- allow to restore a snapshot to a different volume name
1.0 (2017-05-24)
****************
- initial release, used in production
Raw data
{
"_id": null,
"home_page": "https://github.com/ccomb/buttervolume",
"name": "buttervolume",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": null,
"author": "Christophe Combelles",
"author_email": "ccomb@free.fr",
"download_url": "https://files.pythonhosted.org/packages/94/2f/fa543a33c5ee74242e1e68be4f778805239c936953524300be2df315374c/buttervolume-3.12.tar.gz",
"platform": null,
"description": ".. image:: https://travis-ci.org/ccomb/buttervolume.svg?branch=master\n :target: https://travis-ci.org/ccomb/buttervolume\n :alt: Travis state\n\n\nBTRFS Volume plugin for Docker\n==============================\n\n**What will Buttervolume allow you to do?**\n\n- Quickly recover recent data after an exploit or failure of your web sites or applications\n- Quickly rollback your data to a previous version after a failed upgrade\n- Implement automatic upgrade of your applications without fear\n- Keep an history of your data\n- Make many backups without consuming more disk space than needed\n- Build a resilient hosting cluster with data replication\n- Quickly move your applications between nodes\n- Create preconfigured or templated applications to deploy in seconds\n\n**What can Buttervolume do?**\n\n- Snapshot your Docker volumes\n- Restore a snapshot to its original volume or under a new volume\n- List and remove existing snapshots of your volumes\n- Clone your Docker volumes\n- Replicate or Sync your volumes to another host\n- Run periodic snapshots, sync or replication of your volumes\n- Remove your old snapshots periodically\n- Pause or resume the periodic jobs, either individually or globally\n\n**How does it work?**\n\nButtervolume is a Docker Volume Plugin that stores each Docker volume as a\nBTRFS subvolume.\n\n\n.. contents::\n\n\nIntroduction\n************\n\n`BTRFS <https://btrfs.wiki.kernel.org/>`_ is a next-generation copy-on-write\nfilesystem with subvolume and snapshot support. A BTRFS `subvolume\n<https://btrfs.wiki.kernel.org/index.php/SysadminGuide#Subvolumes>`_ can be\nseen as an independant file namespace that can live in a directory and can be\nmounted as a filesystem and snapshotted individually.\n\nOn the other hand, `Docker volumes\n<https://docs.docker.com/storage/volumes/>`_ are commonly used\nto store persistent data of stateful containers, such as a MySQL/PostgreSQL\ndatabase or an upload directory of a CMS. By default, Docker volumes are just\nlocal directories in the host filesystem. A number of `Volume plugins\n<https://docs.docker.com/engine/extend/legacy_plugins/#/volume-plugins>`_\nalready exist for various storage backends, including distributed filesystems,\nbut small clusters often can't afford to deploy a distributed filesystem.\n\nWe believe BTRFS subvolumes are a powerful and lightweight storage solution for\nDocker volumes, allowing fast and easy replication (and backup) across several\nnodes of a small cluster.\n\nPrerequisites\n*************\n\nMake sure the directory ``/var/lib/buttervolume/`` is living in a BTRFS\nfilesystem. It can be a BTRFS mountpoint or a BTRFS subvolume or both.\n\nYou should also create the directories for the config and ssh on the host::\n\n sudo mkdir /var/lib/buttervolume\n sudo mkdir /var/lib/buttervolume/config\n sudo mkdir /var/lib/buttervolume/ssh\n\n\nBuild and run as a contributor\n******************************\n\nIf you want to be a contributor, read this chapter. Otherwise jump to the next section.\n\nYou first need to create a root filesystem for the plugin, using the provided Dockerfile::\n\n git clone https://github.com/ccomb/buttervolume\n ./build.sh\n\nBy default the plugin is built for the latest commit (HEAD). You can build another version by specifying it like this::\n\n ./build.sh 3.7\n\nAt this point, you can set the SSH_PORT option for the plugin by running::\n\n docker plugin set ccomb/buttervolume SSH_PORT=1122\n\nNote that this option is only relevant if you use the replication feature between two nodes.\n\nNow you can enable the plugin, which should start buttervolume in the plugin\ncontainer::\n\n docker plugin enable ccomb/buttervolume:HEAD\n\nYou can check it is responding by running a buttervolume command::\n\n export RUNCROOT=/run/docker/runtime-runc/plugins.moby/ # or /run/docker/plugins/runtime-root/plugins.moby/\n alias drunc=\"sudo runc --root $RUNCROOT\"\n alias buttervolume=\"drunc exec -t $(drunc list|tail -n+2|awk '{print $1}') buttervolume\"\n sudo buttervolume scheduled\n\nIncrease the log level by writing a `/var/lib/buttervolume/config/config.ini` file with::\n\n [DEFAULT]\n TIMER = 120\n\nThen check the logs with::\n\n sudo journalctl -f -u docker.service\n\nYou can also locally install and run the plugin in the foreground with::\n\n python3 -m venv venv\n ./venv/bin/python setup.py develop\n sudo ./venv/bin/buttervolume run\n\nThen you can use the buttervolume CLI that was installed in developer mode in the venv::\n\n ./venv/bin/buttervolume --version\n\n\nInstall and run as a user\n*************************\n\nIf the plugin is already pushed to the image repository, you can install it with::\n\n docker plugin install ccomb/buttervolume\n\nCheck it is running::\n\n docker plugin ls\n\nFind your runc root, then define useful aliases::\n\n export RUNCROOT=/run/docker/runtime-runc/plugins.moby/ # or /run/docker/plugins/runtime-root/plugins.moby/\n alias drunc=\"sudo runc --root $RUNCROOT\"\n alias buttervolume=\"drunc exec -t $(drunc list|tail -n+2|awk '{print $1}') buttervolume\"\n\nAnd try a buttervolume command::\n\n buttervolume scheduled\n\nOr create a volume with the driver. Note that the name of the driver is the\nname of the plugin::\n\n docker volume create -d ccomb/buttervolume:latest myvolume\n\nNote that instead of using aliases, you can also define functions that you\ncan put in your .bash_profile or .bash_aliases::\n\n function drunc () {\n RUNCROOT=/run/docker/runtime-runc/plugins.moby/ # or /run/docker/plugins/runtime-root/plugins.moby/\n sudo runc --root $RUNCROOT $@\n }\n function buttervolume () {\n drunc exec -t $(docker plugin ls --no-trunc | grep 'ccomb/buttervolume:latest' | awk '{print $1}') buttervolume $@\n }\n\n\nUpgrade\n*******\n\nYou must force disable it before reinstalling it (as explained in the docker documentation)::\n\n docker plugin disable -f ccomb/buttervolume\n docker plugin rm -f ccomb/buttervolume\n docker plugin install ccomb/buttervolume\n\n\nConfigure\n*********\n\nYou can configure the following variables:\n\n * ``DRIVERNAME``: the full name of the driver (with the tag)\n * ``VOLUMES_PATH``: the path where the BTRFS volumes are located\n * ``SNAPSHOTS_PATH``: the path where the BTRFS snapshots are located\n * ``TEST_REMOTE_PATH``: the path during unit tests where the remote BTRFS snapshots are located\n * ``SCHEDULE``: the path of the scheduler configuration\n * ``RUNPATH``: the path of the docker run directory (/run/docker)\n * ``SOCKET``: the path of the unix socket where buttervolume listens\n * ``TIMER``: the number of seconds between two runs of the scheduler jobs\n * ``DTFORMAT``: the format of the datetime in the logs\n * ``LOGLEVEL``: the Python log level (INFO, DEBUG, etc.)\n\nThe configuration can be done in this order of priority:\n\n #. from an environment variable prefixed with ``BUTTERVOLUME_`` (ex: ``BUTTERVOLUME_TIMER=120``)\n #. from the [DEFAULT] section of the ``/etc/buttervolume/config.ini`` file\n inside the container or ``/var/lib/buttervolume/config/config.ini`` on the\n host\n\nExample of ``config.ini`` file::\n\n [DEFAULT]\n TIMER = 120\n\nIf none of this is configured, the following default values are used:\n\n * ``DRIVERNAME = ccomb/buttervolume:latest``\n * ``VOLUMES_PATH = /var/lib/buttervolume/volumes/``\n * ``SNAPSHOTS_PATH = /var/lib/buttervolume/snapshots/``\n * ``TEST_REMOTE_PATH = /var/lib/buttervolume/received/``\n * ``SCHEDULE = /etc/buttervolume/schedule.csv``\n * ``RUNPATH = /run/docker``\n * ``SOCKET = $RUNPATH/plugins/btrfs.sock`` # only if run manually\n * ``TIMER = 60``\n * ``DTFORMAT = %Y-%m-%dT%H:%M:%S.%f``\n * ``LOGLEVEL = INFO``\n\n\nUsage\n*****\n\nRunning the plugin\n------------------\n\nThe normal way to run it is as a new-style Docker Plugin as described above in\nthe \"Install and run\" section, which will start it automatically. This will\ncreate a ``/run/docker/plugins/<uuid>/btrfs.sock`` file to be used by the\nDocker daemon. The ``<uuid>`` is the unique identifier of the `runc/OCI`\ncontainer running it. This means you can probably run several versions of the\nplugin simultaneously but this is currently not recommended unless you keep in\nmind the volumes and snapshots are in the same place for the different\nversions. Otherwise you can configure a different path for the volumes and\nsnapshots of each different versions using the ``config.ini`` file.\n\nThen the name of the volume driver is the name of the plugin::\n\n docker volume create -d ccomb/buttervolume:latest myvolume\n\nor::\n\n docker volume create --volume-driver=ccomb/buttervolume:latest\n\nWhen creating a volume, you can choose to disable copy-on-write on a per-volume\nbasis. Just use the `-o` or `--opt` option as defined in the `Docker documentation\n<https://docs.docker.com/engine/reference/commandline/volume_create/#options>`_ ::\n\n docker volume create -d ccomb/buttervolume -o copyonwrite=false myvolume\n\nRunning the plugin locally or in legacy mode\n--------------------------------------------\n\nIf you installed it locally as a Python distribution, you can also\nstart it manually with::\n\n sudo buttervolume run\n\nIn this case it will create a unix socket in ``/run/docker/plugins/btrfs.sock``\nfor use by Docker with the legacy plugin system. Then the name of the volume\ndriver is the name of the socket file::\n\n docker volume create -d btrfs myvolume\n\nor::\n\n docker create --volume-driver=btrfs\n\nWhen started, the plugin will also start its own scheduler to run periodic jobs\n(such as a snapshot, replication, purge or synchronization)\n\n\nCreating and deleting volumes\n-----------------------------\n\nOnce the plugin is running, whenever you create a container you can specify the\nvolume driver with ``docker create --volume-driver=ccomb/buttervolume --name <name>\n<image>``. You can also manually create a BTRFS volume with ``docker volume\ncreate -d ccomb/buttervolume``. It also works with docker-compose, by specifying the\n``ccomb/buttervolume`` driver in the ``volumes`` section of the compose file.\n\nWhen you delete the volume with ``docker rm -v <container>`` or ``docker volume\nrm <volume>``, the BTRFS subvolume is deleted. If you snapshotted the volume\nelsewhere in the meantime, the snapshots won't be deleted.\n\n\nManaging volumes and snapshots\n------------------------------\n\nWhen buttervolume is installed, it provides a command line tool\n``buttervolume``, with the following subcommands::\n\n run Run the plugin in foreground\n snapshot Snapshot a volume\n snapshots List snapshots\n schedule Schedule, unschedule, pause or resume a periodic snapshot, replication, synchronization or purge\n scheduled List, pause or resume all the scheduled actions\n restore Restore a snapshot (optionally to a different volume)\n clone Clone a volume as new volume\n send Send a snapshot to another host\n sync Synchronise a volume from a remote host volume\n rm Delete a snapshot\n purge Purge old snapshot using a purge pattern\n\n\nCreate a snapshot\n-----------------\n\nYou can create a readonly snapshot of the volume with::\n\n buttervolume snapshot <volume>\n\nThe volumes are currently expected to live in ``/var/lib/buttervolume/volumes`` and\nthe snapshot will be created in ``/var/lib/buttervolume/snapshots``, by appending the\ndatetime to the name of the volume, separated with ``@``.\n\n\nList the snapshots\n------------------\n\nYou can list all the snapshots::\n\n buttervolume snapshots\n\nor just the snapshots corresponding to a volume with::\n\n buttervolume snapshots <volume>\n\n``<volume>`` is the name of the volume, not the full path. It is expected\nto live in ``/var/lib/buttervolume/volumes``.\n\n\nRestore a snapshot\n------------------\n\nYou can restore a snapshot as a volume. The current volume will first\nbe snapshotted, deleted, then replaced with the snapshot. If you provide a\nvolume name instead of a snapshot, the **latest snapshot** is restored. So no\ndata is lost if you do something wrong. Please take care of stopping the\ncontainer before restoring a snapshot::\n\n buttervolume restore <snapshot>\n\n``<snapshot>`` is the name of the snapshot, not the full path. It is expected\nto live in ``/var/lib/buttervolume/snapshots``.\n\nBy default, the volume name corresponds to the volume the snapshot was created\nfrom. But you can optionally restore the snapshot to a different volume name by\nadding the target as the second argument::\n\n buttervolume restore <snapshot> <volume>\n\n\nClone a volume\n------------------\n\nYou can clone a volume as a new volume. The current volume will be cloned\nas a new volume name given as parameter. Please take care of stopping the\ncontainer before cloning a volume::\n\n buttervolume clone <volume> <new_volume>\n\n``<volume>`` is the name of the volume to be cloned, not the full path. It is expected\nto live in ``/var/lib/buttervolume/volumes``.\n``<new_volume>`` is the name of the new volume to be created as clone of previous one,\nnot the full path. It is expected to be created in ``/var/lib/buttervolume/volumes``.\n\n\nDelete a snapshot\n-----------------\n\nYou can delete a snapshot with::\n\n buttervolume rm <snapshot>\n\n``<snapshot>`` is the name of the snapshot, not the full path. It is expected\nto live in ``/var/lib/buttervolume/snapshots``.\n\n\nReplicate a snapshot to another host\n------------------------------------\n\nYou can incrementally send snapshots to another host, so that data is\nreplicated to several machines, allowing to quickly move a stateful docker\ncontainer to another host. The first snapshot is first sent as a whole, then\nthe next snapshots are used to only send the difference between the current one\nand the previous one. This allows to replicate snapshots very often without\nconsuming a lot of bandwith or disk space::\n\n buttervolume send <host> <snapshot>\n\n``<snapshot>`` is the name of the snapshot, not the full path. It is expected\nto live in ``/var/lib/buttervolume/snapshots`` and is replicated to the same path on\nthe remote host.\n\n\n``<host>`` is the hostname or IP address of the remote host. The snapshot is\ncurrently sent using BTRFS send/receive through ssh, with an ssh server direcly\nincluded in the plugin. This requires that ssh keys be present and already\nauthorized on the target host (under ``/var/lib/buttervolume/ssh``), and that\nthe ``StrictHostKeyChecking no`` option be enabled in\n``/var/lib/buttervolume/ssh/config`` on local host.\n\nPlease note you have to restart you docker daemons each time you change ssh configuration.\n\nThe default SSH_PORT of the ssh server included in the plugin is **1122**. You can\nchange it with `docker plugin set ccomb/buttervolume SSH_PORT=<PORT>` before\nenabling the plugin.\n\nSynchronize a volume from another host volume\n---------------------------------------------\n\nYou can receive data from a remote volume, so in case there is a volume on\nthe remote host with the **same name**, it will get new and most recent data\nfrom the distant volume and replace in the local volume. Before running the\n``rsync`` command a snapshot is made on the local machine to manage recovery::\n\n buttervolume sync <volume> <host1> [<host2>][...]\n\nThe intent is to synchronize a volume between multi hosts on running\ncontainers, so you should schedule that action on each nodes from all remote\nhosts.\n\n.. note::\n\n As we are pulling data from multiple hosts we never remove data, consider\n removing scheduled actions before removing data on each hosts.\n\n.. warning::\n\n Make sure your application is able to handle such synchronisation\n\n\nPurge old snapshots\n-------------------\n\nYou can purge old snapshot corresponding to the specified volume, using a retention pattern::\n\n buttervolume purge <pattern> <volume>\n\nIf you're unsure whether you retention pattern is correct, you can run the\npurge with the ``--dryrun`` option, to inspect what snapshots would be deleted,\nwithout deleting them::\n\n buttervolume purge --dryrun <pattern> <volume>\n\n``<volume>`` is the name of the volume, not the full path. It is expected\nto live in ``/var/lib/buttervolume/volumes``.\n\n``<pattern>`` is the snapshot retention pattern. It is a semicolon-separated\nlist of time length specifiers with a unit. Units can be ``m`` for minutes,\n``h`` for hours, ``d`` for days, ``w`` for weeks, ``y`` for years. The pattern\nshould have at least 2 items.\n\nHere are a few examples of retention patterns:\n\n- ``4h:1d:2w:2y``\n Keep all snapshots in the last four hours, then keep only one snapshot\n every four hours during the first day, then one snapshot per day during\n the first two weeks, then one snapshot every two weeks during the first\n two years, then delete everything after two years.\n\n- ``4h:1w``\n keep all snapshots during the last four hours, then one snapshot every\n four hours during the first week, then delete older snapshots.\n\n- ``2h:2h``\n keep all snapshots during the last two hours, then delete older snapshots.\n\n\nSchedule a job\n--------------\n\nYou can schedule, pause or resume a periodic job, such as a snapshot, a\nreplication, a synchronization or a purge. The schedule it self is stored in\n``/etc/buttervolume/schedule.csv``.\n\n**Schedule a snapshot** of a volume every 60 minutes::\n\n buttervolume schedule snapshot 60 <volume>\n\nPause this schedule::\n\n buttervolume schedule snapshot pause <volume>\n\nResume this schedule::\n\n buttervolume schedule snapshot resume <volume>\n\nRemove this schedule by specifying a timer of 0 min (or `delete`)::\n\n buttervolume schedule snapshot 0 <volume>\n\n**Schedule a replication** of volume ``foovolume`` to ``remote_host``::\n\n buttervolume schedule replicate:remote_host 3600 foovolume\n\nRemove the same schedule::\n\n buttervolume schedule replicate:remote_host 0 foovolume\n\n**Schedule a purge** every hour of the snapshots of volume ``foovolume``, but\nkeep all the snapshots in the last 4 hours, then only one snapshot every 4\nhours during the first week, then one snapshot every week during one year, then\ndelete all snapshots after one year::\n\n buttervolume schedule purge:4h:1w:1y 60 foovolume\n\nRemove the same schedule::\n\n buttervolume schedule purge:4h:1w:1y 0 foovolume\n\nUsing the right combination of snapshot schedule timer, purge schedule timer\nand purge retention pattern, you can create you own backup strategy, from the\nsimplest ones to more elaborate ones. A common one is the following::\n\n buttervolume schedule snapshot 1440 <volume>\n buttervolume schedule purge:1d:4w:1y 1440 <volume>\n\nIt should create a snapshot every day, then purge snapshots everydays while\nkeeping all snapshots in the last 24h, then one snapshot per day during one\nmonth, then one snapshot per month during only one year.\n\n**Schedule a syncrhonization** of volume ``foovolume`` from ``remote_host1``\nabd ``remote_host2``::\n\n buttervolume schedule synchronize:remote_host1,remote_host2 60 foovolume\n\nRemove the same schedule::\n\n buttervolume schedule synchronize:remote_host1,remote_host2 0 foovolume\n\n\nList, pause or resume all scheduled jobs\n----------------------------------------\n\nYou can list all the scheduled job with::\n\n buttervolume scheduled\n\nor::\n\n buttervolume scheduled list\n\nIt will display the schedule in the same format used for adding the schedule,\nwhich is convenient to remove an existing schedule or add a similar one.\n\nPause all the scheduled jobs::\n\n buttervolume scheduled pause\n\nResume all the scheduled jobs::\n\n buttervolume scheduled resume\n\nThe global job pause/resume feature is implemented separately from the\nindividual job pause/resume. So it will not affect your individual\npause/resume settings.\n\nCopy-on-write\n-------------\n\nCopy-On-Write is enabled by default. You can disable it if you really want.\n\nWhy disabling copy-on-write? If your docker volume stores databases such as\nPostgreSQL or MariaDB, the copy-on-write feature may hurt performance, though\nthe latest kernels have improved a lot. The good news is that disabling\ncopy-on-write does not prevent from doing snaphots.\n\n\nTesting\n*******\n\nIf your volumes directory is a BTRFS partition or volume, tests can be run\nwith::\n\n ./test.sh\n\n\nWorking without a BTRFS partition\n*********************************\n\nIf you have no BTRFS partitions or volumes you can setup a virtual partition\nin a file as follows (tested on Debian 8):\n\nSetup BTRFS virtual partition::\n\n sudo qemu-img create /var/lib/docker/btrfs.img 10G\n sudo mkfs.btrfs /var/lib/docker/btrfs.img\n\n.. note::\n\n you can ignore the error, in fact the new FS is formatted\n\nMount the partition somewhere temporarily to create 3 new BTRFS subvolumes::\n\n sudo -s\n mkdir /tmp/btrfs_mount_point\n mount -o loop /var/lib/docker/btrfs.img /tmp/btrfs_mount_point/\n btrfs subvolume create /tmp/btrfs_mount_point/snapshots\n btrfs subvolume create /tmp/btrfs_mount_point/volumes\n btrfs subvolume create /tmp/btrfs_mount_point/received\n umount /tmp/btrfs_mount_point/\n rm -r /tmp/btrfs_mount_point/\n\nStop docker, create required mount point and restart docker::\n\n systemctl stop docker\n mkdir -p /var/lib/buttervolume/volumes\n mkdir -p /var/lib/buttervolume/snapshots\n mkdir -p /var/lib/buttervolume/received\n mount -o loop,subvol=volumes /var/lib/docker/btrfs.img /var/lib/buttervolume/volumes\n mount -o loop,subvol=snapshots /var/lib/docker/btrfs.img /var/lib/buttervolume/snapshots\n mount -o loop,subvol=received /var/lib/docker/btrfs.img /var/lib/buttervolume/received\n systemctl start docker\n\nOnce you are done with your test, you can unmount those volumes and you will\nfind back your previous docker volumes::\n\n\n systemctl stop docker\n umount /var/lib/buttervolume/volumes\n umount /var/lib/buttervolume/snapshots\n umount /var/lib/buttervolume/received\n systemctl start docker\n rm /var/lib/docker/btrfs.img\n\n\nMigrate to version 3\n********************\n\nIf you're currently using Buttervolume 1.x or 2.0 in production, you must\ncarefully follow the guidelines below to migrate to version 3.\n\nFirst copy the ssh and config files and disable the scheduler::\n\n sudo -s\n docker cp buttervolume_plugin_1:/etc/buttervolume /var/lib/buttervolume/config\n docker cp buttervolume_plugin_1:/root/.ssh /var/lib/buttervolume/ssh\n mv /var/lib/buttervolume/config/schedule.csv /var/lib/buttervolume/config/schedule.csv.disabled\n\nThen stop all your containers, excepted buttervolume\n\nNow snapshot and delete all your volumes::\n\n volumes=$(docker volume ls -f driver=ccomb/buttervolume:latest --format \"{{.Name}}\")\n # or: # volumes=$(docker volume ls -f driver=ccomb/buttervolume:latest|tail -n+2|awk '{print $2}')\n echo $volumes\n for v in $volumes; do docker exec buttervolume_plugin_1 buttervolume snapshot $v; done\n for v in $volumes; do docker volume rm $v; done\n\nThen stop the buttervolume container, **remove the old btrfs.sock file**, and\nrestart docker::\n\n docker stop buttervolume_plugin_1\n docker rm -v buttervolume_plugin_1\n rm /run/docker/plugins/btrfs.sock\n systemctl stop docker\n\nIf you were using Buttervolume 1.x, you must move your snapshots to the new location::\n\n mkdir /var/lib/buttervolume/snapshots\n cd /var/lib/docker/snapshots\n for i in *; do btrfs subvolume snapshot -r $i /var/lib/buttervolume/snapshots/$i; done\n\nRestore /var/lib/docker/volumes as the original folder::\n\n cd /var/lib/docker\n mkdir volumes.new\n mv volumes/* volumes.new/\n umount volumes # if this was a mounted btrfs subvolume\n mv volumes.new/* volumes/\n rmdir volumes.new\n systemctl start docker\n\nChange your volume configurations (in your compose files) to use the new\n``ccomb/buttervolume:latest`` driver name instead of ``btrfs``\n\nThen start the new buttervolume 3.x as a managed plugin and check it is started::\n\n docker plugin install ccomb/buttervolume:latest\n docker plugin ls\n\nThen recreate all your volumes with the new driver and restore them from the snapshots::\n\n for v in $volumes; do docker volume create -d ccomb/buttervolume:latest $v; done\n export RUNCROOT=/run/docker/runtime-runc/plugins.moby/ # or /run/docker/plugins/runtime-root/plugins.moby/\n alias drunc=\"sudo runc --root $RUNCROOT\"\n alias buttervolume=\"drunc exec -t $(drunc list|tail -n+2|awk '{print $1}') buttervolume\"\n # WARNING : check the the volume you will restore are the correct ones\n for v in $volumes; do buttervolume restore $v; done\n\nThen restart your containers, check they are ok with the correct data.\n\nReenable the schedule::\n\n mv /var/lib/buttervolume/config/schedule.csv.disabled /var/lib/buttervolume/config/schedule.csv\n\nCredits\n*******\n\nThanks to:\n\n- Christophe Combelles\n- Pierre Verkest\n- Marcelo Ochoa\n- Christoph Rist\n- Philip Nagler-Frank\n- Yoann MOUGNIBAS\n\n\nCHANGELOG\n=========\n3.12 (2024-11-05)\n*****************\n\n- Updated the Docker image to Debian 12\n- changed requests-unixsocket to requests-unixsocket2\n\n3.11 (2024-10-12)\n*****************\n\n- updated the doc to link to the new name\n- Updated the Docker image\n\n3.10 (2023-04-09)\n*****************\n\n- updated dependencies\n- fixed bug #45\n\n3.9 (2022-10-11)\n****************\n\n- Fixed a crash when option_copyonwrite is not set\n- Restored the test suite\n- Improved and simplified the build script and test script\n\n3.8 (2022-10-07)\n****************\n\n- Switched to copy-on-write by default\n- Allow to choose to enable/disable copy-on-write for each volume\n- Allow to change the default SSH_PORT in the plugin config\n- Updated the base docker image and dependencies\n- Added an option to show the version number\n- Improved documentation\n\n3.7 (2018-12-13)\n****************\n\n- Unpinned urllib3\n\n3.6 (2018-12-11)\n****************\n\n- Fixed zombie sshd processes inside the plugin\n- Minor documentation change\n\n3.5 (2018-06-07)\n****************\n\n- Improved documentation\n\n3.4 (2018-04-27)\n****************\n\n- Fix rights at startup so that ssh works\n\n3.3 (2018-04-27)\n****************\n\n- Fixed a bug preventing a start in certain conditions\n\n3.2 (2018-04-27)\n****************\n\n- Fixed the socket path for startup\n\n3.1 (2018-04-27)\n****************\n\n- Fixed a declaration in Python 3.6\n- Automatically detects the btrfs.sock path\n- Made the runpath and drivername configurable\n\n3.0 (2018-04-24)\n****************\n\n- Now use the docker *managed plugin* system\n- Stop the scheduler before shutdown to avoid a 5s timeout\n- Improved logging\n- Improved the migration doc from version 1 or 2\n\n2.0 (2018-03-24)\n****************\n\n- BREAKING CHANGE: Please read the migration path from version 1 to version 2:\n BTRFS volumes and snapshots are now stored by default in different directories under ``/var/lib/buttervolume``\n- Configuration possible through environment variables or a ``config.ini`` file\n- implemented ``VolumeDriver.Capabilities`` and just return ``'local'``\n- other minor fixes and improvements\n\n1.4 (2018-02-01)\n****************\n\n- Add clone command\n- replace sync by `btrfs filesystem sync`\n\n1.3.1 (2017-10-22)\n******************\n\n- fixed packaging (missing README)\n\n1.3 (2017-07-30)\n****************\n\n- fixed the cli for the restore command\n\n1.2 (2017-07-16)\n****************\n\n- fixed the purge algorithm\n\n1.1 (2017-07-13)\n****************\n\n- allow to restore a snapshot to a different volume name\n\n1.0 (2017-05-24)\n****************\n\n- initial release, used in production\n\n",
"bugtrack_url": null,
"license": "Apache License, Version 2.0",
"summary": "Docker plugin to manage Docker Volumes as BTRFS subvolumes",
"version": "3.12",
"project_urls": {
"Homepage": "https://github.com/ccomb/buttervolume"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "f12ff6e56a4e0f15b77f70cacd0344d75c76af1be0313ef46f5a951f9a916253",
"md5": "7d767ddc9bcfbbec83a1377580ee6a89",
"sha256": "7061da3a2d51ebe791642254e3d3f395b42d490ae601bae8aabfa5bf7df92997"
},
"downloads": -1,
"filename": "buttervolume-3.12-py3-none-any.whl",
"has_sig": false,
"md5_digest": "7d767ddc9bcfbbec83a1377580ee6a89",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 24702,
"upload_time": "2024-11-05T17:11:06",
"upload_time_iso_8601": "2024-11-05T17:11:06.384409Z",
"url": "https://files.pythonhosted.org/packages/f1/2f/f6e56a4e0f15b77f70cacd0344d75c76af1be0313ef46f5a951f9a916253/buttervolume-3.12-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "942ffa543a33c5ee74242e1e68be4f778805239c936953524300be2df315374c",
"md5": "7c7bd45f88b930f7eb162dd718b97648",
"sha256": "a1ded4a90703fddf0d83e3942cdca858c269d76cc8cdfd094c219a6554a8606f"
},
"downloads": -1,
"filename": "buttervolume-3.12.tar.gz",
"has_sig": false,
"md5_digest": "7c7bd45f88b930f7eb162dd718b97648",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 32954,
"upload_time": "2024-11-05T17:11:09",
"upload_time_iso_8601": "2024-11-05T17:11:09.695934Z",
"url": "https://files.pythonhosted.org/packages/94/2f/fa543a33c5ee74242e1e68be4f778805239c936953524300be2df315374c/buttervolume-3.12.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-05 17:11:09",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ccomb",
"github_project": "buttervolume",
"travis_ci": true,
"coveralls": false,
"github_actions": false,
"lcname": "buttervolume"
}
JSON
