dumpnet.userdefined.conf - the host-specific dumpnet.host.userdefined configuration file
A dumpnet.userdefined.conf file is used to configure the module dumpnet.host.userdefined for a specific target host. It should be placed in a host configuration directory (a subdirectory of $DUMPNET_HOME/conf/) - see the CONFIGURATION section in dumpnet(8) for details. The general format of this configuration file is specified in the section CONFIGURATION FILE FORMAT in dumpnet(8).
Each userdefined command is specified on a separate line; fields on each line are separated by spaces or tabs. Lines starting with `#' are comments - for the exeption of the statements ``option'' and ``extends'', see below. The order of records in dumpnet.userdefined.conf is important because dumpnet.host.userdefined will perform the execution in the order specified. The configuration file knows the following fields (in this order):
- Dirname
-
The name of the sub-directory where the output is to be stored: $backupDir/$host/$dirname.
- Compression
-
Compression of the command's output: ``remote'', ``local'' or ``none''.
- remote
-
Does the compression on the target host before transferring the data. This requires more CPU-resources on the target host but is fastest on slow connections. It is recommended for use over the Internet.
- local
-
Does the compression on the backup machine after transferring the data. This is easyier to handle for the target host but requires a fast connection and a lot of CPU-power on the backup machine.
- none
-
Does no compression at all. Choose this option if the data is already compressed or if you always need it to be available in uncrompressed form for some reason.
- Postfix
-
A postfix (a file extension in most cases) to append to the name of the file in which the output is stored.
- Level
-
The level or level mode to use for this command. Please see the LEVELS and LEVEL MODES sections of dumpnet(8) for details.
- Cleanup Policy
-
The cleanup policy to apply for the output files of this command. Please see the CLEANUP section in dumpnet(8) for details.
- Command:run_after:run_before
-
The last filed itself knows three sub-fields sparated by colons: Command, run_after and run_before (in that order). run_after and run_before are optional. If you need to use a colon within one of the sub-fields, escape it with anonther colon.
- Command
-
The userdefined command to execute. If the command is prefixed by an `@' sign the command will be run locally. Commands without the prefix will be run on the target host. If the option runLocally (see below) is set to ``true'' all commands are run locally. A local command can be used to integrate third party software installed on the dumpnet host. If the command is run on the target host and the remote shell is not bash no single quotes can be used within Command. This is because Command will get executed as bash -c '$command'.
-
If Command actually consists of multiple commands separated by pipes you are highly encouraged to take advantage of the COMMAND_RETURN_CODE feature. If you pipe the output of one command into another command the exit status of the whole expression will be the one of the last command. So you wouldn't notice if anything went wrong with the first command. To solve this problem dumpnet.host.userdefined.cmd will look on STDERR for lines starting with the string ``COMMAND_RETURN_CODE '' followed by a nueric value. If that value is not 0 we know that one of the commands used in the expression failed.
-
Example:
-
( some_cmd; echo COMMAND_RETURN_CODE $? >&2 ) | some_other_cmd
-
The braces contain the first command and an echo statement that sends the string ``COMMAND_RETURN_CODE '' followed by the first command's exit status to STDERR.
-
Here is a little more complicated example:
-
( mysqldump -aA; echo COMMAND_RETURN_CODE $? >&2 ) \
| ( gzip -c; echo COMMAND_RETURN_CODE $? >&2 ) \
| gpg -er dumpnet@backup.example.com
-
Sidenote: in order to make mysqldump not ask for a password when logging into the MySQL server use a ~/.my.cnf file. Do not provide the password on the command line!
-
The following variables can be used in the command:
- $level
-
This variable will be replace with the level resulting from the level mode chosen. dumpnet.host.userdefined.cmd will save the information when which command was executed with what level in dumpnet.cmddates. Please see the LEVELS and LEVEL MODES sections of dumpnet(8) for details. In order to run a command with a level higher than 0 all levels lower than the current one must have been run before. If the prior level does not exist, dumpnet.host.userdefined.cmd will downgrade the level until there is a lower level or until 0. This means that if you try to run the command ``/sbin/dump -$level -f - /usr'' with a level of 2 without having it run with level 0 or 1, dumpnet.host.userdefined.cmd will downgrade the level to 0.
- $lastLevSeconds
-
The number of seconds that passed since the last lower level was done. If there is no lower level the number of seconds since the epoche will be used. For example if the configured level mode results in a level of 2, $lastLevSeconds will be replaced with the number of seconds that passed since the last level 1 backup. The time on the target host is used for date and time calculations.
- $lastLevMinutes
-
The number of minutes that passed since the last lower level was done. If there is no lower level the number of minutes since the epoche will be used. For example if the configured level mode results in a level of 2, $lastLevMinutes will be replaced with the number of minutes that passed since the last level 1 backup. The number of minutes will be rounded up. The time on the target host is used for date and time calculations.
- $lastLevHours
-
The number of hours that passed since the last lower level was done. If there is no lower level the number of hours since the epoche will be used. For example if the configured level mode results in a level of 2, $lastLevHours will be replaced with the number of hours that passed since the last level 1 backup. The number of hours will be rounded up. The time on the target host is used for date and time calculations.
- $lastLevDays
-
The number of days that passed since the last lower level was done. If there is no lower level the number of days since the epoche will be used. For example if the configured level mode results in a level of 2, $lastLevDays will be replaced with the number of days that passed since the last level 1 backup. The number of days will be rounded up. So if you do a level 1 backup at 12:30 and a level 2 backup just 20 minutes later, $lastLevDays will be set to 1. The time on the target host is used for date and time calculations.
- $lastLevDate
-
The date on which the last lower level was done. The format is YYYY-MM-DD. The time on the target host is taken for this.
- $lastLevDateRFC822
-
The date and time on which the last lower level was done followed by an rfc822 timezone specification: either a plus or minus sign followed by two digits for the number of hours and two digits for the minutes. For example, -0800 for eight hours west of Greenwich or +0230 for two hours and a half east of Greenwich. The format is therefore YYYY-MM-DD HH:MM:SS +/-ZZZZ. The time on the target host is taken for this.
- $lastLevDateDumpFormat
-
The date and time on which the last lower level was done in a format that is understood by the -T option of dump(8). The dump man page says the format is the same as that of ctime(3) followed by an rfc822 timezone specification. This results in a date formatted like that: date +``%a %b %e %T %Y %z'' - for example ``Mon Jan 31 12:38:08 2005 +0100''. The time on the target host is taken for this.
- $lastLevDateBSDDumpFormat
-
The date and time on which the last lower level was done in a format that is understood by the -T option of dump(8) version used on OpenBSD. The dump man page says the format is the same as that of ctime(3). This results in a date formatted like that: date +``%a %b %e %T %Y'' - for example ``Mon Jan 31 12:38:08 2005''. The time on the target host is taken for this. The differnece to $lastLevDateDumpFormat is the missing timezone specification.
- $lastLevLocalDate
-
Like $lastLevDate but the local date from the dumpnet host is used.
- $lastLevLocalDateRFC822
-
Like $lastLevDateRFC822 but the local date from the dumpnet host is used.
- $lastLevLocalDateDumpFormat
-
Like $lastLevDateDumpFormat but the local date from the dumpnet host is used.
- $lastLevLocalDateBSDDumpFormat
-
Like $lastLevDateBSDDumpFormat but the local date from the dumpnet host is used.
Keep in mind that if you need the date and time in any different format you can always use date(1) to reformat $lastLevDateRFC822. For example:
date -d "$lastLevDateRFC822" +"%a %b %e %T %Y"
- run_after
-
The command to run after Command was successfully executed. The command runs in the context of the script itself. Before it gets executed, dumpnet.host.userdefined.cmd changes into the directory where the destination file is stored. By default only a log entry with the priority WARN will be created if run_after fails. To make dumpnet.host.userdefined.cmd create a log entry with the priority ERRO and exit immedeatly, prefix the command with an exclamation mark (`!'). You can use the variables listed above and all variables used in the script itself. The most useful will be:
- $dest
-
The absulute path to the destination file where the output of the userdefined command will be stored.
- $destinationFile
-
The name of the destination file where the output of the userdefined command will be stored.
- $destinationDir
-
The absolute path to the directory where the destination file is stored.
- $sessionId
-
The ID of the current backup session.
- $host
-
The host name or IP-address of the target host.
- $oslogin
-
The login used to connect via SSH.
One of the best ways to use run_after is to generate a TOC file. To do that for a gzip-crompressed dump archive you would use a run_after command of:
gunzip -c $dest | $local_restore -tf - > $dest.toc
The variable $local_restore is defined in dumpnet.conf.
- run_before
-
The command to run before Command gets executed. The command runs in the context of the script itself. Before it gets executed, dumpnet.host.userdefined.cmd changes into the directory where the destination file is stored. By default only a log entry with the priority WARN will be created if run_before fails. To make dumpnet.host.userdefined.cmd create a log entry with the priority ERRO and exit immedeatly, prefix the command with an exclamation mark (`!'). You can use the variables listed above and all variables used in the script itself.
You can use the ``option'' and ``extends'' statements in this file - as documented in the CONFIGURATION FILE FORMAT section in dumpnet(8). This allows you to overwrite options set in the host configuration file - see dumpnet.HOST.conf(8). Options you might want to set are:
- runLocally
-
Run all commands - and not just the one's prefixed by an `@' sign - locally on the dumpnet host and not on the target host. This may help you to integrate third party software.
- dosudo
-
If set to ``true'' all commands will be run using sudo on the target host. The default is ``false''. The location of the sudo command can be configured using the option sudo in dumpnet.HOST.conf(8). Keep in mind that the login name used to log into the target host can only be defined in dumpnet.HOST.conf. If you set dosudo globally to true and use complex commands with sub-shells in your dumpnet.userdefined.conf you might have to set dosudo to false this configuration file and integrate the sudo into your command manually.
- read_options
-
Options to be passed to the bash builtin read to read in the configuration file. In some cases you will want to use the -r option which causes the backslash not to act as an escape character. The backslash is considered to be part of the line. In particular, a backslash-newline pair may not be used as a line continuation. If read_options is not set (or set to an empty string) a backslash-newline pair can be used as a line continuation but all literal backslashes will have to be escaped.
-
Example:
-
# option read_options="-r"
dumpnet.host(8)
dumpnet.host.userdefined(8)
dumpnet.host.userdefined.cmd(8)
Lukas Feiler <lukas.feiler@lukasfeiler.com>
dumpnet is published under the LGPL (GNU LESSER GENERAL PUBLIC LICENSE). Please see the LICENSE file contained in the installation tarball for details. The official web site is http://dumpnet.sourceforge.net.