RVM(1)RVM(1)NAMErvm - rsync vault manager
SYNOPSISrvm [ 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 com‐
mand 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
archive 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 com‐
mand 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 configu‐
ration 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 time‐
stamp will override any timestamp-resolution setting that may appear
in the configuration files. Caution should be used by the archive
manager when specifying custom timestamps on the command line, as
specifying a timestamp of lesser resolution than the timestamp reso‐
lution normally used from the configuration file(s), could result in
the archive generated from the custom timestamp being the first ar‐
chive deleted by rvm later when the vault exceeds it's overflow
threshold.
--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 con‐
fig-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 rela‐
tive to the location from which rvm is executed. If config-file con‐
tains 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.
This command line option may be used multiple times to have rvm read
several configuration files.
--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 con‐
figuration 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 beginning 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 alpha‐
betical 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.
When using multiple vaults it is recommended that 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 ar‐
chive 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 configu‐
ration 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 con‐
figuration 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. For the
duration of the archival process the archive subdirectory name will be
appended with the extension ".incomplete".
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 speci‐
fied otherwise with the rsync-parallel configuration command. If the
rsync-hardlink command appears in the job configuration for this job,
or in a previous default job configuration, then the child rvm process
will select an older archive on the same vault to use as a hardlink
source for rsync. This can save space within the vault by hardlinking
files that have not changed from one invocation of rvm to the next.
Each child will interpret rsync's output and exit codes, and if unsuc‐
cessful, 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 will rename the archive directory,
removing the ".incomplete" extension. Then, 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 out‐
put 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 occurred.
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 com‐
mand 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, result‐
ing 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 certain 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 sec‐
tions, 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 configura‐
tion context then the new context remains in effect when rvm fin‐
ishes 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 plac‐
ing 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 overridden
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 fol‐
lowing:
<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 val‐
ues 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 ar‐
chives from all vaults in the directory path using relative sym‐
bolic 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 rela‐
tive 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.
delete-old-log-files bool
Enable or disable deletion of old log files. If rvm deletes an ar‐
chive to make more space in a vault, then, if delete-old-log-files
is enabled, rvm will also search for and delete the archive's log
file from the log directory.
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 set‐
ting is found. Multiple uses of this command will overwrite any
previous value within the same context.
delete-old-report-files bool
Enable or disable deletion of old report files. If rvm deletes an
archive to make more space in a vault, then, if delete-old-report-
files is enabled, rvm will also search for and delete the archive's
report file from the log directory.
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 set‐
ting is found. Multiple uses of this command will overwrite any
previous value within the same context.
logging-level option
Specify the degree of verbosity used when writing 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 pro‐
cesses.
rsync
Log all messages from rvm and from rsync.
Rvm will use the default value of "child" if no other setting is
provided. Multiple use of this command will overwrite any previous
value.
error-logging-level option
Specify the degree of verbosity used when writing to the log file
when retrying a failed rsync command. Valid values are the same as
for the logging-level command above.
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 cre‐
ate 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.
delete-command-path path
Specify the location of the program or script of your choice for
recursively deleting a directory. The value for path should be an
absolute pathname.
The program or script should not return until deletion completes.
The program or script is expected to return an exit code of zero on
success, and non-zero on failure. If a value for path is not spec‐
ified, then the internal recursive delete function is used.
Multiple uses of this command will 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 for‐
mat.
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 the
basename used for log files and report files. A new timestamp is
generated each time rvm is executed. The timestamp resolution set‐
ting 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 fail‐
ure.
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 char‐
acters, 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. Only one
archive deletion is allowed per execution, after that rvm will
exit with an error if there is insufficient space.
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. Caution should be used by the archive administrator when
using this setting.
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-old‐
est" 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.
NOTICE: Some filesystems do not use inodes, such as FAT formatted
filesystems used by Windows. If such a filesystem is used to house
a vault then the operating system may report that there are 0 free
inodes available. For such filesystems it is required that vault-
overflow-inodes be set to 0 to avoid erroneous filesystem overflow
errors.
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.
vault-locking bool
Turn on or off vault locking to prevent subsequent instances of rvm
from using the same vault while this instance of rvm is still run‐
ning.
If disabled, rvm will not attempt to lock a vault, and rvm will
ignore any locks created by other instances of rvm. (Note: This
could be dangerous.)
If enabled, then rvm will lock the vault that it's using. Subse‐
quent instances of rvm run with vault-locking enabled will check to
see if a vault is locked when selecting a vault. The behavior of
rvm under vault-locking is as follows:
- If a locked vault contains an archive with the same timestamp as
the one being used by rvm, then rvm will exit with an error.
- Otherwise, if a vault is locked, then that vault is ignored dur‐
ing the vault selection process, and the next best vault will be
chosen instead.
- Otherwise, if all vaults are locked, then rvm will exit with an
error.
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 set‐
ting is found. Multiple uses of this command will overwrite any
previous value within the same context.
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 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 sub‐
directory under which to store files and directories backed up from
this archive job. The complete path to an archive job's files fol‐
lows from the root of the filesystem, down the path of the selected
vault, into the archive subdirectory, and then down this user-spe‐
cific path.
The value for this command consists of one or more options sepa‐
rated 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 permuta‐
tion 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 dou‐
ble quotes. Directory slash characters are not allowed within
the string, and double quotes within the string must be escaped
by preceding 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 set‐
ting 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
<default>
archive-path groupname
</default>
<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 over‐
write root's crontab file from ren, resulting in a corrupted ar‐
chive.
clear keyword
Erase a previous default value for a specific configuration set‐
ting. This override does not change default settings nor affect
subsequent jobs, only the current job is affected. 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.
ssh-options
Clear the list of options to pass to the ssh 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.
rsync-remote-path
Clear the module name used when starting an rsync server on a
remote machine over a shell connection.
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 com‐
mand 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 com‐
mand 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 spec‐
ify 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 not specified by
any other rsync-behavior command. 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 com‐
mand. (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 over‐
coming 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
24 Some files vanished before they could be transferred
25 The --max-delete limit stopped deletions
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 differ‐
ent 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 four 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. Lastly, the fourth method, remote-
rsync-local-dir, uses ssh to log into the remote host and then run
rsync to back up to a locally-mounted directory. This last option
is useful for storage clusters that mount directly to the client.
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.
remote-rsync-local-dir
Use ssh to connect to the remote host, and then run rsync with a
locally-mounted destination directory.
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 set‐
ting is found. Multiple uses of this command will overwrite any
previous value within the same context.
rsync-multi-hardlink bool
Turn on or off the use of multiple hardlink sources (supported by
rsync version 2.6.4 and newer). Turning this option on also
implies turning on rsync-hardlink.
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 "off" if no other set‐
ting is found. Multiple uses of this command will overwrite any
previous value within the same context.
rsync-multi-hardlink-max integer
The maximum number of hardlink sources to pass to rsync. At the
time of this writing rsync will support up to 20 hardlink sources.
Valid values are any integer greater than 0. Rvm will assume a
default value of 20 if no other setting is found. Multiple uses of
this command overwrite any previous value.
rsync-options options
Define the command line options that rvm is to pass to rsync. Com‐
mand 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.
When rvm parses this line to pass it to rsync, each of the options
listed will be parsed into separate strings. If one of your
options requires whitespace (for instance, if you are backing up a
directory named My Music/, then you can escape the whitespace in
the pathname by entering it as My\ Music. Escapes work with spaces
and tabs, characters which are both otherwise considered delimiters
separating options.
This command is not required. This command has no default value.
Multiple uses of this command append to any previously defined val‐
ues, including any value previously set by an <rsync-options> block
command.
ssh-options options
Define the command line options that rvm is to pass to ssh. Inclu‐
sion of the option 'BatchMode=yes' is automatic. This option only
affects remote-rsync-local-dir rsync connection types.
<rsync-options> ... </rsync-options>
Options to pass to the rsync program may be specified by plac‐
ing 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 excep‐
tions: Blank lines and lines beginning with a '#' are ignored.
This form of passing options to rsync allows the archive admin‐
istrator 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.)
When rvm parses these lines to pass them to rsync, each of the
options listed will be parsed into separate strings. If one of
your options requires whitespace (for instance, if you are
backing up a directory named My Music/, then you can escape the
whitespace in the pathname by entering it as My\ Music.
Escapes work with spaces and tabs, characters which are both
otherwise considered delimiters separating options.
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.
<ssh-options> ... </ssh-options>
Options to pass to the ssh program may be specified by placing
those options inside an ssh-options block. An ssh-options
block begins with the text "<ssh-options>" on a line by itself,
and ends with the text "</ssh-options>" on another line by
itself. Lines in between are considered to be literal text to
pass to the ssh program, with the following exceptions: Blank
lines and lines beginning with a '#' are ignored.
THis form of passing options to ssh allows the archive adminsi‐
trator to break what could be one long line into multple lines
for greater readability. (It also allows easy addition or
removal of options by simple commenting or uncommenting a
line.)
When rvm parses these lines to pass them to ssh, each of the
options listed will be parsed into separate strings. If one of
your options requires white space then you can escape the
whitespace by prefixing a leading '\'. Escapes work with spa‐
ces and tabs, characters which are both otherwise considered
delimiters separating options.
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 ssh-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 con‐
nections 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-module module-name
Specify the module name to use when connecting to an rsync
server on a remote host or over an SSH or RSH shell connection.
When using this option, set rsync-connection-type to server and
set the appropriate --rsh=shell-options rsync command line
option in the rsync-options command.
rsync-connection-type server
rsync-options -av --rsh-"/usr/bin/ssh -l ssh-user"
rsync-remote-module ftp
See the rsync and rsyncd.conf man pages for more information on
modules.
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 con‐
nect 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 previ‐
ous value within the same context.
rsync-retry-delay integer
The number of minutes to delay after a failed rsync command
before retrying. Rvm will use the default value of 0 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 sec‐
onds 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. White‐
space is allowed between syntactic parts, but not the newline or car‐
riage return characters. For example:
<foobar> ::= <foo> + <bar>
- A choice between two or more syntactic parts may be defined by sepa‐
rating 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"
| "rsync-remote-module\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<DeleteOldLogFiles>
0*1<DeleteOldReportFiles>
0*1<LoggingLevel>
0*1<ErrorLoggingLevel>
*<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'
<DeleteOldLogFiles> ::=
"delete-old-log-files" + <BoolString> + '\n'
<DeleteOldReportFiles> ::=
"delete-old-report-files" + <BoolString> + '\n'
<LoggingLevel> ::=
"logging-level" + <LoggingLevelOption> + '\n'
<ErrorLoggingLevel> ::=
"error-logging-level" + <LoggingLevelOptions> + '\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'
<RsyncRemoteModule> ::=
"rsync-remote-module" + <String> + '\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 charac‐
ters>
<WildcardPathString> ::=
<WildcardFilenameString>
<+ [ "/" <+ <WildcardPathString> ]
FILES
/usr/local/etc/rvm.conf
The default configuration file. Rvm will search for this con‐
figuration 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 configu‐
ration 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 ALSOrsync(1), rsyncd.conf(5), SSH(1)BUGS
This version of rvm is still in beta testing. The interfaces and in‐
frastructure is considered to be completed, although additions and
alterations may be made, and bugs may yet to be found and resolved.
Bug reports and feature requests may be sent to the author. Due to the
author's lack of time, the reports that will be given the most atten‐
tion are the ones accompanied by a patch file.
The author welcomes all patch submissions.
DISCLAIMER
Rvm is given to the public as-is with no guarantee of it's functional‐
ity, either expressed or implied, and the author takes no responsibil‐
ity for damages that may result from it's use or misuse.
AUTHOR
Rvm was written by Michael Peek. See the RVM home page for author con‐
tact 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
LOG FILE TRICKS
Here are some quick one-liners that you might find useful:
tail -f *.log* | awk '/STATUS REPORT:/,/> $/ {print}'
cat <timestamp>.log | grep 'Spawning child process' | cut -c32-44 |
while read jobid; do cat <timestamp>.log | grep $jobid | gvim -Rn - ;
done
02 December 2003 RVM(1)
