RVM(1)

NAME

rvm - rsync vault manager

SYNOPSIS

    rvm [ action ]
        [ --timestamp timestamp ]
        [ --no-default-config ]
        [ [ --config config-file ] ... ]
        [ [ --job job-file ] ... ]

DESCRIPTION

Rvm is an archive manager that uses rsync to create and maintain a list of archives that span one or more archive vaults. A vault is defined as a directory on a logical partition that holds one or more archives. An archive is defined as a subdirectory on a vault, with a time stamp for a name, that holds the files and directories backed up from one or more archive jobs. Files in newer archives that are identical to files in older archives may be optionally replaced with hard links to save space.

COMMAND LINE ACTION OPTIONS

Rvm will expect one action command line option to be given. Actions are mutually exclusive. If multiple action options appear on the command line, only the last option encountered will be taken.

--archive

    Create a new archive or update the files in an existing archive. Whether an existing archive is updated or a new archive is created depends on the timestamp-resolution configuration command, and the timestamp of the last archive created. If an archive is found with the same timestamp as the one generated at execution time, then that archvie is used regardless of the vault on which it appears.

    If the link-catalog-dir configuration command is used, then the link catalog is updated after all archive jobs have been processed.
--relink

    Update the link catalog. Do not create a new archive or refresh any existing archive. This option requires that the configuration command link-catalog-dir appear somewhere in the configuration file(s). This command is not required and has no default value. If no value is specified in a configuration file then rvm will take no action.
--check-config

    Load the configuration file(s) and perform all configuration checks, but do nothing more. Rvm will print an error on standard error and exit with an error code if any problems were found with the configuration settings. Rvm will print nothing and exit with a successful exit code if there are no problems.
--help

    Print the version number and a synopsis of command line options, then exit.
--version

    Print the version number then exit.

COMMAND LINE OPTIONS

The following command line options are used in conjunction with one of the action options to direct rvm's behavior. --timestamp timestamp

    Override the default timestamp generated at execution time and force rvm to use the given timestamp instead. This option may only be used on the command line once. If it appears multiple times then only the last timestamp given will be used.

    Timestamps must be specified in the form of:

        [ YYYY [ - MM [ - DD [ . HH [ MM [ SS ]]]]]]

    Where:

        YYYY
            A four-digit year.

        MM  A two-digit month.

        DD  A two-digit day of the month.

        HH  A two-digit hour of the day, in 24-hour format (00-23).

        MM  A two-digit minute.

        SS  A two-digit second.

    No spaces are allowed. The number of segments specified in the timestamp will override any timestamp-resolution setting that may appear in the configuration files.
--no-default-config

    Do not attempt to read configuration information from the default configuration file /usr/local/etc/rvm.conf. This command line option must be used in conjunction with the --config command line option to tell rvm to read another configuration file instead of the default configuration file. Rvm will exit with an error if no configuration files are read.
--config config-file

    Read configuration information from config-file. If used without the --no-default-config option, rvm will read the configuration file config-file after attempting to read the default configuration file /usr/local/etc/rvm.conf. If used with --no-default-config, rvm will read only config-file, and will not read /usr/local/etc/rvm.conf. Multiple uses of this command line option will result in rvm reading each file passed on the command line in the order given.

    If config-file is a relative pathname, then it is assumed to be relative to the location from which rvm is executed. If config-file contains wildcard characters, then all files that match will be read in alphabetical order. Note that wildcard characters must either be quoted or escaped or the shell may expand it's value before passing the command line to rvm, which may result in undesired behavior.
--job job-file

    Read the contents of job-file as the contents of an archive job block. This command line option is synonymous with the read-job configuration command. Contents of the file job-file should not be enclosed in a <job>...</job> block, as a job context is already implied. If a begining or ending job block command is found in the job-file file, then rvm will exit with an error.

    If job-file is a relative pathname, then it is assumed to be relative to the location from which rvm is executed. If job-file contains wildcard characters, then all files that match will be read in alphabetical order, each as a separate job. Note that wildcard characters given on the command line must either be quoted or escaped or the shell may expand it's value before passing the command line to rvm, which may result in undesired behavior.

    This command line option may be used multiple times to have rvm read several job files.

TERMINOLOGY

Archive Administrator

    The user in charge of setup and maintenance of rvm and all associated files and directories.
Configuration File

    A file used to change rvm's behavior. Multiple configuration files may be used, and each file may include the contents of other files. By default rvm will look for the file /usr/local/etc/rvm.conf, unless told to do otherwise by the --no-default-config command line option. Rvm may also be told to read extra configuration files with the --config and --job command line options.
Vault

    A repository for archives. A vault is merely a directory under which archives are created and maintained. One or more vaults may be used. It is recommended that, when using multiple vaults, each vault be located either on separate physical devices or at least separate logical partitions for increased reliability in the event of disk corruption or failure.
Archive

    An archive is a subdirectory within a vault, with a time-sensitive directory name, that houses the files and directories from one or more archive jobs. The name of the archive subdirectory is generated from the timestamp created at the time that rvm is executed. An archive may optionally contain hardlinks from files within to files in an older archive if the file has not changed.
Archive Job

    An archive job consists of files and directories that are to be backed up from some source. A job may consist of local files and directories, or files and directories mounted over NFS or Samba, or files and directory located on a remote host accessible by rsync via RSH or SSH, or files and directories located on an rsync server. The files and directories backed up from the specified source may be stored in a user-configurable subdirectory tree under the archive directory.

EXECUTION

When rvm is executed it will first set default values for all configuration settings. Next rvm will parse command line options.

If rvm was executed with the --help or --version command line options, then rvm will print out it's version number, and optionally a usage summary, then exit.

If any other action options were selected, then rvm will next try to read configuration files. If the --no-default-config command line option was used then rvm will not try to read the default configuration file, /usr/local/etc/rvm.conf. Otherwise, rvm will attempt to locate and read this file first. If this file cannot be found, rvm will exit with an error. Next, if any --config or --job command line options were used then rvm will attempt to find and read those configuration files. If any errors were detected in any of the configuration files found then rvm will exit with an error.

If rvm was executed with the --check-config option, then rvm will exit after successfully reading all configuration files.

If the --relink action was selected, and a valid directory was given for link-catalog-dir in the configuration file(s), then rvm will rebuild the link catalog directory and exit.

If the --archive action was selected, then rvm will begin the archiving process. Rvm will next select a vault and prepare that vault for a new archive. Vault selection may be modified with the vault-selection-behavior configuration command. Vaults may be selected round-robin style, where each vault listed in rvm's configuration files will be used in turn, or vaults may be selected on the grounds of which vault has the most free space available.

Vault preparation involves checking the vault for available space, as specified with the vault-overflow-blocks and vault-overflow-inodes configuration commands. If the filesystem on which the selected vault resides has fewer than the specified percentage of free blocks or inodes, then the vault is considered to have exceeded it's overflow threshold. If this condition occurs, then rvm will take the action specified by the vault-overflow-behavior configuration command. Depending on this configuration setting, rvm may take one of three actions. By default, rvm will simply exit with an error. Rvm may also be instructed to delete the oldest archive found on the selected vault and re-check the filesystem's available space. If, after deleting the oldest archive found, the filesystem's used space has fallen below the overflow threshold, then rvm will continue with execution; otherwise rvm will exit with an error. Lastly, and most dangerously, rvm may be instructed to continue deleting old archives until either sufficient space is found or the vault runs out of old archives.

After vault selection and preparation, rvm will create a new archive subdirectory on the vault using either the timestamp given by the --timestamp command line option, or a generated timestamp constructed according to the timestamp-resolution configuration command.

Next rvm will spawn children to process archiving jobs. Each child will handle a single job and archive all the paths associated with that job, and then send a report back to the parent rvm process. By default, rvm will only spawn one child process at a time unless specified otherwise with the rsync-parallel configuration command. Each child will interpret rsync's output and exit codes, and if unsuccessful, the child may retry the command a certain number of times before giving up, as specified by the rsync-retry-count and rsync-behavior configuration commands.

After all jobs have completed, rvm may optionally create or update the link catalog directory, if link-catalog-dir configuration command was found in the configuration file(s).

Finally, rvm will generate a report that it will print to standard output and save to a file in the log directory.

EXIT CODES

Exit codes returned by rvm are:

0   Successful completion of all archive jobs.

1   A configuration error occured.

2   The selected vault is full.

3   One or more archive jobs failed.

4   An internal or fatal error occurred.

CONFIGURATION

Rvm is configured through the use of one or more configuration files. By default rvm will search for the file /usr/local/etc/rvm.conf, unless this behavior is overridden by the use of the --no-default-config command line option. If /usr/local/etc/rvm.conf does not exist then rvm will search for files passed to it using the --config and --job command line options. If no configuration files can be found then rvm will exit with an error.

Blank lines and lines that begin with a '#' are ignored.

A configuration file may include the contents of another file, or a configuration file may include the contents of all files that match a wildcard filename. Included files may in turn include more files. (Note that reading the contents of included files is done recursively, meaning that it is possible for rvm to exceed it's stack size, resulting in an error.)

All configurable settings are listed on a single line in the form of keyword-value pairs unless specified otherwise. Each line begins with a case-insensitive keyword followed by a value and a newline character '\n'. White space is ignored except for certian values that may be specified using double quotes. Some configuration commands are required to appear in a configuration file, others have default values that are assumed. Some configuration commands may be used multiple times, for others, multiple use will override that command's previous settings.

Configuration commands are context-sensitive. A configuration file consists of three sections: a global section, one or more default sections, and one or more job sections. Some configuration commands are allowed in any context, while others may only be used in a default or job context.

CONFIGURATION COMMANDS USED IN ANY CONTEXT

These are commands that may appear anywhere in a configuration file in any context. include path

    Stop reading the current configuration file and read the contents of the file path. When finished, continue reading the current file.

    If path is a relative pathname, then it is assumed to be relative to the directory of the configuration file in which this command is found. This is in contrast to the --config and --job command line options, where a relative pathname is assumed to be relative to the directory from which rvm is executed.

    If path contains wildcard characters, then each matching file found will be read in alphabetical order. If no files are found, then rvm will exit with an error. Included files may in turn contain commands to include other files. Multiple uses of this command are allowed. This command is not required, and has no default value.

    When including the contents of another file, rvm behaves as though the file included were literally pasted into the current file at the current location. If an included file changes the configuration context then the new context remains in effect when rvm finishes reading the included file and continues with the current file. This must be taken into account when authoring configuration files or at best, an error will occur, and at worst, confusing and undesired effects may occur.

GLOBAL CONTEXT CONFIGURATION COMMANDS

When rvm begins reading the first configuration file it assumes a global context until a default or job context is specified. Global commands affect the overall behavior of rvm, such as the method used to select vaults, the location of the local rsync binary, or the number of jobs to process in parallel. This is in contrast to default or job contexts, where commands affect the behavior of rvm's children as they process a particular job. <default>...</default>

    Configuration settings in a default context are specified by placing those settings inside a default block. A default block begins with the text "<default>" on a line by itself, and ends with the text "</default>" on another line by itself. Lines in between are applied to the default settings. These default settings will be assumed by all jobs that follow until another default block is encountered. Commands given in a default block may be overriden by commands found within a job block, but this override will not affect other jobs that follow.

    The settings used in a default block are only changed by the appearance of another default block. When another default block is encountered, all default settings not specified in the new default block are reset, settings from previous default blocks do not carry over into the new default block.

    This command is not required, and if not used the following values are assumed:

        <default>
          archive-path hostname/path
          rsync-behavior * = retry
          rsync-behavior 0 = ok
          rsync-behavior 1 = fail
          rsync-behavior 2 = fail
          rsync-behavior 4 = fail
          rsync-behavior 23 = retry-without-hardlinks
          rsync-behavior 124 = fail
          rsync-behavior 125 = fail
          rsync-behavior 126 = fail
          rsync-behavior 127 = fail
          rsync-connection-type remote
          rsync-hardlink yes
          rsync-retry-count 3
          #
          # 14400 = 60 sec/min * 60 min/hr * 4 = 4 hours
          #
          rsync-timeout 14400
        </default>

    Default values may themselves be reset to rvm's built-in default values by specifying an empty default block, like so:

        <default>
        </default>
include-job path

    Stop reading the current configuration file, assume a job context, and read the contents of the file path. When finished, switch back to a global context and continue reading the current configuration file.

    This command may be thought of as a one line short cut for the following:

        <job>
          include path
        </job>

    If path is a relative pathname, then it is assumed to be relative to the directory of the configuration file in which this command appears. This is in contrast to the --job command line option, where job-file is assumed to be relative to the location from which rvm is executed.

    If path contains wildcard characters, then each matching file found will be included in alphabetical order as a separate job. If no matching files are found then rvm will exit with an error.

    Multiple uses of this command will append new jobs to the job list.
<job>...</job>

    Configuration settings in a job context are specified by placing those settings inside a job block. A job block begins with the text "<job>" on a line by itself, and ends with the text "</job>" on another line by itself. When rvm encounters a job block in a configuration file a new job is created and appended to the job list. The newly created job will assume default values either from rvm or from the last default block encountered. After default values have been assigned then the commands inside the job block are read and their settings applied.
link-catalog-dir path

    If this command is found, then rvm will create a catalog of all archives in the directory path using relative symbolic links. If path does not exist, then rvm will exit with an error. If path is a relative pathname, then it is assumed to be relative to the location from which rvm is executed.

    This command is not required and has no default value. Multiple uses of this command will overwrite any previous value.

    NOTICE: If the archive administrator chooses to export the path directory to other hosts, then all vault directories must also be exported. Also, these directories must be mounted on remote machines in such a way that will preserve the validity of the relative symbolic links in path.
log-dir path

    Create log files under the directory path. Rvm will use /var/log/rvm if no other setting is found. Multiple uses of this command will overwrite any previous value. If path is a relative pathname, then it is assumed to be relative to the location from which rvm is executed.
logging-level option

    Specify the degree of verbosity used when writting to the log file. Valid values for option are:

        manager
            Log only the messages that come from the controlling parent rvm process.

        child
            Log messages from the controlling parent and from child rvm processes.

        rsync
            Log all messages from rvm and from rsync.

    Rvm will use the default value of "rsync" if no other setting is provided. Multiple use of this command will overwrite any previous value.
rsync-local-path path

    Specify the location of the rsync program on the local host. The value for path should be an absolute pathname.

    At the time that rvm is compiled, if rsync was found in the one of the directories specified by the PATH environment variable, then that value will be used by default. Otherwise, if rsync could not be found at compile time, and rsync-local-path is not specified, rvm will exit with an error.

    Multiple uses of this command will overwrite any previous value.
rsync-parallel integer

    The number of jobs rvm is to process in parallel. Rvm will spawn up to integer child processes to handle jobs from the job list. When one job completes that child will exit and another child process will be created to handle the next available job. If rvm encounters an error when attempting to create a child process, then rvm will print an error message to the log file and attempt to create a new process again at a later time.

    Valid values are any integer greater than 0. Rvm will assume the default value of 1 if no other setting is found. Multiple uses of this command overwrite any previous value.
io-poll-interval integer

    The number of seconds to sleep between polling for I/O from child processes. Valid values are any positive integer value including 0. Rvm will assume the default value of 1 if no other setting is found. Multiple uses of this command overwrite any previous value.
timestamp-resolution option

    A configuration setting specifying the depth of resolution used in creating timestamps. Valid values for option are:

        year
            Use a four-digit year as the archive timestamp.
            Example: 2003

        month
            Same as year, followed by '-' and a two-digit month.
            Example: 2003-09

        day Same as month, followed by '-' and a two-digit day of the month.
            Example: 2003-09-10

        hour
            Same as day, followed by '.' and a two-digit hour in 24-hour format.
            Example: 2003-09-10.13

        minute
            Same as hour, followed by a two-digit minute.
            Example: 2003-09-10.1359

        second
            Same as minute, followed by a two-digit second.
            Example: 2003-09-10.135933

    Timestamps are used to generate archive directory names and log filename extensions. A new timestamp is generated each time rvm is executed. The timestamp resolution setting allows the archive administrator to control to what degree timestamps are created. For instance, a timestamp resolution of "year" would result in a new archive being created once a year. If rvm is then run a second time within the same year then rvm will update the existing archive rather than create a new archive. At the other end of the scale, a timestamp resolution of "second" would result in a new archive being created each second (or more likely, each time rvm is run, since rvm will probably take longer than one second to complete an archive of any significant size).

    The default value used is "day". Multiple uses of this command will overwrite any previous value.

    NOTICE: Care should be taken when modifying this value. If rvm is executed twice with the same timestamp-resolution period, and the first instance of rvm has not completed, then that archive may be corrupted.
vault path

    Designate the directory path to use as a vault. More than one vault may exist on the same logical disk partition, although it is recommended that vaults exist on separate physical devices, or at least on separate logical partitions. This is for the safety and integrity of the archives in the event of disk corruption or failure.

    If path is a relative pathname, then it is assumed to be relative to the location from which rvm is executed. If path does not exist then rvm will exit with an error. If path contains wildcard characters, then all matching pathnames are used as vaults. If no matching pathnames are found then rvm will exit with an error.

    Once rvm has finished reading all of it's configuration files, if no usable vaults exist then rvm will exit with an error.

    Multiple uses of this command will add to the list of vaults.
vault-overflow-behavior keyword

    Define how rvm should handle a vault that is approaching maximum capacity. Valid values for keyword are:

        quit
            If there is insufficient space available on the selected vault then exit with an error.

        delete-oldest
            If there is insufficient space available on the selected vault, then delete the oldest archive from the vault and check for available space again. If, after deleting the oldest archive, there is still insufficient space, exit with an error.

        delete-until-free
            If there is insufficient space available on the selected vault, then delete the oldest archive from the vault and check for available space again. If there is still insufficient space in the vault, then continue deleting the oldest archive found until either sufficient space is available or there are no old archives left. If there is still insufficient space, then exit with an error.

        Rvm will assume a value of quit by default. Multiple uses of this command overwrite any previous value.

        NOTICE: Rvm will check the free space on the selected vault several times during execution. If a child process exits with an error, the vault is checked to see if it has exceeded it's overflow threshold. If so, and vault-overflow-behavior is set to either "delete-oldest" or "delete-until-free", then rvm will attempt to remove the oldest archive in the vault and retry the failed job. If, during archival, the size of an archive increases dramatically (to 50% of a vault's capacity or more) then the use of "delete-oldest" or "delete-until-free" could cause rvm to continually delete older archives, which may not be the desired behavior.
vault-overflow-blocks integer

    Define for rvm a threshold used to decide when a vault has become alarmingly close to full capacity. Rvm is to consider the selected vault to have exceeded it's overflow capacity if there is less than integer percent of free blocks left on the logical partition in which the vault resides. The value for integer must be between 0 and 50 inclusively.

    Rvm will use a default value of 15 if no other setting is found. Multiple uses of this command will overwrite any previous value.
vault-overflow-inodes integer

    Define for rvm a threshold used to decide when a vault has become alarmingly close to full capacity. Rvm is to consider the selected vault to have exceeded it's overflow capacity if there is less than integer percent of free inodes left on the logical partition in which the vault resides. The value for integer must be between 0 and 50 inclusively.

    Rvm will use a default value of 15 if no other setting is found. Multiple uses of this command will overwrite any previous value.
vault-selection-behavior keyword

    Specify the method by which rvm is to select the next vault from the list of available vaults. Valid values for keyword are:

        max-free
            Determine the amount of free space available on each vault and choose the vault with the most free space. If all vaults are equally filled, then fall back to using the round-robin method.

        round-robin
            Determine the last vault used the last time rvm was executed and select the next vault from the list of available vaults. If the last vault in the list was the last vault used, then begin again with the first vault in the list.

    Rvm will use the default value "round-robin" if no other setting is found. Multiple uses of this command overwrite any previous value.

DEFAULT CONTEXT CONFIGURATION COMMANDS

Configuration commands in a default context specify a default behavior to be assumed for subsequent archive jobs. Multiple default contexts may be used to set and reset the default values. When multiple default contexts are used, all values from the previous default context are cleared. When default settings are reset, all subsequent jobs are assigned values from the new default settings, while previous jobs are left unaffected. archive-path keyword[/keyword...]

    This command specifies how rvm should generate the archive job subdirectory under which to store files and directories backed up from this archive job. The complete path to an archive job's files follows from the root of the filesystem, down the path of the selected vault, into the archive subdirectory, and then down this user-specific path.

    The value for this command consists of one or more options separated by a directory slash character with no whitespaces allowed in between. Valid values for keyword are:

        jobname
            The name assigned to this job.

        groupname
            The group name assigned to this job.

        hostname
            The remote machine's host name.

        pathname
            The path currently being archived. Each job may specify multiple paths, therefore the value of archive-path must be calculated for each path listed in a job.

        permutation
            A permutation of the path currently being archived. The permutation process removes any preceding or trailing slashes, and changes all intermediate slashes in the path name to dashes. An example permutation of the path "/var/spool/cron/crontabs" would be "var-spool-cron-crontabs".

        (literal)
            A literal string may be used by surrounding the string with double quotes. Directory slash characters are not allowed within the string, and double quotes within the string must be escaped by preceeding them with a '\' character. An example could be:
            archive-path groupname/"Samba-Mounted-Hosts"/permutation

    Rvm will use the default value "hostname/pathname" if no other setting is found. Multiple uses of this command will overwrite any previous values within the same context.

    NOTICE: Great care should be taken when using this command, as incorrect settings could result in a corrupted archive. Consider the following configuration:
        vault /export/vault1
        archive-path groupname
        <job>
          groupname cartoon
          hostname ren
          path /var/spool/cron/crontabs
        </job>
        <job>
          groupname cartoon
          hostname stimpy
          path /var/spool/cron/crontabs
        </job>

    For the above configuration, files from the host ren:/var/spool/cron/crontabs and files from the host stimpy:/var/spool/cron/crontabs are both placed in the directory /export/vault1/timestamp/cartoon/. If both ren and stimpy contain crontabs for root, then root's crontab file from stimpy will overwrite root's crontab file from ren, resulting in a corrupted archive.
clear keyword

    Erase a previous default value for a specific configuration setting. Valid values for keyword are:

        archive-path
            Clear the default archive-path value.

        exclude-from
            Clear the list of files in the exclude list.

        groupname
            Clear the default groupname.

        hostname
            Clear the default hostname.

        include-from
            Clear the list of files in the include list.

        jobname
            Clear the job name.

        paths
            Clear the list of paths to be archived.

        rsync-behavior
            Clear the rsync behavior table.

        rsync-options
            Clear the list of options to pass to the rsync binary.

        rsync-remote-user
            Clear the username to pass to rsync to use when connecting to a remote machine.

        rsync-remote-port
            Clear the port number to pass to rsync to use when connecting to a remote machine.

        rsync-remote-path
            Clear the pathname of rsync on the remote machine.

    This command can be used to override default values either set by rvm or set in the last default context.
exclude-from path

    Specify a file to pass to the rsync program using the --exclude-from command line option. The rsync man page should be consulted on the syntax and usage of this file. When rvm constructs the command line to pass to rsync, files listed in the exclude-from list are passed before files listed in the include-from list.

    If path is a relative pathname, then it is assumed to be relative to the directory of the configuration file in which this command appears. If path contains wildcard characters, then all matching files will be passed to rsync in alphabetical order, each using a separate --exclude-from command line option. If no matching files are found then rvm will exit with an error.

    Multiple uses of this command will generate a list of pathnames within the current context, all of which will be passed to rsync, each on a separate --exclude-from command line option.
groupname name

    This configuration setting assigns a group name to a job. The value of name may be any string of valid filename characters except a directory slash.

    This command is only required if the "groupname" keyword is used by archive-path.

    Multiple uses of this command will overwrite any previous values within the same context.
hostname name

    Assign a hostname to a job. If rsync must connect to a remote host for this job, then it will connect to name.

    This command is only required if:

        -   This job either must connect to a remote host via RSH or SSH, or to an rsync server, as specified by the rsync-connection-type command.

        -   The "hostname" keyword is used by archive-path (which it is by default).

    Multiple uses of this command will overwrite any previous value within the same context.
include-from path

    Specify a file to pass to the rsync program using the --include-from command line option. The rsync man page should be consulted on the syntax and usage of this file. When rvm constructs the command line to pass to rsync, files listed in the exclude-from list are passed before files listed in the include-from list.

    If path is a relative pathname, then it is assumed to be relative to the directory of the configuration file in which this command appears. If path contains wildcard characters, then all matching files will be passed to rsync in alphabetical order, each using a separate --include-from command line option. If no matching files are found then rvm will exit with an error.

    Multiple uses of this command will generate a list of pathnames within the current context, all of which will be passed to rsync, each on a separate --include-from command line option.
path path

    Assign a file or directory to be archived in a job.

    This command is required to appear at least once, either in a job context or in a previous default context.

    This command has no default value. Multiple uses of this command will append to a list of pathnames to be archived.

    NOTICE: When archiving an entire directory tree, a trailing '/' must appear at the end of path, and the -r option must be passed to rsync via the rsync-options command.
rsync-behavior exit-code = action

    If an rsync command returns a non-zero exit code, rvm may retry the command up to the number of times specified by the rsync-retry-count configuration setting. Rvm may also be directed to modify it's command line for rsync, or to take some specific action, depending on the exit code returned. This command is used to specify how rvm should handle different exit codes that may be returned by rsync. Valid values for exit-code may be an integer value between 0 and 255 inclusively. The asterisk character, '*', may also be used as a wildcard to mean any exit code. When the given exit code is encountered the associated action is taken. Valid values for action are:

        ok  Ignore the error code returned by rsync and pretend rsync exited successfully.

        fail
            Give up immediately without attempting to retry the rsync command. (See rsync-retry-count.) This is most useful for exit codes from which retrying will not yield better results. For example, if the current job is configured to connect to a remote host using SSH, and SSH is reporting that rsync cannot be found on the remote host.

        retry
            Try the rsync command again exactly as before. Useful for overcoming intermittent connectivity problems.

        retry-without-hardlinks
            Try the rsync command again, except this time disable the option that allows rsync to create hardlinks for files that have not changed from previous archives. (This is useful in situations where the older archive chosen as the hardlink source contains corrupted file modes.)

    A complete list of known rsync exit codes are, as found in errcode.h of the rsync source tree:

        0   Success

        1   Syntax or usage error

        2   Protocol incompatibility error

        3   Errors selecting I/O files or directories

        4   Requested action not supported

        5   Error starting client-server protocol

        10  Error in socket I/O

        11  Error in file I/O

        12  Error in rsync protocol data stream

        13  Errors with program diagnostics

        14  Error in IPC code

        20  Status returned when sent SIGUSR1, SIGINT

        21  Some error returned by waitpid()

        22  Error allocating core memory buffers

        23  Partial transfer

        30  Timeout in data send/receive

        124 The command executed by SSH exited with status 255

        125 The command executed by SSH was killed by a signal

        126 The command given to SSH cannot be run

        127 The command given to SSH cannot be found

    Multiple instances of this directive may be used to specify different actions for different exit codes.

    Rvm will use the following settings if no other settings are found:
        rsync-behavior * = retry
        rsync-behavior 0 = ok
        rsync-behavior 1 = fail
        rsync-behavior 2 = fail
        rsync-behavior 4 = fail
        rsync-behavior 23 = retry-without-hardlinks
        rsync-behavior 124 = fail
        rsync-behavior 125 = fail
        rsync-behavior 126 = fail
        rsync-behavior 127 = fail

    Multiple uses of this command will overwrite any previous value for the same exit-code within the same context.
rsync-connection-type keyword

    There are three ways of using rsync to update files. One method is to use rsync in a local mode, where files and directories in one location on the local host are updated by comparing them to files and directories in another location also on the local host. This method may be used to archive files mounted on the local machine, either from a physical device, an NFS mount, or a Samba mount. The second method of using rsync is to connect to a remote host via RSH or SSH. The third method is to use rsync to connect to an rsync server. This command changes the way that rvm will use rsync when processing an archive job.

    Valid values for keyword are:

        local
            Use rsync in local mode to archive files from a source that is mounted on the local machine.

        remote
            Use rsync to archive files from a remote host using RSH or SSH.

        server
            Use rsync to archive files from a remote host running an rsync server.

    Rvm will use the default value of "remote" if no other setting is found.

    Multiple uses of this command will overwrite any previous value within the same context.
rsync-hardlink bool
    Turn on or off the ability to hardlink unchanged files from an older archive.

    Valid values for bool are:
        "y"|"n", "yes"|"no", "t"|"f", "true"|"false", "1"|"0", or "on"|"off"

    This command is not required. Rvm will use "on" if no other setting is found. Multiple uses of this command will overwrite any previous value within the same context.
rsync-options options
    Define the command line options that rvm is to pass to rsync. Command line options listed here should not include --rsync-path, --hard-links, --link-dest, --exclude-from, --include-from, or the local and remote host or path. These options are added by rvm automatically when generating the complete command line to pass to rsync.

    Use of this command may result in a long line, depending on the number of options that the archive administrator wishes to pass to rsync. For greater readability and flexibility there is a second way of specifying options to pass to rsync. See the <rsync-options> block command below.

    This command is not required. This command has no default value. Multiple uses of this command append to any previously defined values, including any value previously set by an <rsync-options> block command.
<rsync-options> ... </rsync-options>

    Options to pass to the rsync program may be specified by placing those options inside an rsync-options block. An rsync-options block begins with the text "<rsync-options>" on a line by itself, and ends with the text "</rsync-options>" on another line by itself. Lines in between are considered to be literal text to pass to the rsync program, with the following exceptions: Blank lines and lines begining with a '#' are ignored.

    This form of passing options to rsync allows the archive administrator to break what could be one long line into multiple lines for greater readability. (It also allows easy addition or removal of options by simply commenting or uncommenting a line.)

    This command is not required. This command has no default value. Multiple uses of this command overwrite any previous value within the same context, including any value previously set by the rsync-options command.
rsync-remote-path path

    Specify the location of the rsync program on a remote host for a particular job. This value is only necessary for remote connections via RSH or SSH. It is not needed for local sources or connections to an rsync server. The value for path should be an absolute pathname.

    This command is not required. Rvm will use the same value specified for rsync-local-path if no other setting is found. Multiple uses of this command overwrite any previous value within the same context.
rsync-remote-user username

    Define the user name to use when connecting to a remote host using either RSH, SSH, or an rsync server.

    This command is not required. This command has no default value. Multiple uses of this command overwrite any previous value within the same context.
rsync-remote-port integer

    Define the port number to connect to when using rsync to connect to a remote host via RSH, SSH, or an rsync server.

    This command is not required. This command has no default value. Multiple uses of this command overwrite any previous value within the same context.
rsync-retry-count integer

    The number of times rvm is to retry a failed rsync command. This setting is used in conjunction with the rsync-behavior setting to determine how to handle a failed rsync command based on it's exit code.

    Rvm will use the default value of 3 if no other setting is found. Multiple uses of this command will overwrite any previous value within the same context.
rsync-timeout seconds

    Instruct the rvm child processing the current job to wait seconds seconds before assuming that rsync has hung. If there is no I/O from rsync after seconds seconds, rvm will kill rsync and try again (up to rsync-retry-count times).

JOB CONTEXT CONFIGURATION COMMANDS

Configuration commands in a job context specify how to archive files and directories from a single source, where a source is either a set of files and directories mounted locally, a set of files and directories on a remote host, or a set of files and directories hosted on an rsync server. Each job will assume a set of default values, either from rvm or from the last default block.

All of the commands listed above for a default context also apply to a job context, with the addition of the following commands: jobname string

    Assign a name to this job.

    Use of this command is required only if the "jobname" keyword is used in the archive-path command.

    Multiple uses of this command will overwrite any previous value.

EXAMPLE CONFIGURATION FILE

An example configuration file might look like the following:
    #
    # RVM Manager Configuration
    #
    # - Commands outside of a <default> block or
    #   a <job> block are assumed to be of a global
    #   context.
    #
    #
    # After all archive jobs have been completed,
    # create relative symbolic links here.
    #
    # We will arrange to export this directory and
    # all vault directories via NFS so that users
    # can cd into the catalog and select an archive
    # by it's timestamp, then peruse their files
    # for what they're looking for.
    #
    link-catalog-dir /export/archive/catalog
    #
    # Create log files under this directory.
    #
    log-dir /var/log/rvm
    #
    # The location of the rsync program on this
    # machine.  This path must not contain
    # wildcard characters, and should be an
    # absolute path.
    #
    rsync-local-path /usr/local/bin/rsync
    #
    # How many archive jobs to process in parallel.
    #
    rsync-parallel 5
    #
    # How often to poll children for a change in I/O state.
    #
    io-poll-interval 5
    #
    # The resolution of timestamp we want.
    #
    timestamp-resolution day
    #
    # Where are the vaults?  Notice that wildcard
    # characters are allowed here:
    #
    vault /export/archive/raid/*/daily-archives
    #
    # How to select the next vault to use:
    #
    vault-selection-behavior round-robin
    #
    # What do we do when the vault gets too close
    # to full capacity?
    #
    vault-overflow-behavior delete-until-free
    #
    # What percentage of blocks and inodes must be
    # free before we declare the vault too full to
    # continue archiving?
    #
    vault-overflow-blocks 10
    vault-overflow-inodes 10
    #
    # Set up some default values to be assumed by
    # all jobs read below:
    #
    <default>
    	archive-path hostname/pathname
    	exclude-from /etc/rvm/excludes/*
    	#
    	# Some default paths to back up on all hosts.
    	#
    	# Notice that wildcard characters are not
    	# allowed here.
    	#
    	# Files will be stored under:
    	# /<vault>/<archive>/<hostname>/var/spool/...
    	# /<vault>/<archive>/<hostname>/export/...
    	#
    	path /var/spool
    	path /export
    	#
    	# Define how rvm is to handle non-zero exit
    	# codes from rsync.  The values below happen to
    	# be the same values that are assumed by rvm by
    	# default, but they're listed here for the sake
    	# of example:
    	#
    	rsync-behavior * = retry
    	rsync-behavior 1 = fail
    	rsync-behavior 2 = fail
    	rsync-behavior 4 = fail
    	rsync-behavior 23 = retry-without-hardlinks
    	rsync-behavior 124 = fail
    	rsync-behavior 125 = fail
    	rsync-behavior 126 = fail
    	rsync-behavior 127 = fail
    	rsync-connection-type remote
    	#
    	# What options should be pass to rsync?
    	#
    	<rsync-options>
    		-a
    		-e "/usr/bin/ssh -l root"
    		-v
    		--checksum
    		--delete
    		--delete-excluded
    		--force
    		--ignore-errors
    		--one-file-system
    		--stats
    		--progress
    	</rsync-options>
    	rsync-retry-count 5
    </default>
    #
    # Archive Job 1: Back up alces
    #
    <job>
    	hostname alces
    	#
    	# In addition to /var/spool and /export, also
    	# back up the following:
    	#
    	# Files will be stored under:
    	# /<vault>/<archive>/<hostname>/export/home/a/...
    	# /<vault>/<archive>/<hostname>/export/home/b/...
    	# /<vault>/<archive>/<hostname>/export/home/c/...
    	# /<vault>/<archive>/<hostname>/export/home/d/...
    	# /<vault>/<archive>/<hostname>/export/home/e/...
    	#
    	path /export/home/a
    	path /export/home/b
    	path /export/home/c
    	path /export/home/d
    	path /export/home/e
    </job>
    #
    # Archive Job 2: Back up fragaria
    #
    <job>
    	hostname fragaria
    	path /export/home/a
    	path /export/home/b
    </job>
    #
    # Set some new defaults for samba-mounted
    # directories under /k-boxes.
    #
    <default>
    	#
    	# The following must be re-defined because
    	# each default block completely clears all
    	# values defined in the last default block:
    	#
    	exclude-from /etc/rvm/excludes/*
    	#
    	# (Good thing these are actually the default
    	# settings for rsync-behavior.  It would be a
    	# pain to have to enter it over and over
    	# again...  But then, you could always place
    	# these commands in a separate file and
    	# "include" them.)
    	#
    	rsync-behavior * = retry
    	rsync-behavior 1 = fail
    	rsync-behavior 2 = fail
    	rsync-behavior 4 = fail
    	rsync-behavior 23 = retry-without-hardlinks
    	rsync-behavior 124 = fail
    	rsync-behavior 125 = fail
    	rsync-behavior 126 = fail
    	rsync-behavior 127 = fail
    	rsync-retry-count 5
    	#
    	# These settings do change, however:
    	#
    	archive-path group/name/"files"
    	groupname k-boxes
    	rsync-connection-type local
    	<rsync-options>
    		-a
    		-v
    		--checksum
    		--delete
    		--delete-excluded
    		--force
    		--ignore-errors
    		--one-file-system
    		--stats
    		--progress
    	</rsync-options>
    </default>
    #
    # Back up files from David's machine
    #
    <job>
    	# Files will be stored under:
    	# /<vault>/<archive>/<group>/<name>/files/...
    	# ...or, to be more specific:
    	# /<vault>/<archive>/k-boxes/david/files/...
    	jobname david
    	path /k-boxes/david/files
    </job>
    #
    # Back up files from Joe's machine
    #
    <job>
    	# Files will be stored under:
    	# /<vault>/<archive>/<group>/<name>/files/...
    	# ...or, to be more specific:
    	# /<vault>/<archive>/k-boxes/joe/files/...
    	jobname joe
    	path /k-boxes/joe/files
    </job>
    #
    # The End
    #

CONFIGURATION FILE SYNTAX

  Syntax Notation:

Everyone seems to have their own form of EBNF notation to express a language syntax, therefore I define my own here:

    -   A syntactic part is written as an identifier surrounded by '<' and '>'.

    -   A syntactic assignment is written as a syntactic part, followed by the symbol "::=", followed by one or more syntactic parts that may be joined in various ways. For a simple example:
            <foo> ::= <bar>

    -   Literal text is specified by wrapping the text in double quotes. If the literal text contains special characters such as tab, newline, or the double quote character, they will appear using a C-style escape format using the '\' character. Literal characters are wrapped in single quotes and use the same C-style escape format for special characters and the single quote character itself. For example:
            <a> ::= 'a'
            <text> ::= "Hello World"
            <response> ::= "Tell him I said, \"Go away.\""
            <newline> ::= '\n'

    -   A range of literal characters may be specified separating two literal characters with a '-' character, with no whitespace in between. For example:
            <digit> ::= '0'-'9'

    -   Syntactic parts may be concatenated together in an unordered form by separating two or more syntactic parts with whitespace. For example:
        The following:
            <foobar> ::= <foo> <bar>
        will match either <foo><bar> or <bar><foo>.

    -   Syntactic parts may be concatenated together in a specific order by separating two or more syntactic parts with a '+' character. Whitespace is allowed between syntactic parts, but not the newline or carriage return characters. For example:
            <foobar> ::= <foo> + <bar>

    -   A choice between two or more syntactic parts may be defined by separating the choices with the '|' character. For example:
            <right-or-wrong> ::= <right> | <wrong>

    -   Syntactic parts may contain subparts that are treated as a single entity by surrounding syntactic parts with '(' and ')'. For example:
        The following:
            <foobarelem> ::= <elem> (<foo> <bar>) <elem>
        is equivalent to:
            <foobar> ::= <foo> <bar>
            <foobarelem> ::= <elem> <foobar> <elem>

    -   Optional syntactic parts are written by enclosing the syntactic part in '[' and ']'. For example:
            <all-options> ::= [<option1>] [<option2>] [<option3>]
            <a-foo-or-bar-b> ::= "a" [ "foo" | "bar" ] "b"

    -   Syntactic parts may be concatenated together with no whitespace allowed between parts by separating the syntactic parts with the "<+" symbol. For example:
        A string with no whitespaces allowed:
            <alpha> ::= 'a'-'z'
            <no-ws-string> ::= <alpha> | <alpha> <+ <no-ws-string>

    -   Syntactic parts may be replicated using the format min*max<syntactic-part>, where min and max are optional. For example:

        a)  A number consisting of 1 to three digits may be written as:
            <number> ::= 1*3<digit>

        b)  A number consisting of at least one digit:
            <number> ::= 1*<digit>

        c)  A double-quotes string consisting of zero to three characters:
            <alpha> ::= 'a'-'z' | 'A' - 'Z'
            <string> ::= '"' <+ *3<alpha> <+ '"'

    -   A specific number of replicates of a syntactic part may be specified using a variant of min*max<syntactic-part> written as num*<syntactic-part>. For example:
        The following:
            <3-digit-number> ::= 3*3<digit>
        is the same as:
            <3-digit-number> ::= 3<digit>

  RVM Configuration Syntax

    <RVMConfigurationFile> ::=
          <Global>
        + 1*(*<DefaultBlock> *<JobBlock>)

    <ArchivePathKeyword> ::=
          "jobname"
        | "groupname"
        | "hostname"
        | "path"
        | "permutation"
        | ( "\"" <+ <FilenameString> <+ "\"" )

    <ArchivePathSpecs> ::=
           <ArchivePathKeyword>
        <+ [ "/" <+ <ArchivePathKeyword> ]

    <ArchivePath> ::=
          "archive-path"
        + ( "empty" | <ArchivePathSpecs> ) + '\n'

    <BoolString> ::=
          "y" | "n"
        | "yes" | "no"
        | "t" | "f"
        | "true" | "false"
        | "1" | "0"
        | "on" | "off"

    <Clear> ::=
          "archive-path\n"
        | "exclude-from\n"
        | "groupname\n"
        | "hostname\n"
        | "include-from\n"
        | "jobname\n"
        | "paths\n"
        | "rsync-behavior\n"
        | "rsync-options\n"
        | "rsync-remote-user\n"
        | "rsync-remote-path\n"

    <DefaultBlock> ::=
        <GenericBlock> *[<Path>]

    <Default> ::=
          "<default>\n"
        + <DefaultBlock>
        + "</default>\n"

    <ExcludeFile> ::=
        "exclude-from" + <WildcardPathString> + '\n'

    <FilenameString> ::=
        <Any valid file or directory name>

    <GenericBlock> ::=
          [<Group>]
          [<Host>]
         *[<IncludeFile>]
          [<ArchivePath>]
          [<Clear>]
         *[<ExcludeFile>]
        1*<Path>
         *[<RsyncBehavior>]
          [<RsyncConnectionType>]
          [<RsyncHardlink>]
          [<RsyncOptions>]
          [<RsyncRemotePath>]
          [<RsyncRemoteUser>]
          [<RsyncRemotePort>]
          [<RsyncRetryCount>]
          [<RsyncTimeout>]

    <Global> ::=
        0*1<LinkDir>
        0*1<LogDir>
        0*1<LoggingLevel>
          *<Include>
          1<RsyncLocalPath>
           [<RsyncParallel>]
           [<IOPollInterval>]
           [<TimestampResolution>]
         1*<Vault>
           [<VaultOverflowBehavior>]
           [<VaultOverflowBlocks>]
           [<VaultOverflowInodes>]
           [<VaultSelectionBehavior>]

    <Group> ::=
        "groupname" + <String> + '\n'

    <Host> ::=
        "hostname" + <String> + '\n'

    <IncludeFile> ::=
        "include-from" + <WildcardPathString> + '\n'

    <IncludeJob> ::=
        "include-job" + <WildcardPathString> + '\n'

    <Integer> ::=
        <Any non-negative integer value>

    <Integer-50> ::=
        <Any integer value from 0 to 50 inclusive>

    <Integer-255> ::=
        <Any integer value from 0 to 255 inclusive>

    <Job> ::=
        "<job>\n" + <JobBlock> + "</job>\n"

    <JobBlock> ::=
        [<Name>] + <GenericBlock> + 1*<Path>

    <Name> ::=
        "name" + <String> + '\n'

    <LinkCatalogDir> ::=
        "link-catalog-dir" + <PathString> + '\n'

    <LogDir> ::=
        "log-dir" + <PathString> + '\n'

    <LoggingLevel> ::=
        "logging-level" + <LogingLevelOption> + '\n'

    <LoggingLevelOption> ::=
          "manager"
        | "child"
        | "rsync"

    <Path> ::=
        "path" + <PathString> + '\n'

    <PathString> ::=
        <FilenameString> + [ "/" + <PathString> ]

    <RsyncBehavior> ::=
          "rsync-behavior"
        + ( "*" | <Integer-255> )
        + "="
        + ( "ok" | "retry" | "fail" | "retry-without-hardlinks" )
        + '\n'

    <RsyncConnectionType> ::=
          "rsync-connection-type"
        + ( "local" | "remote" | "server" )
        + '\n'

    <RsyncHardlink> ::=
        "rsync-hardlink" + <BoolString> + '\n'

    <RsyncLocalPath> ::=
        "rsync-local-path" + <PathString> + '\n'

    <RsyncOptions> ::=
          ( "rsync-options" + <String> + '\n' )
        | ( "<rsync-options>\n"
          + <RsyncOptionBlock>
          + "</rsync-options>\n"
          )

    <RsyncParallel> ::=
        "rsync-parallel" + <Integer> + '\n'

    <IOPollInterval> ::=
        "io-poll-interval" + <Integer> + '\n'

    <RsyncRemotePath> ::=
        "rsync-remote-path" + <PathString> + '\n'

    <RsyncRemoteUser> ::=
        "rsync-remote-user" + <String> + '\n'

    <RsyncRemotePort> ::=
        "rsync-remote-port" + <Integer> + '\n'

    <RsyncRetryCount> ::=
        "rsync-retry-count" + <Integer> + '\n'

    <RsyncTimeout> ::=
        "rsync-timeout" + <Integer> + '\n'

    <String> ::=
          "\""
        + <Any number of characters, using C-style escapes>
        + "\""

    <TimestampResolution> ::=
          "timestamp-resolution"
        + ( "year"
          | "month"
          | "day"
          | "hour"
          | "minute"
          | "second"
          )
        + '\n'

    <Vault> ::=
        "vault" + <WildcardPathString> + '\n'

    <VaultOverflowBehavior> ::=
          "vault-overflow-behavior" + ( "quit"
          | "delete-oldest"
          | "delete-until-free"
          )
        + '\n'

    <VaultOverflowBlocks> ::=
        "vault-overflow-blocks" + <Integer-50> + '\n'

    <VaultOverflowInodes> ::=
        "vault-overflow-inodes" + <Integer-50> + '\n'

    <VaultSelectionBehavior> ::=
          "vault-selection-behavior"
        + ( "max-free" | "round-robin" )
        + '\n'

    <WildcardFilenameString> ::=
        <Any valid file or directory name, including wildcard characters>

    <WildcardPathString> ::=
           <WildcardFilenameString>
        <+ [ "/" <+ <WildcardPathString> ]

FILES

/usr/local/etc/rvm.conf
    The default configuration file. Rvm will search for this configuration file first unless the --no-default-config command line option is used.

/var/log/rvm
    The default log directory. Rvm will create log files under this directory. This may be modified with the log-dir configuration command.

Vaults
    One or more directories must be specified in the configuration file(s) as a vault under which to create archives. See the vault configuration command for more information.

link-catalog-dir
    An optional directory under which rvm will create relative links to all archives on all vaults. See the link-catalog-dir configuration command for more information.

SEE ALSO
rsync(1), SSH(1)

BUGS

This version of rvm is still in alpha development. Interfaces and infrastructure may change on a whim. Many bugs have been squashed, more probably lurk in dark corners...

Bug reports and feature requests may be sent to the author. (Although due to the author's lack of time, submittals may be silently ignored for an undisclosed amount of time unless they are accompanied by a patch file.)

NOTES

In version 0.79.1-alpha, the author used a crude method of analysis to determine the number and size of new files versus files that had been hardlinked from older archives. This method of analysis required some assumptions that could not be assured. The author is considering a new analyzer, but for the time being the analyzer has been removed. As of this version, rvm relies on output from the rsync binary when run with the --stats command line option to produce statistical results. Unfortunately this has resulted in some confusing output:

    -   When all the files to be archived are new, rsync reports that 98% of the files were transfered, instead of 100%.

    -   When none of the files to be archived are new, and all files are hardlinks to an older archive, rsync reports nothing, leaving rvm to assume that there were 0 files and 0% of them were transfered.

DISCLAIMER
Rvm is given to the public as-is with no guarantee of it's functionality, either expressed or implied, and the author takes no responsibility for damages that may result from it's use or misuse.

AUTHOR

Rvm was written by Michael Peek. See DISTRIBUTION below for contact information.

Occasionally the author fancies that he knows what he is doing. It is at these times more than at any other that his coworkers should cower in fear.

DISTRIBUTION

The latest version of rvm may always be found at:
    http://rvm.sourceforge.net
    http://freshmeat.net/projects/rvm