Rsyslog configuration on Linux: selectors, imfile, and forwarding

Configure Rsyslog on Linux. Read facility and severity, write JSON with templates, tail application files with imfile, and test TCP forwarding and retries.

Best practices
Illustration of logs and observability data

A Linux host is writing authentication events to disk, yet those events never show up in the central log store. Start with a message you can recognize. Rsyslog may be accepting it locally while a selector sends it to the wrong file, or a forwarding action may be waiting on an unreachable receiver. Each stage can be checked separately.

Rsyslog takes messages from inputs, matches them against rules, and runs actions such as writing a file or forwarding to another server. How messages reach it varies by distribution and configuration. On a systemd host, check whether Rsyslog reads the journal, listens on a syslog socket, or collects the application's file before changing the output.

Read the facility and severity together

Facility describes the source category. Facilities such as authpriv, kern, and mail let the same host handle authentication, kernel, and mail events differently. Applications can use local0 through local7 for local routing conventions. Severity describes how urgent the message is.

Severity number Name Meaning
0–2 emerg, alert, crit Emergency, alert, and critical conditions
3–4 err, warning Error and warning
5–7 notice, info, debug Notice, informational, and debug messages

The selector documentation calls severity priority. In the syslog wire format, PRI combines both numbers as facility × 8 + severity. For example, local0.info has facility 16 and severity 6, so its PRI is <134>. Syslog PRI in RFC 5424

Follow a message through the rules

On many Linux installations, /etc/rsyslog.conf includes snippets under /etc/rsyslog.d/. Check the include order before you add a rule. The examples below are configuration snippets. Use paths and destinations appropriate to your host.

auth,authpriv.*            /var/log/auth.log
*.err                      /var/log/errors.log
mail.*                     -/var/log/mail.log
kern.*                     @@log-center.example.com:514

*.err includes err, crit, alert, and emerg. Use *.=err for errors alone. A leading - on a legacy file action disables synchronous writes for that action. The @@ in the last rule selects TCP, while a single @ selects UDP. Rsyslog filter conditions · Rsyslog legacy actions

When the program name matters too, use a RainerScript condition. This one writes Nginx warnings and more severe events to a dedicated file, then stops processing the message.

if ($programname == "nginx" and $syslogseverity <= 4) then {
  action(type="omfile" file="/var/log/nginx-error.log")
  stop
}

The program name is derived from the syslog tag, so check how your Nginx messages actually arrive. If you also need them forwarded, make sure the forwarding action can run before this stop. Actions that ran earlier have already handled the message.

Write one JSON object per line

A template controls the representation an action writes. The list template below escapes the hostname and message as JSON string content and terminates each object with a newline. The timestamp comes from timereported, the timestamp on the message as parsed by Rsyslog.

template(name="JsonFormat" type="list") {
  constant(value="{\"time\":\"")      property(name="timereported" dateFormat="rfc3339")
  constant(value="\",\"host\":\"")    property(name="hostname" format="json")
  constant(value="\",\"msg\":\"")     property(name="msg" format="json")
  constant(value="\"}\n")
}
action(type="omfile" file="/var/log/app.json" template="JsonFormat")

Put the file action inside the relevant filter if the output should contain only one application's events. A remote syslog receiver may expect a syslog header and specific framing, so select the forwarding template separately from the local JSON file. Rsyslog templates · Property replacer formats

Read application log files with imfile

If an application appends plain text to files, imfile can bring those lines into the same Rsyslog rules. Use a persistent working directory that the daemon can write to. If the main configuration already sets workDirectory, keep that setting and add just the module and input as needed.

global(workDirectory="/var/spool/rsyslog")
module(load="imfile")
input(type="imfile"
      File="/var/log/myapp/*.log"
      Tag="myapp:"
      Severity="info"
      Facility="local0"
      PersistStateInterval="100")

Here the input checkpoints its position every 100 lines. After a crash, lines read after the last saved checkpoint may be processed again. With rename-and-create rotation, a running Rsyslog can finish reading the old file and follow the new one. Rotation while Rsyslog is down can leave unread lines behind. Keep rotated files out of the glob and exercise your actual rotation policy, especially if it uses copy-and-truncate. imfile input

Forward over TCP and plan for receiver outages

A per-action queue lets the forwarding action buffer messages separately from other outputs. This example enables a disk-assisted queue with a disk usage limit configured through queue.maxDiskSpace and retries indefinitely. The hostname and port are placeholders for a plain TCP syslog listener.

action(type="omfwd" Target="log-center" Port="514" Protocol="tcp"
       queue.type="LinkedList" queue.filename="fwd" queue.saveOnShutdown="on"
       queue.maxDiskSpace="1g"
       action.resumeRetryCount="-1")

A disk-assisted queue normally starts in memory. queue.saveOnShutdown="on" saves queued in-memory messages to disk on orderly shutdown. An abrupt termination or exhausted queue capacity can still lose messages. Size the queue for the outage and the incoming volume you expect. Rsyslog queue concepts

UDP can lose datagrams without the sender knowing. TCP retransmits bytes and can signal connection failures, but offers no syslog message-level acknowledgment. TLS requires a receiver that supports it and matching port, framing, and certificate trust and name verification. When both endpoints support RELP and you need application-level acknowledgments, use omrelp with a RELP receiver such as imrelp. Check what the receiver persists before treating that acknowledgment as durable storage. omfwd forwarding · omrelp forwarding

Verify the message at both ends

Check the assembled configuration before reloading. Then emit a test message with a unique marker and confirm that your forwarding rule includes local0.info. In particular, an earlier stop can keep a message from reaching a later action.

sudo rsyslogd -N1
logger -t rsyslog-check -p local0.info "rsyslog-check-001"

If Guance is where you investigate incidents, DataKit can receive the existing syslog stream. Enable its Syslog integration and match the Rsyslog action to the listener's protocol and port. In the log store, search for the marker and check the parsed hostname, program, timestamp, and severity. Then repeat with the receiver briefly offline and see which messages arrive after it recovers. For a file input, also append a test marker on each side of a rotation and check for gaps or duplicates. DataKit Syslog integration

Common questions

What is the difference between Rsyslog and journald?

systemd-journald collects records into a structured journal, which you can query with journalctl. Rsyslog and syslog-ng can route messages to files and other systems. Rsyslog can read from the journal or receive forwarded messages depending on the host setup. journald configuration

Why does imfile repeat messages after a restart?

Check whether its working directory survived the restart and whether the daemon can write to it. Then check whether the file pattern also matches rotated logs. After an abrupt stop, restarting from the last saved checkpoint can replay some lines even with a persistent working directory.

What should I measure before scaling Rsyslog?

Replay representative message sizes and routing rules. Measure queue depth and drain time with the receiver available, then repeat with a planned interruption. The recovered rate needs to exceed the ongoing ingest rate if the backlog is to shrink.

Further reading

Get a tailored plan

Contact us

Join the community

Scan with WeChat
to join the community

Try Guance

Start online and pay only for what you use.

Get started

Choose a Guance plan

Code hosting