diff --git a/tbku.txt b/tbku.txt index 259598c..cf5e111 100644 --- a/tbku.txt +++ b/tbku.txt @@ -16,6 +16,11 @@ script can be run either from the command line or, more typically, as a ``cron`` job to automate system backup tasks. + ``tbku`` uses standard utilities common on Unix-like systems, like + ``tar``, ``sed``, and ``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 ``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 @@ -57,6 +62,8 @@ **USING tbku** + **Using Filesets** + ``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 @@ -78,28 +85,126 @@ ``/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``:: + more than the suffix of the name of the fileset used to produce the + tarball, in this case, ``homedirs``. 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 -al /bku``:: 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 + 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 + on. + + The *name* of a fileset can be used to change ``tbku`` behavior + (described below). The *content* of a fileset file must conform + to only a few rules: + + 1) Each line may contain the name of a *single* file or directory. + You cannot place multiples of these on a single line. + + 2) Each entry should be *an absolute path*. That way, ``tar`` + will be able to figure out what it is you want to back up. By + default, most modern ``tar`` implementations will strip the + leading ``/`` so your backup tarball will be relative to + wherever you are when you restore from it. + + 3) 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. + + **Fileset Naming** + + ``tbku`` semantics (behavior) depend on how you've named your + filesets. In general, a fileset should be named as follows:: + + auto.fileset.setname + + OR + + manual.fileset.setname + + Any fileset name that begins with "auto." will automatically be + backed up when you run the script without arguments:: + + tbku + + 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, ``manual.fileset.music`` + and ``manual.fileset.docs``. Then:: + + 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. + + Strictly speaking, ``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 + substring:: + + 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:: + + tbku allsets + + The "allsets" argument must be the first argment 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: + + 1) You ran ``tbku`` without arguments, but there are no + "auto" file sets defined. + + 2) You ran ``tbku`` with arguments, but no file sets with + matching set names were found. + + 3) There are no file sets at all. + **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 with -the entire system you want to "clone" in it. Then, you can dump that -onto a newly prepared filesystem on the target machine. + 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. -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: + 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 @@ -122,7 +227,7 @@ briefly documented there. -**ENVIRONMENT VARIABLES & DEFAULTS** +**DEFAULTS & ENVIRONMENT VARIABLES** You can override the various ``tbku`` defaults by setting a corresponding environment variable. @@ -151,6 +256,15 @@ **OTHER** + ``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 file set + 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 + other than ``root`` user. + ``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: @@ -203,4 +317,4 @@ http://docutils.sourceforge.net/rst.html -``$Id: tbku.txt,v 1.106 2008/03/19 17:25:38 tundra Exp $`` +``$Id: tbku.txt,v 1.107 2008/03/19 20:02:36 tundra Exp $``