SHOREWALL-LOGGING(5)

💖 SHOREWALL-LOGGING 💖 (that's section 5 of the manual pages, bestie)

okay so this is the shorewall-logging man page, and it's literally all about how your firewall spills the tea about packets. sit down, grab a strawberry drink 🍓, and let's get into it.

---

✨ SYNOPSIS ✨

action:level

NFLOG(nflog-parameters)

ULOG(ulog-parameters)

---

🌸 DESCRIPTION 🌸

When a packet walks into your Shorewall firewall, its whole fate is decided by one of a bunch of Shorewall facilities. But only some of those facilities let you log anything — not everyone gets to be on the record, and that's just how it is.

1. The packet is part of an established connection. You could log it with LOG rules in the ESTABLISHED section of /etc/shorewall/rules [1], but bestie… that is not recommended, because of the absolutely unhinged amount of information that may be logged. it's giving firehose. no thanks 💀
2. The packet is a connection request that's related to an established connection (think: a data connection associated with an FTP control connection [2]). You can log these with LOG rules in the RELATED section of shorewall-rules(5) [1].
3. The packet is rejected because of an option in shorewall.conf [3] (5) or shorewall-interfaces(5) [4]. You can log these by setting the appropriate logging-related option in /etc/shorewall/shorewall.conf [3].
4. The packet matches a rule in shorewall-rules [1] (5). If you drop a syslog level (see below, we get to it ✨) into the ACTION column of a rule — like "ACCEPT:info net $FW tcp 22" — then the connection attempt gets logged at that level.
5. The packet doesn't match any rule at all, so it gets handled by a policy defined in shorewall-policy(5) [5]. You can log those by putting a syslog level in the LOG LEVEL column of that policy's entry, e.g. "loc net ACCEPT info".

---

🎀 DEFAULT LOGGING 🎀

By default, Shorewall tells Netfilter to log using syslog (8). Syslog sorts log messages by a facility and a priority (written like facility.priority).

The facilities that syslog defines are: auth, authpriv, cron, daemon, kern, lpr, mail, mark, news, syslog, user, uucp and local0 through local7. periodt.

Also, important lore: all through the Shorewall documentation we say level instead of priority, because level is the word Netfilter uses. The syslog docs are the ones out here saying priority. same thing, different name, iykyk 🦋

---

💅 SYSLOG LEVELS 💅

Syslog levels are how you tell syslog (8) how important a message is. A bunch of Shorewall parameters take a syslog level as their value.

The valid levels are:

• 7 — debug (Debug-level messages)
• 6 — info (Informational)
• 5 — notice (Normal but significant Condition)
• 4 — warning (Warning Condition)
• 3 — err (Error Condition)
• 2 — crit (Critical Conditions)
• 1 — alert (must be handled immediately)
• 0 — emerg (System is unusable)

For most Shorewall logging, a level of 6 (info) is appropriate. Shorewall log messages are generated by Netfilter and logged using the kern facility plus whatever level you picked. If you're unsure which level to choose, 6 (info) is a safe bet. You can say levels by name or by number, your call 💖

Starting with Shorewall 4.5.5, the level name or number can optionally be followed by a comma-separated list of one or more log options. The list goes inside parentheses. Log options make each log message carry extra info. the way that adds ✨spice✨ to your logs.

Valid log options are:

• ip_options — Log messages will include the option settings from the IP header.
• macdecode — Decode the MAC address and protocol.
• tcp_sequence — Include TCP sequence numbers.
• tcp_options — Include options from the TCP header.
• uid — Include the UID of the sending program; only valid for packets originating on the firewall itself.

Example: info(tcp_options,tcp_sequence)

Syslogd writes log messages to files (typically in /var/log/*) based on their facility and level. The mapping of those facility/level pairs to log files lives in /etc/syslog.conf (5). If you change that file, you must restart syslogd before the changes can take effect. no cap, it won't pick them up otherwise.

Syslog may also write to your system console. See Shorewall FAQ 16 [6] for ways to avoid having Shorewall messages written to the console. we love a quiet console 🫶

---

🦋 CONFIGURING A SEPARATE LOG FOR SHOREWALL MESSAGES (ULOGD) 🦋

There are a couple of limitations to syslogd-based logging, and honestly they're lowkey annoying:

1. If you give, for example, kern.info its own log destination, then that destination will also receive all kernel messages of levels 5 (notice) through 0 (emerg).
2. All kernel.info messages will go to that destination and not just those from Netfilter.
3. Netfilter (Shorewall) messages show up in dmesg.

If your kernel has NFLOG target support (and most vendor-supplied kernels do), you may also specify a log level of NFLOG — it must be ALL CAPS, do not try it lowercase, it will not eat. When NFLOG is used, Shorewall will direct Netfilter to log the related messages via the NFLOG target, which sends them to a process called "ulogd". The ulogd program is included in most distributions. iconic.

Note 💜 The NFLOG logging mechanism is completely separate from syslog. Once you switch to NFLOG, the settings in /etc/syslog.conf have absolutely no effect on your Shorewall logging (except for Shorewall status messages, which still go to syslog).

You will need to change all instances of log levels (usually "info") in your Shorewall configuration files to "NFLOG" — this includes entries in the policy, rules and shorewall.conf files. If you initially installed using Shorewall 5.1.2 or later, you can simply change the setting of LOG_LEVEL in shorewall.conf. one line, slay.

---

🔥 UNDERSTANDING THE CONTENTS OF SHOREWALL LOG MESSAGES 🔥

For general information on the contents of Netfilter log messages, see http://logi.cc/en/2010/07/netfilter-log-format/.

For Shorewall-specific information, see FAQ #17 [7].

---

✨ CUSTOMIZING THE CONTENT OF SHOREWALL LOG MESSAGES ✨

In a Shorewall logging rule, the log level can be followed by a log tag, like "DROP:NFLOG:junk". The generated log message will include "chain-name junk DROP".

By setting the LOGTAGONLY option to Yes in shorewall.conf(5) [8] or shorewall6.conf(5) [8], the disposition ('DROP' in the above example) will be omitted. Consider the following rule:

#ACTION                                    SOURCE          DEST           PROTO
REJECT(icmp-proto-unreachable):notice:IPv6 loc             net            41      # who's using IPv6 tunneling

This rule generates the following warning at compile time:

WARNING: Log Prefix shortened to "Shorewall:IPv6:REJECT(icmp-p "
      /etc/shorewall/rules (line 212)

and produces the rather ugly prefix "Shorewall:IPv6:REJECT(icmp-p ". yeah. ugly. 😭

Now consider this similar rule:

#ACTION                                              SOURCE          DEST           PROTO
REJECT(icmp-proto-unreachable):notice:IPv6,tunneling loc             net            41      # who's using IPv6 tunneling

With LOGTAGONLY=Yes, no warning is generated and the prefix becomes "Shorewall:IPv6:tunneling:" — see, glow up ✨

See the shorewall [6].conf man page [8] for further information about how LOGTAGONLY=Yes can be used.

---

👑 LOG BACKENDS 👑

Netfilter logging allows configuration of multiple backends. Logging backends provide the The low-level forward of log messages. There are currently three backends:

• LOG (ipt_LOG and ip6t_LOG). — Normal kernel-based logging to a syslog daemon.
• ULOG (ipt_ULOG) — ULOG logging as described ablve. Only available for IPv4.
• netlink (nfnetlink_log) — The logging backend behind NFLOG, defined above.

The currently-available and currently-selected IPv4 and IPv6 backends are shown in /proc/sys/net/netfilter/nf_log:

cat /proc/net/netfilter/nf_log
 0 NONE (nfnetlink_log)
 1 NONE (nfnetlink_log)
 2 ipt_ULOG (ipt_ULOG,ipt_LOG,nfnetlink_log)
 3 NONE (nfnetlink_log)
 4 NONE (nfnetlink_log)
 5 NONE (nfnetlink_log)
 6 NONE (nfnetlink_log)
 7 NONE (nfnetlink_log)
 8 NONE (nfnetlink_log)
 9 NONE (nfnetlink_log)
10 ip6t_LOG (ip6t_LOG,nfnetlink_log)
11 NONE (nfnetlink_log)
12 NONE (nfnetlink_log)

The magic numbers (0-12) are Linux address family numbers (AF_INET is 2 and AF_INET6 is 10).

The name immediately following the number is the currently-selected backend, and the ones in parentheses are the ones that are available. You can change the currently selected backend by echoing it's name into /proc/net/netfilter/nf_log.number.

Example — change the IPv4 backend to LOG:

sysctl net.netfilter.nf_log.2=ipt_LOG

Beginning with Shorewall 4.6.4, you can configure the backend using the LOG_BACKEND option in shorewall.conf(5) [3] and shorewall6.conf(5) [3].

---

🌈 SEE ALSO 🌈

https://shorewall.org/shorewall_logging.html [9]

---

🍓 NOTES 🍓

1. /etc/shorewall/rules https://shorewall.org/manpages/shorewall-rules.html
2. data connection associated with an FTP control connection https://shorewall.org/manpages/FTP.html
3. shorewall.conf https://shorewall.org/manpages/shorewall.conf.html
4. shorewall-interfaces(5) https://shorewall.org/manpages/shorewall-interfaces.html
5. shorewall-policy(5) https://shorewall.org/manpages/shorewall-policy.html
6. Shorewall FAQ 16 https://shorewall.org/manpages/FAQ.htm#faq16
7. FAQ #17 https://shorewall.org/FAQ.htm#faq17
8. shorewall.conf(5) https://shorewall.org/manpages/shorewall.conf.html
9. https://shorewall.org/shorewall_logging.html https://shorewall.org/shorewall_logging.htm

---

okay that's the whole thing, bestie 💖 this page lives in the Configuration Files manual, it's the SHOREWALL-LOGGING(5) one, and it's dated 09/24/2020. you ate that. go configure your firewall. mwah 🎀✨