avatar is a system for maintaining the state of a file system in a baseline and uses that baseline to check and correct the contents of file systems.

avatar can be used:

• Interactively
• In a fully automated mode, invoked by scheduling processes (such as UNIX cron)
• Or as part of a stimulus/response from other packages (e.g., virus detection)

• their existence
• their permissions
• their user and group ownerships
• a cryptographic signature of their contents
• their actual contents

When it determines that one or more of these attributes is incorrect, avatar can restore the attributes to their recorded state.

Which attributes are recorded for which files is completely configurable.

The root of the file system used is specified with most avatar commands. This allows a baseline created using the contents of one file system to be used to check and correct many different file systems located at various places in a file system hierarchy.

LICENSES

At startup, avatar searches for the LICENSE file in these locations:

Avatar Command Usage

avatar has eight modes of operation: create, update, iupdate, add, delete, configuration, check, and correct.

The first six commands create, examine and modify the baseline. The last two use the baseline to check and/or correct individal files, directory hierarchies, or whole file systems.

Each of these commands is invoked by invoking the avatar program with the command name as its first argument. For example:

    avatar create foo bar n.cfg

Most commands take other arguments as well which come after the function name (i.e., ``foo'', ``bar'' and ``n.cfg'' above). They will be explained in the entry for each command.

In general, though, most commands have root and baseline as their first two arguments. These are the root of the file system to be used and the name of the baseline directory to be used (or created) respectively.

The Configuration

An example of a possible real configuration is to protect the entire file system with the exception of /home and /logs. The configuration file used to initialize this configuration via the create command could look like:

    E /
    ! /home
    ! /logs

The configuration can also allow the system to record varying sets of attributes for different files and directories. It also allows the specification of a directory to be recursively baselined with certain files and subdirectories excluded or recorded with different attributes.

Configuration File Format

Each line of the configuration file contains a pathname to be baselined which can be either a file, special file, or a directory.

Each pathname is prefixed by a list of the attributes to baseline, followed by a space. The attributes are represented by single letters as follows:

e = existence
p = permissions
o = ownership
s = cryptographic signature
c = file contents
! = do not baseline the pathname
R = baseline the recursive contents of directories
E = everything (eposcR)

Thus, a configuration file that consisted of the single line:

    E /

    !R /var

The Commands

avatar create root baseline configfile [altbaseline]

The create command baselines all the pathnames listed in configfile, with root prefixed, placing the baseline database in the baseline directory.

If provided, the altbaseline parameter specifies the location of an alternate baseline which is a secondary source of information used by the check and correct commands (See the extended discussion of this below). There can be one alternate baseline for each baseline. It can be set via the create, update or iupdate commands.

Note that a baseline may consist of a pointer to an alternate baseline, such as on a CD-ROM or an NFS mounted drive.

If create has no problems, it will exit with a status of 0; otherwise, it will exit with a non-zero status.

avatar update root baseline [altbaseline]

The update command updates the baseline in the baseline directory with information about the pathnames in the configuration (with root prefixed). If altbaseline is provided, avatar uses it as a second source of information. Exit status is 0 if there are no problems.

One example of a use of the update command would be to modify the baseline due to the installation of a product upgrade on the system when the files of the upgrade reside in an already configured (in the configuration) directory. Another use is to change the alternate baseline without updating any other baseline contents via the invocation:

    avatar update / , , altbaseline

The commas indicate that file information is not to be updated.

avatar iupdate root baseline [altbaseline]

The iupdate command performs the same function as update except that the baseline administrator is interactively prompted for a yes/no response on each file that needs updating. Only files for which a `yes' response is given will have their baseline information updated.

avatar configuration root baseline

The configuration command outputs a report to standard output describing the current configuration of baseline. This is in a form suitable for use as a configfile argument to the create command. An example of using this command to output the entire configuration of a baseline residing in the directory /baseline is:

    avatar configuration / /baseline

The root argument to this program has no effect and is only present for purposes of consistency.

avatar check root baseline [file]

The check command checks the directory structure based at root (or the individual file, with root prefixed, if specified) against the information in the baseline database in the baseline directory. Exit status is 0 if there are no problems. Exit status is 1 is there if a discrepancy between the baseline and the file system. In that case, a report of the discrepancies is written to standard output. The exit status is greater than 1 in the case of other problems.

avatar correct root baseline [file]

The correct attempts to restore the directory structure based at root (or the individual file, with root prefixed, if specified) to the state described in the baseline database in the baseline directory. correct automatically invokes check for the purposes of determining which corrections are needed. Exit status is 0 if the restoration is completely successful and a report of the corrections made is written to standard output. Otherwise, the exit status is non-zero and a report of the problems encountered is written to standard error.

avatar add root baseline attributes path

The add command allows the addition of files to the baseline configuration. It also updates the corresponding file information in the baseline. attributes is an attribute list as described for the configuration file above. An example of its use is adding protection to a disk drive that was recently added to the system.

avatar delete root baseline path

Is equivalent to:

    avatar add root baseline ! path

which uses the ! flag to indicate that the path is not to be baselined. Information about path is removed from baseline and the configuration is modified so that subsequent updates to the baseline will not include information about path.

Explanation of Alternate Database

The alternate baseline may be used if there is a failure of the primary baseline during the operation of the check or correct commands. If the program was able to obtain the reference to the alternate database before the failure of the primary one, it can be used instead. This would be useful in the case of a network failure where the primary baseline is contained remotely. A smaller, secondary baseline of very critical files may be contained on the unit operating.

If, during a correct operation, a file is found to have an incorrect cryptographic signature and the file contents are not contained in the primary baseline, then the alternate baseline is consulted.

The alternate baseline may also be used if there is an explicit file argument to the check or correct commands. If the file isn't in the configuration of the primary baseline, these programs check for it in the alternate baseline.

Lastly, alternate baselines may be explicitly used in scripts that invoke avatar. Avatar always exits with status 23 if, upon initialization, it can't access the specified baseline. This exit status can then be checked in a script to automatically reinvoke avatar, explicitly pointing to an alternate baseline.

Simple Introductory Use

Create a config file called avatar.cfg with the single line:

    E /data

    avatar create / baseline avatar.cfg

Run `avatar configuration / baseline'; that should just regurgitate the contents of avatar.cfg.

Run `avatar spew / baseline'; this undocumented function lists the entire baseline contents.

Run `avatar check / baseline'; this should produce no output as nothing has been changed.

Run `avatar update / baseline'; again, there should be no output because nothing has changed.

Modify a file somewhere in /data.

Perform a check followed by an update followed by another check. The first check should report the change; the update should report incorporating the change; the second check should report nothing, since nothing's been changed since the last update.

Modify another file in /data.

Perform a check, followed by `avatar correct / baseline', followed by another check.