Provided by: natlog_1.00.2-1_amd64 
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.
Using 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: 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 the connection since Jan 1,
1970, 0:00 UTC. Natlog offers the --datetime option if time representations like Nov 2
13:29:11 are preferred.
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.
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
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. Command-line options override configuration
file options.
o --conntrack-path=path
The path to the conntrack(1) program. By default this is /usr/sbin/conntrack. The
conntrack program must be available when requesting natlog’s conntrack command.
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 --help (-h)
Write basic usage information to the standard output stream and terminate.
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 /var/run/natlog.pid.
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-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 --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 --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
option value
syntax. Option and value are separated by white space, Option values may consist of
multiple words.
# This configuration file shows the default option values.
# Each option could also be omitted without affecting natlog’s default
# behavior.
# all options and values are case sensitive
# see `man natlog’ for further details
# the path to the conntrack program:
conntrack-path /usr/sbin/conntrack
# the used syslog tag:
syslog-tag NATLOG
# the used syslog facility:
syslog-facility DAEMON
# the used syslog priority:
syslog-priority NOTICE
# the time specification:
time raw
# end of the cofiguration file
FILES
o /etc/natlog.conf: default configuration file.
SEE ALSO
conntrack(1), iptables(1), rsyslogd(1), syslog(3)
BUGS
None reported
AUTHOR
Frank B. Brokken (f.b.brokken@rug.nl).