tbku - Table-driven backup script
tbku allsets | [fileset] ...
tbku is a utility script for producing "tarball" backups of
some- or all of your files. It is useful both for producing
incremental backups or for systemwide images or "snapshots". The
script can be run either from the command line or, more typically,
cron job to automate system backup tasks.
tbku uses standard utilities common on Unix-like systems, like
uname. It uses no other special or custom
tools. For this reason, it is highly portable across many variants
of these systems.
The central benefit of using
tbku over hand written
commands is that
tbku is "table driven". You specify the set
of files to back up in a table (a separate file). You can have as
many of these "filesets" as you wish, corresponding to different
kinds of backups you want done.
tbku will do backups
automatically or manually, based on the name of the "fileset". This
considerably simplifies automating backups, keeping backup logs, and
generally maintaining an orderly backup environment.
tbku was originally developed as a backup tool for FreeBSD
servers. Since then, it has been updated to also work with SUSE
Linux, both servers and desktops.
tbku should work with little-
or no modification on any other Unix-like system. For example,
tbku will run without modification (other than default
locations) in a
cywgin environment under MS-Windows.
tbku, all you have to do is install the file somewhere in
$PATH. Typically, a good place for it is in
/usr/local/bin. Just make sure its permissions are 755 so all
users will be able to use it.
You may optionally want to put
tbku.1.gz somewhere in your
$MANPATH so this documentation will be available as a man page.
There is also a
tbku port for FreeBSD users that automates the
installation and deinstallation of
tbku. This port can be found
/usr/ports/sysutils/tbku. Once installed, all of the
tbku (in a variety of formats) including the
tool itself, the licensing terms, and the instructions for imaging
systems with it, will be found in
Once you've installed the program, you should verify that its
default settings are to your liking. If not, you can override them
via environment variables (described later in this document). For
interactive use, make sure the environment variables you want to set
are exported when you log in. If you're running
tbku from a
cron job, be sure to set the environment variables of interest
tbku has to know just what you want backed up. You do
this by creating a so-called fileset in the appropriate
$HOME/tbku/). Filesets are just text
files that list all the files and/or directories that are
to be backed up together. For instance, suppose you had
a fileset called
manual.fileset.homedirs that contained
just these three lines:
If you now run this command:
The files and/or contents of
would be written to a tarball in the backup directory (default:
/bku/). By default, the resulting tarball's name has a long
string of text that includes the date, machine name, system type, OS type,
and the so-called set name. The "set name" is nothing
more than the suffix of the name of the fileset used to produce the
tarball, in this case,
Additionally, you'll also find a log of the backup and "dot files"
that tell you when the backup began and when it ended. Here's part
of what you might see if you did an
ls -a /bku:
The "dot files" don't actually contain any information, but their
date/time stamps (you can see this with
ls -al /bku) will tell
you when the backup began and ended.
The log file contains a list of all the files that actually
made it into the tarball. The log file also captures the
errors encountered during a backup. This means that
is generally pretty quiet during a backup run. It scribbles
any complaints it has into the log. So... you should check
your logs regularly to make sure everything is working as
You can create as many different filesets as you like (for as many
different kinds of backups as you need). So, for example, you may
have one for the files you want backed up daily, another for weekly
backups, another for taking a snapshot of the entire system, and so
The name of a fileset can be used to change
(described below). The content of a fileset file must conform
to only a few rules:
- Each line may contain the name of a single file or directory.
You cannot place multiples of these on a single line.
- Each entry should be an absolute path. That way,
will be able to figure out what it is you want to back up. By
default, most modern
tar implementations will strip the
/ so your backup tarball will be relative to
wherever you are when you restore from it.
- There is no support for comments or other metadata inside a
fileset. File- and directory names are the only thing
that should ever be there.
tbku semantics (behavior) depend on how you've named your
filesets. In general, a fileset should be named as follows:
Any fileset name that begins with "auto." will automatically be
backed up when you run the script without arguments:
If a fileset begins with something other than "auto.", you
have to explicitly name the set on the command line for
it to be backed up. Say we have only two filesets,
tbku # Does nothing
tbku music # Only backs up the manual.fileset.music fileset
tbku music docs # Backs up both filesets
The "setname" is used to uniquely name each backup tarball.
tbku only cares about the "auto" string.
Anything other than "auto" as a prefix in the fileset name, will
cause the file to be seen as requiring manual invocation. Using
"manual" is just a helpful convention.
Similarly, you don't need the "fileset" in the middle of the
filename, it's just a helpful convention.
tbku only examines
the prefix of the filename (up to the ".") to determine whether to
do automatic backups. It uses the suffix (from the last "." to the
end of the file name) to determine the set name. In fact, you
don't even have to fully specify the set name, just any trailing
tbku ic # Backs up manual.fileset.music
While these little semantic subtleties may be interesting, you are
strongly discouraged from using them, as they are not guaranteed
to be preserved in future releases of
tbku. Stick to the
conventions described above, and you should be fine.
The allsets Option
As you might guess, you can force all backup sets to be done
regardless of whether they are marked as "auto" or "manual"
by doing this:
The "allsets" argument must be the first argument on the command
line, and anything following it will be ignored. In other words,
only the form shown above is meaningful.
tbku: Nothing to do!
You may see
tbku grumbling about having nothing to do. This
happens under one of several circumstances:
- You ran
tbku without arguments, but there are no
"auto" filesets defined.
- You ran
tbku with arguments, but no filesets with
matching set names were found.
- There are no filesets at all.
Autodeletion Of Old Backups
tbku uniquely identifies each backup set based on
date, machine name, OS, CPU architecture, and set name. If you've
set it up to run as a cron job, over time you'll accumulate lots of
older copies of backups. That's because each new day, the backup
file name will change (since it begins with the date).
If you don't like this default behavior, change the
environment variable to be "YES". It must be exactly this string,
all in upper case. Anything else will cause
tbku to not
autodelete old backups. This is intentional, to make it hard to
accidentally enable this feature.
Enabling this feature forces
tbku to delete all older files
associated with the selected set name. This includes the start/stop
"dot" files, the log, and the backup tarball itself. In effect,
this option forces
tbku to only keep the most recent backup of
each backup set.
Use this option with caution! If you only keep the most recent
copy of your backups in your backup directory, you may never be able
to get to changes made days, weeks, or months prior.
IMAGING WITH tbku
It is possible to use
tbku backups to completely (re)image a
machine. The general idea is to have
tbku produce a tarball of
all the (relevant) files on the system you want to "clone". Then,
you can dump that onto a newly prepared filesystem on the target
machine. This is a handy (and relatively quick) way to recover a
system after a hard drive failure or upgrade, for example.
tbku distribution contains separate documents that describe
in detail how to image both FreeBSD and SUSE Linux systems. You can
also read the documents on line at:
tbku is written to be "smart" enough to figure out where your
system keeps needed tools like
sed. The only
requirement here is that
tbku be run in an environment that can
which command somewhere in its
which to figure out just where everything it needs lives on
your filesystem. If
tbku cannot figure out where your system
keeps things, it will use the FreeBSD default values.
For most FreeBSD and Linux users, this should work without any
customization beyond setting environment variables to override
default behavior (described below). In rare circumstances, you may
need further customization. All the things you're likely to ever
want to change appear first in the actual
tbku script, and are
briefly documented there.
DEFAULTS & ENVIRONMENT VARIABLES
You can override the various
tbku defaults by setting a
corresponding environment variable.
================= =============================== =========================
Env. Variable Default Value Meaning
-------------- ------------------------------- -------------------------
TBKUDEL NO YES -> Delete old backups
TBKUDIR /bku Where to write backups
TBKUNAME $MACHINE-$OSTYPE-$OSREV-$HWTYPE Tarball base name
TBKUSETS $HOME/tbku Filesets found here
TBKUTAPE /dev/sa0 Tape device (or file)
================= =============================== =========================
export TBKUDIR=/mnt/backups # Backups written to /mnt/backups
export TBKUNAME=JoeBackup # Backups named: JoeBackup-<setname>
export TBKUSETS=/tbku # Looks for filesets in /tbku
export TBKUTAPE-/tmp/faketape # Tape backups actually written to *file*
export TBKUDEL="YES" # Autodelete old backups when starting a set
tbku was originally designed for use by experienced
systems administrators and users. As such, it does little
or no error checking. If you define backup or fileset
directories that are non-existent, for instance, you will
get strange behavior.
tbku will try to create the
backup directory you've specified if it does not already
exist, but this may not work if you're running as anything
tbku is intended to make it easier/more automatic to
to backups. It is not, however, idiot-proof. There are
some general backup guidelines you should observe:
NEVER, EVER, EVER, EVER, EVER ... EVER, trust a backup tool
until you've confirmed that it is correctly producing backups
and you can properly restore from them!
Always keep multiple copies of your backups. If
writing its backups to the same drive/system it runs on, make
sure you also keep a copy of those backups "off system".
It's a pretty good idea to keep multiple backup copies, on
different media (disk, tape, DVD, thumbdrive), in different
UPDATES & SUPPORT
To get the latest version of 'tbku', go to:
For questions, comments, or other feedback, send email to:
Tim Daneliuk, TundraWare Inc.
COPYRIGHT & LICENSING
tbku is Copyright (c) 2004-2014, TundraWare Inc., Des Plaines, IL, USA
There is no fee for using
tbku either personally or commercially
so long as the terms of the tbku license are met. Please read the
tbku-license.txt file for a full explanation of the licensing
This document was produced using the very useful
reStructuredText tools in the
docutils package. For more
$Id: tbku.rst,v 1.4 2014/10/22 22:36:15 tundra Exp $