Updated: 2022/Sep/29

Please read Privacy Policy. It's for your privacy.


IPMON(5)                      File Formats Manual                     IPMON(5)



NAME
       ipmon, ipmon.conf - ipmon configuration file format

DESCRIPTION
       The ipmon.conf file is optionally loaded by ipmon when it starts.  Its
       primary purpose is to direct ipmon to do extra actions when it sees a
       specific log entry from the kernel.

       A line in the ipmon.conf file is either a comment or a match line.
       Each line must have a matching segment and an action segment.  These
       are to the left and right of the word "do", respectively.  A comment
       line is any line that starts with a #.

       NOTE: This file differs from all other IPFilter configuration files
       because it attempts to match every line with every log record received.
       It does not stop at the first match or only use the last match.

       For the action segment, a match line can delivery output to one of
       three destinations: file, email or command.  For example:

       match { type = ipf; } do { save("file:///var/log/ipf-log"); };
       match { type = nat; } do { syslog; };
       match { type = state; } do { execute("/bin/mail root"); };

       and is roughly described like this:

       match { match-it ,match-it, ... } do { action, action, ...};

       where there can be a list of matching expressions and a list of actions
       to perform if all of the matching expressions are matched up with by
       the current log entry.

       The lines above would save all ipf log entries to /var/log/ipf-log,
       send all of the entries for NAT (ipnat related) to syslog and generate
       an email to root for each log entry from the state tables.

SYNTAX - MATCHING
       In the above example, the matching segment was confined to matching on
       the type of log entry generated.  The full list of fields that can be
       used here is:

       direction <in|out>
              This option is used to match on log records generated for
              packets going in or out.

       dstip <address/mask>
              This option is used to match against the destination address
              associated with the packet being logged.  A "/mask" must be
              given and given in CIDR notation (/0-/32) so to specify host
              192.2.2.1, 192.2.2.1/32 must be given.

       dstport <portnumber>
              This option is used to match against the destination port in log
              entries.  A number must be given, symbolic names (such as those
              from /etc/services) are not recognised by the parser.

       every <second|# seconds|packet|# packets>
              This option is used to regulate how often an ipmon.conf entry is
              actioned in response to an otherwise matching log record from
              the kernel.

       group <name|number>

       interface <interface-name>
              This option is used to match against the network interface name
              associated with the action causing the logging to happen.  In
              general this will be the network interface where the packet is
              seen by IPFilter.

       logtag <number>
              This option is used to match against tags set by ipf rules in
              ipf.conf.  These tags are set with "set-tag(log=100)" appended
              to filter rules.

       nattag <string>
              This option is used to match against tags set by NAT rules in
              ipnat.conf.

       protocol <name|number>
              This option is used to match against the IP protocol field in
              the packet being logged.

       result <pass|block|nomatch|log>
              This option is used to match against the result of packet
              matching in the kernel.  If a packet is logged, using a log rule
              in ipf.conf then it will match "log" here.  The "nomatch" option
              is for use with matching log records generated for all packets
              as the default.

       rule <number>
              This option is used to match against the number of the rule
              causing the record to be generated.  The number of a rule can be
              observed using "ipfstat -ion".

       srcip <address/mask>
              This option is used to match against the source address
              associated with the packet being logged.  A "/mask" must be
              given and given in CIDR notation (/0-/32) so to specify host
              192.2.2.1, 192.2.2.1/32 must be given.

       srcport <portnumber>
              This option is used to match against the source port in log
              entries.  A number must be given, symbolic names (such as those
              from /etc/services) are not recognised by the parser.

       type <ipf|nat|state>
              The format for files accepted by ipmon is described by the
              following grammar: NOTE: At present, only IPv4 matching is
              available for source/destination address matching.

SYNTAX - ACTIONS
       The list of actions supported is as follows:

       save("file://<filename>")
              save("raw://<filename>") Write out the log record to the
              filename given.  This file will be closed and reopened on
              receipt of a SIGHUP.  If the raw target is used, binary log
              data, as read from the kernel, is written out rather than a text
              log record. The filename should be an absolute target, including
              the root directory. Thus, saving to /var/log/ipmon.log would be,
              as an example, save("file:///var/log/ipmon.log").

       syslog("<facility>.<priority>")
              syslog("<facility>.") syslog(".<priority>") To log a text record
              via syslog, the syslog action word is used.  The facility used
              by default is determined at first by the default compiled into
              ipmon (usually LOG_LOCAL0), which can be changed via the command
              line (-L <facility>) or in an ipf.conf rule using the level
              option with logging.  If the facility is specified here, it
              takes precedence over all other settings.  The same applies to
              the syslog priority. By default, ipmon will determine a priority
              for the packet, depending on whether or not it has been blocked,
              passed, etc. It is possible to force the complete
              facility/priority value for each log entry or to choose to
              replace only one of them.

       execute("<command string>")
              The execute action runs the specified command each time the log
              entry matches and feeds the log entry, as text, to the command
              being executed.  The command string given is executed using
              /bin/sh.

       nothing
              Literally, do nothing.  Use this if you want to be verbose in
              your config file about doing nothing for a particular log
              record.

PLUGIN ACTIONS
       It is possible to configure ipmon to use externally supplied modules to
       save log entries with.  These are added to ipmon using the load_action
       configuration line. The syntax of this line is:

       load_action <name> <path>;

       name   is a short name for the action. It does not need to correspond
              to the name of the library file, but inside the library file,
              the functions <name>destroy , <name>parse and <name>store must
              be present.

       path   specifies the path in the filesystem to the shared object that
              contains the implementation of the new action. After the new
              action has been declared using load_action it can then be used
              in any do statement.

EXAMPLES
       Some further examples are:

       #
       # log everything to syslog local4, regardless
       #
       match { ; } do { syslog("local4."); };
       #
       # keep a local copy of things packets to/from port 80
       #
       match { srcport = 80; } do { save("file:///var/log/web"); };
       match { dstport = 80; } do { save("file:///var/log/web"); };
       #
       load_action local "/usr/lib/libmyaction.so";
       match { dstip 127.0.0.1; } do { local("local options"); };
       #

MATCHING
       All entries of the rules present in the file are compared for matches -
       there is no first or last rule match.

FILES
       /dev/ipl
       /dev/ipf
       /dev/ipnat
       /dev/ipstate
       /etc/ipmon.conf

SEE ALSO
       ipmon(8), ipl(4)



                                                                      IPMON(5)