/ 
CLI-Startup-0.29
River stage zero No dependents
/ rs

NAME

rs - Wrapper for backups using rsync

SYNOPSIS

rs                        ;# Use default settings from $HOME/.rsrc
rs [options] [module ...] ;# Backup the named modules

DESCRIPTION

The rs command is a simple wrapper around rsync that provides three basic services:

  • It uses only the plain-English versions of rsync options,

  • It supports a config file containing default options, and

  • The config file supports named groups of options, called (for lack of a better term) "modules."

    • A combination of options lets you invent custom "modes."

    • A combination including --src and --dest helps you make routine backups.

Default Options

The default options are convenient for doing ad hoc copies using rsync with default options. It lets you say this:

rs --src $HOME --dest backup:homedir/

instead of this:

rsync --archive --compress --delete --rsh ssh \
      --src $HOME/ --dest backup:homedir/

If you usually use the latter combination of options, as I do, then rs can at least save you some typing.

Named Modules

As Command Names

Named "modules" are groupings of options in the config file, $HOME/.rsrc by default. The rsync command supports the --archive option, which represents the grouping:

--recursive --links --perms --times --group --owner --devices --specials

Using rs, you can define a new grouping called "backup" which adds additional options, by putting the following in your config file:

[backup]
archive=1
compress=1
delete=1
rsh=ssh -2 -c arcfour -l backup_user -p 2222 -y -o BatchMode=yes

Now you can make a backup of your home directory simply by issuing the command:

rs backup --src $HOME/ --dest backup:homedir/

As Backup Tasks

If a grouping in your config file includes --src and --dest options, then you can make a backup of a specific folder to a specific destination without remembering combinations of options. For example, you can put this in your config file:

[documents]
delete=1
exclude=*.tmp, *.bak, tmp/
src=/home/USERNAME/Documents/
dest=backup:Documents/

And now you can backup your Documents folder by issuing the command:

rs documents

You can define multiple backup targets in this way, and then do all your nightly backups in a single command, like this:

rs documents music pictures

Restoring from Backup

rs also adds the --restore option, which reverses the role of --src and --dest. If you're using those options directly, you probably don't want to use --restore option to swap them, since that will only confuse you. If you're using modules defined in the config file, however, and you think of those modules as backups, then --restore probably does exactly what you think it does.

OPTIONS

--archive

Use rsync in "archive" mode; see the manpage for rsync. Defaults to true. Can be negated by setting the --no-archive option.

--checksum

Use rsync checksums to decide which files to update, instead of looking at the modification time and file size. Turned off by default.

--compress

Use compression; defaults to true. Disable compression entirely by using the --no-compress option.

--delete

Delete extraneous files in the destination folders. Not enabled by default, but for backup purposes you probably want to enable it.

--dest [ HOST:DIRECTORY | HOST: | DIRECTORY ]

Local or remote directory to copy to. Mandatory unless one or more modules are specified on the command line.

--devices

Preserve device files (super-user only). Implied by --archive, which is enabled by default, so this option is unset by default. It can be specifically disabled using the --no-devices option.

--dry-run

Don't write any files; just print what actions would be taken.

--exclude [pattern]

Exclude files matching pattern. Can be limited by also specifying the --include option.

--group

Preserve group ownership. Implied by --archive, which is enabled by default. This option is unset by default, since it would be redundant. It can be specifically disabled using the --no-group option.

--help

Print a helpful help message.

--include [pattern]

Don't exclude files that match pattern. Only does anything if the --exclude option is also specified.

--links

Copy symbolic links as symbolic links. Implied by --archive, which is enabled by default. This option is unset by default, since it would be redundant. It can be explicitly disabled using the --no-links option.

--manpage

Display this manpage and exit.

--owner

Preserve file ownership (super-user only). Implied by --archive, which is enabled by default. This option is unset by default, since it would be redundant. It can be explicitly disabled using the --no-owner option.

--perms

Copy file permissions. Implied by --archive, which is enabled by default. This option is not set by default, since it would be redundant. It can be explicitly disabled using the --no-perms option.

--rcfile FILE

Read default settings from FILE instead of $HOME/.rsrc.

--recursive

Recurse into sub-directories. Implied by --archive, which is enabled by default, so this option is unset by default. It can be specifically disabled using the --no-recursive option.

--restore

Reverse the roles of --src and --dest. If you think of rs as making a backup, then --restore does just what you think it does: it pulls from the backup destination and overwrites the file or directory that you're normally backing up.

--rsh [command]

Command to use for remote access. Defaults to ssh. A good choice for performance reasons is ssh -c arcfour.

--rsync-path [path]

Path to run rsync on the remote host.

--specials

Preserve special files (super-user only). Implied by --archive, which is enabled by default, so this option is unset by default. It can be specifically disabled using the --no-specials option.

--src [ HOST:DIRECTORY | HOST: | DIRECTORY ]

Local or remote directory to copy from. Mandatory unless one or more modules are specified on the command line.

--times

Preserve file creation and modification times. Implied by --archive, which is enabled by default, so this option is unset by default. It can be specifically disabled using the --no-times option.

--version

Print version information and exit.

--write-rcfile

Write $HOME/.rsrc or the file specified by --rcfile with the settings from the current invocation.

SEE ALSO

rsync(1), ssh(1)

COPYRIGHT

Copyright (C) 2011 Len Budney.

This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.

See http://dev.perl.org/licenses/ for more information.