Published on (
 See this if you're having trouble printing code examples

FreeBSD Basics Archiving with Pax

by Dru Lavigne

In today's article, I'd like to finish up the archiving series with the pax utility. It's unfortunate that this utility never seems to get the coverage that tar and cpio do. I've found that it combines the best qualities of both utilities into one easy-to-use and fairly intuitive utility.

The name of the utility stands for "portable archive exchange," as it was designed specifically to allow portability between different versions of Unix. There's also a bit of wry humor in the name, as pax attempts to bring some "peace" to the long-standing battle over which is better: tar or cpio. The pax utility can be used to create either type of archive, and during a restore, it automagically detects the type of archive for you. And it doesn't matter what type of Unix that archive happened to be created on, meaning you can back up files from your FreeBSD system and restore them to, say, a SCO system.

Let's start with some examples of basic pax usage, then move on to some fancier stuff. To back up the contents of your home directory, invoke write mode using the w switch:

pax -wf home.pax .

In this example, I went to my home directory with cd, then told pax to write (w) to a file (f) named home.pax the contents of the current directory ("."). When you use pax, it's very important to remember to include that f switch to indicate the name of the archive you'd like to create. If you forget the f, weird characters will be sent to your screen, accompanied by horrible, pained noises. Also, if you want to watch as pax does its thing, simply add the v, or verbose, switch to the switch portion of the command.

To see what type of file you've just created, use the file command:

file home.pax
home.pax: POSIX tar archive

To see the contents of that archive, tell pax which archive file you'd like to view, using the f switch:

pax -f home.pax |more

Since my archive file is rather large, I piped this output to the more command so I could read the contents of the archive one page at a time. If you also include the v switch, you'll get an "ls -l"-type output of the archive contents. Again, don't forget to specify the name of the archive with the f switch, or nothing will happen, except that you'll lose your prompt until you press CTRL-C.

The pax utility does support compression, so I could have performed a compressed backup by including the z switch:

pax -wzf home.pax .

Related Reading

Essential System Administration
Tools and Techniques for Linux and Unix Administration
By Æleen Frisch

Let's do another example. This time I'll back up the /etc directory to a floppy:

cd /etc
pax -wf /dev/fd0 .

You'll note that I became the superuser in this example. This was necessary for two reasons. First, the files in /etc are owned by root, since they are the configuration files for the system. Second, by default, only the superuser has permission to back up to a floppy drive. Also notice that I specified the floppy as the name of the archive file (/dev/fd0).

A couple of notes about backing up to a floppy: the pax utility is intelligent enough to realize when it fills up a floppy, and will prompt for another one if the archive file is too large to fit onto one floppy. However, pax does not support compression to a floppy; if you try adding the z switch to the above example, you'll receive this error message:

gzip: stdout: Invalid argument

You should also be aware that, by default, when you back up to a floppy, you will lose any previous data stored on that floppy. If you would like to append to a previous archive, use the a switch:

pax -wvf /dev/fd0 jpegs
pax -wavf /dev/fd0 pdfs
pax -f /dev/fd0

The above example will back up the jpegs directory to a floppy, then append the pdfs directory to the backup. When I list the archive, the contents of both the jpegs and pdfs directories will be on the floppy.

To restore (or use read mode on) an archive, first cd into the destination directory, then use the r switch. For example, I'll restore the backup named home.pax into the test subdirectory of my home directory:

cd test
pax -rvf ~/home.pax

The pax utility can also restore tar and cpio archives. It is able to automatically detect the correct format for you; however, you should use the file utility before attempting the restore to determine whether or not the archive is compressed. If it is, you'll need to include the z switch.

As an example, I have a file called backup.old located in my home directory (~). I'll first use the file utility:

file backup.old
backup: gzip compressed data, deflated, last modified: 
        Sat Aug 17 14:21:12 2002, os: Unix

Since this backup is compressed, I'll use this command to restore it to the test directory:

cd test
pax -rvzf ~/backup.old

I have another file in my home directory called backup:

file ~/backup
backup: cpio archive

This file isn't compressed, so I'll restore it, like so:

pax -rvf ~/backup

The fact that the first backup happened to be a tar archive and the second a cpio archive didn't confuse pax; however, I would have received some strange error messages if I had forgotten to inform pax that the first archive was compressed.

You can do some pretty funky things when restoring with pax. For example, you can do an interactive rename/restore by including the i switch. Issuing the following command:

pax -rif ~/backup

will start an interactive restore of the archive named backup into the current directory. In interactive mode, pax will display the name of each file, one at a time, and prompt you to either rename it as it's restored, restore it with the original name, or to skip it and not restore it:

ATTENTION: pax interactive file rename operation.
drwxr-xr-x Aug 17 15:08 .
Input new name, or a "." to keep the old name, or a "return" to skip this file.
Input > 
Skipping file.

Here, I pressed enter as I didn't want to change the name of "." or the current directory.

ATTENTION: pax interactive file rename operation.
drwxr-xr-x Jul 26 16:10 file1
Input new name, or a "." to keep the old name, or a "return" to skip this file.
Input > old
Processing continues, name changed to: old

ATTENTION: pax interactive file rename operation.
-rw-r--r-- Jun 11 00:20 file2
Input new name, or a "." to keep the old name, or a "return" to skip this file.
Input > .
Processing continues, name unchanged.

You'll note that I changed the name of file1 to old and kept file2 as is. A listing of the restored directory will show two files: one named old and one named file2.

One of the most powerful features of pax is that it is able to very quickly copy a complete directory structure to another portion of your hard drive, using copy mode. To use copy mode:

pax -rw . destination_directory

Note that you don't include the f switch in copy mode, as an archive file doesn't get created. Instead, the old directory structure is directly recreated into the new directory structure.

Also note that you never want to do this:

mkdir test
pax -rw . test

In the above example, I cd'd into my home directory, made a subdirectory named test, then invoked copy mode. In doing so, I ended up in an endless loop of test subdirectories, each containing the contents of my home directory. If I hadn't interrupted this cycle with a CTRL-C, pax would have continued ad infinitum, where infinitum is defined as the point where I run out of disk space.

That's what this section of man pax refers to:

Warning: The destination directory must not be one of the file operands or a member of a file hierarchy rooted at one of the file operands. The result of a copy under these conditions is unpredictable.

However, this works beautifully and almost instantaneously:

cd ~user1/big_project
mkdir ~user2/big_project
chown user2 ~user2/big_project
pax -rw . ~user2/big_project

Voila, the entire big_project directory structure is now also in the second user's home directory. When using copy mode, you'll have to become the superuser as you'll be copying out of your home directory, so you can avoid the endless loop situation. If you have to make the new directory, it will be owned by root; if need be, use the chown command like I did to ensure that it has the desired ownership before doing the copy operation. You'll also want to take a look at man pax first to see how you want to handle the permissions of the copied directory structure.

It is also possible to interactively copy a directory structure by including the i switch:

pax -rwi .  ~user2/big_project

Similarly to the previous interactive example, pax will display each filename, one at a time, so you can decide which files to copy over and which files to rename as you do so.

Now, let's do something useful with the pax command. I'll demonstrate how to create an incremental backup system. In this example, the user "genisis" would like to back up any changes she made to her home directory on a daily basis.

First, I'll become the superuser to create a directory to hold the backups:

mkdir /usr/backups

I'll then create a subdirectory and give the user "genisis" ownership of that subdirectory:

mkdir /usr/backups/genisis
chown genisis /usr/backups/genisis

I'll then leave the superuser account and as the user "genisis," cd into my home directory:


I'll then do a full backup of my home directory and save it to an archive file called Monday:

pax -wvf /usr/backups/genisis/Monday .

Now that I have a full backup, I can take daily incremental backups to just back up each day's changes. So when I'm finished with my work on Tuesday, I'll issue this command:

pax -wv -T 0000 -f /usr/backups/genisis/Tuesday .

Notice that I included the time (T) switch and specified a time of midnight (0000). This tells pax to only back up the files that have changed since midnight, so it will catch all of the files that changed today. On Wednesday, I'll repeat that command but will change the archive name to Wednesday.

Also in FreeBSD Basics:

Fun with Xorg

Sharing Internet Connections

Building a Desktop Firewall

Using DesktopBSD

Using PC-BSD

If you have the disk space and want to keep backups for longer than a week, modify your archive names to something like: Aug01, Aug02, etc. It's still a good idea to do a full backup once a week, followed by incremental backups the other days of that week. If disk space is an issue, include the z switch so the backups will be compressed. Also note that the T switch can be much pickier than I've demonstrated; see man pax for the details.

You have to be a bit careful when restoring an archive. By default, pax will overwrite any existing files. If you don't want it to overwrite any files, include the k switch. If you want to be picky about which files are overwritten, use the i switch.

You don't have to restore every file in an archive. If you're going to be selective, it's a good idea to list the archive first to see what you want and don't want. For example:

pax -f ~/backup

To restore all of the files except file3, use this command:

pax -rvf ~/backup -c './file3'

The c switch is the exception switch. Note that your exception pattern (in my case, file3) needs to be enclosed in single quotes (the key next to your enter key). Either use the literal pattern like I did (to pax, this file is known as ./file3, not file3) or use a wildcard, like so:

pax -rvf ~/backup -c '*file3'

If you use a wildcard (*) at the beginning of your pattern as in the above example, you will exclude all files that end with "file3" -- for example: file3, myfile3, thatfile3.

You can also specify which file to restore by using the n, or pattern matching, switch. The following will just restore file2:

pax -rvf ~/backup -n './file2'

The n switch differs from the c switch in that it will only restore the first file that matches the pattern. This means that this command will not restore file3, myfile3, and thatfile3:

pax -rvf ~/backup -n '*file3'

Since file3 is the first file to match the expression, it will be the only file that will be restored.

The c and n switches are also useful when creating an archive; use them to specify which file you'd like to back up, or which file(s) you don't want to back up.

Hopefully, this archiving series has taken some of the mystique out of Unix backups, so that you can choose the utility that works best for you and implement a regular backup schedule for the files on your FreeBSD system. Hopefully, you'll never need to restore a backup, but if you do, you'll be glad that you took the time to master and use your favorite archiving utility.

Dru Lavigne is a network and systems administrator, IT instructor, author and international speaker. She has over a decade of experience administering and teaching Netware, Microsoft, Cisco, Checkpoint, SCO, Solaris, Linux, and BSD systems. A prolific author, she pens the popular FreeBSD Basics column for O'Reilly and is author of BSD Hacks and The Best of FreeBSD Basics.

Read more FreeBSD Basics columns.

Return to the BSD DevCenter.

Copyright © 2009 O'Reilly Media, Inc.