Command Line Use

Options for the automatic backup scripts in more detail.

[Back to PSC home page]

Using the run_pbackup script

The script run_pbackup is normally run at system shutdown by /etc/init.d/pbackupd to make the incremental backups of the system at a point when virtually everything has stopped, so files are no longer in use.

This uses the “-D” option for run_pbackup to run the default backup types (i.e. the lists of things to backup), and the output results of the script are saved to the file /var/log/pbackupd.log (which can be viewed using the system log file viewer next time the PC is started).

It is also possible to run the script from the command prompt to perform a backup with more options as required.

NOTE: In this case you have to be logged in as root, or use sudo, to have the privileges to access all of the file system as required.

Command Line Options

The following options are available for the run_pbackup script:

-b type

To backup using the lists in type.include and type.exclude (in /etc/pbackup). This results in output files of the form type.mode.txt where 'mode' is one of: full, major, month, week or day.

-B directory

To specify a different back-up destination directory from those in pbackup.conf The files are stored in a sub-directory names from the PC's machine name, so different PCs can use the same nominal directory for their backups.

-C

Clear the lock on a previous failed backup attempt. This should be used with caution, and only when you are sure no other backup is running (for example, if you just stopped a command line backup with Ctrl+C then it is safe to use it!)

-D

Run the default backup types, as specified in pbackup.conf

-F 1|0

This allows the forcing of a 'full' backup if '1' is specified. If '0' is specified then the script will run a normal backup (which is only 'full' when no existing backup of that type exists on the chosen storage device).

Because of the way the command line is processed, you can use this multiple times to control each of multiple “-b type” backups. For example, the following will run normal backups for 'home' and 'vm', but force a full backup for 'system':

run_pbackup -F 0 -b home -F 1 -b system -F 0 -b vm

-L nn

This option controls how older backups are cleaned up. The following values for nn are supported:

    0=Never delete old incremental sets (needs a lot of storage space!)

    1=Long mode, keep 'day' sets for 6 weeks, etc.

    2=Normal mode, keep 'day' sets for 2 weeks, etc.

This is equivalent to CLEAN_UP_MODE=2 in pbackup.conf

-N

Shut down the computer once the script has completed. Intended for cases when you want to run a long backup from the command prompt, but want to shut down the PC once it has finished. It issues the shutdown command with a 2 minute delay, so if anyone else was using it they get some warning before it powers off!

-P 1|0

Used to override the pbackup.conf file's setting for clearing the print queue. For most home users, if the printer is off and you are shutting down the PC you don't expect/want it to burst into life printing next time both are on. This is particularly true if you have impatient youngsters using the PC!

0 = Normal behavior, preserve print queue over reboot/shutdown.

1 = Clear print queue on backup, expecting shutdown and clean start another day.

-T

Ignore the disk 'too full' test on the backup directory. In effect, this suppresses the MAX_DISK_USED=85 parameter in pbackup.conf

-U 1|0

This option allows the choice of uncompressed archive files when '1' is used, or the normal gzip compressed files when '0' is used, as for TAR_UNCOMPRESSED=0 in pbackup.conf

Typically the uncompressed mode is faster and useful if most of the files do not compress very well (e.g. JPEG images, etc). This can be used in a similar manner to the -F option, before each backup type when several are wanted. For example, to run a full backup of 'home' and 'system', but uncompressed for 'home', you could use this:

run_pbackup -F 1 -U 0 -b home -U 1 -b system

(Here the -F option is given at the start, and the same value will be used unless another option is given, hence both 'home' and 'system' are full backups.)

[top]

Using the run_prestore script

Having an automated backup is only useful if you can then restore files in the event of a problem! So it is important to be able to use the run_prestore script to match the run_pbackup one, and this relies on the command line, as it is assumed the person attempting to restore files to a new or damaged system has some administrative skills.
Effect of User Account

Unlike the run_pbackup script, you do not need to be root to restore files. however, what you can do depends on your user account settings and the value of 'ALLOW_READ' in the pbackup.conf file. Basically there are three cases:

   1. If you are logged in as root, or use the sudo command, then you can restore any files to anywhere. This is typically needed to restore a new or damaged system, and obviously you can mess things up by restoring stuff to inappropriate places. The files you restore will have the original user and group settings, just as they were archived.
   2. If you are logged in as someone in the 'adm' group, which normally means you could use sudo, then you can read the backup files and restore stuff to your own area only. In this case, all restored files will have your owner/group values.
   3. If you are logged in as a non-administrative account, then if ALLOW_READ=1 you are in the same position as (2), but if ALLOW_READ=0 then you can't query or restore anything.

Operations Supported

The restore script basically allows three types of operation:

(1) You can verify the integrity of all backup files using the MD5 checksums stored when they were originally written, see the -V option.

This is very good at detecting any data errors (e.g. failing storage disk) but has not got the ability to verify that all sets to an incremental point are present.

In short, it checks for a bad backup disk, and you should do this periodically so you know your data could be restored if you need it!

(2) You can query for the existence of certain files in the archive, and selectively restore them from any selected point in time that is still available.

NOTE: While the clean-up process can result in archive files that cannot be used to restore everything to a given point-in-time, each archive is complete for the files it has. So if a file is present, it represents the whole/correct data at that time. However, a directory may not contain every file it originally did.

The -Q option is normally used for this, as it is slightly more intuitive than the -q option.

(3) You can restore everything to a point-in time. See the -A example.

[top]

Command Line Options

The command line options are:

-A

Restore ALL files. For this option you have to specify a point-in-time using the “-d date-time” option, and optionally you can limit it to single type with the “-b type” option (if the point-in-time has multiple types.

To restore the system to the original state, you have to be root (or sudo) and use the -X option to restore to the root directory of the file system. For example:

run_prestore -A -d 20091001-12.23.34 -X /

Think very carefully before using the root directory!

-b type

Specify backups of 'type'. The default is the wildcard “*” that is interpreted as all backup types.

-d date-time

Specify a given date-time directory. This is in the form of YYYYMMDD-hh.mm.ss and the default is “20*” for all backups (at least, this century!)

-Q filename

Query the archives for files matching the filename in any way. This is typically used to look for any parts of a file's path or name that you know. The use of this is slightly complicated as it is based on regular expressions, but not fully (as the -q option is).

when -b and -d are using the defaults, this will print out all matches in all archives. If you know more about the file(s), you can then use -b or -d to limit the type and/or data-time values to the set you want.

Once you have a query/type/date-time that lists exactly what you want, then you use the -R and -X options to restore those files.

-q filename

This is the query option using normal regular expressions. This is a non-obvious thing as it is quite different from the “globbing” used to expand wildcard file names on the command line. The -Q option uses this but replaces the '.' and '+' with escaped versions '\.' and '\+' so they are matched literally in the file name.

An example of this is to match all files ending with “.doc” is:

run_prestore -q '\.doc$'

The back-slach character means the '.' is treated as a period character, and not the regex 'any character' match, while the '$' at the end means the pattern must be found at the end of the name (so it would ignore test.document but find test.doc).

-B directory

Specify other back-up directory from those in pbackup.conf

-R

Restore files based on the '-Q name' sort of options. Again, use -Q (or -q) and then -b and/or -d to limit to the files you really want.

-V

Verify all backup archive file files in backup directory using the MD5 sums.

-X destination

Change to destination directory when restoring. This should be used with caution when you are root/sudo user!

The default is to restore files to the current directory. So if you log in as 'paul' you will probably start the command prompt in your home directory, say /home/paul and all files are restored to the original directory paths below this location. For example, if I restore the file /etc/pbackup/pbackup.conf then it will end up in /home/paul/etc/pbackup/pbackup.conf unless you use the -X option to tell it to put it somewhere else.

It is strongly recommended that you unpack to a safe location normally, then once you are sure, either copy the files to the wanted location, or restore to the original point. Normally only root (or sudo user) can restore anything to '/' where the original paths started.

[top]