TW.CONFIG(5)

NAME
tw.config - configuration file for Tripwire

SYNOPSIS
tw.config

DESCRIPTION
The tw.config file contains the list of files and directories to be scanned by Tripwire. Information on these files is collected and stored in the tw.db database file. Stored with each tw.config entry is a selection-mask that describes what changes Tripwire can safely ignore without reporting to the user (e.g., access timestamp).

The first section in this manual page describes the entry format in tw.config for the files monitored by Tripwire. The second section describes the proprocessing directives that Tripwire provides. These directives, which provide functionality similar to the C preprocessor and M4 macro processor, allow Tripwire to make bindings at run-time. This allows system administrators to use common tw.config files across multiple machines - or even across an entire site.

ENTRY FORMAT

Each entry in tw.config is a single line in the following form:

    Format:     [!|=] entry [select-flags | template] [# comment]

    entry
        An entry is the absolute pathname of a file or a directory. Without any prefixes, the entry is added to the list of files to be scanned.

        Note that directories listed in the tw.config file are recursively descended. However, filesystems are never crossed. (I.e., if /usr and /usr/local are seperate filesystems, a /usr in tw.config entry will not scan files that reside in the /usr/local filesystem.)

        !   Inclusive prune. Prunes entry from the list of files to be scanned. If entry is a file, the file is removed from the list of files. If entry is a directory, the directory and all of its children are removed from the list of files.

        =   Exclusive prune. Does not prune entry, but does prune its children. This has no effect if entry is a file. This option is useful for monitoring directories with transient files (e.g., /tmp and /var/tmp).

    select-flags
        select-flags describe inode and file attributes. select-flags either specifies Tripwire to ignore changes in a specific attribute, or to report them. select-flags are provided in the form: [ [+|-][pinugsam123456789] ... ]

        -   ignore the following attributes

        +   record and check the following attributes

        p   permission and file mode bits

        i   inode number

        n   number of links (i.e., inode reference count)

        u   user id of owner

        g   group id of owner

        s   size of file

        a   access timestamp

        m   modification timestamp

        c   inode creation/modification timestamp

        0   signature 0 - null signature

        1   signature 1 - MD5, the RSA Data Security, Inc. Message Digesting Algorithm.

        2   signature 2 - Snefru, the Xerox Secure Hash Function.

        3   signature 3 - CRC-32, POSIX 1003.2 compliant 32-bit Cyclic Redundancy Check.

        4   signature 4 - CRC-16, the standard (non-CCITT) 16-bit Cyclic Redundancy Check.

        5   signature 5 - MD4, the RSA Data Security, Inc. Message Digesting Algorithm.

        6   signature 6 - MD2, the RSA Data Security, Inc. Message Digesting Algorithm.

        7   signature 7 - SHA, the NIST Secure Hash Algorithm (NIST FIPS 180)

        8   signature 8 - Haval, a strong 128-bit signature algorithm

        9   signature 9 - null signature (reserved for future expansion)

    templates
        template are predefined sets of select-flags that are commonly used by system administrators.

The following templates have been pre-defined to make these long select-masks descriptions unnecessary.

    R   [R]ead-only (+pinugsm12-ac3456789) (default)

    L   [L]og file (+pinug-sacm123456789)

    N   ignore [N]othing (+pinusgsamc123456789)

    E   ignore [E]verything (-pinusgsamc123456789)

    >   monotonically growing file (+pinug>-samc1233456789) - the ``>'' indicates
        that file changes are ignored only when the file is smaller than the last
        recorded size.  This is useful for log files that are expected to grow.

By default, Tripwire uses the R template. Because it applies the set of select-flags {+pinugsm12-a3456789}, Tripwire ignores those changed files where only the access timestamp changed.

You can combine the use of templates with select-flag modifiers. The following entry monitors only changes in user-id and group-id information.
    /etc/lp    E+ug

ENTRY EXAMPLES

The following entry will scan all the files in /etc, and report any changes in mode bits, inode number, reference count, uid, gid, modification and creation timestamp, and the signatures. However, it will ignore any changes in the access timestamp.
    /etc    +pinugsm12-a

It is equivalent to:
    /etc    R

The following example shows a very simple tw.config file that monitors selected directories.
    /etc		R	# all system files
    !/etc/lp		R	# ...but not those logs
    =/tmp		N	# just the directory, not its files

Note the difference between pruning (via "!") and ignoring everything (via "N" template): ignoring everything in a directory still monitors for added and deleted files, but pruning a directory will prevent Tripwire from even looking in the specified directory for any changes.

Hint: Is Tripwire running too slowly? Modify your tw.config entries to use only a few signatures (e.g., signatures 1 and 5) when this computationally-exorbitant protection is not needed. (See README and design document for further details.)

PREPROCESSOR

Tripwire incorporates a general purpose preprocessor that parses the tw.config file in one-pass. Available preprocessing directives include file inclusion, macro defines, conditionals based upon hostname or macros, and on-the-fly macro substitution. These directives provide C-preprocessor and m4-like capabilities.

The Tripwire preprocessor was included to allow its scalable use at large sites, allowing system administrators to reuse tw.config files by either including component files or having multiple machines share a common tw.config file.

    @@ifhost HOSTNAME
        includes text until matching @@endif if the machine hostname matches the specified HOSTNAME. Remember that you must use the exact hostname that uname(1) or hostname(1) returns. This usually implies that you must use the fully qualified hostname (e.g., mentor.cc.purdue.edu).

    @@ifnhost HOSTNAME
        includes text until matching @@endif if the machine hostname does not match the specified HOSTNAME.

    @@else
        provides if-else semantics to preprocessor.

    @@define VAR STRING
        defines variable VAR to STRING. If the second argument is not provided, then a null-string is assigned to VAR.

    @@undef VAR
        clears the definition associated with variable VAR.

    @@ifdef VAR
        includes text until the matching @@endif or @@else if the variable VAR has been defined.

    @@ifndef VAR
        includes text until matching @@endif or @@else if the variable VAR has not been defined.

    @@endif
        closes up @@ifhost, @@ifnhost, @@ifdef, and @@ifndef.

    @@include ``PATHNAME''
        reads in the specified source file. The double-quotes are optional.

    @@VAR
        substitutes the definition of VAR with the @@define'ed value.

    @@{VAR}
        substitutes the definition of VAR with the @@define'ed value.

Example: A host-dependent inclusion can be specified many ways so tw.config files can be shared among multiple machines. So, if the machine "mentor.cc.purdue.edu" is the only machine that has a certain file, you could use:
    @@ifhost mentor.cc.purdue.edu
    /etc/tw.log.mentor	R
    @@endif
    @@define ARCHIVE	R
    /etc/tw.log		@@ARCHIVE

CAVEATS

Although Tripwire provides hooks for ten different signature routines, using all ten would certainly be overkill in almost any imaginable situation. However, having up to ten signature routines in your signature arsenal allows system administrators considerable flexibility in finding the balance between performance and security for their specific site. This is the reason for supplying CRC-16 and CRC-32, which are trivially simple to spoof. These routines are not secure, but they are faster than the message-digesting routines.

DATABASE VERSIONS

Tripwire v1.0 used database version 1. Database version 2 changed the base-64 alphabet so that ``0'' retained its traditional value.

Database version 3 changed the base-64 encoding so that all the bits were packed, reducing the size of 160-bit signatures from 30 characters to 27 characters. Tripwire v1.1 used database version 3. The program twconvert is provided to convert from the older database formats to version 3.

Tripwire v1.2 uses database version 4, supporting signatures for symbolic links and more consistent handling of entry numbers. (Note that twconvert cannot convert older database versions to database version 4. These databases will have to be regenerated.)

SEE ALSO
tripwire(8), twconvert(8)

AUTHOR
Gene Kim
Purdue University
gkim@cs.purdue.edu
Eugene Spafford
Purdue University
spaf@cs.purdue.edu