Ubuntu Manpage: natlog - source-nat logging tool

name
synopsis
description
commands
options
rsyslog filtering
examples
files
see also
bugs
author

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-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 (-P)
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 all three protocols: TCP, UDP, and ICMP.

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:"   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 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.

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).