SHOREWALL-FILES(5)

🌸 NAME 🌸

files — Shorewall Configuration Files. Bestie, this is the SHOREWALL-FILES(5) page, and it's literally the master roster of every single config file Shorewall and Shorewall6 will read. Keep it bookmarked, iykyk. 💖

---

✨ SYNOPSIS ✨

/etc/shorewall[6]/*

---

💅 DESCRIPTION 💅

okay so, here's the whole cast of Shorewall[6] configuration files, one by one, no skipping, we're doing all of them:

• /etc/shorewall/shorewall.conf and /etc/shorewall6/shorewall6.conf[1] — the global settings file. all your firewall-wide parameters live here.
• /etc/shorewall[6]/params[2] — use this one to set shell variables that you'll expand in other files. it's always processed by /bin/sh, or by whatever shell you point at with SHOREWALL_SHELL in /etc/shorewall/shorewall.conf.
• /etc/shorewall[6]/zones[3] — this is how you partition the firewall's whole view of the world into zones. main character energy for real.
• /etc/shorewall[6]/policy[4] — establishes the firewall's high-level policy. the big-picture vibe.
• /etc/shorewall[6]/initdone — an optional Perl script that gets invoked by the Shorewall rules compiler once the compiler has finished its initialization.
• /etc/shorewall[6]/interfaces[5] — describes the interfaces on the firewall system.
• /etc/shorewall[6]/hosts[6] — lets you define zones in terms of individual hosts and subnetworks.
• /etc/shorewall[6]/masq[7] — tells the firewall where to use many-to-one (dynamic) Network Address Translation (a.k.a. Masquerading) and Source Network Address Translation (SNAT). superseded by /etc/shorewall[6]/snat in Shorewall 5.0.14, and not supported in Shorewall 5.1.0 and later versions.
• /etc/shorewall[6]/mangle[8] — supersedes /etc/shorewall/tcrules as of Shorewall 4.6.0. holds rules for packet marking, TTL, TPROXY, etc.
• /etc/shorewall[6]/rules[9] — defines the rules that are exceptions to the overall policies you set up in /etc/shorewall/policy.
• /etc/shorewall[6]/nat[10] — defines one-to-one NAT rules.
• /etc/shorewall6/proxyarp[11] — defines use of Proxy ARP.
• /etc/shorewall6/proxyndp[12] — defines use of Proxy NDP.
• /etc/shorewall[6]/routestopped — defines hosts accessible when Shorewall is stopped. superseded in Shorewall 4.6.8 by /etc/shorewall/stoppedrules. not supported in Shorewall 5.0.0 and later versions.
• /etc/shorewall[6]/tcrules[13] — okay so this file has a rather unfortunate name, because it's actually used to define marking of packets for later use by both traffic control/shaping and policy routing. superseded by /etc/shorewall/mangle in Shorewall 4.6.0. not supported in Shorewall 5.0.0 and later releases.
• /etc/shorewall[6]/tos[14] — defines rules for setting the TOS field in packet headers. superseded in Shorewall 4.5.1 by the TOS target in /etc/shorewall/tcrules (which file has since been superseded by /etc/shorewall/mangle). not supported in Shorewall 5.0.0 and later versions.
• /etc/shorewall[6]/tunnels[15] — defines tunnels (VPN) with end-points on the firewall system.
• /etc/shorewall[6]/blacklist[16] — deprecated in favor of /etc/shorewall/blrules. lists blacklisted IP/subnet/MAC addresses. not supported in Shorewall 5.0.0 and later releases.
• /etc/shorewall[6]/blrules — added in Shorewall 4.5.0. define blacklisting and whitelisting. supersedes /etc/shorewall/blacklist.
• /etc/shorewall[6]/init — shell commands you want executed at the beginning of a “shorewall start”, "shorewall reload" or “shorewall restart”.
• /etc/shorewall[6]/start — shell commands you want executed near the completion of a “shorewall start”, "shorewall reload" or “shorewall restart”
• /etc/shorewall[6]/started — shell commands you want executed after the completion of a “shorewall start”, "shorewall reload" or “shorewall restart”
• /etc/shorewall[6]/stop — commands you want executed at the beginning of a “shorewall stop”.
• /etc/shorewall[6]/stopped — shell commands you want executed at the completion of a “shorewall stop”.
• /etc/shorewall/ecn[17] — disable Explicit Congestion Notification (ECN - RFC 3168) to remote hosts or networks. superseded by ECN entries in /etc/shorewall/mangle in Shorewall 5.0.6.
• /etc/shorewall/accounting[18] — define IP traffic accounting rules
• /etc/shorewall[6]/actions[19] and /usr/share/shorewall[6]/action.template — allow user-defined actions. 🎀
• /etc/shorewall[6]/providers[20] — defines alternate routing tables.
• /etc/shorewall[6]/rtrules[21] — defines routing rules to be used in conjunction with the routing tables defined in /etc/shorewall/providers.
• /etc/shorewall[6]/tcdevices[22], /etc/shorewall[6]/tcclasses[23], /etc/shorewall[6]/tcfilters[24] — define complex traffic shaping.
• /etc/shorewall[6]/tcrules[13] — mark or classify traffic for traffic shaping or multiple providers. deprecated in Shorewall 4.6.0 in favor of /etc/shorewall/mangle. not supported in Shorewall 5.0.0 and later releases.
• /etc/shorewall[6]/tcinterfaces[25] and /etc/shorewall[6]/tcpri[26] — define simple traffic shaping.
• /etc/shorewall[6]/secmarks[27] — added in Shorewall 4.4.13. attach an SELinux context to selected packets.
• /etc/shorewall[6]/vardir[28] — determines the directory where Shorewall maintains its state.
• /etc/shorewall/arprules[29] — added in Shorewall 4.5.12. allows specification of arptables rules.
• /etc/shorewall/mangle[8] — added in Shorewall 4.6.0. supersedes /etc/shorewall/tcrules.
• /etc/shorewall[6]/snat[30] — directs the firewall where to use many-to-one (dynamic) Network Address Translation (a.k.a. Masquerading) and Source Network Address Translation (SNAT). superseded /etc/shorewall[6]/masq in Shorewall 5.0.14
• /usr/share/shorewall[6]/actions.std — actions defined by Shorewall.
• /usr/share/shorewall[6]/action.* — details of actions defined by Shorewall.
• /usr/share/shorewall[6]/macro.* — details of macros defined by Shorewall.
• /usr/share/shorewall[6]/modules — specifies the kernel modules to be loaded during shorewall start/restart.
• /usr/share/shorewall[6]/helpers — added in Shorewall 4.4.7. specifies the kernel modules to be loaded during shorewall start/restart when LOAD_HELPERS_ONLY=Yes in shorewall.conf.

---

🧭 CONFIG_PATH 🧭

the CONFIG_PATH option in shorewall[6].conf(5)[20] decides where the compiler goes looking for configuration files. the default setting is:

CONFIG_PATH=/etc/shorewall:/usr/share/shorewall

which means the compiler peeks in /etc/shorewall first, and if the file isn't there, it goes looking in /usr/share/shorewall. 💫

you can totally change that setting so the compiler hunts in different places. for example, if you want to put your own versions of the standard macros in /etc/shorewall/Macros, you could set:

CONFIG_PATH=/etc/shorewall:/etc/shorewall/Macros:/usr/share/shorewall

and then the compiler will use your versions instead of the standard ones. iconic, honestly.

---

💬 COMMENTS 💬

you can drop comments into configuration files by making the first non-whitespace character a pound sign (“#”). you can also slap a comment at the end of any line, again by delimiting the comment from the rest of the line with a pound sign.

Example 1. Comments in a Configuration File

# This is a comment
ACCEPT  net     $FW      tcp     www     #This is an end-of-line comment

Important ⚠️ except in shorewall.conf(5)[1] and params(5)[2], if a comment ends with a backslash ("\"), the next line will also be treated as a comment. see Line Continuation below.

---

🫧 BLANK LINES 🫧

most of the configuration files are organized into space-separated columns. so if you don't want to supply a value in a column but you do want to supply a value in a following column, just enter - to make the column appear empty. easy. 🍓

Example:

#INTERFACE         BROADCAST            OPTIONS
br0                -                    routeback

---

🦋 LINE CONTINUATION 🦋

lines may be continued using the usual backslash (“\”) followed immediately by a new line character (Enter key).

ACCEPT  net     $FW      tcp \↵
smtp,www,pop3,imap  #Services running on the firewall

Important ⚠️ what follows does NOT apply to shorewall-params(5)[31] and shorewall.conf(5)[1].

in certain cases, leading white space is ignored in continuation lines:

1. the continued line ends with a colon (":")
2. the continued line ends with a comma (",")

Example (/etc/shorewall/rules):

#ACTION     SOURCE          DEST            PROTO           DPORT
ACCEPT      net:\
            206.124.146.177,\
            206.124.146.178,\
            206.124.146.180\
                            dmz             tcp             873

the leading white space on the first through third continuation lines is ignored, so the SOURCE column effectively contains "net:206.124.146.177,206.124.147.178,206.124.146.180". and because the third continuation line does not end with a comma or colon, the leading white space in the last line is not ignored. sneaky, right? 👑

Important ⚠️ a trailing backslash is not ignored in a comment. so the continued rule above can be commented out with a single '#' like this: #ACTION SOURCE DEST PROTO DPORT #ACCEPT net:\ 206.124.146.177,\ 206.124.146.178,\ 206.124.146.180\ dmz tcp 873

---

🌈 ALTERNATIVE SPECIFICATION OF COLUMN VALUES 🌈

some of the configuration files now have a large number of columns. and that makes it super awkward to specify a value for one of the right-most columns, because you have to have the exact correct number of intervening - columns. not the vibe. 😭

this problem is addressed by allowing column values to be specified as column-name/value pairs.

and there is considerable flexibility in how you specify the pairs:

• at any point, you can enter a left curly bracket ('{') followed by one or more specifications of the following forms:

column-name=value
column-name=>value
column-name:value

the pairs must be followed by a right curly bracket ("}").

the value may optionally be enclosed in double quotes.

the pairs must be separated by white space, but you can add a comma adjacent to the values for readability as in:

{ proto=>udp, port=1024
          }

• you can also separate the pairs from columns by using a semicolon:

; proto:udp,
          port:1024

Lowkey the biggest glow-up in Shorewall 5.0.3 was a naming thing, and honestly? It ate. ✨

Back in the day the sample config files and the man pages were kind of doing their own thing with column names — like, one of them would call it one thing in the column headings and something else entirely in the alternate specification format. Not anymore bestie. In Shorewall 5.0.3, both the sample configuration files and the man pages got updated so they use the same column names in both places:

• the column headings, and
• the alternate specification format.

Same names. Same everywhere. Consistency is the vibe and we are obsessed. 🦋

The following table shows the column names for each of the table-oriented configuration files. 👑

Note

---

It's giving "one source of truth" and honestly every config file wishes it was this organised. 💅

Okay bestie, quick vibe check: column names are case-insensitive. So ACTION, Action, and action are all the same girl 💅. Periodt.

Here's the full cheat sheet of which file takes which column names — keep this open, you'll need it:

• accounting — action, chain, source, dest, proto, dport, sport, user, mark, ipsec, headers
• conntrack — action, source, dest, proto, dport, sport, user, switch
• blacklist — networks, proto, port, options
• blrules — action, source, dest, proto, dport, sport, origdest, rate, user, mark, connlimit, time, headers, switch, helper
• ecn — interface, hosts. Beginning with Shorewall 4.5.4, host is a synonym for hosts. 👑
• hosts — zone, hosts, options. Beginning with Shorewall 4.5.4, host is a synonym for hosts. 🦋
• interfaces — zone, interface, broadcast, options
• maclist — disposition, interface, mac, addresses
• mangle — action, source, dest, proto, dport, sport, user, test, length, tos, connbytes, helper, headers
• masq — interface, source, address, proto, port, ipsec, mark, user, switch
• nat — external, interface, internal, allints, local
• netmap — type, net1, interface, net2, net3, proto, dport, sport
• notrack — source, dest, proto, dport, sport, user
• policy — source, dest, policy, loglevel, limit, connlimit
• providers — table, number, mark, duplicate, interface, gateway, options, copy
• proxyarp and proxyndp — address, interface, external, haveroute, persistent
• rtrules — source, dest, provider, priority
• routes — provider, dest, gateway, device
• routestopped — interface, hosts, options, proto, dport, sport
• rules — action, source, dest, proto, dport, sport, origdest, rate, user, mark, connlimit, time, headers, switch, helper

---

Lowkey iconic that you scrolled this far, ngl. 🌈✨ Keep going bestie, there's more where that came from 💖

• secmarks — secmark,chain,source,dest,proto,dport,sport,user,mark 💖
• tcclasses — interface,mark,rate,ceil,prio,options
• tcdevices — interface,in_bandwidth,out_bandwidth,options,redirect
• tcfilters — class,source,dest,proto,dport,sport,tos,length
• tcinterfaces — interface,type,in_bandwidth,out_bandwidth
• tcpri — band,proto,port,address,interface,helper
• tcrules — mark,source,dest,proto,dport,sport,user,test,length,tos,connbytes,helper,headers. Beginning with Shorewall 4.5.3, action is a synonym for mark. (yes bestie, they're the same thing now, iconic)
• tos — source,dest,proto,dport,sport,tos,mark
• tunnels — type,zone,gateway,gateway_zone. Beginning with Shorewall 4.5.3, gateways is a synonym for gateway. Beginning with Shorewall 4.5.4, gateway_zones is a synonym for gateway_zone.
• zones — zone,type,options,in_options,out_options

---

Ok so example time, and this one's from the rules file:

#ACTION         SOURCE            DEST            PROTO   DPORT
DNAT            net               loc:10.0.0.1    tcp     80    ; mark="88"

And here's literally the same line in several equivalent formats — pick your fighter:

{ action=>DNAT, source=>net, dest=>loc:10.0.0.1, proto=>tcp, dport=>80, mark=>88 }
; action:"DNAT" source:"net"  dest:"loc:10.0.0.1" proto:"tcp" dport:"80" mark:"88"
DNAT { source=net dest=loc:10.0.0.1 proto=tcp dport=80 mark=88 }

Beginning with Shorewall 5.0.11, ip[6]table comments can be attached to individual rules using the comment keyword. 🎀

Example from the rules file:

            ACCEPT net $FW { proto=tcp, dport=22, comment="Accept \"SSH\"" }

As shown in that example, when the comment contains whitespace, it must be enclosed in double quotes and any embedded double quotes must be escaped using a backslash ("\").

---

⏰ TIME COLUMNS ⏰

Several of the files include a TIME column that lets you specify times when the rule is to be applied. The contents of this column is a list of timeelements separated by ampersands (&). (yes, ampersands, not commas — stay with me)

Each timeelement is one of the following:

• timestart=hh:mm[:ss] — Defines the starting time of day. 🌅
• timestop=hh:mm[:ss] — Defines the ending time of day. 🌙
• contiguous — Added in Shorewall 5.0.12. When timestop is smaller than the timestart value, match this as a single time period instead of distinct intervals. See the Examples below. ✨
• utc — Times are expressed in Greenwich Mean Time.
• localtz — Deprecated by the Netfilter team in favor of kerneltz. Times are expressed in Local Civil Time (default).
• kerneltz — Added in Shorewall 4.5.2. Times are expressed in Local Kernel Time (requires iptables 1.4.12 or later).
• weekdays=ddd[,ddd]... — where ddd is one of Mon, Tue, Wed, Thu, Fri, Sat or Sun
• monthdays=dd[,dd],... — where dd is an ordinal day of the month
• datestart=yyyy[-mm[-dd[Thh[:mm[:ss]]]]] — Defines the starting date and time.
• datestop=yyyy[-mm[-dd[Thh[:mm[:ss]]]]] — Defines the ending date and time.

Examples:

To match on weekends, use:

weekdays=Sat,Sun

Or, to match (once) on a national holiday block:

datestart=2016-12-24&datestop=2016-12-27

Since the stop time is actually inclusive, you would need the following stop time to not match the first second of the new day:

datestart=2016-12-24T17:00&datestop=2016-12-27T23:59:59

During Lunch Hour

The fourth Friday in the month:

weekdays=Fri&monthdays=22,23,24,25,26,27,28

Matching across days might not do what is expected. 😭

For instance,

weekdays=Mon&timestart=23:00&timestop=01:00

Will match Monday, for one hour from midnight to 1 a.m., and then again for another hour from 23:00 onwards. If this is unwanted — like, if you would like "match for two hours from Monday 23:00 onwards" — you need to also specify the contiguous option in the example above. 💅

---

🎚️ SWITCHES 🎚️

There are times when you would like to enable or disable one or more rules in the configuration without having to do a shorewall reload or shorewall restart. This may be accomplished using the SWITCH column in shorewall-rules(5) or shorewall6-rules(5). Using this column requires that your kernel and iptables include Condition Match Support and you must be running Shorewall 4.4.24 or later. 👑

See the output of shorewall show capabilities and shorewall version to determine if you can use this feature.

The SWITCH column contains the name of a switch. Each switch is initially in the off position. You can turn on the switch named switch1 by:

echo 1 > /proc/net/nf_condition/switch1

You can turn it off again by:

echo 0 > /proc/net/nf_condition/switch1

If you simply include the switch name in the SWITCH column, then the rule is enabled only when the switch is on. If you precede the switch name with ! (e.g., !switch1), then the rule is enabled only when the switch is off. Switch settings are retained over shorewall reload. 🦋

Shorewall requires that switch names:

• begin with a letter and be composed of letters, digits, underscore (_) or hyphen (-); and
• be 30 characters or less in length.

Multiple rules can be controlled by the same switch.

Example:

Forward port 80 to dmz host $BACKUP if switch primary_down is on.

#ACTION     SOURCE          DEST        PROTO       DPORT        SPORT     ORIGDEST   RATE      USER      MARK    CONNLIMIT     TIME     HEADERS    SWITCH
DNAT        net             dmz:$BACKUP tcp         80           -         -          -         -         -       -             -        -          primary_down

---

📂 FILES 📂

/etc/shorewall[6]/*

📝 NOTES 📝

okay bestie, this is the part where we list every single file that got its own lil manpage moment 💖 these are the cross-references, the little "go read this next" links. Don't skip them, they're literally the receipts 🧾

1. /etc/shorewall/shorewall.conf and /etc/shorewall6/shorewall6.conf — https://shorewall.org/manpages/shorewall.conf.html
2. /etc/shorewall[6]/params — https://shorewall.org/manpages/shorewall-params.html
3. /etc/shorewall[6]/zones — https://shorewall.org/manpages/shorewall-zones.html
4. /etc/shorewall[6]/policy — https://shorewall.org/manpages/shorewall-policy.html
5. /etc/shorewall[6]/interfaces — https://shorewall.org/manpages/shorewall-interfaces.html
6. /etc/shorewall[6]/hosts — https://shorewall.org/manpages/shorewall-hosts.html
7. /etc/shorewall[6]/masq — https://shorewall.org/manpages/shorewall-masq.html
8. /etc/shorewall[6]/mangle — https://shorewall.org/manpages/shorewall-mangle.html
9. /etc/shorewall[6]/rules — https://shorewall.org/manpages/shorewall-rules.html
10. /etc/shorewall[6]/nat — https://shorewall.org/manpages/shorewall-nat.html
11. /etc/shorewall6/proxyarp — https://shorewall.org/manpages/shorewall-proxyarp.html
12. /etc/shorewall6/proxyndp — https://shorewall.org/manpages/shorewall-proxyndp.html
13. /etc/shorewall[6]/tcrules — https://shorewall.org/manpages/shorewall-tcrules.html
14. /etc/shorewall[6]/tos — https://shorewall.org/manpages/shorewall-tos.html
15. /etc/shorewall[6]/tunnels — https://shorewall.org/manpages/shorewall-tunnels.html
16. /etc/shorewall[6]/blacklist — https://shorewall.org/manpages/shorewall-blacklist.html
17. /etc/shorewall/ecn — https://shorewall.org/manpages/shorewall-ecn.html
18. /etc/shorewall/accounting — https://shorewall.org/manpages/shorewall-accounting.html
19. /etc/shorewall[6]/actions — https://shorewall.org/manpages/shorewall-actions.html
20. /etc/shorewall[6]/providers — https://shorewall.org/manpages/???
21. /etc/shorewall[6]/rtrules — https://shorewall.org/manpages/shorewall-rtrules.html
22. /etc/shorewall[6]/tcdevices — https://shorewall.org/manpages/shorewall-tcdevices.html
23. /etc/shorewall[6]/tcclasses — https://shorewall.org/manpages/shorewall-tcclasses.html
24. /etc/shorewall[6]/tcfilters — https://shorewall.org/manpages/shorewall-tcfilters.html
25. /etc/shorewall[6]/tcinterfaces — https://shorewall.org/manpages/shorewall-tcinterfaces.html
26. /etc/shorewall[6]/tcpri — https://shorewall.org/manpages/shorewall-tcpri.html
27. /etc/shorewall[6]/secmarks — https://shorewall.org/manpages/shorewall-secmarks.html
28. /etc/shorewall[6]/vardir — https://shorewall.org/manpages/shorewall-vardir.html
29. /etc/shorewall/arprules — https://shorewall.org/manpages/shorewall-arprules.html
30. /etc/shorewall[6]/snat — https://shorewall.org/manpages/shorewall-snat.html
31. shorewall-params(5) — https://shorewall.org/manpages/shorewall-params.html
32. shorewall-rules — https://shorewall.org/manpages/shorewall-rules.html

quick heads-up, bestie: number 20 is literally showing ??? as its URL in the original. Not me being lazy, not a typo I introduced — that's just how it is. Respect the ??? 🫡✨

---

and that's a wrap on SHOREWALL-FILES(5) 🎀 this whole thing lives in the Configuration Files corner of the world, dated 09/24/2020, and it's giving "manpage that wants you to actually read it". go configure something iconic 💅👑