# 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.
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.
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.
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:

    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.

## 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

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