NAME¶
natlog - source-nat logging tool
SYNOPSIS¶
natlog [OPTIONS]
command
DESCRIPTION¶
Firewalls like
iptables(1) usually offer
POSTROUTING (source
network address translation, snat) facilities changing the source address of a
host behind the firewall to the address of the host before the firewall. With
snat the following combinations of IP addresses and port numbers are
encountered:
- o
- the IP address and port number used by the host behind the firewall (in
this manual page referred to as IPsrc, sport);
- o
- the IP address and port number of the host IPsrc connects to (in
this manual page referred to as IPdst, dport);
- o
- the IP address and port number used by the firewalling host when source
natting IPsrc and sport (in this manual page referred to as
IPfw, fwport).
Source natting usually uses
sport for
fwport, but
fwport
may already be in use, in which case the firewalling host must use another,
available port to forward communication from
IPsrc, sport to
IPdst, dport.
The general scheme that applies to source natting, therefore, looks like this:
IPsrc:sport is translated by the firewall to IPfw:fwport;
IPfw:fwport is used when communicating with IPdst:dport.
From the perspective of the destination host the communication originates at
IPfw::fwport and consequently all communication (e.g., and incident
report) sent by the systems administrator maintaining
IPdst to
IPfw’s systems administrator will refer to
IPfw:fwport,
rather than to
IPsrc::sport.
The standard log facilities provided by
iptables do not easily allow us
to relate
IPfw:fwport to
IPsrc:sport, and
natlog was
developed to fill in that particular niche.
When running
natlog, messages are sent to the syslog daemon (e.g.,
rsyslogd(1)) and/or the standard output stream showing the essential
characteristics of the connection using source natting. Here is an example:
NATLOG: (TCP) From 1338990672:55588 until 1338990747:807100:
192.168.19.72:4467 (via: 129.125.90.132:4467) to 200.49.219.180:443
In this example the values
1338990672:55588 and
1338990747:807100
represent time stamps showing the begin- and end-times in seconds:microseconds
of a TCP connection since Jan 1, 1970, 0:00 UTC.
Natlog offers the
--datetime option, resulting in time representations like
Nov 2
13:29:11 rather than time representations using seconds and micro
seconds.
The next value (
192.168.19.72:4467) represents
IPsrc::sport. This
is followed by
129.125.90.132:4467, representing
IPfw:fwport.
The third pair of values (
200.49.219.180:443) represents
IPdst:dport.
In this example, host
192.168.19.72, using port
4467, connected to
host
200.49.219.180, port
443. To this latter host the
connection appeared to have originated from
129.125.90.132 port
4467. The provided log message easily allows us to related this to the
`real’ host and port from which the connection originated:
192.168.19.72:4467.
When
natlog terminates
natlog can no longer track connections that
are still open. If
natlog was terminated by a
SIGTERM signal,
then it sends a `terminating’ line to syslog, followed by an overview
of all still open connections. The end-microseconds values of connections that
are no longer tracked are shown as
0000.
COMMANDS¶
- o
- conntrack: this command can only be used on platforms using
iptables(1) on which conntrack(1) has also been installed.
Information about source-natted connections is obtained from
conntrack(1)’s output. With this command the TCP, UDP, and
ICMP layer four protocols can be monitored (by default the TCP protocol is
monitored). See also the conntrack-command option.
- o
- indevice outdevice: indevice is the name of the device
behind the firewall. Addresses living behind the indevice are
source-natted to the firewall’s IP address when passed on to the
outdevice; outdevice is the name of the device to which
source-natted packets are forwarded, c.q. from where replies for
source-natted hosts living behind the indevice are received.
Currently, this command is only available for tracking TCP connections.
OPTIONS¶
- o
- --config=config-path (-c)
The argument config-path defines the path to the configuration file
to be used by natlog. By default the configuration file is expected
in /etc/natlog.conf. All configuration options have defaults, which
are used when no configuration file and no command-line options are
provided.
- All options, except for config, help and verbose can also be
specified in the configuration file. The configuration file ignores empty
lines and all information on lines beginning with a hash-mark ( #).
In the configuration file option names do not use initial hyphens, and may
immediately be followed by a colon. Multi-word arguments should not be
surrounded by quotes. Examples:
stdout
syslog-facility: LOCAL0
Command-line options override configuration file options.
- o
- --conntrack-command=path [options]
The path and options to the conntrack(1) program. By default this is
/usr/sbin/conntrack -p tcp -E -n -o timestamp -e NEW,DESTROY,
resulting in:
- - Monitoring the TCP layer four protocol;
- Displaying real-time event logs ( -E);
- Displaying time stamps ( -o timestamp);
- Logging all new and destroyed (ended) events ( -e
NEW,DESTROY);
- The protocols to monitor can separately be configured using the
--protocol option.
- The conntrack program must be available when requesting
natlog’s conntrack command. Layer four protocols
other than TCP, UDP and ICMP are currently not supported. A subset of the
supported protocols may be requested using conntrack’s -p tcp,
-p udp or -p icmp options.
- o
- --conntrack-path=path
Option discontinued: this option is replaced by conntrack-command.
When conntrack-path is used, the program ends after displaying an
informative message.
- o
- --conntrack-restart=max
If the conntrack process prematurely ends it is restarted at most max
times (these are pure restarts: conntrack’s initial startup
is not counted for this option). By default 10 restarts are allowed.
- o
- --help (-h)
Write basic usage information to the standard output stream and
terminate.
- o
- --no-daemon
By default, natlog runs in the background (a daemon). Natlog
runs as an ordinary program (i.e., in the foreground when the option
no-daemon is provided). When running as a daemon, --stdout
(see below) is suppressed, and --verbose messages (see below) are
sent to the sylog daemon, unless --no-syslog was specified.
- o
- --no-syslog
By default natlog writes syslog messages to the DAEMON
facility with priority NOTICE. No messages are sent to the syslog
daemon when this option is specified.
- o
- --pid-file=path (-p)
When natlog runs in the background, then path is the name of
the path of the file holding the daemon’s process-id. By default
this is /run/natlog.pid. To end the daemon, send a SIGTERM signal
to the process id mentioned in the pid-file. Natlog ignores
SIGHUP signals (but writes a log message if a SIGHUP
interrupt is received).
- o
- --protocol=specification
The protocols to monitor by conntrack(1). By default
conntrack-command monitors the TCP layer four protocol. Currently
natlog’s conntrack command can monitor the TCP, UDP, and
ICMP layer four protocols. Using the protocol option (note:
singular!) any subset of these protocols can be selected by specifying a
colon-separated subset of TCP, UDP, and ICMP (e.g., --protocol
udp:tcp). The specification all can be used to monitor the
TCP, UDP, and ICMP protocols.
- If the conntrack-command option is specified, the protocol
option is ignored.
- o
- --stdout (-s)
Syslog-equivalent messages are sent to the standard output. This option is
implied by --verbose, but is suppressed when natlog runs as
a daemon..
- o
- --syslog-facility=facility
The facility that is used to write the syslog messages to. By default this
is DAEMON. For an overview of facilities and their meanings, see,
e.g., syslog(3). With natlog the facilities DAEMON,
LOCAL0, LOCAL1, LOCAL2, LOCAL3, LOCAL4, LOCAL5, LOCAL6, LOCAL7, and
USER can be used.
- o
- --syslog-priority=priority
The priority that is used to write the syslog messages to. By default this
is NOTICE. For an overview of priorities and their meanings, see,
e.g., syslog(3). With natlog all defined priorities can be
used. E.g., EMERG, ALERT, CRIT, ERR, WARNING, NOTICE, INFO and
DEBUG.
- o
- --syslog-tag=tag
When syslog messages are generated they can be provided with a tag,
which can be used to filter natlog’s syslog messages from
the log-files. By default the tag NATLOG is used. See also section
RSYSLOG FILTERING below.
- o
- --time=spec (-t)
By default time stamps written by natlog are in raw, numeric form.
E.g.,
NATLOG: From 1338990672:55588 until 1338990747:807100
These time stamps indicate times in seconds:microseconds since the beginning
of the epoch, January 1, 1970, 0:00 UTC. This option can be used to change
the seconds part of the time stamps to more conventional representations.
Specify raw (the default) for the default representation in seconds
since the epoch;
specify utc for a representation like Jun 6 13:29:11, using
Universal Time Coordinated;
specify local for a representation like Jun 6 13:29:11, using
the local time zone defined by the computer running natlog.
- o
- --verbose
Additional messages about natlog’s mode of operation are sent
to the standard output stream. When natlog runs as a daemon these
messages are sent to the syslog daemon, unless --no-syslog was
specified.
- o
- --version (-v)
Write natlog’s version number to the standard output stream
and terminate.
- o
- --warn (-w)
Warn about terminating connections not yet registered in
natlog’s database. This normally only happens during a short
period after starting natlog, when existing connections
haven’t yet been noticed.
RSYSLOG FILTERING¶
When using
rsyslogd(1) property based filters may be used to filter
syslog messages and write them to a file of your choice. E.g., to filter
messages starting with the syslog message tag (e.g.,
NATLOG) use
:syslogtag, isequal, "NATLOG:" /var/log/natlog.log
:syslogtag, isequal, "NATLOG:" ~
Note that the colon is part of the tag, but is not specified with the
syslog-tag option.
This causes all messages having the
NATLOG: tag to be written on
/var/log/natlog.log after which they are discarded. More extensive
filtering is also supported, see, e.g.,
http://www.rsyslog.com/doc/rsyslog_conf_filter.html and
http://www.rsyslog.com/doc/property_replacer.html
EXAMPLES¶
Examples of
natlog activations:
- o
- natlog --no-daemon --no-syslog -s tun0 eth0
Natlog remains active as a foreground process, no syslog messages
are written, syslog-equivalent message are written to the standard output.
Natlog uses the pcap library to capture packets from the
tun0 device (e.g., an openvpn(1) device), which is active
behind the firewall, and to capture packets from the eth0 device,
which is the device to where source-natted packages are sent.
- o
- natlog conntrack
Depending on the options specified in /etc/natlog.conf (or, if not
available, natlog’s default options) source-natted
connections are obtained from conntrack(1). By default
natlog continues as a daemon process, generating syslog messages
using syslog tags NATLOG:, and containing information about
source-natted connections.
Here is
natlog’s default configuration file. Empty lines and lines
starting with hash-marks (#) are ignored. Options adhere to the following
syntax:
option value
Option and value are separated by white space, a colon may be appended to option
names, and option values may consist of multiple words.
# This configuration file shows the default option values.
# all options and values are case sensitive
# see `man natlog’ for further details
# the path and options of the conntrack program:
# when no filtering options are specified, the tcp
# protocol is monitored
# the default command is shown:
#conntrack-command: /usr/sbin/conntrack -p tcp -E -n -o timestamp -e NEW,DESTROY"
# the protocols that are scanned with the ’conntrack’ command:
# protocol: all - monitors tcp, udp, icmp
# protocol: udp:tcp - monitors upd and tcp (any non-empty subset,
# possibly including icmp is OK)
# ignored when conntrack-command is specified
#protocol: tcp
# the default syslog tag:
#syslog-tag: NATLOG
# the default syslog facility:
#syslog-facility: DAEMON
# the default syslog priority:
#syslog-priority: NOTICE
# the time specification:
#time: raw
# the path to the pid-file of natlog’s daemon process
#pid-file: /var/natlog.pid
# end of the configuration file
FILES¶
- o
- /etc/natlog.conf: default configuration file.
SEE ALSO¶
conntrack(1),
iptables(1),
rsyslogd(1),
syslog(3)
BUGS¶
The
conntrack command currently only supports the TCP, UDP and ICMP layer
four protocols.
The
indevice outdevice command currently only supports the TCP protocol.
AUTHOR¶
Frank B. Brokken (f.b.brokken@rug.nl).