NAME

rsyncdb -⁠ Maintain an rsync checksum DB

SYNOPSIS

rsyncdb --db=CONFIG [OPTION...] [DIR...]

DESCRIPTION

Rsyncdb can maintain a checksum-caching DB that rsync can use to make its --checksum option more optimal. You must specify a config file via the --db=CONFIG_FILE option in order for rsyncdb to know what DB to manipulate. See the rsync manpage's --db option for full details on the file's format.

You can specify one or more directory args for rsyncdb to scan. If no DIR args are specified, the current directory is assumed to be the spot to start scanning.

Note that the rsyncdb program is usually just a symlink to the rsync program. You can force rsync to behave as rsyncdb either by having a symlink (or hardlink) name that ends with "db" or by starting the rsync args with --db-only=CONFIG (and that option works just like --db=CONFIG to a program named rsyncdb).

EXAMPLES

The following command will update checksum information in the database described in the /etc/db.conf file:

rsyncdb --db=/etc/db.conf -o n --clean /dir1 /dir2

It scans 2 directory hierarchies (/dir1 & /dir2) and cleans out any checksums whose inodes are no longer found in those directories (so that directory args are presumed to be complete for this host's DB contents).

The following command will scan all the files in the /dir2 directory (without recursive scanning, due to the --no-r option) and check them against the DB:

rsyncdb --db=/etc/db.conf --check --no-r /dir2

Any errors found are output as well as being fixed in the DB. (See --no-update for how to check without updating.)

The following command will output MD5 sums for all the files found in the directories mentioned, even if they are unchanged (due to the --output=us option):

rsyncdb --db=/etc/db.conf -rous /dir* >/tmp/md5sums.txt

This is just like running md5sum, only faster. Unlike md5sum, you can't specify a single file, so use --no-r and grep the output if you just want to see a single file's value.

The following command initializes a new DB, and is required for any new DB:

rsyncdb --db=/etc/db.conf --init --mounts

The --init option should only be used once (unless you want to destroy existing data). The --mounts option may need to be used periodically, and makes use of a helper script (see below).

OPTIONS SUMMARY

Rsyncdb accepts the following options:

--db=CONFIG       Specify the CONFIG file to read for the DB info
--db-lax          Ignore ctime changes (use with CAUTION)
--recursive, -r   Scan files in subdirs (the default w/o --no-recursive)
--sums=SUMS, -s   List which checksums to update (default: 4,5)
--output=STR, -o  One or more letters of what to output (default: "")
--check, -c       Check checksums (by reading the files) and fix any
                  issues.  Makes --output default to "dni".
--clean           Note all inodes in the DIRS and remove DB extras
--no-update, -N   Avoids updating/adding info w/--check and/or --clean
--init            Initialize a DB by (re-)creating its tables
--mounts          Scan for mounted filesystems and update the DB
--quiet, -q       Disable the default non-error output
--help, -h        Display this help message

OPTIONS

Rsyncdb accepts both long (double-dash + word) and short (single-dash + letter) options. The full list of the available options are described below. If an option can be specified in more than one way, the choices are comma-separated. Some options only have a long variant, not a short. If the option takes a parameter, the parameter is only listed after the long variant, even though it must also be specified for the short. When specifying a parameter, you can either use the form -⁠-⁠option=param or replace the '=' with whitespace. The parameter may need to be quoted in some manner for it to survive the shell's command-line parsing.

--db=CONFIG_FILE

This tells rsyncdb what DB-config file to read for the DB setup. This is the same as the option in rsync, so refer to that manpage for full details.

--db-lax

This option works just like it does in rsync, so refer to that manpage for full details.

--no-recursive, --no-r

This disables the default recursive directory scan that is performed on the listed directory args. The options --recursive and -r are also accepted, if someone wants to override an earlier --no-r override.

--sums=SUMS, -s

Only output/update the listed checksum types. By default we deal with just the newer md5 checksums (i.e. --sums=5).

Note that this option does NOT affect the order that checksums are output if "-⁠o s" is enabled, so -s5,4 is the same as -s4,5.

--output=STR, -o

The output option lets you specify one or more letters indicating what information should be output. If --output is not specified, the default is either "dn" or (with --check) "dni".

The following letters are accepted in the string:

• d outputs "... dir_name ..." lines for each directory in our scan. if "d" is omitted, then this progress indictor is not output.
• n includes the file's name in the per-file output. These lines are only output for changed files unless "u" is given. The "n" option is implied by every other output option letter except "d".
• s includes the checksum info in the per-file output.
• c is a synonym for 's'.
• i includes itemized change info in the per-file output.
  • !i indicates that the time and/or size is wrong.
  • +4 indicates the MD4 sum is missing.
  • +5 indicates the MD5 sum is missing.
  • !4 indicates the MD4 sum is wrong.
  • !5 indicates the MD5 sum is wrong.
  • ?4 indicates an unknown MD4 difference. This can happen if we didn't need to read the file; i.e. if the time/size is wrong and no sum info was requested.
  • ?5 indicates an unknown MD5 difference.
• u includes unchanged files in the per-file output lines.

--check, -c

Check the checksums (forcing the reading of all the files) and fix any issues that are found. Makes --output default to "dni".

--clean

Makes a temp-DB of all the inodes that we find in all the listed directories and removes any extraneous checksums from the DB. You will need to specify all the mounted directories that are present (and listed as mounted) in the DB on this host or else the checksums from the unvisited directories will be discarded from the DB. If you want to just -⁠-⁠clean without adding or updating the info of new or changed files, specify --no-update as well.

--no-update, -N

Avoids updating/adding info with --check and/or --clean.

--quiet, -q

Disable the default (non-error) output settings. This turns off the messages that --init, --mount, and --clean output, and makes the default for --output be nothing (though an explicit --output option is not affected).

--init

Create the tables in the DB. If it is used on an existing DB, all the existing tables are dropped and re-created.

This option cannot be combined with the updating or reporting of checksum information, but may be combined with --mounts.

--mounts

Populate the "disk" DB with the available device numbers and change any mounted/unmount information for devices. This should be run every time a mount-change happens that may affect a directory hierarchy in the DB. Rsyncdb will not save any checksums for a device that is not listed in the "disk" table.

The helper script "rsyncdb-mountinfo" is used as the source of the mount information on the host, which it derives from various system files and UUID directories (if available). That script supports the use of an override file named ".rsyncdb_mount_uniq" in the root of the mount as one way to manually assign unique values to a shared (mountable) device's various disks.

Some advanced users may want to maintain the disk table themselves in order to support mounting a drive in different (or multiple) locations, etc.

Specifying the --mounts option cannot be combined with updating or reporting of checksum information, but may be combined with --init.

--help, -h

Display a summary of the options.

SEE ALSO

rsync(1)

AUTHOR

Rsyncdb was written by Wayne Davison.