netl.conf - netl (8) configuration file
the file netl.conf is the main configuration file for the program
netl (8) . there is an example netl.conf which comes with the
netl distribution. it is well commented and highly recommended that
you play around with that to learn its structure. this is intended for
reference only.
blank lines and lines beginning with the # characters are ignored by
netl. extra white space is ignored.
the first elements of the netl.conf file should be a device
statement, followed by an optional detect statement and then an
optional list of alias statements. lets look at them first.
device device type
this line specifies the device and what type it is. type should be
ethernet, as that is the only device type currently supported and device
should indicate the device, such as eth0 or eth1.
detect
this instructs netl (8) to detect the hostname that it is running on
and assign two aliases, local to the IP address of your machine, and
localhost to 127.0.0.1, traditionally loop back. this is helpful if you
are using one standard configuration file over a whole network where more
than one machine may be running with the same configuration file.
alias hostname ipnumber
this allows you to define an alias for a specific host. this is name can
be used later in the configuration file (with the dstip= and srcip=
options), and is also used to report the hostname to syslogd (8) when
a log is triggered.
dir lib "directory"
enables you to specify the directory where netl will look in order to
find dynamic netl modules. see netl_modules (1) for more information.
by placing this strategically, you can draw modules from various
different directories, though i don't see much point in this. this is
equivalent to the --lib-dir command line option. see netl (8) for
more information on that.
dir dump "directory"
allows you to specify the directory netl will dump packets to when the
dump action rule is used. similar notations as to the dir lib rule.
equivalent to the --dump-dir command line option.
rule syntax is as follows:
action protocol if(requirement)
which can be shortened (if specified on a single line) to:
action protocol requirement
the parenthetical notation is useful for complicated, multi line
requirements. action is one of
log - send information about the datagram to syslogd (8) (by
default), or stdout (with the --foreground option). see the
syslog.conf (5) for information on redirecting syslogd output to a
specific file.
dump - save the datagram to a file. this will be a unique file in
/usr/local/lib/netl/dump.
ignore - ignore the datagram, do not process any further rules.
dl - dump and log the datagram. this is equivalent to having a log
and then a dump rule with the same requirements.
null - do nothing. this is the desired action when using a filter
module which also does its own output.
userdefined - this indicates a user defined filter module. see
netl_module (1) for more information on the netl API.
protocol is one of tcp , udp , icmp , ignp (unimplemented),
raw , ip or &userdefined . tcp, udp, icmp and ignp are sub
protocols of ip. currently only IPv4 is supported, but IPv6 is in the
works. raw indicates a raw ethernet frame. on such a packet, currently
only source and destination hardware addresses can be checked on such a
packet. a user defined protocol must be implemented as a netl module.
see the netl_module (1) man page for more information on programming
your own user defined protocol filters. the netl distribution comes with
two useful filter modules, aside from the standard protocol filters.
&gnr logs the usual useful things, but is much faster than using the
equivalent protocol filter rules. &ping logs pings and "pongs" (my
term for ECHO_REPLY, the standard reply to a ping).
there are now experimental IPv6 filters, although they have not been
tested, and may not be completely implemented. you are welcome to try
them out though. if you use the netl -6 option, then netl will use
its standard filter rules on IPv6 packets. you can also specify IPv4 and
IPv6 explicitly by adding a version number to the desired protocol. for
example, tcp becomes tcp4 for IPv4 or tcp6 for IPv6. this
interface is likely to change in the near future.
the requirement of a rule is a list of the following. you may only use a
particular requirement and its negation once, with the exception of the
flags requirement, which may be used multiple times on the same line.
not all requirements are valid for all protocols. netl will silently
ignore requirements which do not make sense for the protocol. a
requirement may be negated by putting a `!' character in front of it.
an example configuration will follow.
name= is technically not a requirement. it indicates a string by
which the packet may be identified. this identification will be used by
log when sent to syslogd (8) , or as part of the filename when dumped.
flags= [TCP only] allows you to specify that certain TCP flags be set.
each flag is separated with a comma (,) character. valid flags are syn,
fin, rst, psh, ack, urg. the special `flag' all is used to indicate that
all flags should be set.
dstport= [TCP and UDP only] specify the destination port number. for
example, httpd (web) requests are made to port 80.
srcport= [TCP and UDP only] same as dstport= , except this is for
source port numbers.
dstip= [all IP protocols] this specifies the destination IP address,
either as a dotted decimal (10.10.10.1) or as an aliased hostname (see
alias above).
an ip address may optionally be followed by a `/x' where x is the size of
the bitmask which should match the ip address. for example, 10.0.0.0/8
will match 10.*.*.* and 150.135.0.0/16 will match 150.135.*.*. this is
useful for making rules for a whole subnet.
srcip= [all IP protocols] same as dstip= , except this is for the
source IP address.
dsthw= and srchw= indicate the destination and source hardware
addresses at the beginning of the ethernet frame are to be checked. a
hardware address is specified as six two digit hexadecimal numbers
delimited by the colon (:) character. e.g. a6:f1:33:00:32:aa.
type= and code= [ICMP only] these allow you to specify the type and
code values on ICMP packets. this may either be a numeric value, or the
appropriate ICMP_ code. see the file lookup.c with the netl
distribution for specific details. the most common values are for
type=echo or type=echoreply which indicate a ping and a ping reply
respectively.
netl (8) , netl.conf (5) , netlcc (1) , netl_install (1) ,
netl_module (1) , neta (1) , hwpassive (8) , hwlookup (1) ,
dcp (1) and xd (1)
there are almost certainly bugs, please report them to me. send bugs and
bug fixes to netl@netl.org. the netl home page is at
http://www.netl.org,which should contain up to date information on
netl .
i have attempted to write pretty readable documentation, however, i'm not
really the best technically writer. if you are, maybe we could
colaborate?
Copyright 1996, 1997, 1999 Graham THE Ollis
This program is free software; you can redistribute it and/or modify it
under the terms of the GNU General Public License as published by the
Free Software Foundation; either version 2 of the License, or (at your
option) any later version.
This program is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General
Public License for more details.
You should have received a copy of the GNU General Public License along
with this program; if not, write to the Free Software Foundation, Inc.,
675 Mass Ave, Cambridge, MA 02139, USA.
Graham THE Ollis You can contact the netl team at netl@netl.org.
NAME
DESCRIPTION
INITIALIZATION RULES
ACTION RULES
EXAMPLE
# netl config file see the man page netl.conf(5)
device eth0 ethernet # only ethernet is suported
# the detect line replaces manual configeration of your netl.conf file,
# so that you can have one single netl.conf file for multiple hosts.
# here is what it does:
# 1. aliases localhost to be 127.0.0.1 (net byte order)
# 2. aliases local to be your hosts IP number (for this config file)
# 3. aliases your hostname to be your hosts IP number (for the actual logging)
detect
# note: the aliasing of your own host has been replaced with the much simpler
# detect config line. however, if there are remote aliases you want to make,
# here is where you'd want to do that.
#aliases
#alias hostname ipnumber
#alias fred.com 10.1.1.1
#here are some examples:
ignore udp if(dstport=644);
ignore udp if(srcport=644);
#log udp if(name=udp);
#pop3
dl tcp if ( name=pop3 # post office protocol version 3
dstport=110 # destination port for pop3
!srcip=local ); # don't spy on myself!
ignore tcp if(dstport=110) # from here on in, ignore pop3 stuff
#web
ignore tcp if(srcport=80) # web traffic is booooring.
#ridiculous stuff
null &ping # special code "ping" for echo and "pong" for echo reply.
log udp if(name=traceroute dstport=33434-60000) # same notation
#ignore localhost for tcp udp icmp source ip
ignore tcp srcip=local
ignore udp srcip=local
ignore icmp srcip=local
#specific services, open or not
log tcp if( name=telnet # standard 23 telnet
dstport=23 # standard telnet port
flag=syn # syn is set
!flag=all ) # everything else is not set.
log tcp name=ftp dstport=21 flag=syn !flag=all # similar notation
log tcp name=smtp dstport=25 flag=syn !flag=all # see above
#tcp stuff- this will log syn when a connection is attempted and
#fin when the connection is closed.
log tcp name=syn flag=syn !flag=all !srcip=localhost
log tcp name=fin flag=fin !srcip=localhost
# end netl config
SEE ALSO
BUGS
COPYING
AUTHOR
Contact Information
1999 CORE software international