contrib/ipfilter/man/ipmon.5

   1 .\"     $FreeBSD$
   2 .\"
   3 .TH IPMON 5
   4 .SH NAME
   5 ipmon, ipmon.conf \- ipmon configuration file format
   6 .SH DESCRIPTION
   7 The
   8 .B ipmon.conf
   9 file is optionally loaded by
  10 .B ipmon
  11 when it starts.  Its primary purpose is to direct
  12 .B ipmon
  13 to do extra actions when it sees a specific log entry from the kernel.
  14 .PP
  15 A line in the
  16 .B ipmon.conf
  17 file is either a comment or a
  18 .B match
  19 line.  Each line must have a matching segment and an action segment.
  20 These are to the left and right of the word "do", respectively.
  21 A comment line is any line that starts with a #.
  22 .PP
  23 .B NOTE:
  24 This file differs from all other IPFilter configuration files because it
  25 attempts to match every line with every log record received.  It does
  26 .B not
  27 stop at the
  28 .B first
  29 match or only use the
  30 .B last
  31 match.
  32 .PP
  33 For the action segment, a
  34 .B match
  35 line can delivery output to one of three destinations:
  36 \fBfile\fR, \fBemail\fR or \fBcommand\fR.  For example:
  37 .nf
  38
  39 match { type = ipf; } do { save("file:///var/log/ipf-log"); };
  40 match { type = nat; } do { syslog; };
  41 match { type = state; } do { execute("/bin/mail root"); };
  42 .fi
  43 .PP
  44 and is roughly described like this:
  45 .PP
  46 match { \fImatch-it ,match-it, ...\fP } do { \fIaction, action, ...\fP};
  47 .PP
  48 where there can be a list of matching expressions and a list of actions
  49 to perform if all of the matching expressions are matched up with by
  50 the current log entry.
  51 .PP
  52 The lines above would save all ipf log entries to /var/log/ipf-log, send
  53 all of the entries for NAT (ipnat related) to syslog and generate an email
  54 to root for each log entry from the state tables.
  55 .SH SYNTAX - MATCHING
  56 .PP
  57 In the above example, the matching segment was confined to matching on
  58 the type of log entry generated.  The full list of fields that can be
  59 used here is:
  60 .TP
  61 direction <in|out>
  62 This option is used to match on log records generated for packets going
  63 in or out.
  64 .TP
  65 dstip <address/mask>
  66 This option is used to match against the destination address associated
  67 with the packet being logged.  A "/mask" must be given and given in CIDR
  68 notation (/0-/32) so to specify host 192.2.2.1, 192.2.2.1/32 must be given.
  69 .TP
  70 dstport <portnumber>
  71 This option is used to match against the destination port in log entries.
  72 A number must be given, symbolic names (such as those from /etc/services)
  73 are not recognised by the parser.
  74 .TP
  75 every <second|# seconds|packet|# packets>
  76 This option is used to regulate how often an \fBipmon.conf\fR entry is
  77 actioned in response to an otherwise matching log record from the kernel.
  78 .TP
  79 group <name|number>
  80 .TP
  81 interface <interface-name>
  82 This option is used to match against the network interface name associated
  83 with the action causing the logging to happen.  In general this will be the
  84 network interface where the packet is seen by IPFilter.
  85 .TP
  86 logtag <number>
  87 This option is used to match against tags set by ipf rules in \fBipf.conf\fR.
  88 These tags are set with "set-tag(log=100)" appended to filter rules.
  89 .TP
  90 nattag <string>
  91 This option is used to match against tags set by NAT rules in \fBipnat.conf\fR.
  92 .TP
  93 protocol <name|number>
  94 This option is used to match against the IP protocol field in the packet
  95 being logged.
  96 .TP
  97 result <pass|block|nomatch|log>
  98 This option is used to match against the result of packet matching in the
  99 kernel.  If a packet is logged, using a \fBlog\fR rule in \fBipf.conf\fR
 100 then it will match "log" here.  The "nomatch" option is for use with
 101 matching log records generated for all packets as the default.
 102 .TP
 103 rule <number>
 104 This option is used to match against the \fInumber\fR of the rule
 105 causing the record to be generated.  The \fInumber\fR of a rule can be
 106 observed using "ipfstat -ion".
 107 .TP
 108 srcip <address/mask>
 109 This option is used to match against the source address associated
 110 with the packet being logged.  A "/mask" must be given and given in CIDR
 111 notation (/0-/32) so to specify host 192.2.2.1, 192.2.2.1/32 must be given.
 112 .TP
 113 srcport <portnumber>
 114 This option is used to match against the source port in log entries.
 115 A number must be given, symbolic names (such as those from /etc/services)
 116 are not recognised by the parser.
 117 .TP
 118 type <ipf|nat|state>
 119 The format for files accepted by ipmon is described by the following grammar:
 120 .B NOTE:
 121 At present, only IPv4 matching is available for source/destination address
 122 matching.
 123 .SH SYNTAX - ACTIONS
 124 The list of actions supported is as follows:
 125 .TP
 126 save("file://<filename>")
 127 save("raw://<filename>")
 128 Write out the log record to the filename given.  This file will be closed
 129 and reopened on receipt of a SIGHUP.  If the \fIraw\fP target is used,
 130 binary log data, as read from the kernel, is written out rather than a
 131 text log record. The filename should be an absolute target, including
 132 the root directory. Thus, saving to /var/log/ipmon.log would be, as an
 133 example, save("file:///var/log/ipmon.log").
 134 .TP
 135 syslog("<facility>.<priority>")
 136 syslog("<facility>.")
 137 syslog(".<priority>")
 138 To log a text record via syslog, the \fBsyslog\fP action word is used.
 139 The facility used by default is determined at first by the default
 140 compiled into \fBipmon\fP (usually LOG_LOCAL0), which can be changed
 141 via the command line (-L <facility>) or in an \fBipf.conf\fP rule
 142 using the \fIlevel\fP option with logging.  If the facility is
 143 specified here, it takes precedence over all other settings.
 144 The same applies to the syslog priority. By default, ipmon will
 145 determine a priority for the packet, depending on whether or not it
 146 has been blocked, passed, etc. It is possible to force the complete
 147 facility/priority value for each log entry or to choose to replace
 148 only one of them.
 149 .TP
 150 execute("<command string>")
 151 The
 152 .B execute
 153 action runs the specified command each time the log entry matches
 154 and feeds the log entry, as text, to the command being executed.
 155 The command string given is executed using /bin/sh.
 156 .TP
 157 nothing
 158 Literally, do nothing.  Use this if you want to be verbose in your config
 159 file about doing nothing for a particular log record.
 160 .SH PLUGIN ACTIONS
 161 It is possible to configure
 162 .B ipmon
 163 to use externally supplied modules to save log entries with.
 164 These are added to
 165 .B ipmon
 166 using the
 167 .I load_action
 168 configuration line. The syntax of this line is:
 169 .nf
 170
 171 load_action <name> <path>;
 172 .fi
 173 .TP
 174 name
 175 is a short name for the action. It does not need to correspond to the
 176 name of the library file, but inside the library file, the functions
 177 .B <name>destroy
 178 ,
 179 .B <name>parse
 180 and
 181 .B <name>store
 182 must be present.
 183 .TP
 184 path
 185 specifies the path in the filesystem to the shared object
 186 that contains the implementation of the new action. After the new
 187 action has been declared using
 188 .I load_action
 189 it can then be used in any
 190 .I do
 191 statement.
 192 .SH EXAMPLES
 193 .PP
 194 Some further examples are:
 195 .nf
 196
 197 #
 198 # log everything to syslog local4, regardless
 199 #
 200 match { ; } do { syslog("local4."); };
 201 #
 202 # keep a local copy of things packets to/from port 80
 203 #
 204 match { srcport = 80; } do { save("file:///var/log/web"); };
 205 match { dstport = 80; } do { save("file:///var/log/web"); };
 206 #
 207 load_action local "/usr/lib/libmyaction.so";
 208 match { dstip 127.0.0.1; } do { local("local options"); };
 209 #
 210 .fi
 211 .SH MATCHING
 212 .PP
 213 All entries of the rules present in the file are
 214 compared for matches - there is no first or last rule match.
 215 .SH FILES
 216 /dev/ipl
 217 .br
 218 /dev/ipf
 219 .br
 220 /dev/ipnat
 221 .br
 222 /dev/ipstate
 223 .br
 224 /etc/ipmon.conf
 225 .SH SEE ALSO
 226 ipmon(8), ipl(4)