--- name: "ippl.conf" section: "5" platform: "linux" package: "ippl" version: "1.4.14-13" release: "Debian 12 (Bookworm)" platforms: ["linux"] url: "https://new.carta.tech/ippl.conf" --- # ippl.conf(5) IP Protocols Logger configuration file ## NAME ippl.conf - IP Protocols Logger configuration file ## DESCRIPTION The *ippl.conf* file is the only configuration file for the **ippl** logger. It defines what protocols to log, and the kind of packets to log. A hash mark (\`\`#'') indicates that the end of the line is a comment and it will therefore not be read. ## USER RUNNING THREADS **ippl** does not run (unless specified) the protocol logging threads as root for security reasons. You can specify which user should be use with the *runas* keyword. **Syntax:** runas \[user\] *user* is a user defined in /etc/passwd. By default, the nobody user is used. ## PROTOCOLS Each protocol is run by an different thread. To run a thread, use the: **Syntax:** run \[protocol\] \[protocol\] ... *protocol* can be: *icmp* to specify that the thread logging ICMP messages should be run. *tcp* to specify that the thread logging TCP connections should be run. *udp* to specify that the thread logging UDP datagrams should be run. *all* to log all the protocols. ## ADDRESS RESOLUTION You can enable or disable IP address resolution on a protocol basis. To enable address resolution, use: **Syntax:** resolve \[protocol\] \[protocol\] ... *protocol* is the same as in the protocols section. To disable address resolution, use: **Syntax:** noresolve \[protocol\] \[protocol\] ... *protocol* is the same as before. By default, IP address resolution is disabled for all the protocols. Ippl by default resolves tcp/udp port numbers to their respective service names. If you pass a protocol to the noportresolve option, ippl logs the port number instead. This is a Debian specific extension. By default service resolving is enabled, since this is the behaviour of the upstream program. ## LOGGING FORMAT **ippl** can log IP protocols in a more or less detailed format. By default, it only shows the source address and the type or the destination port. A more detailed version can be used. There is also a shortest version. **Syntax:** logformat \[format\] \[protocol\] \[protocol\] ... *format* can be: *short* to use a short format for logging. *normal* to use the normal format. This is the default. *detailed* to log more information. This option displays the source and destination ports and addresses. *protocol* is the same as in the protocols section. ## IDENT MECHANISM To enable the IDENT remote username resolution, use the *ident* keyword. To disable it, use the *noident* keyword. Note that the information returned is \*NOT\* reliable in general since it is returned by the remote host. By default, the ident resolution is off. ## TCP CONNECTION TERMINATION **ippl** can detect when a TCP connection is closed. To enable this feature, use the *logclosing* keyword. To disable it, use the *nologclosing* keyword. By default, TCP connection terminations are ignored. ## LOGGING MECHANISM **ippl** can log messages using syslog (using the LOG\_DAEMON facility) or it can write directly into a file. This is specified using *log-in* keyword. **Syntax:** log-in \[protocol\] \[filename\] *protocol* is the same as in the protocols section. *filename* is an absolute path to a file. Note that the file cannot be in the root directory; it has to be in a directory. NOTE: when the logs are rotated, **ippl** opens new files when it is sent the SIGHUP signal. ## RULES When a thread is run, it will catch all the packets using the protocol logged. The user may want to ignore certain packets. This is done with Apache-like rules. There are two different types of rules. The first one describes what packets to log, and the second one describes the packets that should be ignored. The syntax of a rule is as follows: **Syntax:** \[log\|ignore\] {option \[option\],\[option\],...} \[protocol\] \[description\] *log* means that the packets described should be logged and *ignore* is used if the user does not want to log a certain type of packets. ### Option The *option* keyword will permit to override the default values for this rule only. *options* is also recognized. Valid options are: *resolve* enable IP address resolution. *noresolve* disable IP address resolution. *portresolve* enable IP service resolution. *noportresolve* disable IP service resolution. *ident* use ident logging (only for TCP). *noident* disable ident logging (only for TCP). *logclosing* log connection termination (only for TCP). *nologclosing* do not log connection termination (only for TCP). *short* use the short logging format. *normal* use the normal logging format. *detailed* use the detailed logging format. ### Protocol protocol is one of the supported protocols (see the protocols section), except the *all* keyword, which is not supported. ### Description *description* holds the type of packet and the hosts to which the rule applies. *Type of packet:* type \ Specify an ICMP message type.\ port \ Specify a destination TCP or UDP port number.\ port \ Specify a destination TCP or UDP port name.\ srcport \ Specify a source TCP or UDP port number.\ srcport \ Specify a source TCP or UDP port name. number is specified like this:\ n Number n.\ n-- Every number m \>= n.\ \--n Every number m \<= n.\ l--k Every number m, with l \<= m \<= k.\ string If a string is specified, it is\ either the name of a service\ (see /etc/services) or an\ ICMP message.\ Keywords for ICMP messages are:\ echo\_reply 0\ dest\_unreach 3\ src\_quench 4\ redirect 5\ echo\_req 8\ router\_advert 9\ router\_solicit 10\ time\_exceeded 11\ param\_problem 12\ ts\_req 13\ ts\_reply 14\ info\_req 15\ info\_reply 16\ addr\_mask\_req 17\ addr\_mask\_reply 18 *Source of the packets:* from \ where host is specifed as follows:\ x.x.x.x IP address of a host\ x.x.x.x/x.x.x.x IP address, followed by a network mask to specify a subnet\ x.x.x.x/n IP address, followed by the number of 1's at the left side of the network mask\ host.net.domain host name (wildcards accepted) *Destination of the packets:* to \ where host is specified as follows:\ x.x.x.x IP address of the local interface\ host.net.domain host name of the local interface (\*no\* wildcards accepted) This rule is useful only if you have multiple interfaces connected to your box, or if you use IP aliasing. This can also be useful if you want to log or ignore broadcasts. To do so, just use your broadcast address as destination IP address. Please note that rules using IP addresses are faster to check than rules using host names. If you log UDP, it is \*strongly\* recommended to ignore the broadcasts! (until we implement an option for that). ## EXPIRATION OF DNS CACHE The time for which **ippl** holds cached DNS data without performing any queries can be changed. **Syntax:** expire \ defines how often the DNS data expires. *time* is specified in seconds (default is 3600). ## FILES /etc/ippl.conf - configuration file\ /usr/share/doc/ippl/\* - files worth reading if you still have a question ## SEE ALSO [ippl(8)](/ippl/8.md) ## AUTHORS Hugo Haas (hugo@larve.net) Etienne Bernard (eb@via.ecp.fr)