Provided by: natlog_2.03.00-1build1_amd64 
NAME
natlog - source-nat logging tool
SYNOPSIS
natlog [OPTIONS] command
DESCRIPTION
Firewalls like iptables(1) may offer POSTROUTING (source network address translation, snat) facilities
changing the source address of a host behind the firewall to the address of the host connected to the
outer world. With snat the following combinations of IP addresses and port numbers are encountered:
o the IP address and port number used by the host protected by (i.e., behind) the firewall initiates
a connection to the outer world (the source host, in this manual page referred to as IPsrc,
sport);
o the IP address and port number of the host outside (i.e., before) the firewall that IPsrc connects
to (the destination host, in this manual page referred to as IPdst, dport);
o the IP address and port number of the host where the firewall has been installed. This host
performs the source natting, and its IP-address and the port it uses when forwarding IPsrc,
sport’s requests to IPdst, dport are 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., incident reports) sent by the systems administrator maintaining
IPdst to IPfw’s systems administrator will refer to IPfw:fwport, rather than to IPsrc::sport.
Relating IPfw:fwport to IPsrc:sport is difficult when merely using the standard log facilities provided
by iptables and natlog was developed to fill in that particular niche.
Natlog provides data about source natting in various forms. The standard logging mode consists of
messages sent to the syslog daemon (cf., rsyslogd(1)) and/or to the standard output stream showing the
essential characteristics of connections using source natting. Here is an example of a logged message
(log-entries occupy single lines; the line-breaks below are to enhance readability):
NATLOG: from 1338990672:55588 thru 1338990747:807100 (UTC): tcp
192.168.19.72:4467 (via: 129.125.90.132:4467) to
to 200.49.219.180:443; sent: 802, received: 7669
The values 1338990672:55588 and 1338990747:807100 are time stamps showing the begin- and end-times in
seconds:microseconds of a tcp connection since the beginning of the epoch (Jan 1, 1970, 0:00 UTC). Natlog
offers the --time option for requesting human-readable time specifications 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 appears to have originated from 129.125.90.132 port 4467. The log message
allows us to associate this with the `real’ host and port from which the connection originated:
192.168.19.72:4467.
The final entries show the number of bytes that were sent by the source-host (IPsrc) and received from
the destination-host (IPdst).
When natlog is terminated it can no longer track connections that are still open. If natlog was
terminated (by a SIGINT or SIGTERM signal), then it logs a `terminating’ line, followed by an overview of
all (potentially) still open connections. Those connections are flagged with a trailing ’(EOP)’ (end of
program) log-element, and their end-times show natlog’s termination time. Incomplete connections show
(EXPIRED).
In addition to the standard logs the option --log-data is available. This option requires the path to a
file where information is logged in tabular form, which can easily be processed by statistical software
like R(1). When specifying this option information will be appended to an existing file. When the log
file does not yet exist it is created. The first line of the thus written log files names the columns of
the table. The column names are (all on one line):
type, srcNr, srcIP, srcPort, dstNr, dstIP, dstPort,
sent, recvd, begin, end, beginTime, endTime, status
Most column labels will be self-explanatory. Type indicates the connection type, logged as icmp, tcp, or
udp; srcNr and dstNr are the 32 bit numeric values of, respectively, the source host’s IP address and the
destination host’s IP address (decimal representations); begin and end are the times in seconds since the
beginning of the epoch, corresponding to the times displayed at, respectively, beginTime and endTime;
status indicates the status of the logged connection information: ok indicates a connection that was
normally completed; expired indicates that the connection was recognized, but was not normally completed;
eop is used for connections that were still active by the time natlog terminates. When the status equals
expired, the time entries show the times of receiving the first and last packets of that connection; when
eop, then the end and endTime entries show natlog’s termination time.
Log entries look like this (each entry occupies one line, header line and logged data lines are
right-aligned):
tcp, 101820608, 192.168.17.6, 48886,
4012145084, 188.121.36.239, 80,
430, 2266, 1517387644, 1517387644,
Jan 31 08:34:04:318340, Jan 31 08:34:04:383170, ok
MODES AND COMMANDS
o conntrack: the `conntrack’-mode. This command can only be used on platforms using iptables(1)
where conntrack(1) has also been installed. Information about source-natted connections is
obtained from conntrack(1)’s output. In this mode all, or one of the (by default) tcp, udp, and
icmp layer four protocols can be monitored.
By default conntrack does not report byte counts. To have conntrack report byte counts the command
$ echo 1 > /proc/sys/net/netfilter/nf_conntrack_acct
must have been issued before starting conntrack.
Conntrack includes the sizes of the IP headers (usually 20 bytes) in reported byte counts. Thus,
icmp packets are usually reported as having size 84, even though ping(1) reports a payload of 64
bytes. Since the actual sizes of IP headers cannot be determined from conntrack’s output, the
sizes reported when using natlog’s conntrack mode are as reported by conntrack, and are therefore
not corrected for IP header lengths. The option --conntrack-ip-header-size can be used to correct
for the (assumed) IP header sizes.
See also the conntrack-command option.
o indevice outdevice: the `devices’-mode. Here, indevice is the name of the device behind the
firewall: addresses living behind the indevice are source-natted to the firewall host’s IP address
when passed on to the outdevice;
outdevice is the name of the device where source-natted packets are forwarded to, and from where
replies for source-natted hosts living behind the indevice are received. With this command all, or
any combination of the (by default) tcp, udp, and icmp layer four protocols can be monitored.
o infile in-address in-mask outfile out-address out-mask: the `tcpdump’-mode. This command can be
used to process tcpdump(1) generated binary files, generated on the source-natting host. If a
source natting host uses interface eth1 behind the firewall and eth0 to connect to the outside
world, then the follow tcpdump commands produce the required binary files (these commands will
normally be run in the background, hence the trailing &):
tcpdump -wi eth0 /tmp/eth0 &
tcpdump -wi eth1 /tmp/eth1 &
To have natlog process these files, terminate the tcpdump commands, and transfer the files
/tmp/eth0 and /tmp/eth1 to the host where natlog has been installed. The required addresses and
masks are shown by the ifconfig(1) command. E.g.,
eth0: flags=4163<UP,BROADCAST,RUNNING,MULTICAST> mtu 1500
inet 129.125.1.123 netmask 255.255.0.0
broadcast 129.125.255.255
eth1: flags=4163<UP,BROADCAST,RUNNING,MULTICAST> mtu 1500
inet 192.168.1.1 netmask 255.255.255.0
broadcast 192.168.1255
The relevant info is shown in the lines following the interface’s name: the value following inet
is the interface’s IP address, and the value following netmask is the network’s mask.
Combining files and addresses, natlog is run as follows (all on one line):
natlog /tmp/eth0 129.125.1.123 255.255.0.0
/tmp/eth1 192.168.1.1 255.255.255.0
Instead of fully specifying the netmask, netmaks specifications like /24 are also accepted. In
that case the number following the slash indicates the number of non-zero bits of the netmask. In
practice, each value of the netmask is either 255 (8 bits are set) or 0 (0 bits are set), and so
255.255.0.0 can also be specified as /16, while 255.255.255.0 can be specified like /24.
OPTIONS
See also section SYSTEMD.
o --config=config-path (-c)
The argument config-path defines the path to natlog’s configuration file. By default it is
/etc/natlog.conf. All configuration options have defaults, which are used when no configuration
file and no command-line options were provided.
All options, except for config, help, verbose and version 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 initial hyphens should be omitted, and
option names 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);
By default tcp is monitored. Other protocols can 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-device=dev
By default conntrack monitors the information made available at the /proc/net/nf_conntrack device.
When another device is used, it can be specified using this option.
o --conntrack-ip-header-size=size
This option can be used to correct for the IP header sizes. By default, conntrack includes these
sizes in reported byte counts. By specifying this option packet sizes reported by conntrack are
reduced by size. Commonly IP headers consist of 20 bytes (so, to correct for this specify
--conntrack-ip-header-size 20).
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 --debug
Write additional info to the log file. Suppressed when --log off has been specified. Currently,
--debug writes information about memory consumption to the log file.
o --help (-h)
Write basic usage information to the standard output stream and terminate.
o --log=argument
By default natlog forwards log messages about natlog and connection information to the syslog
daemon using the DAEMON facility with priority NOTICE (see below at the syslog* options). This is
identical to specifying the argument syslog. Alternatively, specify the argument off to suppress
writing log messages. Any other argument is interpreted as a path-specification to a file to
receive the log messages: log-messages are appended to existing files. If the log file does not
yet exist it is first created.
o --log-data=path
Path specifies the pathname of the file where information about observed connections is written in
tabular form. Information is appended to existing files. If path does not yet exist it is first
created. Refer to the DESCRIPTION section for information about the format of the generated table.
Specify "" as command-line option if the configuration file specifies a log data file but you
don’t want the data to be logged in a particular run of natlog.
o --log-rotate=spec
This option is used to specify the frequency and the number of log-files that are rotated. By
default log-files are not rotated.
Specify time[mhd] or time[mhd]nFiles. A time unit specification must follow time and is m for
minutes, h for hours, and d for days. nFiles specifies the max. number of rotated files. If only
time[mhd] is specified, then nFiles is set to 1. By default (or if time or nfiles are specified
as zero) log files are not rotated.
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 syslog daemon, unless
--no-syslog was specified. When using the tcpdump-mode natlog does not run in the background. In
this case, if no-daemon is omitted a warning message is logged, and natlog continues as an
ordinary program.
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 SIGINT or
SIGTERM signal to the process id mentioned in the pid-file. Natlog ignores SIGHUP signals (but
writes a log message when receiving a SIGHUP interrupt).
o --protocol=specification (-P)
The protocol(s) to monitor. By default the tcp layer four protocol is monitored. 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 all three protocols (tcp, udp, and icmp). When using the conntrack-mode, only a
single protocol (including all) can be specified.
o -S
Use this option as first option, immediately following the program name, when starting natlog from
a systemd(1) natlog.service file. See also section SYSTEMD below.
o --stdout (-s)
Syslog-equivalent messages are sent to the standard output. This option is implied by --verbose,
but is suppressed once 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 --terminate
When natlog is running as a daemon, a separate command natlog --terminate can be issued to
terminate the daemon. This assumes that the default pid-file (/run/natlog.pid) was used or that a
non-default pid-file was specified in the default configuration file. If not, then the location of
the pid-file or the location of the non-default configuration file must also be specified. When
the daemon could be terminated 0 is returned. Otherwise, an error message is displayed and 1 is
returned,
o --time=spec (-t)
By default time stamps written by natlog are in raw, numeric form. E.g.,
NATLOG: From 1338990672:55588 thru 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 --ttl=secs[ui] (-T)
time-to-live for received connections. At most two time-to-live specifications can be provided:
for udp/icmp connections a letter u must be appended to the specified seconds. By default 60u is
used. For tcp connections a letter t must be appended to the specified seconds. By default 3000t
is used. Both time-to-live specifications may be combined: --ttl 120u1800t specifies a
time-to-live of two minutes for udp/icmp connections and a time-to-live of half an hour for tcp
connections. Time-to-live is not used in conntrack-mode.
o --verbose (-V)
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.
When --verbose is specified twice then all actual configuration parameters are shown just before
natlog starts.
When --verbose is specified more often then natlog ends after reporting the configuration
parameters.
o --version (-v)
Write natlog’s version number to the standard output stream and terminate.
SYSTEMD
An annoying characteristic of systemd(1) is that environment variables containing blanks are passed as
single arguments to the program being called by their .service files. As a consequence, it is very hard
to provide an environment variable in, e.g., /etc/default/natlog specifying natlog’s arguments: in
practice the number of arguments varies, and so even constructions like ARG1=value1, ARG2=value2, etc.
are awkward at best.
As a stopgap for this unwelcome characteristic of systemd the option -S is provided. When used it must be
specified as natlog’s first argument. Natlog will then inspect all remaining arguments, splitting
arguments containing blanks into separate arguments, which are then processed by natlog as intended. Be
aware that, to limit the complexity of the splitting-procedure, it is not full-proof: double- or
single-quote delimited string-arguments will also be split into separate arguments. Unless filenames
themselves containing blanks are passed as arguments to natlog this limitation is probably not very
serious.
As an example, here is an example of systemd’s ExecStart specification:
ExecStart=/usr/bin/natlog -S -p ${PIDFILE} ${DAEMON_ARGS}
where DAEMON_ARGS might have been specified in /etc/default/natlog as
DAEMON_ARGS=--log /tmp/natlog.log --log-data /dev/null conntrack
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:" stop
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 br0 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 br0 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:
# 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 device used by conntrack
#conntrack-device: /proc/net/nf_conntrack
# correction for the IP header size
# (standard IP header size is 20 bytes)
#conntrack-ip-header-size: 0
# max. number of conntrack restarts
#conntrack-restart: 10
# data file for tabular logs (specify path, default:
# data file is not used)
#log-data:
# flush the log-data file after writing log-data-flush lines
#log-data-flush: 32
# do not run as a daemon (by default: natlog runs as a daemon)
#no-daemon
# do not write messages handled by syslog
#no-syslog
# the path to the pid-file of natlog’s daemon process
#pid-file: /run/natlog.pid
# 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
# write messages to stdout (ignored by daemons)
#stdout
# the default syslog facility:
#syslog-facility: DAEMON
# the default syslog priority:
#syslog-priority: NOTICE
# the default syslog tag:
#syslog-tag: NATLOG
# the time specification:
#time: raw
# ttl: time to live (seconds) for udp/icmp connections
#ttl: 60
# end of the configuration file
FILES
o /etc/natlog.conf: default configuration file location;
o /etc/default/natlog: arguments for startup scripts;
o /etc/init.d/natlog: SysV startup script;
o /etc/systemd/system/natlog.service: systemd startup script (calling /etc/init.d/natlog).
SEE ALSO
conntrack(1), ifconfig(1), iptables(1), pcap-filter(7), ping(1), R(1), rsyslogd(1), syslog(3),
systemd(1), tcpdump(1)
BUGS
Natlog currently may process tcp, udp and icmp layer four protocols.
AUTHOR
Frank B. Brokken (f.b.brokken@rug.nl).