Obnam, a backup program

Obnam is a backup program. It is currently in BETA quality, meaning that all the necessary features should be there, but there are bugs that may annoy you a lot, and performance may be entirely inadequate for you. Hopefully using Obnam will no longer turn you bitter and hateful, and make you abandon all hope for civilisation, move into the rain forest, and talk to birds for the rest of your life.

It would be inadvisable to rely on Obnam as your only backup solution, but it should be ready for feature evaluation use.

Home page

The Obnam home page is at http://liw.fi/obnam/, see there for more information.

Installation

The source tree contains packaging for Debian. Run debuild -us -uc to build an installation package.

On other systems, using the setup.py file should work: run "python setup.py --help" for advice. If not, please report a bug. (I've only tested setup.py enough for to build the Debian package.)

You need to install my Python B-tree library, and some of my other libraries and tools, which you can get from:

http://liw.fi/larch/
http://liw.fi/ttystatus/
http://liw.fi/coverage-test-runner/ (for automatic tests)
http://liw.fi/tracing/
http://liw.fi/seivot/ (for benchmarks)

You also need third party libraries:

paramiko: http://www.lag.net/paramiko/

Use

To get a quick help summary of options:

./obnam --help

To make a backup:

./obnam backup --repository /tmp/mybackup $HOME

For more information, see the manual page:

man -l obnam.1

Hacking

The canonical version control repository for obnam itself is at:

http://code.liw.fi/obnam/bzr/

The 'trunk' branch is the main development one. Note that the URL points at a bzr repository, it is not useful to browse it by hand.

To build and run automatic tests:

./check
./check --fast # unit tests only, no blackboxtests
./check --network # requires ssh access to localhost

check is a wrapper around python setup.py, but since using that takes several steps, the script makes things easier.

You need my CoverageTestRunner to run tests, see above for where to get it. A couple of scripts exist to run benchmarks and profiles:

./metadata-speed 10000
./obnam-benchmark --size=1m/100k --results /tmp/benchmark-results
viewprof /tmp/benchmark-results/*/*backup-0.prof
seivots-summary /tmp/benchmark-results/*/*.seivot | less -S

There are two kinds of results: Python profiling output, and .seivot files.

For the former, viewprof is a little helper script I wrote, around the Python pstats module. You can use your own, or get mine from extrautils (http://liw.fi/extrautils/). Running the benchmarks under profiling makes them a little slower (typically around 10% for me, when I've compared), but that's OK: the absolute numbers of the benchmarks are less important than the relative ones. It's nice to be able to look at the profiler output, if a benchmark is surprisingly slow, without having to re-run it.

seivots-summary is a tool to display summaries of the measurements made during a benchmark run. seivot is the tool that makes the measurements. I typically save a number of benchmark results, so that I can see how my changes affect performance over time.

If you make any changes, I welcome patches, either as plain diffs, bzr bundles, or public repositories I can merge from.

The code layout is roughly like this:

obnamlib/               # all the real code
obnamlib/plugins/       # the plugin code (see pluginmgr.py)
obnam                   # script to invoke obnam
_obnammodule.c          # wrapper around some system calls

In obnamlib, every code module has a corresponding test module, and "make check" uses CoverageTestRunner to run them pairwise. For each pair, test coverage must be 100% or the test will fail. Mark statements that should not be included in coverage test with "# pragma: no cover", if you really, really can't write a test. without-tests lists modules that have no test modules.

If you want to make a new release of Obnam, I recommend following my release checklist: http://liw.fi/obnam/release/.

Feedback

I welcome bug fixes, enhancements, bug reports, suggestions, requests, and other feedback. I prefer e-mail (liw@liw.fi).

There's a mailing list for Obnam users: see http://vlists.pepperfish.net/cgi-bin/mailman/listinfo/obnam-flarn.net for instructions.

It would be helpful if you can run make clean check before submitting a patch, but it is not strictly required.

Legal stuff

Most of the code is written by Lars Wirzenius. (Please provide patches so that can change.)

The code is covered by the GNU General Public License, version 3 or later.

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see http://www.gnu.org/licenses/.

See also