TABLE OF CONTENTS


Config/rdist_macros [ Modules ]

[ Top ] [ 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

SAVEINSTALL


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

SAVEINSTALL, BACKUP


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

FORCERUN, RUN


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

RUN

USES

DATESTAMP

USED BY

RUN


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

POSTACTION FORCERUN


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

IFPOSTACTION


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

FORCERUN

USES

FORCERUN, DATESTAMP


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

BACKUP


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);