imtcp: TCP Syslog Input Module

Module Name:	imtcp
Author:	Rainer Gerhards <rgerhards@adiscon.com>

Purpose

Provides the ability to receive syslog messages via TCP. Encryption is natively provided by selecting the appropriate network stream driver and can also be provided by using stunnel (an alternative is the use the imgssapi module).

Note

Reverse DNS lookups for remote senders are cached. To control refresh intervals, see Reverse DNS caching.

Notable Features

• Statistic Counter

The imtcp module runs on all platforms but is optimized for Linux and other systems that support epoll in edge-triggered mode. While earlier versions of imtcp operated exclusively in single-threaded mode, starting with version 8.2504.0, a worker pool is used on epoll-enabled systems, significantly improving performance.

The number of worker threads can be configured to match system requirements.

Starvation Protection

A common issue in high-volume logging environments is starvation, where a few high-traffic sources overwhelm the system. Without protection, a worker may become stuck processing a single connection continuously, preventing other clients from being served.

For example, if two worker threads are available and one machine floods the system with data, only one worker remains to handle all other connections. If multiple sources send large amounts of data, all workers could become monopolized, preventing other connections from being processed.

To mitigate this, imtcp allows limiting the number of consecutive requests a worker can handle per session. Once the limit is reached, the worker temporarily stops processing that session and switches to other active connections. This ensures fair resource distribution while preventing any single sender from monopolizing rsyslog’s processing power.

Even in single-threaded mode, a high-volume sender may consume significant resources, but it will no longer block all other connections.

Configurable Behavior

• The maximum number of requests per session before switching to another connection can be adjusted.

• In epoll mode, the number of worker threads can also be configured. More workers provide better protection against single senders dominating processing.

Monitoring and Performance Insights

Statistics counters provide insights into key metrics, including starvation prevention. These counters are critical for monitoring system health, especially in high-volume datacenter deployments.

Configuration Parameters

Module Parameters

Note

Parameter names are case-insensitive; camelCase is recommended for readability.

Parameter	Summary
AddtlFrameDelimiter	Specifies an additional frame delimiter for message reception.
DisableLFDelimiter	Disables LF as a frame delimiter to allow a custom delimiter.
MaxFrameSize	Sets the maximum frame size in octet-counted mode before switching to octet stuffing.
NotifyOnConnectionOpen	Emits a message when a remote peer opens a connection.
NotifyOnConnectionClose	Emits a message when a remote peer closes a connection.
KeepAlive	Enables TCP keep-alive packets on connections.
KeepAlive.Probes	Defines how many unacknowledged probes are sent before a connection is considered dead.
KeepAlive.Time	Sets the interval between last data and first keepalive probe.
KeepAlive.Interval	Defines the interval for keep-alive packets.
FlowControl	Applies light flow control to throttle senders when queues near full.
MaxListeners	Sets the maximum number of listener ports supported.
MaxSessions	Sets the maximum number of sessions supported.
StreamDriver.Name	Selects the network stream driver for all inputs using this module.
WorkerThreads	Sets the default number of worker threads for listeners on epoll-enabled systems.
StarvationProtection.MaxReads	Limits consecutive reads per connection before switching to another session.
StreamDriver.Mode	Sets the driver mode for the selected network stream driver.
StreamDriver.AuthMode	Sets stream driver authentication mode.
StreamDriver.PermitExpiredCerts	Controls how expired certificates are handled in TLS mode.
streamDriver.checkExtendedKeyPurpose	Checks certificate extended key purpose for compatibility with rsyslog operation.
StreamDriver.PrioritizeSAN	Uses stricter SAN/CN matching for certificate validation.
StreamDriver.TlsVerifyDepth	Specifies the maximum depth allowed for certificate chain verification.
PermittedPeer	Restricts connections to listed peer identities.
DiscardTruncatedMsg	Discards data beyond the truncation point in octet-stuffing mode.
gnutlsPriorityString	Provides driver-specific TLS configuration via a priority string.
PreserveCase	Controls whether the case of fromhost is preserved.

Input Parameters

Parameter	Summary
Port	Starts a TCP server on the specified port.
ListenPortFileName	Writes the listener’s port number into the given file.
Address	Local address that the listener binds to; * uses all interfaces.
Name	Sets the value for the inputname property.
Ruleset	Binds the listener to a specific ruleset.
SupportOctetCountedFraming	Enables legacy octet-counted framing compatibility.
SocketBacklog	Sets the backlog length for pending TCP connections.
RateLimit.Interval	Sets the rate-limiting interval in seconds.
RateLimit.Burst	Defines the maximum number of messages allowed per rate-limit interval.
StreamDriver.Name	Selects the network stream driver for all inputs using this module.
StreamDriver.Mode	Sets the driver mode for the selected network stream driver.
StreamDriver.AuthMode	Sets stream driver authentication mode.
StreamDriver.PermitExpiredCerts	Controls how expired certificates are handled in TLS mode.
streamDriver.checkExtendedKeyPurpose	Checks certificate extended key purpose for compatibility with rsyslog operation.
StreamDriver.PrioritizeSAN	Uses stricter SAN/CN matching for certificate validation.
StreamDriver.TlsVerifyDepth	Specifies the maximum depth allowed for certificate chain verification.
streamDriver.CAFile	Overrides DefaultNetstreamDriverCAFile for this input.
streamDriver.CRLFile	Overrides the CRL file set via the global configuration.
streamDriver.KeyFile	Overrides DefaultNetstreamDriverKeyFile for this input.
streamDriver.CertFile	Overrides DefaultNetstreamDriverCertFile for this input.
PermittedPeer	Restricts connections to listed peer identities.
gnutlsPriorityString	Provides driver-specific TLS configuration via a priority string.
MaxSessions	Sets the maximum number of sessions supported.
MaxListeners	Sets the maximum number of listener ports supported.
FlowControl	Applies light flow control to throttle senders when queues near full.
DisableLFDelimiter	Disables LF as a frame delimiter to allow a custom delimiter.
DiscardTruncatedMsg	Discards data beyond the truncation point in octet-stuffing mode.
NotifyOnConnectionClose	Emits a message when a remote peer closes a connection.
AddtlFrameDelimiter	Specifies an additional frame delimiter for message reception.
MaxFrameSize	Sets the maximum frame size in octet-counted mode before switching to octet stuffing.
PreserveCase	Controls whether the case of fromhost is preserved.
KeepAlive	Enables TCP keep-alive packets on connections.
KeepAlive.Probes	Defines how many unacknowledged probes are sent before a connection is considered dead.
KeepAlive.Time	Sets the interval between last data and first keepalive probe.
KeepAlive.Interval	Defines the interval for keep-alive packets.

Statistic Counter

This plugin maintains statistics for each listener. The statistic is named after the given input name (or “imtcp” if none is configured), followed by the listener port in parenthesis. For example, the counter for a listener on port 514 with no set name is called “imtcp(514)”.

The following properties are maintained for each listener:

• submitted - total number of messages submitted for processing since startup

Worker Statistics Counters

When imtcp operates with multiple worker threads (workerthreads > 1), it automatically generates statistics counters to provide insight into worker activity and system health. These counters are part of the impstats module and can be used to monitor system performance, detect bottlenecks, and analyze load distribution among worker threads.

Note: These counters do not exist if workerthreads is set to 1, as imtcp runs in single-threaded mode in that case.

Statistics Counters

Each worker thread reports its statistics using the format tcpsrv/wX, where X is the worker thread number (e.g., tcpsrv/w0 for the first worker). The following counters are available:

• runs → Number of times the worker thread has been invoked.

• read → Number of read calls performed by the worker. - For TLS connections, this includes both read and write calls.

• accept → Number of times this worker has processed a new connection via accept().

• starvation_protect → Number of times a socket was placed back into the queue due to reaching the StarvationProtection.MaxReads limit.

Example Output An example of impstats output with three worker threads:

10 Thu Feb 27 16:40:02 2025: tcpsrv/w0: origin=imtcp runs=72 read=2662 starvation_protect=1 accept=2
11 Thu Feb 27 16:40:02 2025: tcpsrv/w1: origin=imtcp runs=74 read=2676 starvation_protect=2 accept=0
12 Thu Feb 27 16:40:02 2025: tcpsrv/w2: origin=imtcp runs=72 read=1610 starvation_protect=0 accept=0

In this case:

• Worker w0 was invoked 72 times, performed 2662 reads, applied starvation protection once, and accepted 2 connections.

• Worker w1 handled more reads but did not process any accept() calls.

• Worker w2 processed fewer reads and did not trigger starvation protection.

Usage and Monitoring

• These counters help analyze how load is distributed across worker threads.

• High starvation_protect values indicate that some connections are consuming too many reads, potentially impacting fairness.

• If a single worker handles most of the accept() calls, this may indicate an imbalance in connection handling.

• Regular monitoring can help optimize the workerthreads and StarvationProtection.MaxReads parameters for better system efficiency.

By using these statistics, administrators can fine-tune imtcp to ensure fair resource distribution and optimal performance in high-traffic environments.

Caveats/Known Bugs

• module always binds to all interfaces

• can not be loaded together with imgssapi (which includes the functionality of imtcp)

Examples

Example 1

This sets up a TCP server on port 514 and permits it to accept up to 500 connections:

module(load="imtcp" MaxSessions="500")
input(type="imtcp" port="514")

Note that the global parameters (here: max sessions) need to be set when the module is loaded. Otherwise, the parameters will not apply.

Additional Resources

• rsyslog video tutorial on how to store remote messages in a separate file (for legacy syntax, but you get the idea).

---

Support: rsyslog Assistant | GitHub Discussions | GitHub Issues: rsyslog source project

Contributing: Source & docs: rsyslog source project

© 2008–2025 Rainer Gerhards and others. Licensed under the Apache License 2.0.