bKappa

bKappa is a 2009 experiment in crude but transparent and cross-platform incremental backup. bKappa backups are simple directory trees and lists of files. They are easy to browse and examine and do not use symbolic or hard links. It is crude in the sense that bKappa only tracks files by name, not by content. This means it cannot detect when a file has been renamed and makes full copies of renamed and partially changed files.

bKappa is written in Python. It generates standalone restore scripts for the POSIX shell and PowerShell 1.0 and later that do not require Python. The PowerShell scripts are cross-platform.

While bKappa 1.x saw some real use on the developer’s machines, it is not heavily-tested the way backup software should be. The 2024 update bKappa 2 was made to satisfy curiosity rather than for production. Do not trust bKappa to preserve important data.

You can download bKappa from SourceForge.

Requirements

bKappa requires Python 3.7 or later. Using evaluated settings requires Starlark-PyO3 to be installed. You can install Starlark-PyO3 in a venv.

Documentation

bkappa.sourceforge.io/old houses outdated documentation written for version 1.x.

bKappa creates snapshots in repositories. bKappa repositories are directories with a structure that bKappa recognizes. You can back up multiple source directories to a repository. Source directories are the top-level directories of your backups. A snapshot is a backup copy of any number of source directories that for every directory may reference previous snapshots of the same directory.

To avoid conflicts, back up only one source directory with a particular name per repository.

Only a single bKappa process should be using a repository at any time. In the current version it is up to the user to ensure this (for example, through locking in a cron job).

bKappa is configured with a text configuration file that can be one of two types. The first type contains lines with a source directory path followed by optional exclusion patterns. Each part of the line is separated with the pipe character |. This is called “non-evaluated settings”. The exclusion patterns are Python fnmatch patterns applied to whole paths.

/home/foo/Documents
/home/foo|*/Downloads/*|*/Documents/*

The second type contains lines with Python-like Starlark expressions that can reference built-in and environment variables. They are called “evaluated settings”. The following is an example of evaluated settings. It similar to the non-evaluated example but uses a variable for the home directory.

(home + "/Documents", [])
(home, ["*/Downloads/*", "*/Documents/*"])

bKappa defines these additional global variables for evaluated expressions:

• home—the user’s home directory.
• environ—a dictionary containing the environment variables.
• platform—a dictionary with system information. Its keys are:
  • bits: platform.architecture()[0]
  • machine: platform.machine()
  • node: platform.node()
  • os_name: os.name
  • platform: platform.platform()
  • processor: platform.processor()
  • release: platform.release()
  • system: platform.system()
  • version: platform.version()

Example

Here is how you can create and restore a snapshot on a POSIX system.

mkdir -p /tmp/bkappa/repo/
mkdir /tmp/bkappa/source/
echo '/tmp/bkappa/source' > /tmp/bkappa/repo/settings.ne
echo 'Hello, world!' > /tmp/bkappa/source/test-file
./backup.py /tmp/bkappa/repo/
./backup.py /tmp/bkappa/repo/ -r /tmp/bkappa/repo/*/restore.json -o /tmp/bkappa/restore/
cat /tmp/bkappa/restore/tmp/bkappa/source/test-file

Alternatives

• BorgBackup
• restic

Changelog

• bKappa 2.0 (2024-06-08):
  • Ported from Python 2 to Python 3.
  • Replaced insecure pickle restore files (restore.dat) with JSON (restore.json).
  • Added a migration tool from bKappa 1 to 2 (restore-dat2json.py).
  • Fixed path quoting in POSIX restore scripts. Replaced batch files with PowerShell restore scripts.
  • Replaced eval with Starlark (Starlark-PyO3) for safe evaluated settings.
  • Removed the Windows-binary build system. It expanded the scope of the project and had fallen behind external options.
• bKappa 1.4 (2012-10-06)
  • Added a command-line option to ignore I/O errors during backup. By default, bKappa still fails if it cannot copy a file.
  • Added a simulation (dry-run) mode.
  • The binary build system has been refactored and improved. The code in build scripts is now easier to understand, and the scripts themselves present the user with a menu explaining what every menu option does.
• bKappa 1.3b (2009-07-05):
  • Now the executables recognize parameters passed to them, just like the script itself.
  • Fixed a bug in the function findlatest that resulted in some unmodified files getting copied over.
• bKappa 1.3a (2009-07-04):
  • Fixed an issue in run.bat that would retain old parameters on a new run.
  • The check for valid backup directories is now more strict.
  • The command-line options have been clarified.
• bKappa 1.3 (2009-07-03):
  • Added saving a file list and restore data.
  • Added restoring backups, including restoring to a custom location.
  • Restore scripts for Windows (read the on-line documentation before using them) and Unix are now generated for backups.
  • The backup log is now saved to the destination directory.
  • Added an option to force a full backup.
  • Fixed a bug in joinpath that could result in an corrupted path on concatenation (though not if used the way bKappa currently uses it).
  • Importing bKappa as a Python module will now not result in it running.
  • Less gratuitous version bumping!
  • More style changes.
  • Smaller fixes all around.
• bKappa 1.2 (2009-07-02):
  • The findlatest function has been optimized.
  • The default behavior is now to separate multiple backups made on one day. Use the option -m/--merge to merge them instead.
  • Style changes in code to match PEP 8 better (fully?).
  • Code comments revised and expanded.
  • Various small changes.
• bKappa 1.1a (2009-06-29):
  • Fixed support for Unix-style separators in paths.
  • The build system has been reworked and simplified.
• bKappa 1.1 (2009-06-28):
  • First public release.

License

bKappa is free software distributed under the MIT License. See the file LICENSE for details.