bKappa

Welcome to bKappa's documentation page. This page serves as an introduction to bKappa, a free incremental backup tool. Please visit the project page for downloads.

1. Description

bKappa is a simple cross-platform incremental backup tool that works on Microsoft Windows, Linux and Mac OS X. It was created to fill what appeared to be an unoccupied niche in the backup software market and make a program that

  • іs simple to set up and use;
  • makes incremental backups of given directories to a given location ("incremental" meaning that only the files that have been modified since the last backup get copied over);
  • keeps the previous versions of those files;
  • automatically organizes backups on disk by their creation date and time;
  • does not use a proprietary archive format -- or any archive format at all;
  • does not require installation.

bKappa meets all of the above criteria. When you first run bKappa it creates a current-date subdirectory (e.g., "2012-07-24" -- "YYYY-MM-DD" is the default date format) at a predefined location (by default that is the current directory). It then copies to this subdirectory the directories listed in its settings. The newly created subdirectory contains each file found in the original directories with the directory structure preserved. Next time bKappa is run it will create another subdirectory (e.g., "2012-07-25") and only copy those files that have changed since the last time, again preserving the directory structure. While bKappa is running you can monitor its work through a real-time log.

2. Usage and configuration

Note: bKappa was created with the power user in mind. You need to be reasonably comfortable with using the command line prompt/terminal to make it do most things.

Now, let's start.

The simplest way to invoke bKappa is by pointing your Python interpreter at it (versions 2.5.x and 2.6.x are known to work), e.g.

$ python backup.py

Under Windows bKappa comes with just enough Python to run it. Go to the bkappa-1.x\source directory and use run.bat to run bKappa this way.

Since Windows doesn't come with a Python interpreter and you might not want to carry one around separately there are two ready-to-go executables packaged with the distribution, bKappa-eval.exe and bKappa-noneval.exe. The difference between the two is in the way they store their settings. bKappa-eval.exe uses an "evaluated" format in which the settings file is itself Python code, which can be useful to advanced users, while bKappa-noneval.exe uses a "non-evaluated" one, i.e., plain text. If you want to build your own custom binaries of bKappa you can use buildall.bat in bkappa-1.x\source to produce a new set of binaries based on the current state of the source code. Note that the build system uses BatExe for packaging, which may cause a false positive with some antivirus software.

Here is the list of the command line options you can use with bKappa:

-v, --verbose         display all messages (default)
-q, --quite           only display warnings and errors at the end
-s FILE, --settings=FILE
                  specifies a settings file
-e, --eval            use an "evaluated" (Python structures) settings file
                  (default)
-n, --noneval         use a "non-evaluated" settings file
-l, --savelog         save the full execution log into a file
-m, --merge           merge singe day's backups
                  (overwriting earlier files)
-r RESTFILE, --restore=RESTFILE
                  restores a backup (the options meant for backup are
                  ignored)
-w, --overwrite       overwrites files while restoring (off by default)
-o OUTPUTDIR, --output=OUTPUTDIR
restore files into a custom directory instead of their original locations
-f, --full            do a full, non-incremental backup (undesirable;
                  don't use unless you know you need it)

The recommended way to configure bKappa depends on whether or not you know a little about how to program in Python. If you do, you can read section 2.1; if not, skip to 2.2.

2.1. Configuring the source code and bKappa-eval.exe

First, the source code. Open backup.py in a text editor and scroll down until you see something like this:

# [S]ettings are below this point
backup_dirs = [
(joinpath(u"C:\\Documents and Settings", environ['USERNAME'], "My Documents"), \
[r'*\Downloads\*']),
(joinpath(u"C:\\Documents and Settings", environ['USERNAME'], "Desktop"), []),
]
destination_root = getcwd()
# Hereby the settings end

Those are the settings. As you can see, the backup_dirs list contains tuples. These describe how to back up My Documents and the Desktop directory for the current user whose name is found via the USERNAME environment variable. The second item in each tuple is a list of exceptions. The files the full location (path + file name) of which matches any of the patterns on the list are excluded from the backup (the matching patterns are not regular expressions; the wildcard characters * and ? are matched like they would be by the shell). The variable destination_root specifies the backup's "home" directory in which the subdirectories for particular backups created. By default it is set to the current path.

An evaluated settings file (the one used by bKappa-eval.exe) has a similar structure to the one shown above, although it doesn't allow you to specify destination_root:

(joinpath(u"C:\\Documents and Settings", environ['USERNAME'], "My Documents"), [r'*\Downloads\*'])
(joinpath(u"C:\\Documents and Settings", environ['USERNAME'], "Desktop"), [])

Note the lack of commas before line breaks.

In order for bKappa-eval.exe to recognize an evaluated settings file you must name it settings.e and place it in the same directory as the binary. You can also use the it with backup.py. To do so, run the command

$ python backup.py -s settings.e -e

or

$ python backup.py --settings=settings.e --eval

Note that since settings.e contains source code that is evaled before use you should be careful not to allow untrusted parties to modify your settings file and should always examine a settings file you got from somebody else.

2.2. Using bKappa-noneval.exe

bKappa-noneval uses a different, simplified configuration configuration file format. Its configuration is kept in settings.ne, a non-evaluated settings file.

A typical settings.ne file looks like this:

C:\Documents and Settings\User\My Documents|*\Downloads\*|
C:\Documents and Settings\User\Desktop|

The first thing you'll notice is that a file system path is followed by |. This specifies the directory to back up. The file exclusion patterns come next. The pattern used in the first line in the example above excludes all files in C:\Documents and Settings\User\My Documents\Downloads, C:\Documents and Settings\User\My Documents\Stuff\Downloads, C:\Documents and Settings\User\My Documents\Misc\Downloads, etc., from being backed up.

If, for example, you don't want to back up any temporary *.tmp files in User's My Documents and also want exclude the downloads from the backup, you should change the first line of the settings file to look like this:

C:\Documents and Settings\User\My Documents|*\Downloads\*|*.tmp|

You may add as many patterns as you like, but you must always end a line with a |.

To use the settings.ne (or a similarly formated file) with backup.py, type

$ python backup.py -s settings.ne -n

or

$ python backup.py --settings=settings.ne --noneval

in the command prompt.

3. How bKappa works (technical)

bKappa operates by walking the parts of the directory tree specified in its settings and copying their contents into a subdirectory of a predefined destination while preserving attributes and metadata. The destination subdirectory's name is based on the current date or, if there is already a backup made on that date, on both date and time (e.g, it may be 2009-04-20T174301 if there already is 2009-04-20; T1743 stands for "5:43 PM"). For example, if the destination is /backup, the subdirectory might be /backup/2009-04-20/; if it's D:\backup, it might be D:\backup\2009-04-20\. The program only copies those files that have been updated since the last backup was made and do not match any of the exclusion pattern the user has set for the directory. bKappa puts the files it has copied on a list that can later be used to restore a particular backup. If a file hasn't been modified since the last backup, bKappa puts on the list the path to its latest version found inside the previous backups in the same destination directory. When done, bKappa writes the restore list to disk.

4. Restoring

bKappa is able restore an incremental backup to its original location automatically provided you have the previous backups it references. By default, restoring a backup doesn't overwrite existing files.

Here is how you restore files with bKappa using a Python interpreter under a Unix-like operating system:

$ python backup.py -r 2007-04-20/restore.dat

This restores the files to their original location but doesn't overwrite the existing ones. If you want to do the same thing under Windows type the following into the command prompt:

bkappa-noneval.exe -r 2007-04-20\restore.dat

You may use either bkappa-noneval.exe or bkappa-eval.exe for this operation since they use the same restore file format.

To overwrite existing files (careful!), do this:

$ python backup.py -r 2007-04-20/restore.dat -w

or this

bkappa-noneval.exe -r 2007-04-20\restore.dat -w

If you want to restore files to somewhere other than their original locations use

$ python backup.py -r 2007-04-20/restore.dat -o ~/restored

or

bkappa-noneval.exe -r 2007-04-20\restore.dat -o E:\restores

You may have noticed that when you make a backup bKappa puts restore.bat and restore.sh in the backup's directory. You can use those scripts to restore a backup without invoking the program. It's an good option for when you don't have bKappa on hand or can't run it. Take note, however, that under Windows the default command interpreter (cmd.exe) has trouble supporting UTF-8 in its batch files, so you can only safely run restore.bat if you don't use non-ASCII (non-English) characters in file and directory names. If unsure, do not run the script: it will not restore all the files and will quite likely leave a mess of new empty directories that are hard to delete on your disk. (If this happens to you, know that you can delete such directories by first renaming them in Explorer.)

5. To be fixed/implemented

Currently no major bugs are known in the latest release (version 1.4), but you might want to see the previous section for a warning about using the generated batch scripts under Windows. As for the features to be implemented in future releases, the current list of proposals is as follows:

  • Compression for individual files/file types. (Unlikely to be implemented since it goes against the idea of keeping the backup format as simple as possible).
  • Create a list of files that have been deleted since the last backup. As of v1.3 no longer needed due to the complete file list being saved for each backup.
  • Have an automatic restore tool. Done in v1.3.
  • Dynamically trim the directory tree (which is it say, do not go though the directories that will be excluded from the backup anyway). Done in v1.2.

If you have any other ideas on how to improve this software, contact me.

6. Copyright, acknowledgments & contacts

bKappa is copyright 2009-2012 D. Bohdan. It is free software. For its licensing conditions see COPYING in the distribution or read its GNU GPL 2.0 license online.

bKappa's binary releases use 7-Zip and BatExe. Both are free software. See www.7-zip.org and batexe.sourceforge.io for the source code.

You can contact me through my SourceForge profile.