November 21, 2005

CLI Magic: Simple backup is Mirdir

Author: Joe Barr

This week is all about simplicity. Mirdir provides a quick and easy way to make an ad hoc backup of important data. With it you can copy a file or directories to your keydisk, or save redundant copies of data you can't afford to lose. It tries to do only one thing, and do it well: mirror a directory.

Mirdir is licensed under the GPL. You can download your choice of an executable RPM, source RPM, or a source tarball. To install it on my SUSE 10 desktop box, I chose the executable RPM, used su to install as root, and entered rpm -Uvh mirdir-2.1-1.i386.rpm. On my Ubuntu Breezy machine, I decompressed the tarball, entered the Mirdir subdirectory, ran ./configure and make. However, before running make install, you should edit the Makefile and find the section that looks like this:

prefix = /usr/local
exec_prefix = ${prefix}
bindir = $(prefix)/bin
man1dir = $(prefix)/man/man1

Edit the last line in the section so that it looks like this:

man1dir = $(prefix)/share/man/man1

Then proceed -- as root -- to finish the installation with make install.

Mirror this

The basic format of the Mirdir command is as follows:

mirdir options -e exception-file source-directory target-directory

But before you use Mirdir for the first time, you need to be aware of a few things. First, in the simplest of usage, you won't have an exception file, but you need to tell mirdir this by using -enone. Next, the target-directory has to exist before you run Mirdir. And finally, the most critical thing you need to know is that Mirdir is not just a fancied-up version of cp. It works by bringing the target-directory into line with the source-directory. That means that any files that are in the target but not in the source-directory will be removed. After you run Mirdir, the directories will be as identical as Mirdir was able to make them.

Let's see a basic example. I have a directory of text files in my home directory. I want to make a backup of them. The first thing to do is to create a directory for the backup, by entering mkdir /home/username/text-mirror.

Then it's time for Mirdir:

mirdir -enone /home/username/text-files /home/username/text-mirror

A summary of what Mirdir does appears at the end of the end of Mirdir's output to the terminal:

Elapsed time 0:00:38, rc 1
Statistics: files/directories compared: 1361
Statistics: files/directories removed: 1
Statistics: files/directories created: 1359
Statistics: source read: 18290 Kbytes
Statistics: written: 18290 Kbytes

The most important part of that is the return code -- the rc -- at the end of the first line. An rc of 1 means Mirdir did as requested and encountered no problems. An rc of 0 means the directories were already synchronized and Mirdir didn't have to do anything. An rc of less than zero means an error occurred in processing. Always check the return code. Mirdir currently has 12 specific error codes -- -1 through -12 -- and the man page explains them all.

Optional behavior

There are a couple of options you might find useful. Most have to do with protecting file attributes such as owner, access, and date. Here are the two I think most valuable for the newbie:

  • -i -- The inspect mode itemizes the actions that Mirdir would take, but doesn't actually do them. This lets you make sure your Mirdir command is going to do what you want it to do.
  • -v -- The verbose mode will itemize each action taken, file by file, so you can check to see that Mirdir did as you wanted it to do.

About those exceptions

The exception file allows you to preserve files or file attributes in the target directory, which in our example above would be text-mirror. Any line beginning with a # in the exception file is treated as a comment. The format of an exception entry is:

exception-file-name exception-option

If no exception-option is present, the file named will not be changed, deleted, or created. Note that the file name can be that of a file or a directory. Note as well that we are specifying files in the target directory, not the source.

Exception file options allow you to preserve the list of files within a directory, protect the owner attributes of a file, protect the access attributes of a file, or protect some combination of those things. For basic usage, you probably don't need to worry about them. If you do, refer to the man page for the option arguments or exception file usage that provides the protection you need.

Click Here!