diff --git a/tbku.txt b/tbku.txt
index 716ffcb..259598c 100644
--- a/tbku.txt
+++ b/tbku.txt
@@ -11,75 +11,98 @@
**DESCRIPTION**
``tbku`` is a utility script for producing "tarball" backups of
- some- or all of your file systems. It is useful both for producing
- incremental backups and for systemwide images or "snapshots". The
+ 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,
as a ``cron`` job to automate system backup tasks.
+ The central benefit of using ``tbku`` over hand written ``tar``
+ 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
- systems. Since then, it has been updated to also work with SUSE
- Linux. ``tbku`` should work with little- or no modification on any
- other Unix-like system.
+ 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.
-**HOW tbku WORKS**
+**INSTALLING tbku**
+
+ To use ``tbku``, all you have to do is install the file somewhere in
+ your ``$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``.
+
+ 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
+ in the ``crontab`` file.
- This program produces tarballs of backup "sets". The tarball is
- written to $BKUDIR. By default, this is '/bku' but you can override
- this with the $TBKUDIR environment variable to point to any
- directory you wish. If the directory does not exist, 'tbku' will
- create it for you when it runs.
+**USING tbku**
-A backup "set" consists of a related set of files and directories
-that are all to be backed up together into a single tarball. The
-file containing all the names of all the files and directories in a
-given backup set is called the "fileset". 'tbku' expects to find
-filesets in $FILESETDIR. By default, this is '/root/tbku', but you
-can override this by setting the $TBKUSETS environment variable to
-point to the directory of your choice.
+ ``tbku`` has to know just *what* you want backed up. You do
+ this by creating a so-called *fileset* in the appropriate
+ directory (default: ``$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::
-Notice that if this directory does not exist OR if the fileset you
-name does not actually exist, 'tbku' will appear to run, but will
-produce an empty backup set with an error in it's log indicating
-that it could not find the named fileset. A backup that fails for
-this reason will also be flagged by having the "*" character in its
-backup, log, and timestamp filenames.
+ /root
+ /home
+ /usr/home
-The naming of filesets is important. Fileset names must end in
-".backup name". If the name begins with $COMMON, then this program
-understands that set to be done "automatically". That is, if
-nothing is passed on the command line, the program does an
-"automatic" backup - i.e., It processess ALL the filesets found in
-the backup directory whose names begin with $COMMON.
+ If you now run this command::
-The program can also be started with command line arguments. It
-understands these to be the name of the backups desired. For
-instance:
- tbku foo bar baz
+ tbku homedirs
-Will look for filesets ending in
+ The files and/or contents of ``/root``, ``/home``, and ``/usr/home``
+ 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 machine name, system type, OS type,
+ date, *and* the so-called *set name*. The "set name" is nothing
+ more than the suffix of the fileset used to produce the tarball, in
+ this case, ``homedirs``. Additionally, you 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 -al /bku``::
-".foo", ".bar", ".baz".
+ Mar 19 05:46 .mach.fake.org-FreeBSD-6.3-STABLE-i386-homedirs-begin
+ Mar 19 05:47 .mach.fake.org-FreeBSD-6.3-STABLE-i386-homedirs-end
+ Mar 19 05:46 mach.fake.org-FreeBSD-6.3-STABLE-i386-homedirs-20080319.tar.gz
+ Mar 19 05:46 mach.fake.org-FreeBSD-6.3-STABLE-i386-homedirs.log
-In this case, the program does not care what the beginning of the
-fileset name is. This can potentially be a problem if you have two
-filesets whose names end identically. Say you have 'manual.bku.foo'
-and "auto.bku.foo" in your $FILESETDIR directory and you issue the
-command "tbku foo". BOTH of these filesets will be processed since
-they both have the backup name "foo". The last one to be processes
-will be the one whose backup tarball ends in $BKUDIR. The simple
-way to avoid this is to never name two filesets with the same ending
-backup name.
-Do NOT use the special setname ".allsets". This name is reserved.
-When passed on the command line ("tbku allsets"), it does all of the
-backup sets it finds regardless of whether they are set for
-automatic or not.
+**IMAGING WITH tbku**
-If the setname is "tape", then output will be written to the device
-or file specified in the $TAPEDEV variable instead of a file in the
-backup directory.
+It is possible to use ``tbku`` backups to completely (re)image a
+machine. The general idea is to have ``tbku`` produce a tarball with
+the entire system you want to "clone" in it. Then, you can dump that
+onto a newly prepared filesystem on the target machine.
+
+The ``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:
+
+ http://www.tundraware.com/Software/tbku
+
**CUSTOMIZING tbku**
@@ -126,6 +149,25 @@
export TBKUTAPE-/tmp/faketape # Tape backups actually written to *file*
+**OTHER**
+
+ ``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 ``tbku`` is
+ 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
+ locations**.
+
+
**UPDATES & SUPPORT**
To get the latest version of 'tbku', go to:
@@ -161,4 +203,4 @@
http://docutils.sourceforge.net/rst.html
-``$Id: tbku.txt,v 1.105 2008/03/19 16:31:36 tundra Exp $``
+``$Id: tbku.txt,v 1.106 2008/03/19 17:25:38 tundra Exp $``