TABLE OF CONTENTS
- Config/rdist_macros
- rdist_macros/BACKUP
- rdist_macros/BACKUPTO
- rdist_macros/DATESTAMP
- rdist_macros/FORCERUN
- rdist_macros/IFPOSTACTION
- rdist_macros/NOOP
- rdist_macros/POSTACTION
- rdist_macros/RDIST_SPECIAL_FILTER
- rdist_macros/REPORTTARGET
- rdist_macros/RUN
- rdist_macros/SAVEINSTALL
- rdist_macros/VERIFYFILE
Config/rdist_macros [ Modules ]
NAME
rdist_macros -- macros that can be used to generate rdist commands
SYNOPSIS
filepp -I <directory> <file>
#include "rdist_macros.fpp" (at top of file to be processed)
PURPOSE
A number of different operations can be defined in rdist distfiles. However they are often composed of multiple simple rdist commands. This module defines a number of macros for use when generating a distfile for Config. It also supports adding a tag that can be used to filter out the housekeeping commands making it easier to see what actions have occurred.
rdist_macros/BACKUP [ Macros ]
[ Top ] [ rdist_macros ] [ Macros ]
NAME
BACKUP - manage backup copies of pushed files
SYNOPSIS
BACKUP(5);
PURPOSE
The following macro used in the command block of an rdist stanza keeps a number of backups of all files pushed by a stanza. This can be used in place of SAVEINSTALL in cases where you need to use the rdist intall command instead. Note that this will work only if -osavebackups is defined on install command to make the original backup copy.
The number of backups to keep is specified as the only argument.
Backup files are saved as:
* target_file_name.SAVED -- the most recent backup * target_file_name.SAVED.~N~ -- prior backups. The smaller the number, the older the backup.
EXAMPLE
label-manual: $C/ntp/clients.conf -> ${NTP_SLAVES}
install -osavetargets /etc/ntp.conf; cmdspecial "/etc/rc.d/init.d/ntpd restart" ; BACKUP(10);
SEE ALSO
rdist_macros/BACKUPTO [ Macros ]
[ Top ] [ rdist_macros ] [ Macros ]
NAME
BACKUPTO - backup copies of pushed files to a new directory
SYNOPSIS
BACKUPTO(/var/rdist/backup/qmail/controls,5);
PURPOSE
The following macro used in the command block of an rdist stanza keeps a number of backups of all files pushed by a stanza. Unlike BACKUP this saves the files to a new directory. Note that this will work only if -osavebackups is defined on install command to make the original backup copy.
The the target directory and number of backups to keep are given to the macro. The target directory will be created mode 700 if needed. The target directory must be an absolute path starting with a /. This can be combined with the SAVEINSTALL macro, but it duplicates the functionality of the BACKUP macro and should be used in place of it.
This macro is particularly useful if you are installing an entire directory with the remove option as the backup copies will be removed on each update. Also for directories such as logrotate that don't silently ignore the backup files, this macro allows you to save the backups elsewhere. Backup files are saved as: * target_file_name.SAVED -- the most recent backup * target_file_name.SAVED.~N~ -- prior backups. The smaller the number, the older the backup.
This will also work with the SAVEINSTALL macro.
EXAMPLE
This moves the backup file to /etc/ntp.backup:
label-manual: $C/ntp -> ${NTP_SLAVES} install -osavetargets,remove /etc/ntp; cmdspecial "/etc/rc.d/init.d/ntpd restart" ; BACKUPTO(/etc/ntp.backup, 10);
This moves the backup file to /etc/cron.d.backup so that the old file isn't executed by cron:
label-manual: $C/cron.d/postgres -> ${POSTGRES_HOSTS} SAVEINSTALL(/etc/cron.d, 3); BACKUPTO(/etc/cron.d.backup, 10);
Note in this case, the count for the SAVEINSTALL is ignored and the count provided to BACKUPTO is the one that is used.
SEE ALSO
rdist_macros/DATESTAMP [ Macros ]
[ Top ] [ rdist_macros ] [ Macros ]
NAME
DATESTAMP - a current datestamp
SYNOPSIS
DATESTAMP
PURPOSE
Provides the date of execution as: YYYY-MM-DD-HH-mm-SS where MM is the 2 digit month and mm is a two digit minute.
USED BY
rdist_macros/FORCERUN [ Macros ]
[ Top ] [ rdist_macros ] [ Macros ]
NAME
FORCERUN - always run special commands
SYNOPSIS
FORCERUN;
PURPOSE
The following macro defines an install rule that always installs a file and runs the associated special/cmdspecial commands. Note that it should be used only with a single file.
EXAMPLE
This example will always run /etc/rc.d/init.d/ntpd restart when executed.
label-manual: $C/ntp/clients.conf -> ${NTP_SLAVES} FORCERUN; cmdspecial "/etc/rc.d/init.d/ntpd restart" ;
NOTES
This may leave files of the form /tmp/rdist-2006-05-24-12-03-23-766 around. They can be deleted. Also this should not be used to push a file that has sensitive data in it as the contents of the file may be readable on the remote system.
SEE ALSO
USES
USED BY
rdist_macros/IFPOSTACTION [ Macros ]
[ Top ] [ rdist_macros ] [ Macros ]
NAME
IFPOSTACTION - check to see if there are postinstall commands to run
SYNOPSIS
cmdspecial "IFPOSTACTION(ACTION,[OPTION]); shell command";
PURPOSE
This macro will prevent "shell command" from executing unless a file was pushed that uses the POSTINSTALL macro with the same ACTION and OPTION arguments.
ACTION and OPTION are single words consisting of letters, digits and the underscore '_'.
When called with the optional OPTION argument, IFPOSTACTION can be called in multiple cmdspecial commands and across multiple rdist stanzas. All it does is query if the particular ACTION/OPTION pair has been asserted by a prior POSTACTION macro.
If the OPTION argument is not present, it must be the last or only cmdspecial call as it removes/resets the action and future IFPOSTACTION for the same action will believe that there is no action to be done. If you want to test for the existence of a pending ACTION for any OPTION, use the option consisting of a colon ':'.
Don't use " or ' marks around or in the OPTION argument.
EXAMPLE
This example will run /etc/init.d/sshd stop if a prior installed file included POSTINSTALL(sshd, stop), it will also run rekey if POSTINSTALL(sshd, rekey) was used, and will run start if any file was installed that called POSTINSTALL(sshd), or POSTINSTALL(sshd, ...):
POSTINSTALL-ACTIONS: $C/Distfile -> ${SSHD_SLAVES} FORCERUN; cmdspecial "IFPOSTACTION(sshd, stop); /etc/init.d/ssh stop" ; cmdspecial "IFPOSTACTION(sshd, rekey); /etc/init.d/ssh rekey" ; cmdspecial "IFPOSTACTION(sshd); /etc/init.d/sshd start" ;
In the example below, "/etc/init.d/ssh start" will never be called because it occurs after a call to IFPOSTACTION(sshd) which deletes the file that IFPOSTACTION(sshd, start) needs to determine if it should run.
EXAMPLE
POSTINSTALL-ACTIONS: $C/Distfile -> ${SSHD_SLAVES}
FORCERUN; cmdspecial "IFPOSTACTION(sshd, stop); echo stopping; /etc/init.d/ssh stop" ; cmdspecial "IFPOSTACTION(sshd);" ; cmdspecial "IFPOSTACTION(sshd, start); /etc/init.d/ssh start" ;
NOTES
Rdist adds the POSTINSTALL-ACTIONS by default to the list of targets to be executed.
Using the IFPOSTACTION macro suppresses the printing of the entire cmdspecial or special except at --verbose level 5 in Rdist. If the command is executed, the macro puts out "executing ACTION:OPTION". You can suppliment it with your own echo command as part of the special/cmdspecial.
The POSTINSTALL-ACTIONS must come after all targets in the distfile that could possibly set the ACTION flag. It is best if the POSTINSTALL-ACTIONS stanza is last in the distfile.
This is a different type of macro in that is it used inside a cmdspecial, so it must be used in a quoted string.
SEE ALSO
rdist_macros/NOOP [ Macros ]
[ Top ] [ rdist_macros ] [ Macros ]
NAME
NOOP - Allow a rule in distfile that will never be executed
SYNOPSIS
NOOP;
PURPOSE
It is useful to have dummy targets in the distfile to allow Rdist to updated directories that are not pushed via rdist. This creates a rule to push $C/Config/bin/Rdist to a non-existent target host. It takes the same role as the : command in shell.
EXAMPLE
The following will never actually push any files, but will allow Rdist to update the netdev directory:
netdev: NOOP;
rdist_macros/POSTACTION [ Macros ]
[ Top ] [ rdist_macros ] [ Macros ]
NAME
POSTACTION - register an action for execution after all updates occur
SYNOPSIS
POSTACTION(ACTION,[OPTION])
PURPOSE
rdist supports actions that are run when a file is updated, however if you have multiple files that need to run the same action, and the files are in different rdist stanza's, you currently have to execute the action for every file.
POSTACTION allows an action to be triggered only once regardless of how many files are installed. E.G. you need to restart sshd when the ssh keys change and when the /etc/init.d/sshd file is updated. Because the same rdist stanza/install command can't be used to push both files, you would end up restarting sshd twice if both files are updated. However using POSTACTION sshd can be restarted only once if either or both files are updated.
POSTACTION is used to register the need for an action. The action is defined and executed using IFPOSTACTION.
EXAMPLE
The following installs ssh keys and a new sshd startup file and registers the need to restart sshd. Then a POSTINSTALL-ACTIONS performs the actual action.
ssh: $C/sshd/rc/sshd -> ${SSHD_SLAVES} install -osavetargets /etc/init.d/sshd; POSTACTION(sshd-restart) ; ssh: $C/sshd/keys/a_host/*id_rsa* -> ${SSHD_SLAVES} install -osavetargets /etc/ssh/.; POSTACTION(sshd-restart,keys) ; POSTACTION(sshd-restart,anotheroption) ; ... at the very end of the Distfile POSTINSTALL-ACTIONS: $C/Distfile -> ${SSHD_SLAVES} FORCERUN; cmdspecial "IFPOSTACTION(sshd-restart,keys); touch /etc/newkeys"; cmdspecial "IFPOSTACTION(sshd-restart); /etc/init.d/sshd restart";
Note that "touch /etc/newkeys" won't be done if the only change was to the /etc/init.d/sshd file as the "keys" option won't be registered. NOTE Don't use " or ' marks in the OPTION argument.
SEE ALSO
rdist_macros/RDIST_SPECIAL_FILTER [ Macros ]
[ Top ] [ rdist_macros ] [ Macros ]
NAME
RDIST_SPECIAL_FILTER - use with special commands to filter it from the output
SYNOPSIS
cmdspecial "/bin/ls RDIST_SPECIAL_FILTER";
PURPOSE
This macro is used to tag special/cmdspecial command lines so that they can be filtered out of the rdist output later cleaning up the reporting.
EXAMPLE
With this stanza:
RUN($C/Rdist, ${FEDORA_HOSTS} + ${CENTOS_HOSTS}); cmdspecial "grep tw_cli /etc/sudoers; exit 0 RDIST_SPECIAL_FILTER";
The output of rdist can be run through a grep -v for the expansion of RDIST_SPECIAL_FILTER. This is used internally to the rdist_macro package for the most part and is used to allow filtering of the housekeeping commands generated by BACKUP and other macros.
rdist_macros/REPORTTARGET [ Macros ]
[ Top ] [ rdist_macros ] [ Macros ]
NAME
REPORTTARGET - report the name of the updated file as it is known on the target machine.
SYNOPSIS
REPORTTARGET;
PURPOSE
The following macro defines a command that reports the names of the updated files using the pathname on the target host.
EXAMPLE
The following example will report "*** /etc/ntp.conf updated." when it is updated. as opposed to the standard "Updating /config/ntp/clients.conf" reported by rdist (assuming $C is /config).
label-manual: $C/ntp/clients.conf -> ${NTP_SLAVES} install -osavetargets /etc/ntp.conf; cmdspecial "/etc/rc.d/init.d/ntpd restart" ; REPORTTARGET;
rdist_macros/RUN [ Macros ]
[ Top ] [ rdist_macros ] [ Macros ]
NAME
RUN - always run the provided commands
SYNOPSIS
RUN($C/Config/distfile/settings, ${FEDORA_HOSTS} + ${CENTOS_HOSTS});
cmdspecial "cd /etc/config; ./HOSTVERIFY" ;
PURPOSE
This is an abbreviated version of the FORCERUN command. It's two arguments set up a rule to always run the following special/cmdspecial commands on the remote host(s). It can be used only with a single file.
Note the ';' after the RUN command.
EXAMPLE
The following example will report run "cd /etc/config; ./HOSTVERIFY" every time it is invoked.
label-manual: RUN($C/Config/distfile/settings, ${FEDORA_HOSTS} + ${CENTOS_HOSTS}); cmdspecial "cd /etc/config; ./HOSTVERIFY" ;
It generates something like:
label-manual: $C/Config/distfile/settings ->${FEDORA_HOSTS} + ${CENTOS_HOSTS}) install -oquiet /tmp/rdist.2006-05-24-13-33-02.798 ; cmdspecial "cd /etc/config; ./HOSTVERIFY" ;
SEE ALSO
USES
rdist_macros/SAVEINSTALL [ Macros ]
[ Top ] [ rdist_macros ] [ Macros ]
NAME
SAVEINSTALL - Install a file saving some number of copies.
SYNOPSIS
SAVEINSTALL(file/directory, count, install_args);
SAVEINSTALL(/etc/passwd, 10);
SAVEINSTALL(/etc/passwd, 10, compare);
SAVEINSTALL(/etc/passwd, 10, compare\,nochkgroup);
PURPOSE
The following macro installs the file(s) to it's first argument and keeps it's second argument's number of backups. If the optional third argument is provided this single option is passed as an option to the rdist install directive. Note that commas in the install_args must be escaped with a \. So install_args can be "compare\,nochkgrp" (without the quotes). This will result in an install command of:
install -osavetargets,compare,nochkgrp
The SAVEINSTALL macro is the preferred way to push/backup individual files/directories. Use BACKUP for just the backup portion if you have more complex needs.
EXAMPLE
The following example will install /etc/passwd and keep 7 backups.
label-manual: $C/passwd/tigris -> ( tigris ) SAVEINSTALL(/etc/passwd, 7);
It generates something like:
label-manual: $C/passwd/tigris -> ( tigris ) install -osavetargets /etc/passwd; special "if [ -r ${REMFILE}.OLD ]; then mv --backup=numbered ${REMFILE}.OLD ${REMFILE}.SAVED; ... xargs -r rm -f ; fi";
The following example will install /etc/passwd and keep 7 backups, but only push the file if the contents compare differently.
label-manual: $C/passwd/tigris -> ( tigris ) SAVEINSTALL(/etc/passwd, 7, compare);
The generated output is identical to the above except for the install command which looks like:
install -osavetargets,compare /etc/passwd;
The following example will install (if needed) the files in the directory /etc/nagios and keep 3 backups for each file:
label-manual: $C/nagios/{hosts.cfg,services,cfg,time.cfg} -> ( tigris ) SAVEINSTALL(/etc/nagios/., 3);
SEE ALSO
rdist_macros/VERIFYFILE [ Macros ]
[ Top ] [ rdist_macros ] [ Macros ]
NAME
VERIFYFILE - Diff an installed file against the one in the repository.
SYNOPSIS
VERIFYFILE(/etc/ntp.conf);
PURPOSE
The following macro is given the name of the file (on the client) that it should compare against. Then it installs a copy of the repository file on the remote system and does a unidiff between the installed and repository copies. It returns the unidiff output.
It is useful for checking a file before it is pushed or verifying the correct file is installed.
EXAMPLE
A sample rule is:
ntp-verify: $C/ntp/clients.conf -> ${NTP_SLAVES} VERIFYFILE(/etc/ntp.conf);