2. Your First Configuration¶

Write a minimal RainerScript configuration that logs a specific test message to its own file, test it with logger, and verify with tail -f — without changing distro-provided inputs.

2.1. Goal¶

Create your first custom rsyslog configuration in modern RainerScript syntax. You will add a tiny rule that writes only your test message into a new file, so you don’t duplicate all system logs.

Important

Most distributions already configure inputs (on Ubuntu this is often imjournal, sometimes imuxsock). Do not load input modules here. We’ll just add a safe, small rule in /etc/rsyslog.d/. For background, see Understanding the Default Configuration.

2.2. Steps¶

2.2.1. 1) Create a new config snippet¶

Create /etc/rsyslog.d/10-first.conf with this content:

# Write only messages tagged "tut02" to a custom file
if ($programname == "tut02") then {
    action(type="omfile" file="/var/log/myfirst.log")
    # no 'stop' here: allow normal distro handling to continue
}

2.2.2. Why this approach?¶

We don’t touch inputs (distro already set them up).
We filter by tag so only your test message goes to the new file, keeping it clean.
We don’t use stop so normal logging continues unchanged.

2.2.3. 2) Restart rsyslog¶

sudo systemctl restart rsyslog
systemctl status rsyslog --no-pager

2.2.4. 3) Send a test message¶

Use the logger command to generate a message with the tag tut02:

logger -t tut02 "hello from rsyslog tutorial 02"

2.2.5. 4) Verify the result¶

Check the new file:

sudo tail -f /var/log/myfirst.log

You should see your message. The system’s regular logs (e.g., /var/log/syslog on Ubuntu or /var/log/messages on RHEL-like distros) continue to work as before.

2.3. If it’s not working…¶

No file created
- Service status: systemctl status rsyslog
- Syntax check: sudo rsyslogd -N1
- Ensure the snippet path is correct: /etc/rsyslog.d/10-first.conf
File exists but no message inside
- Confirm you used the exact tag: logger -t tut02 "..."
- Verify the filter matches: it checks $programname == "tut02"
Permission denied
- Ensure rsyslog can write to /var/log/ (default root-owned is fine). For custom paths, adjust ownership/permissions (sudo chown / chmod) as needed.
Ubuntu-specific note
- Ubuntu typically uses imjournal by default. That’s fine — this rule still works. If you previously tried to load inputs manually, remove those lines and restart.

2.4. Verification checkpoint¶

By the end of this tutorial you should be able to:

Restart rsyslog without syntax errors.
Send a tagged test message with logger.
See the message in your custom file without duplicating all system logs.

2.5. See also / Next steps¶

Understanding the Default Configuration – why your distribution’s default config uses different syntax, and how to add modern snippets safely alongside it.
The Message Pipeline: Inputs → Rulesets → Actions – understand the flow: input → ruleset → action.
Existing page: Basic Configuration – neutral reference example.

Tip

🎬 Video idea (3 min): create 10-first.conf, restart rsyslog, run logger -t tut02 "…" and watch /var/log/myfirst.log update live with tail -f.

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

Contributing: Source & docs: rsyslog source project