The following sample report gives a good overview of what one may expect from ost. Files appearing in the report were defined either in the "Solaris" template, or by the system catalog (/var/sadm/install/contents on Solaris) or finally were additions to the system ("unknown").
The following states may be found:
+ /.amandahosts [Solaris] -- /core [Solaris] ! /.ssh/authorized_keys [Solaris] ! /etc/default/kbd [Solaris] ! /etc/default/login [Solaris] - /etc/hosts~ [unknown] !+ /etc/init.d/apache [Solaris] !+ /etc/init.d/inetinit [Solaris] ++ /etc/init.d/sshd [Solaris] ++ /etc/rc0.d/K14sshd [Solaris] !+ /etc/rc0.d/K42inetsvc [vendor] !+ /etc/rc1.d/K42inetsvc [vendor] ++ /etc/rc2.d/K65sshd [Solaris] ++ /etc/rc3.d/S35sshd [Solaris] !+ /etc/rcS.d/K42inetsvc [vendor]
ost - OS Template Checker
ost [ -h | -V ] ost [ -sSctxfdCBUUAnpvr ] [ -T directory ] [ -l level ] [ -L file ] [ -k level ] [ -K file ] target[:zone] [ template(s) ] [ file(s) ] ost -i [ -p ] file(s)
ost is a tool providing mechanisms to automatically audit, maintain and backup systems customizations. It is based on the simple idea that a live system is principally composed of the vendor provided Operating System and local customiza- tions. ost works using the system's (vendor provided) file catalog if it exists along with user defined templates that define local customizations. Templates are applied as separate layers on top of the system with each layer over- riding lower layers (when conflicting). The preferred way to setup ost is to choose a template server which holds all the templates on a local disk area called the template area. The template area is where the templates are actually defined (and stored) and where confi- guration files are also stored. ost is then run on the tem- plate server, it works by obtaining a remote shell on the target (via rsh or ssh for example) where a second ost pro- cess will be started. On the target system, there should be a command ost-sysinfo that is called by ost to gather the system information which is then used on the template server where ost-tmpldef is run to get the list of templates defined for the target. If the caller specifies no template(s) on the command line then the entire list is used, otherwise templates defined by ost-tmpldef by not on the command line are skipped. (There is no way to manually add templates.) By default, ost will audit the filesystem as defined per its trek configuration (see below). This may be further res- tricted by specifying file(s) on the command line. ost will then only audit files that are included by the trek confi- guration and also included on the command line. Extended regular expressions may be used as in configuration files, however there is currently no way to explicitely exclude files on the command line. When ost is done auditing the system, it will report its findings by listing files which were found in an unexpected state. The format of the report is as follows: Error A single character is used to report the error for the file: "-" if the file should not exist, "!" if the file has been modified and "+" if the file is missing. Action A single character is used to report what the ost con- figuration is for the file: "-" if the file should be automatically removed, "+" if the file should automati- cally be updated, and finally a space if no action is to be taken. The action is only actually taken if the -U option was specified. Backup When the -v option is used, a single character is added to report whether ost would backup the file "b", or exclude it from backups "X" even though the file is not an original vendor or template file. Filename Source Finally, between square brackets ost will report where the file is defined. This will either be a template name, "vendor" (for files defined in the system's file catalog), or "unknown" (for files that are not defined anywhere). The last step taken by ost is to run "post" scripts on the target. This is done after performing a backup (see -B option) and applying any update (see -U option) to the sys- tem. The output of these scripts (if any) is appended to the above report.
-h Display a brief help message. -V Display the version information. (Specify twice to see compile time settings.) -i For each file passed as argument, display the following file information: the mode, owner, group, size, atime, mtime, ctime, md5 checksum and, on Solaris, the sum(1) checksum. Note that all of the above except atime and ctime are used by ost to compare files. Note that the md5 checksum is used internally by ost for templates as well as the RPM Package Manager catalog, while the sum(1) checksum is used by the Solaris system catalog. If the optional -p argument is used, the output is condensed into a single line per file making it easily parseable by scripts. -s Display the target's system information without doing anything. -S Display the template set configured for the target sys- tem. -c Don't check divergence from the system's file catalog. -t Don't check divergence from the defined templates. -x Search the entire file system for files that are unde- fined. This option should be used with care, and in particular, the trek configuration set to prevent remote filesystems from being scanned. It is to be noted that the following types of files are not reported by this option: FIFOs, sockets and doors. -f Instead of auditing the system, ost will report on which template files are defined. If -f is used twice on the command line, then it will list all the tem- plates defining the files, instead of the topmost layer only. -d The diff(1) program will be used to compare files that diverge from the defined templates. -C When comparing files, if the size and last modification match, assume that the files are identical without validating the checksum. This significantly speeds up checking divergence from the system's file catalog but may miss some file divergences. -B Perform a backup of all customized files. Backups are performed before applying any update (see -U option) is applied to the system using the tar program specified at compile time, and held under the Backup directory found in the template area. -U Automatically update files that diverge from the defined template and delete files as per the tupdate and remove configurations. -Y When the number of files to automatically update or delete is over a configured threshold (10 and 5 by default, respectively) ost skips the work and issues a warning only. This option may be used to manually override this safety. -A This option allows applying templates onto a live system. Extreme care should be taken when using this option as it provides no safeguard and will apply templates as they are onto the system. In particular, this includes updating template files that are defined as mutable (see the tmutable configuration file below). This is typically used to first initialize a newly built system as well as manually correct template divergences not defined to be automatically corrected (by the tupdate and remove configurations). Extraneous files found with the -x options but not mentioned in the remove configuration will not be removed. -n When used with the -U or -A options, this will cause the automatic updates to be sent to the remote system, and validated by tar but not actually applied to the remote system. Automatic file removals will simply be skipped. When used with the -B option, this will cause the backup to be sent by the remote system, and vali- dated by tar but not actually saved. This is useful to check for corruption. -p This option prevents any "post" script from being run. Depending on what the defined "post" scripts do in your environment, this can be a very dangerous option to use. -I By default, ost calls ssh with the "-oBatchMode=yes" argument. This option disables such behaviour which allows ssh to prompt the user for a password. -v This option causes ost to produce a more verbose report which includes all the files that have been modified on the system, even if such modifications are allowed by the system catalog or the configuration. -r Useful mostly for debugging, this option may be used to produce a raw report that is less readable but more detailed. -T directory Defines the template area. -l level -k level Defines the logging level for the local and remote end, respectively. The logging level is the combination of a category and a level separated by a dot. Multiple levels may be given if separated by a comma. To list the available categories, run "ost -l show". The spe- cial category "all" may be used to specify a level globally. Available levels are "data", "debug", "info", "warn", "err" and "none" (from the most to least verbose). -L file -K file Specify the file to which logging messages should be written to by the local and remote end, respectively. By default, such messages are written to the standard error.
As mentioned above, ost makes use of two commands to get a list of template names for the target. ost defines the "OST_PROTOCOL" environment variable which is set to the pro- tocol version used for this session prior to running either of the following commands. The first command, ost-sysinfo, must return a list of vari- ables, one per line, in the "VARIABLE=VALUE" format. The second command, ost-tmpldef is passed the template area as sole argument and must return two things: the system name in the format "OST NAME: system name", and the template names in the format "OST TEMPLATE: template name", one per line. The variables defined by the ost-sysinfo are available to ost-tmpldef as environment variables. The order in which the template names are defined is criti- cal to the proper operation of ost. ost-tmpldef should list the templates from the lowest to the highest layer.
The file ost.conf found at the top level of the template area may be used to configure ost variables, using the "variable=value" format. On the remote system, the file /etc/ost.conf will be read. The following variables are supported: backups Defines the number of backups to keep for each host. backupsize If the size of the target (compressed) tar backup exceed this value (in MB), issue a warning. The default is 50MB. diff Defines the path of diff command to use (with -d). key Defines the path of the file where ost stores the key ID for the semaphores used for inter-process locking. maxadd Defines the safety threshold for automatically updating files. (See the -U and -Y options.) maxdel Defines the safety threshold for automatically removing files. (See the -U and -Y options.) rofs Comma separated list of file system types that should always be considered read-only regardless of what the mounted file system table says. rsh Defines the path of the command to use to obtain a remote shell on the target. summax sumbatch As described above, ost use sum(1) to compute file checksums for comparison with the Solaris system cata- log. ost will spawn up to summax sum(1) processes, passing each one of them a list of up to sumbatch files to work on. tar Defines the path of the tar command to use for backups and updates.
Each template is found directly under the template area, in the directory named after the template, and contains up to three things: the template itself (under the "template" directory), the template specific configuration files (under the "ost" directory), and the template "post" script. A template is simply a file hierarchy starting with the directory "template" as the root of the template (e.g. "/"). Directories and files appear in the template as they should appear in the filesystem. Each template configuration file adheres to the following simple format: Each line is composed of a "+" or "-" char- acter followed by a single space followed by a pattern. The pattern is matched against filenames using extended regular expressions. A pattern matching a directory will also match any file found below the directory. Patterns associated with the "+" character mean that matching files are included by the configuration while files matching patterns associ- ated with the "-" character are excluded. If no match is found for a file, then the file is excluded. The order of patterns in configuration files is irrelevant. (It would be impossible to order things properly across several templates!). Instead the longest match is used to define which pattern takes precedence, and for matches of same length, exclusion will have precedence over inclusion. So, for example, given the pattern "/etc", the filename "/etc/rc0.d" will match with a length of 4. However, it will match with a length of 10 for the pattern "/etc/rc[0- 6S].d". The following configuration files are currently supported: trek This configuration defines which areas of the file sys- tem will be scanned by ost. It may be used to keep it from wandering too much (especially across mount points) as well as to limit which portions of the system's file catalog are actually used. There are three important facts to note about this configuration. First, it does not have any effect on the template con- tents. Second, for a directory to be scanned, its parent directory must be configured to be scanned and so on until the root of the filesystem is reached. This limitation may be addressed in a future release. Finally, ost reads the mounted filesystem table on startup and automatically excludes any read-only filesystem, regardless of this configuration. (See also the rofs configuration option above.) mutable Files included in this configuration are considered mutable which means that they are allowed to vary from their entry in the system's file catalog. Such files will never raise errors (unless they are expected to exist and do not). Some vendor file catalogs (such as the one for Solaris and the RPM Package Manager) also define files as mutable, ost honors such information. optional This configuration defines files that are optional. Such files will not raise warnings if they are missing, but will if they are present and vary from the correct version. The use of this directive is discouraged as it is impossible to tell from this configuration or the ost backups which files may be missing on a given sys- tem. remove Files included by the configuration will automatically be removed from the system if they are found to exist. tupdate Template files included by this configuration will automatically be added to the system if they are found to be missing or if they have been modified. tmutable This configuration is similar to the mutable configura- tion but applies to files defined by a template. This allows defining files used to initialize a system (using the templates) while letting them diverge later on. preserve It is sometimes necessary to limit in which areas of the file system ost will back up customized files, for example one may choose to do real full backups of "/var", in which case it wouldn't be sensible to also backup customizations using ost. This may be done with this configuration. Finally, the template "post" script is an executable file which will be run by ost on the target after applying any update to the target. If there was no update, then the "post" script is not run. The list of updates is sent to the "post" script's standard input by ost as a simple list of files, prefixed by the character "-" for files that have been removed and "+" for the files that have been added. The output of "post" is relayed to the user. It is impor- tant to note that (1) ost does not actually guarantee that files listed as removed have actually successfully been removed or that files listed as added have actually success- fully been added and (2) The order in which the various "post" scripts are run is undefined.
ost will use the following environment variable if set: OST_RSH May be used to define the command to use to obtain a remote shell on the target.
diff(1), digest(1), lost(1), most(1), tar(1), rsh(1), sum(1), ssh(1).
The latest official release of ost is available on the web. The home page is http://web.taranis.org/ost/
Christophe Kalt <ost[at]taranis.org>
Send bug reports to `ost-bugs[at]taranis.org'.