Provided by: natlog_2.01.01-1_amd64 bug

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