Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
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 be-
       cause  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 pack-
	      ets going	in or out.

       dstip <address/mask>
	      This option is used to match against the destination address as-
	      sociated	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	match-
	      ing  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  associ-
	      ated  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 en-
	      tries.  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 fol-
	      lowing grammar: NOTE: At present,	only IPv4 matching  is	avail-
	      able 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 file-
	      name 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  pri-
	      ority  for  the  packet, depending on whether or not it has been
	      blocked, passed, etc. It is possible to force the	 complete  fa-
	      cility/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 ac-
	      tion 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)

NAME | DESCRIPTION | SYNTAX - MATCHING | SYNTAX - ACTIONS | PLUGIN ACTIONS | EXAMPLES | MATCHING | FILES | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=ipmon&sektion=5&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help