.TH "natlog" "1" "2012\-2014" "natlog\&.1\&.01\&.0\&.tar\&.gz" "natlog" .PP .SH "NAME" natlog \- source\-nat logging tool .PP .SH "SYNOPSIS" \fBnatlog\fP [OPTIONS] \fIcommand\fP .PP .SH "DESCRIPTION" .PP Firewalls like \fBiptables\fP(1) usually offer \fIPOSTROUTING\fP (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 \fIsnat\fP the following combinations of IP addresses and port numbers are encountered: .IP o the IP address and port number used by the host behind the firewall (in this manual page referred to as \fIIPsrc, sport\fP); .IP o the IP address and port number of the host \fIIPsrc\fP connects to (in this manual page referred to as \fIIPdst, dport\fP); .IP o the IP address and port number used by the firewalling host when source natting \fIIPsrc\fP and \fIsport\fP (in this manual page referred to as \fIIPfw, fwport\fP)\&. .PP Source natting usually uses \fIsport\fP for \fIfwport\fP, but \fIfwport\fP may already be in use, in which case the firewalling host must use another, available port to forward communication from \fIIPsrc, sport\fP to \fIIPdst, dport\fP\&. .PP The general scheme that applies to source natting, therefore, looks like this: .nf IPsrc:sport is translated by the firewall to IPfw:fwport; IPfw:fwport is used when communicating with IPdst:dport\&. .fi From the perspective of the destination host the communication originates at \fIIPfw::fwport\fP and consequently all communication (e\&.g\&., and incident report) sent by the systems administrator maintaining \fIIPdst\fP to \fIIPfw\fP\(cq\&s systems administrator will refer to \fIIPfw:fwport\fP, rather than to \fIIPsrc::sport\fP\&. .PP The standard log facilities provided by \fIiptables\fP do not easily allow us to relate \fIIPfw:fwport\fP to \fIIPsrc:sport\fP, and \fInatlog\fP was developed to fill in that particular niche\&. .PP When running \fInatlog\fP, messages are sent to the syslog daemon (e\&.g\&., \fBrsyslogd\fP(1)) and/or the standard output stream showing the essential characteristics of the connection using source natting\&. Here is an example: .nf 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 .fi In this example the values \fI1338990672:55588\fP and \fI1338990747:807100\fP represent time stamps showing the begin\- and end\-times in seconds:microseconds of a TCP connection since Jan 1, 1970, 0:00 UTC\&. \fINatlog\fP offers the \fI\-\-datetime\fP option, resulting in time representations like \fINov 2 13:29:11\fP rather than time representations using seconds and micro seconds\&. .PP The next value (\fI192\&.168\&.19\&.72:4467\fP) represents \fIIPsrc::sport\fP\&. This is followed by \fI129\&.125\&.90\&.132:4467\fP, representing \fIIPfw:fwport\fP\&. The third pair of values (\fI200\&.49\&.219\&.180:443\fP) represents \fIIPdst:dport\fP\&. .PP In this example, host \fI192\&.168\&.19\&.72\fP, using port \fI4467\fP, connected to host \fI200\&.49\&.219\&.180\fP, port \fI443\fP\&. To this latter host the connection appeared to have originated from \fI129\&.125\&.90\&.132\fP port \fI4467\fP\&. The provided log message easily allows us to related this to the `real\(cq\& host and port from which the connection originated: \fI192\&.168\&.19\&.72:4467\fP\&. .PP When \fInatlog\fP terminates \fInatlog\fP can no longer track connections that are still open\&. If \fInatlog\fP was terminated by a \fISIGTERM\fP signal, then it sends a `terminating\(cq\& 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 \fI0000\fP\&. .PP .SH "COMMANDS" .PP .IP o \fIconntrack\fP: this command can only be used on platforms using \fBiptables\fP(1) on which \fBconntrack\fP(1) has also been installed\&. Information about source\-natted connections is obtained from \fBconntrack\fP(1)\(cq\&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 \fIconntrack\-command\fP option\&. .IP .IP o \fIindevice outdevice\fP: \fIindevice\fP is the name of the device behind the firewall\&. Addresses living behind the \fIindevice\fP are source\-natted to the firewall\(cq\&s IP address when passed on to the \fIoutdevice\fP; \fIoutdevice\fP 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 \fIindevice\fP are received\&. Currently, this command is only available for tracking TCP connections\&. .PP .SH "OPTIONS" .PP .IP o \fB\-\-config\fP=\fIconfig\-path\fP (\fB\-c\fP) .br The argument \fIconfig\-path\fP defines the path to the configuration file to be used by \fInatlog\fP\&. By default the configuration file is expected in \fI/etc/natlog\&.conf\fP\&. All configuration options have defaults, which are used when no configuration file and no command\-line options are provided\&. .IP All options, except for \fIconfig, help\fP and \fIverbose\fP can also be specified in the configuration file\&. The configuration file ignores empty lines and all information on lines beginning with a hash\-mark (\fI#\fP)\&. 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: .nf stdout syslog\-facility: LOCAL0 .fi Command\-line options override configuration file options\&. .IP .IP o \fB\-\-conntrack\-command\fP=\fIpath [options]\fP .br The path and options to the \fBconntrack\fP(1) program\&. By default this is \fI/usr/sbin/conntrack \-p tcp \-E \-n \-o timestamp \-e NEW,DESTROY\fP, resulting in: .br .IP \- Monitoring the TCP layer four protocol; .br \- Displaying real\-time event logs (\fI\-E\fP); .br \- Displaying time stamps (\fI\-o timestamp\fP); .br \- Logging all new and destroyed (ended) events (\fI\-e NEW,DESTROY\fP); .br .IP The protocols to monitor can separately be configured using the \fI\-\-protocol\fP option\&. .IP The \fIconntrack\fP program must be available when requesting \fInatlog\fP\(cq\&s \fIconntrack\fP command\&. Layer four protocols other than TCP, UDP and ICMP are currently not supported\&. A subset of the supported protocols may be requested using \fIconntrack\(cq\&s \-p tcp, \-p udp\fP or \fI\-p icmp\fP options\&. .IP .IP o \fB\-\-conntrack\-path\fP=\fIpath\fP .br Option discontinued: this option is replaced by \fIconntrack\-command\fP\&. When \fIconntrack\-path\fP is used, the program ends after displaying an informative message\&. .IP .IP o \fB\-\-conntrack\-restart\fP=\fImax\fP .br If the conntrack process prematurely ends it is restarted at most \fImax\fP times (these are pure \fIrestarts\fP: conntrack\(cq\&s initial startup is not counted for this option)\&. By default 10 restarts are allowed\&. .IP .IP o \fB\-\-help\fP (\fB\-h\fP) .br Write basic usage information to the standard output stream and terminate\&. .IP .IP o \fB\-\-no\-daemon\fP .br By default, \fInatlog\fP runs in the background (a daemon)\&. \fINatlog\fP runs as an ordinary program (i\&.e\&., in the foreground when the option \fIno\-daemon\fP is provided)\&. When running as a daemon, \fI\-\-stdout\fP (see below) is suppressed, and \fI\-\-verbose\fP messages (see below) are sent to the sylog daemon, unless \fI\-\-no\-syslog\fP was specified\&. .IP .IP o \fB\-\-no\-syslog\fP .br By default \fInatlog\fP writes syslog messages to the \fIDAEMON\fP facility with priority \fINOTICE\fP\&. No messages are sent to the syslog daemon when this option is specified\&. .IP .IP o \fB\-\-pid\-file\fP=\fIpath\fP (\fB\-p\fP) .br When \fInatlog\fP runs in the background, then \fIpath\fP is the name of the path of the file holding the daemon\(cq\&s process\-id\&. By default this is \fI/run/natlog\&.pid\fP\&. To end the daemon, send a SIGTERM signal to the process id mentioned in the \fIpid\-file\fP\&. \fINatlog\fP ignores \fISIGHUP\fP signals (but writes a log message if a \fISIGHUP\fP interrupt is received)\&. .IP .IP o \fB\-\-protocol\fP=\fIspecification\fP .br The protocols to monitor by \fBconntrack\fP(1)\&. By default \fIconntrack\-command\fP monitors the TCP layer four protocol\&. Currently \fInatlog\(cq\&s conntrack\fP command can monitor the TCP, UDP, and ICMP layer four protocols\&. Using the \fIprotocol\fP option (note: singular!) any subset of these protocols can be selected by specifying a colon\-separated subset of TCP, UDP, and ICMP (e\&.g\&., \fI\-\-protocol udp:tcp\fP)\&. The specification \fIall\fP can be used to monitor the TCP, UDP, and ICMP protocols\&. .IP If the \fIconntrack\-command\fP option is specified, the \fIprotocol\fP option is ignored\&. .IP .IP o \fB\-\-stdout\fP (\fB\-s\fP) .br Syslog\-equivalent messages are sent to the standard output\&. This option is implied by \fI\-\-verbose\fP, but is suppressed when \fInatlog\fP runs as a daemon\&.\&. .IP .IP o \fB\-\-syslog\-facility\fP=\fIfacility\fP .br The facility that is used to write the syslog messages to\&. By default this is \fIDAEMON\fP\&. For an overview of facilities and their meanings, see, e\&.g\&., \fBsyslog\fP(3)\&. With \fInatlog\fP the facilities \fIDAEMON, LOCAL0, LOCAL1, LOCAL2, LOCAL3, LOCAL4, LOCAL5, LOCAL6, LOCAL7\fP, and \fIUSER\fP can be used\&. .IP .IP o \fB\-\-syslog\-priority\fP=\fIpriority\fP .br The priority that is used to write the syslog messages to\&. By default this is \fINOTICE\fP\&. For an overview of priorities and their meanings, see, e\&.g\&., \fBsyslog\fP(3)\&. With \fInatlog\fP all defined priorities can be used\&. E\&.g\&., \fI EMERG, ALERT, CRIT, ERR, WARNING, NOTICE, INFO\fP and \fIDEBUG\fP\&. .IP .IP o \fB\-\-syslog\-tag\fP=\fItag\fP .br When syslog messages are generated they can be provided with a \fItag\fP, which can be used to filter \fInatlog\fP\(cq\&s syslog messages from the log\-files\&. By default the tag \fINATLOG\fP is used\&. See also section \fIRSYSLOG FILTERING\fP below\&. .IP .IP o \fB\-\-time\fP=\fIspec\fP (\fB\-t\fP) .br By default time stamps written by \fInatlog\fP are in raw, numeric form\&. E\&.g\&., .nf NATLOG: From 1338990672:55588 until 1338990747:807100 .fi 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\&. .br Specify \fIraw\fP (the default) for the default representation in seconds since the epoch; .br specify \fIutc\fP for a representation like \fIJun 6 13:29:11\fP, using Universal Time Coordinated; .br specify \fIlocal\fP for a representation like \fIJun 6 13:29:11\fP, using the local time zone defined by the computer running \fInatlog\fP\&. .IP .IP o \fB\-\-verbose\fP .br Additional messages about \fInatlog\fP\(cq\&s mode of operation are sent to the standard output stream\&. When \fInatlog\fP runs as a daemon these messages are sent to the syslog daemon, unless \fI\-\-no\-syslog\fP was specified\&. .IP .IP o \fB\-\-version\fP (\fB\-v\fP) .br Write \fInatlog\fP\(cq\&s version number to the standard output stream and terminate\&. .IP .IP o \fB\-\-warn\fP (\fB\-w\fP) .br Warn about terminating connections not yet registered in \fInatlog\fP\(cq\&s database\&. This normally only happens during a short period after starting \fInatlog\fP, when existing connections haven\(cq\&t yet been noticed\&. .PP .SH "RSYSLOG FILTERING" .PP When using \fBrsyslogd\fP(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\&., \fINATLOG\fP) use .nf :syslogtag, isequal, \(dq\&NATLOG:\(dq\& /var/log/natlog\&.log :syslogtag, isequal, \(dq\&NATLOG:\(dq\& ~ .fi Note that the colon is part of the tag, but is not specified with the \fIsyslog\-tag\fP option\&. .PP This causes all messages having the \fINATLOG:\fP tag to be written on \fI/var/log/natlog\&.log\fP after which they are discarded\&. More extensive filtering is also supported, see, e\&.g\&., \fIhttp://www\&.rsyslog\&.com/doc/rsyslog_conf_filter\&.html\fP and \fIhttp://www\&.rsyslog\&.com/doc/property_replacer\&.html\fP .PP .SH "EXAMPLES" .PP Examples of \fInatlog\fP activations: .IP o \fInatlog \-\-no\-daemon \-\-no\-syslog \-s tun0 eth0\fP .br \fINatlog\fP remains active as a foreground process, no syslog messages are written, syslog\-equivalent message are written to the standard output\&. \fINatlog\fP uses the pcap library to capture packets from the \fItun0\fP device (e\&.g\&., an \fBopenvpn\fP(1) device), which is active behind the firewall, and to capture packets from the \fIeth0\fP device, which is the device to where source\-natted packages are sent\&. .IP .IP o \fInatlog conntrack\fP .br Depending on the options specified in \fI/etc/natlog\&.conf\fP (or, if not available, \fInatlog\fP\(cq\&s default options) source\-natted connections are obtained from \fBconntrack\fP(1)\&. By default \fInatlog\fP continues as a daemon process, generating syslog messages using syslog tags \fINATLOG:\fP, and containing information about source\-natted connections\&. .PP Here is \fInatlog\fP\(cq\&s default configuration file\&. Empty lines and lines starting with hash\-marks (#) are ignored\&. Options adhere to the following syntax: .nf option value .fi Option and value are separated by white space, a colon may be appended to option names, and option values may consist of multiple words\&. .nf # This configuration file shows the default option values\&. # all options and values are case sensitive # see `man natlog\(cq\& 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\(dq\& # the protocols that are scanned with the \(cq\&conntrack\(cq\& 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\(cq\&s daemon process #pid\-file: /var/natlog\&.pid # end of the configuration file .fi .PP .SH "FILES" .IP o \fI/etc/natlog\&.conf\fP: default configuration file\&. .PP .SH "SEE ALSO" .PP \fBconntrack\fP(1), \fBiptables\fP(1), \fBrsyslogd\fP(1), \fBsyslog\fP(3) .PP .SH "BUGS" .PP The \fIconntrack\fP command currently only supports the TCP, UDP and ICMP layer four protocols\&. .PP The \fIindevice outdevice\fP command currently only supports the TCP protocol\&. .PP .SH "AUTHOR" .PP Frank B\&. Brokken (f\&.b\&.brokken@rug\&.nl)\&.