imtcp: TCP Syslog Input Module¶

imtcp receives syslog messages over TCP and can use network stream drivers for TLS. It can also decompress omfwd TCP streams sent with compression.mode="stream:always".

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 external wrappers such as stunnel (an alternative is the use the imgssapi module).

imtcp can also decompress TCP streams generated by omfwd with compression.mode="stream:always". This is stream compression at the rsyslog framing layer, not TLS-native compression. Use it only where both sender and receiver are explicitly configured for the same compression driver.

Note

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

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.

Stream Decompression¶

imtcp supports stream decompression for peers that send with omfwd using compression.mode="stream:always" and a non-zero zipLevel. Configure compression.mode="stream:always" on the imtcp input and keep compression.driver identical on both sides.

The default driver is zlib. To use zstd, rsyslog must be built with libzstd support and both the omfwd sender and imtcp receiver must set compression.driver="zstd". A zstd sender cannot be received by a zlib receiver, and the reverse is also invalid.

Stream compression is most appropriate for trusted company VPNs and internal WAN/LAN links where reducing bandwidth is more important than exposing message-size patterns. Do not treat compression as a security feature. If the traffic crosses an untrusted network, use TLS for confidentiality and peer authentication, and evaluate whether compression side channels are acceptable for the data being sent. rsyslog does not provide TLS-native compression for imtcp; TLS and rsyslog stream compression are separate layers.

To limit decompression amplification, imtcp bounds the cumulative expansion ratio for the compressed stream and also limits decompressed output for each TCP receive operation. The defaults allow a 1024:1 stream expansion ratio and 64 MiB of decompressed output per receive. If either limit is exceeded, imtcp logs the stream as invalid and closes the session. Set compression.maxExpansionRatio or compression.maxDecompressedBytesPerReceive to 0 only for tightly controlled deployments that need to disable the corresponding guard.

imtcp stream decompression is for stream:always only. It does not receive the sender-side single compression mode.

Example¶

Receiver:

module(load="imtcp")

input(
    type="imtcp"
    port="6514"
    compression.mode="stream:always"
    compression.driver="zstd"
)

Sender:

action(
    type="omfwd"
    target="logs.example.com"
    port="6514"
    protocol="tcp"
    compression.mode="stream:always"
    compression.driver="zstd"
    zipLevel="3"
    queue.type="linkedList"
)

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.
compression.mode	Enables stream decompression for TCP streams sent by omfwd with `compression.mode="stream:always"`.
compression.driver	Selects the decompression driver for `imtcp` stream-compressed TCP input.
compression.maxExpansionRatio	Limits the cumulative decompressed-to-compressed byte ratio accepted for a stream.
compression.maxDecompressedBytesPerReceive	Limits decompressed bytes accepted from one compressed TCP receive operation.
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.
StreamDriver.TlsRevocationCheck	Controls whether TLS certificate revocation checking via OCSP is enabled.
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.
NetworkNamespace	Sets the value for the `networknamespace` property.

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.
compression.mode	Enables stream decompression for TCP streams sent by omfwd with `compression.mode="stream:always"`.
compression.driver	Selects the decompression driver for `imtcp` stream-compressed TCP input.
compression.maxExpansionRatio	Limits the cumulative decompressed-to-compressed byte ratio accepted for a stream.
compression.maxDecompressedBytesPerReceive	Limits decompressed bytes accepted from one compressed TCP receive operation.
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.Name	Specifies the name of the rate limiting policy to use.
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.TlsRevocationCheck	Controls whether TLS certificate revocation checking via OCSP is enabled.
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.
NetworkNamespace	Sets the value for the `networknamespace` property.

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:

Thu Feb 27 16:40:02 2025: tcpsrv/w0: origin=imtcp runs=72 read=2662 starvation_protect=1 accept=2
Thu Feb 27 16:40:02 2025: tcpsrv/w1: origin=imtcp runs=74 read=2676 starvation_protect=2 accept=0
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.

Troubleshooting¶

TLS-enabled clients connecting to a plain listener¶

If a sender negotiates TLS but the listener still uses the plain ptcp driver (streamDriver.mode="0"), imtcp inspects the first bytes it receives. When it detects a TLS ClientHello under these conditions, it emits an error similar to:

imtcp: TLS handshake detected from sender.example.com (192.0.2.10:65123) but
listener is not TLS-enabled. Enable TLS on this listener or disable TLS on
the client. See https://www.rsyslog.com/doc/faq/imtcp-tls-gibberish.html
for troubleshooting.

This message prevents binary TLS handshakes from being mistaken for syslog payloads and points directly to the fix. For detailed remediation guidance, see Why do I see gibberish when connecting with TLS?.

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.

Example 2¶

A single rsyslogd instance can accept messages from multiple network namespaces. This example sets up a TCP server on port 514 in three named namespaces, plus one in the default startup namespace. Note that these namespaces must be created before rsyslogd starts. For example, this can be done using the ExecStartPre option in a systemd service file.

module(load="imtcp" MaxSessions="500")
input(type="imtcp" port="514" NetworkNamespace="ns_eth0.0")
input(type="imtcp" port="514" NetworkNamespace="ns_eth0.1")
input(type="imtcp" port="514" NetworkNamespace="ns_eth0.2")
input(type="imtcp" port="514")

Example 3¶

This example sets a default NetworkNamespace at the module level. Multiple TCP servers are then started within that namespace. It also shows that setting NetworkNamespace to an empty string (“”) makes an input listen in the startup namespace instead. The Address parameter is used to bind listeners to specific interfaces within their namespaces. This can be combined with a PermittedPeer list to control which peers can connect to these ports.

module(load="imtcp" MaxSessions="500" NetworkNamespace="ns_eth0")
input(type="imtcp" Address="172.0.0.1" port="514")
input(type="imtcp" Address="172.0.1.1" port="514")
input(type="imtcp" Address="172.0.2.1" port="514")
input(type="imtcp" port="514" NetworkNamespace="")

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