.TH "natlog" "1" "2012\-2022" "natlog\&.3\&.00\&.01" "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) may 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 connected to the outer world\&. 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 protected by (i\&.e\&., behind) the firewall initiates a connection to the outer world (the source host, in this manual page referred to as \fIIPsrc, sport\fP); .IP o the IP address and port number of the host outside (i\&.e\&., before) the firewall that \fIIPsrc\fP connects to (the destination host, in this manual page referred to as \fIIPdst, dport\fP); .IP 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 \fIIPsrc, sport\fP\(cq\&s requests to \fIIPdst, dport\fP are 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\&., incident reports) 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 Relating \fIIPfw:fwport\fP to \fIIPsrc:sport\fP is difficult when merely using the standard log facilities provided by \fIiptables\fP and \fInatlog\fP was developed to fill in that particular niche\&. .PP \fINatlog\fP provides data about source natting in various forms\&. The standard logging mode consists of messages sent to the syslog daemon (cf\&., \fBrsyslogd\fP(8)) 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): .nf 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 .fi The values \fI1338990672:55588\fP and \fI1338990747:807100\fP 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)\&. \fINatlog\fP offers the \fI\-\-time\fP option for requesting human\-readable time specifications 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 appears to have originated from \fI129\&.125\&.90\&.132\fP port \fI4467\fP\&. The log message allows us to associate this with the `real\(cq\& host and port from which the connection originated: \fI192\&.168\&.19\&.72:4467\fP\&. .PP The final entries show the number of bytes that were sent by the source\-host (\fIIPsrc\fP) and received from the destination\-host (\fIIPdst\fP)\&. .PP When \fInatlog\fP is terminated it can no longer track connections that are still open\&. If \fInatlog\fP was terminated (by a \fISIGINT\fP or \fISIGTERM\fP signal), then it logs a `terminating\(cq\& line, followed by an overview of all (potentially) still open connections\&. Those connections are flagged with a trailing \(cq\&(EOP)\(cq\& (end of program) log\-element, and their end\-times show \fInatlog\(cq\&s\fP termination time\&. Incomplete connections show \fI(EXPIRED)\fP\&. .PP In addition to the standard logs the option \fI\-\-log\-data\fP 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 \fBR\fP(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): .nf type, srcNr, srcIP, srcPort, dstNr, dstIP, dstPort, sent, recvd, begin, end, beginTime, endTime, status .fi Most column labels will be self\-explanatory\&. \fIType\fP indicates the connection type, logged as \fIicmp, tcp,\fP or \fIudp\fP; \fIsrcNr\fP and \fIdstNr\fP are the 32 bit numeric values of, respectively, the source host\(cq\&s IP address and the destination host\(cq\&s IP address (decimal representations); \fIbegin\fP and \fIend\fP are the times in seconds since the beginning of the epoch, corresponding to the times displayed at, respectively, \fIbeginTime\fP and \fIendTime\fP; \fIstatus\fP indicates the status of the logged connection information: \fIok\fP indicates a connection that was normally completed; \fIexpired\fP indicates that the connection was recognized, but was not normally completed; \fIeop\fP is used for connections that were still active by the time \fInatlog\fP terminates\&. When the status equals \fIexpired\fP, the time entries show the times of receiving the first and last packets of that connection; when \fIeop\fP, then the \fIend\fP and \fIendTime\fP entries show \fInatlog\(cq\&s\fP termination time\&. .PP Log entries look like this (each entry occupies one line, header line and logged data lines are right\-aligned): .nf 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 .fi .PP .SH "MODES AND COMMANDS" .PP .IP o \fIconntrack\fP: the `conntrack\(cq\&\-mode\&. This command can only be used on platforms using \fBiptables\fP(1) where \fBconntrack\fP(1) has also been installed\&. Information about snat connections is obtained from \fBconntrack\fP(1)\(cq\&s output\&. In this mode all, or one of the tcp (the protocol used by default), udp, and icmp layer four protocols can be monitored\&. .IP When using the \fIconntrack\fP mode the \fIconntrack\fP program will report sent and received number of bytes unless the option \fIno\-bytes\fP has been specified\&. .IP \fIConntrack\fP includes the sizes of the IP headers (usually 20 bytes) in reported byte counts\&. Thus, \fIicmp\fP packets are usually reported as having size 84, even though \fBping\fP(1) reports a payload of 64 bytes\&. Since the actual sizes of IP headers cannot be determined from conntrack\(cq\&s output, the sizes reported when using \fInatlog\(cq\&s\fP conntrack mode are as reported by \fIconntrack\fP, and are therefore not corrected for IP header lengths\&. The option \fI\-\-conntrack\-ip\-header\-size\fP can be used to correct for the (assumed) IP header sizes\&. .IP \fIConntrack\fP can also be used to track all connections, not just the snat connections\&. If that\(cq\&s required omit \fIconntrack\(cq\&s\fP option \fI\-n\fP, and optionally specify option \fIno\-via\fP\&. .IP See also the \fIconntrack\-command\fP option\&. .IP .IP o \fIindevice outdevice\fP: the `devices\(cq\&\-mode\&. Here, \fIindevice\fP is the name of the device behind the firewall: addresses living behind the \fIindevice\fP are source\-natted to the firewall host\(cq\&s IP address when passed on to the \fIoutdevice\fP\&. .IP \fIOutdevice\fP is the name of the device where source\-natted packets are forwarded to, and from where replies for source\-natted hosts living behind the \fIindevice\fP are received\&. With this command all, or any combination of the tcp (the protocol monitored by default), udp, and icmp layer four protocols can be monitored\&. .IP For example, when specifying the arguments .nf eth1 eth0 .fi thene \fIeth1\fP is the device behind the firewall, and \fIeth0\fP is the device to where source\-natted packets are forwared\&. .IP This command can also be used to track all connections using a single device, instead of merely tracking snat connections\&. In that case specify the same devices for \fIindevice\fP and \fIoutdevice\fP, and optionally specify option \fIno\-via\fP\&. E\&.g\&., .nf eth0 eth0 .fi .IP .IP o \fIinfile in\-address in\-mask outfile out\-address out\-mask\fP: the `tcpdump\(cq\&\-mode\&. This command can be used to process \fBtcpdump\fP(1) generated binary files, generated on the source\-natting host\&. If a source natting host uses interface \fIeth1\fP behind the firewall and \fIeth0\fP to connect to the outside world, then the follow \fItcpdump\fP commands produce the required binary files (these commands will normally be run in the background, hence the trailing \fI&\fP): .nf tcpdump \-wi eth0 /tmp/eth0 & tcpdump \-wi eth1 /tmp/eth1 & .fi To have \fInatlog\fP process these files, end the \fItcpdump\fP processes, and transfer the files \fI/tmp/eth0\fP and \fI/tmp/eth1\fP to the host where \fInatlog\fP has been installed\&. The required addresses and masks are shown by the \fBifconfig\fP(1) command\&. E\&.g\&., .nf eth0: flags=4163 mtu 1500 inet 129\&.125\&.1\&.123 netmask 255\&.255\&.0\&.0 broadcast 129\&.125\&.255\&.255 eth1: flags=4163 mtu 1500 inet 192\&.168\&.1\&.1 netmask 255\&.255\&.255\&.0 broadcast 192\&.168\&.1255 .fi The relevant info is shown in the lines following the interface\(cq\&s name: the value following \fIinet\fP is the interface\(cq\&s IP address, and the value following \fInetmask\fP is the network\(cq\&s mask\&. .IP Combining files and addresses, \fInatlog\fP is run as follows (all on one line): .nf natlog /tmp/eth0 129\&.125\&.1\&.123 255\&.255\&.0\&.0 /tmp/eth1 192\&.168\&.1\&.1 255\&.255\&.255\&.0 .fi 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\&. .PP .SH "OPTIONS" .PP See also section \fISYSTEMD\fP\&. .PP .IP o \fB\-\-config\fP=\fIconfig\-path\fP (\fB\-c\fP) .br The argument \fIconfig\-path\fP defines the path to \fInatlog\(cq\&s\fP configuration file\&. By default it is \fI/etc/natlog\&.conf\fP\&. All configuration options have defaults, which are used when no configuration file and no command\-line options were provided\&. .IP All options, except for \fIconfig, help, S, terminate, verbose\fP and \fIversion\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 initial hyphens should be omitted, and option names may immediately be followed by a colon\&. Do not surround option values with 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 .nf /usr/sbin/conntrack \-p tcp \-E \-n \-o timestamp \-e NEW,DESTROY .fi resulting in: .br .IP \- Monitoring the tcp layer four protocol; .br \- Displaying real\-time event logs (\fI\-E\fP); .br \- Only use snat connections (\fI\-n\fP); .br \- Displaying time stamps (\fI\-o timestamp\fP); .br \- Logging all new and destroyed (ended) events (\fI\-e NEW,DESTROY\fP); .br \- Reporting the number of bytes sent\- and received by connections; .br .IP By default \fItcp\fP is monitored\&. Other protocols can 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 When all connections should be logged (not just snat connections) then omit \fIconntrack\(cq\&s \-n\fP option\&. See also option \fI\-\-no\-via\fP below\&. .IP Unless option \fI\-\-no\-bytes\fP is specified the conntrack program reports the number of sent and received bytes of connections\&. Conntrack does so when the value 1 has been written to \fI/proc/sys/net/netfilter/nf_conntrack_acct\fP\&. When \fInatlog\fP starts, and \fIno\-bytes\fP has not been specified then \fInatlog\fP writes 1 to \fInf_conntrack_acct\fP\&. .IP Note: when specifying the \fIconntrack\-command\fP option in the configuration file do not sourround the command with quotes\&. .IP .IP o \fB\-\-conntrack\-device\fP=\fIdev\fP .br By default \fIconntrack\fP monitors the information made available at the \fI/proc/net/nf_conntrack\fP device\&. When another device should be used, specify it using this option\&. .IP .IP o \fB\-\-conntrack\-ip\-header\-size\fP=\fIsize\fP .br This option is used to correct for the IP header sizes\&. By default, \fIconntrack\fP includes these sizes in reported byte counts\&. By specifying this option packet sizes reported by \fIconntrack\fP are reduced by \fIsize\fP\&. Commonly IP headers consist of 20 bytes (so, to correct for this specify \fI\-\-conntrack\-ip\-header\-size 20\fP)\&. .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\-\-debug\fP .br Write additional info to the log file\&. Currently, \fI\-\-debug\fP writes information about memory consumption to the log file\&. .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\-\-log\fP=\fIargument\fP .br By default \fInatlog\fP forwards log messages about \fInatlog\fP and connection information to the syslog daemon using the \fIDAEMON\fP facility with priority \fINOTICE\fP (see below at the \fIsyslog*\fP options)\&. This is identical to specifying the argument \fIsyslog\fP\&. .IP Alternatively, specify the argument \fIoff\fP 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\&. .IP The \fIstdout\fP option is handled independently from the \fIlog\fP option: log messages will appear to the standard output stream if \fIstdout\fP and \fIlog: off\fP are both specified\&. .IP .IP o \fB\-\-log\-data\fP=\fIpath\fP .br \fIPath\fP specifies the pathname of the file where information about observed connections is written in tabular form\&. If \fIpath\fP does not yet exist it is first created\&. Refer to the \fIDESCRIPTION\fP section for information about the format of the generated table\&. Specify \fI\(dq\&\(dq\&\fP as command\-line option if the configuration file specifies a log data file, but no tabular data should be logged for that \fInatlog\fP run\&. .IP Like the standard log file (option \fI\-\-log\fP) the \fIlog\-data\fP file is not rotated if rotation is requested (cf\&. option \fIlog\-rotate\fP)\&. For statistical analyses rotated log\-data files can be concatenated (usually omitting the first (header) line of rotated log\-data files)\&. .PP .IP o \fB\-\-log\-rotate\fP=\fIspec\fP .br This option specifies the frequency and the number of log\-files that are rotated\&. By default log\-files are not rotated\&. .br To rotate log\-files use \fItime[mhd]\fP or \fItime[mhd]nFiles\fP\&. The \(cq\&time\(cq\& specification is a number, which must be followed by \fIm\fP for minutes, \fIh\fP for hours, and \fId\fP for days\&. \fInFiles\fP specifies the max\&. number of rotated files\&. If only \fItime[mhd]\fP is specified, then \fInFiles\fP is set to 1\&. By default (or if \fItime\fP or \fInfiles\fP are specified as zero (0)) log files are not rotated\&. .PP Note: when using \fBrsyslogd\fP(1) for logging (i\&.e\&., when specifying \fI\-\-log syslog\fP, see also option \fIsyslog\-facility\fP below), then it is assumed that the syslog daemon or a log\-file rotation program like \fBlogrotate\fP(8) handles the log file rotations\&. Rotating the \fIlog\-data\fP file is not affected by specifying \fI\-\-log syslog\fP\&. .PP \fINatlog\fP uses a built\-in minimum rotation interval of 30 seconds\&. .PP .IP o \fB\-\-no\-bytes\fP .br By default log\-entries show numbers of sent and received bytes\&. Specify this option to omit these statistics from log\-entries\&. .PP .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 specified)\&. When running as a daemon, \fI\-\-stdout\fP (see below) is suppressed, and \fI\-\-verbose\fP messages (see below) are sent to the syslog daemon, unless \fI\-\-no\-syslog\fP was specified\&. When using the tcpdump\-mode \fInatlog\fP does not run in the background\&. In this case, if \fIno\-daemon\fP is omitted a warning message is logged, and \fInatlog\fP continues as an ordinary program\&. .PP .IP o \fB\-\-no\-dst\fP .br Normally, when snat connections are logged the destination IP addresses and port numbers are logged as \(cq\&dst\(cq\& entries in log\-data files and as \(cq\&to\(cq\& entries in log\-files\&. If these destination items should be omitted specify \fIno\-via\fP as configuration parameter or as option\&. .PP .IP o \fB\-\-no\-via\fP .br Normally, when snat connections are logged the host handling the address translations are logged as \(cq\&via\(cq\& entries in log\-files\&. If the \(cq\&via\(cq\& entries should be omitted activate \fIno\-via\fP as configuration parameter or as option\&. .PP .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 file is \fI/run/natlog\&.pid\fP\&. To end the daemon, simply call \fInatlog \-\-terminate\fP (or send a \fISIGINT\fP or \fISIGTERM\fP signal to the process id mentioned in the \fIpid\-file\fP)\&. \fINatlog\fP uses \fISIGHUP\fP and \fISIGALRM\fP signals for explicit rotations of log\-files (see options \fI\-\-rotate\fP and \fI\-\-rotate\-data\fP below\&. .PP .IP o \fB\-\-protocol\fP=\fIspecification\fP (\fB\-P\fP) .br The protocol(s) to monitor\&. By default the tcp layer four protocol is monitored\&. Currently \fInatlog\(cq\&s conntrack\fP command can monitor the tcp, udp, and icmp layer four protocols\&. Using the \fIprotocol\fP option (note: only one \fIprotocol\fP option should be specified) 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 all three protocols (tcp, udp, and icmp)\&. .PP .IP o \fB\-\-rotate\fP .br When \fI\-\-log\fP has been used then this option forces rotating the log file independently from the interval specified by \fI\-\-log\-rotate\fP\&. \fINatlog\fP uses a built\-in minimum rotation interval of 30 seconds\&. .PP .IP o \fB\-\-rotate\-data\fP .br When \fI\-\-log\-data\fP has been used then this option forces rotating the log\-data file independently from the interval specified by \fI\-\-log\-rotate\fP\&. \fINatlog\fP uses a built\-in minimum rotation interval of 30 seconds\&. .PP .IP o \fB\-S\fP .br Use this option as first option, immediately following the program name, when starting \fInatlog\fP from a \fBsystemd\fP(1) \fInatlog\&.service\fP file\&. See also section \fBSYSTEMD\fP below\&. .PP .IP o \fB\-\-stdout\fP (\fB\-s\fP) .br Syslog\-equivalent messages are sent to the standard output\&. This option is suppressed when \fInatlog\fP runs as a daemon\&. .PP .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\&. .PP When \fIrsyslog filtering\fP is used (see that section below) then \fBrsyslogd\fP(8) uses that instead of the specified facility\&. .PP .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\&. .PP .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\&. .PP .IP o \fB\-\-terminate\fP .br When \fInatlog\fP runs as a daemon, the command \fInatlog \-\-terminate\fP can be issued to terminate the daemon\&. By default it reads the daemon\(cq\&s process ID from \fInatlog\(cq\&s\fP pid\-file (cf\&. option \fIpid\-file\fP) \fI/run/natlog\&.pid\fP)\&. If another pid\-file holds the process ID of the \fInatlog\fP program to terminate then specify the location of the pid\-file to use using a command like .nf natlog \-\-terminate \-\-pid\-file=/path/to/the/pid\-file .fi When the daemon could be terminated 0 is returned\&. Otherwise, an error message is displayed and 1 is returned\&. .PP .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 thru 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\&. .PP .IP o \fB\-\-ttl\fP=\fIsecs[ui]\fP (\fB\-T\fP) .br time\-to\-live for received connections\&. At most two time\-to\-live specifications can be provided: for udp/icmp connections a letter \fIu\fP must be appended to the specified seconds\&. By default \fI60u\fP is used\&. For tcp connections a letter \fIt\fP must be appended to the specified seconds\&. By default \fI3000t\fP is used\&. Both time\-to\-live specifications may be combined: \fI\-\-ttl 120u1800t\fP 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\&. .PP .IP o \fB\-\-verbose\fP (\fB\-V\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\&. .PP When \fI\-\-verbose\fP is specified twice then all actual configuration parameters are shown just before \fInatlog\fP starts\&. .PP When \fI\-\-verbose\fP is specified more often then \fInatlog\fP ends after reporting the configuration parameters\&. .PP .IP o \fB\-\-version\fP (\fB\-v\fP) .br Write \fInatlog\fP\(cq\&s version number to the standard output stream and terminate\&. .PP ) .PP .SH "SYSTEMD" .PP An annoying characteristic of \fBsystemd\fP(1) is that environment variables containing blanks are passed as single arguments to the program being called by their \fI\&.service\fP files\&. As a consequence, it is very hard to provide an environment variable in, e\&.g\&., \fI/etc/default/natlog\fP specifying \fInatlog\(cq\&s\fP arguments: in practice the number of arguments varies, and so even constructions like \fIARG1=value1, ARG2=value2\fP, etc\&. are awkward at best\&. .PP As a stopgap for this unwelcome characteristic of \fIsystemd\fP the option \fI\-S\fP is provided\&. When used it \fImust\fP be specified as \fInatlog\(cq\&s\fP first argument\&. \fINatlog\fP will then inspect all remaining arguments, splitting arguments containing blanks into separate arguments, which are then processed by \fInatlog\fP 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 \fInatlog\fP this limitation is probably not very serious\&. .PP As an example, here is an example of \fIsystemd\(cq\&s\fP \fIExecStart\fP specification: .nf ExecStart=/usr/bin/natlog \-S \-p ${PIDFILE} ${DAEMON_ARGS} .fi where \fIDAEMON_ARGS\fP might have been specified in \fI/etc/default/natlog\fP as .nf DAEMON_ARGS=\-\-log /tmp/natlog\&.log \-\-log\-data /dev/null conntrack .fi .PP .SH "RSYSLOG FILTERING" .PP When using \fBrsyslogd\fP(8) 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\& stop .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 br0 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 \fIbr0\fP 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: .PP .nf # This configuration file shows the default option values\&. # Options that are *not* active by default have an extra comment\-line # showing \(cq\¬ by default:\(cq\& # 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\&. # Note: do not surround the conntrack command specification with quotes #conntrack\-command: /usr/sbin/conntrack \-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 # write additional info to the log file # not by default: #debug # log messages are written to \(cq\&pathname\(cq\&; use \(cq\&log: off\(cq\& to suppress log # messages # not by default: #log: pathname # data file containing tabular logs # not by default: #log\-data: pathname # tmespec: time[mhd]nFiles \- specification for rotating log\-files # not by default: #log\-rotate: timespec # do not log the sent/received byte counts (default: counts are logged) # not by default: #no\-bytes # do not run as a daemon # not by default: #no\-daemon # do not log the destination entries # not by default: #no\-dst # do not log the via: entries # not by default: #no\-via # the path to the pid\-file of natlog\(cq\&s daemon process #pid\-file: /run/natlog\&.pid # 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) #protocol: tcp # write messages to stdout (ignored by daemons) # not by default: #stdout # the default syslog facility: #syslog\-facility: DAEMON # the default syslog priority: #syslog\-priority: NOTICE # the default syslog tag: #syslog\-tag: NATLOG # the default time specification (alternatives: utc, local): #time: raw # ttl: time to live (seconds) for udp/icmp connections #ttl: 60 # end of the configuration file .fi .PP .SH "FILES" .IP o \fI/etc/natlog\&.conf\fP: default configuration file location; .IP o \fI/etc/default/natlog\fP: arguments for startup scripts; .IP o \fI/etc/init\&.d/natlog\fP: SysV startup script; .IP o \fI/etc/systemd/system/natlog\&.service\fP: systemd startup script (calling \fI/etc/init\&.d/natlog\fP)\&. .PP .SH "SEE ALSO" .PP \fBconntrack\fP(1), \fBifconfig\fP(1), \fBiptables\fP(1), \fBlogrotate\fP(8), \fBpcap\-filter\fP(7), \fBping\fP(1), \fBR\fP(1), \fBrsyslogd\fP(8), \fBsyslog\fP(3), \fBsystemd\fP(1), \fBtcpdump\fP(1) .PP .SH "BUGS" .PP \fINatlog\fP currently can process tcp, udp and icmp layer four protocols\&. .PP .SH "AUTHOR" .PP Frank B\&. Brokken (f\&.b\&.brokken@rug\&.nl)\&. .PP