SHOREWALL-SNAT(5)

💖 SHOREWALL-SNAT 💖

okay bestie, gather round, because we're about to talk about snat — that's the Shorewall SNAT/Masquerade definition file, and yes she's a manual page, and yes she's long, and yes we're doing all of her. this is part one. hydrate. 🧚

---

✨ NAME ✨

snat — the Shorewall SNAT/Masquerade definition file. that's her. that's the whole name. short, iconic, does exactly what it says on the tin. 👑

---

✨ SYNOPSIS ✨

like. that's the path. she lives there. `shorewall` or `shorewall6` depending on which flavor of internet you're doing. 🦋

---

# ✨ DESCRIPTION ✨

so this file is where you define <purple>**dynamic NAT**</purple> (aka Masquerading) *and* where you define <purple>**Source NAT**</purple> (SNAT). she's been carrying this whole operation. and fun fact: this file **superseded** `shorewall-masq`(5) back in Shorewall <yellow>**5.0.14**</yellow>. rip to a real one but she's replaced now. 💅

> ⚠️ **WARNING, and I need you to actually read this one bestie:** the entries in this file are <red>**order-sensitive**</red>. the *first* entry that matches a particular connection is the one that gets used. first match wins. that's it. that's the rule. no takebacks. 😭

> ⚠️ **SECOND WARNING, also important:** if you have more than one ISP link, just adding entries to this file will **not** force connections to go out through a particular link. it will not. it cannot. stop trying. you have to use entries in `shorewall-rtrules`(5) or `PREROUTING` entries in `shorewall-mangle`(5) to actually make that happen. 🫶

Beginning with Shorewall <yellow>**5.2.6**</yellow>, the `snat` file supports <hotpink>**two different formats**</hotpink>:

1. The `SPORT` (source port) column is **omitted**. this is the default unless a `"?FORMAT 2"` compiler directive is included.
2. The `SPORT` column **immediately follows** the `DPORT` column.

The columns in the file are as follows. buckle up. 🌸

---

## 🌈 ACTION 🌈

Defines the type of rule to generate. Beginning with Shorewall <yellow>**5.1.9**</yellow>, with the exception of `NFLOG` and `ULOG`, the action may be followed by a colon (`":"`) and a log level — see `shorewall-logging`(5). 💅

Choices for `ACTION` are:

- **`action[+][(parameter,...)][:level]`** — where *action* is an action declared in `shorewall-actions`(5) with the `nat` option. See `https://shorewall.org/Actions.html` for further information.
- **`CONTINUE[+]:level`** — causes matching packets to be <mint>**exempted**</mint> from any following rules in the file. she's out. she said no further. ✋
- **`LOG:level`** — added in Shorewall <yellow>**5.1.9**</yellow>. simply log the packet and continue with the next rule. noted. logged. moving on. 📝
- **`MASQUERADE[+][([lowport[-highport]][random])][:level]`** — causes matching outgoing packages to have their source IP address set to the **primary IP address** of the interface specified in the `DEST` column. if `lowport-highport` is given, that port range will be used to assign a source port. if only `lowport` is given, that port will be assigned, if possible. if option `random` is used then port mapping will be randomized. 🌈
  > `MASQUERADE` should **only** be used when the `DEST` interface has a **dynamic IP address**. otherwise, `SNAT` should be used and should specify the interface's static address. don't do the wrong one bestie, I'm begging. 🙏
- **`NFLOG[(nflog-parameters)]`** — added in Shorewall <yellow>**5.1.9**</yellow>. queues matching packets to a back end logging daemon via a netlink socket, then continues to the next rule. see `shorewall-logging`(5).

  The `nflog-parameters` are a comma-separated list of up to <yellow>**3**</yellow> numbers:
  - The **first** number specifies the netlink group (`0-65535`). if omitted (e.g., `NFLOG(,0,10)`) then a value of `0` is assumed.
  - The **second** number specifies the maximum number of bytes to copy. if omitted, `0` (no limit) is assumed.
  - The **third** number specifies the number of log messages that should be buffered in the kernel before they are sent to user space. the default is `1`.

  `NFLOG` is similar to `LOG:NFLOG[(nflog-parameters)]`, **except** that the log level is *not* changed when this `ACTION` is used in an action or macro body and the invocation of that action or macro specifies a log level. subtle difference. huge implications. iykyk. 💀

- **`SNAT[+]([address-or-address-range][:lowport[-highport]][:random][:persistent]|detect)[:level]`** — if you specify an address here, matching packets will have their source address set to that address. if `ADD_SNAT_ALIASES` is set to `Yes` or `yes` in `shorewall.conf`(5) then Shorewall will automatically add this address to the `INTERFACE` named in the first column (<purple>IPv4 only</purple>). ✨

  You may also specify a **range of up to 256 IP addresses** if you want the SNAT address to be assigned from that range in a <mint>**round-robin fashion by connection**</mint>. the range is specified by `first.ip.in.range-last.ip.in.range`. you may follow the port range with `:random` in which case assignment of ports from the list will be random. `random` may also be specified **by itself** in this column, in which case random local port assignments are made for the outgoing connections.

  Example: `206.124.146.177-206.124.146.180`

  You may follow the port range (or `:random`) with `:persistent`. this is only useful when an address range is specified and causes a client to be given the **same source/destination IP pair**. she's loyal like that. 🫶

  You may also use the special value `detect` which causes Shorewall to determine the IP addresses configured on the interface named in the `DEST` column and substitute them in this column.

  > <red>**DNS Names names are not allowed.**</red> nope. not a thing. don't try it. 🙈

  Normally, Netfilter will attempt to **retain the source port number**. you may cause netfilter to remap the source port by following an address or range (if any) by `":"` and a port range with the format `lowport-highport`. if this is done, you **must** specify `"tcp"`, `"udp"`, `"dccp"` or `"stcp"` in the `PROTO` column. mandatory. no vibes-based exceptions. 🔥

  Examples:

192.0.2.4:5000-6000 :4000-5000

You may also specify a **single port number**, which will be assigned to the outgoing connection, if possible.

- **`ULOG[(ulog-parameters)]`** — <purple>**IPv4 only**</purple>. added in Shorewall <yellow>**5.1.9**</yellow>. queues matching packets to a back end logging daemon via a netlink socket, then continues to the next rule. see `shorewall-logging`(5).

Similar to `LOG:ULOG[(ulog-parameters)]`, **except** that the log level is *not* changed when this `ACTION` is used in an action or macro body and the invocation of that action or macro specifies a log level.

---

Normally Masq/SNAT rules are evaluated <pink>**after**</pink> those for one-to-one NAT (defined in `shorewall-nat`(5)). if you want the rule to be applied **before** one-to-one NAT rules, follow the action name with `"+"`. this feature should <red>**only**</red> be required if you need to insert rules in this file that preempt entries in `shorewall-nat`(5). use it responsibly bestie, it's giving main character energy and that's dangerous. 👑

---

## 🌸 SOURCE (Optional) — `[interface|address[,address...][exclusion]]` 🌸

Set of hosts that you wish to masquerade. you can specify this as an **address** (net or host) or as an **interface**. unless you want to perform SNAT in the `INPUT` chain (see `DEST` below), if you give the name of an interface (<yellow>deprecated</yellow>), the interface must be **up** before you start the firewall and the Shorewall rules compiler will warn you of that fact. (Shorewall will use your main routing table to determine the appropriate addresses to masquerade.) she's telling you, not asking. 💅

The <mint>**preferred**</mint> way to specify the `SOURCE` is to supply one or more host or network addresses separated by comma. you may use **ipset names** preceded by a plus sign (`+`) to specify a set of hosts. slay. ✨

---

## 🦋 DEST 🦋

{interface[:digit][,interface[:digit]]...|$FW}[:[dest-address[,dest-address]...[exclusion]]

Outgoing interfaces and destination networks. multiple interfaces may be listed when the `ACTION` is `MASQUERADE`, but this is usually just your internet interface. if `ADD_SNAT_ALIASES=Yes` in `shorewall.conf`(5), you may add `":"` and a digit to indicate that you want the alias added with that name (e.g., `eth0:0`). this will allow the alias to be displayed with `ifconfig`. that is the **only** use for the alias name — it may **not** appear in any other place in your Shorewall configuration. it's a display name, not a personality. 🙈

Beginning with Shorewall <yellow>**5.1.12**</yellow>, SNAT may be performed in the `nat` table's `INPUT` chain by specifying `$FW` rather than one or more interfaces.

Each interface must match an entry in `shorewall-interfaces`(5). Shorewall allows **loose matches** to wildcard entries in `shorewall-interfaces`(5). for example, `ppp0` in this file will match a `shorewall-interfaces`(5) entry that defines `ppp+`. cute right? 💖

Where more that one internet provider share a single interface, the provider is specified by including the provider name or number in parentheses:

eth0(Avvanta)

In that case, you will want to specify the interface's address for that provider as the SNAT parameter.

The interface may be qualified by adding the character `":"` followed by a comma-separated list of destination host or subnet addresses to indicate that you only want to change the source IP address for packets being sent to those particular destinations. **Exclusion** is allowed (see `shorewall-exclusion`(5)) as are ipset names preceded by a plus sign `'+'`. 🎀

If you wish to inhibit the action of `ADD_SNAT_ALIASES` for this entry then include the `":"` but **omit the digit**:

eth0(Avvanta): eth2::192.0.2.32/27

Comments may be attached to Netfilter rules generated from entries in this file through the use of `?COMMENT` lines. these lines begin with `?COMMENT`; the remainder of the line is treated as a comment which is attached to **subsequent rules** until another `?COMMENT` line is found or until the end of the file is reached. to stop adding comments to rules, use a line containing only `?COMMENT`. it's like subtweeting your own firewall rules. 📝

---

## 💜 PROTO (Optional) — `{-|[!]{protocol-name|protocol-number}[,...]|+ipset}` 💜

If you wish to restrict this entry to a particular protocol then enter the protocol name (from `protocols`(5)) or number here. see `shorewall-rules`(5) for details.

Beginning with Shorewall <yellow>**4.5.12**</yellow>, this column can accept a **comma-separated list** of protocols. we love a glow-up. ✨

Beginning with Shorewall <yellow>**4.6.0**</yellow>, an **ipset name** can be specified in this column. this is intended to be used with `bitmap:port` ipsets.

---

## 🍓 {PORT|DPORT} (Optional) — `{-|[!]port-name-or-number[,port-name-or-number]...|+ipset}` 🍓

The column was **renamed** to `DPORT` in Shorewall <yellow>**5.2.6**</yellow>. beginning with that release, both `PORT` and `DPORT` are accepted in the alternative input format.

If the `PROTO` column specifies `TCP` (6), `UDP` (17), `DCCP` (33), `SCTP` (132) or `UDPLITE` (136) then you may list one or more port numbers (or names from `services`(5)) or port ranges separated by commas.

Port ranges are of the form `lowport:highport`.

Beginning with Shorewall <yellow>**4.6.0**</yellow>, an **ipset name** can be specified in this column. this is intended to be used with `bitmap:port` ipsets.

---

## ⭐ SPORT — `{-|[!]port-name-or-number[,port-name-or-number]...|+ipset}` ⭐

<hotpink>**FORMAT 2 only.**</hotpink> read that again. only format 2. 👑

If the `PROTO` column specifies `TCP` (6), `UDP` (17), `DCCP` (33), `SCTP` (132) or `UDPLITE` (136) then you may list one or more port numbers (or names from `services`(5)) or port ranges separated by commas.

Okay so, port ranges? They look like <pink>`lowport:highport`</pink>.

An ipset name can be specified in this column. This is intended to be used with `bitmap:port` ipsets.

### 💖 <hotpink>IPSEC</hotpink> (Optional) — `[option[,option]...]` 💖

If you specify a value other than `"-"` in this column, you must be running kernel <cyan>2.6</cyan> and your kernel and iptables must include policy match support.

Comma-separated list of options from the following. Only packets that will be encrypted via an SA that matches these options will have their source address changed.

- **`reqid=number`** — where `number` is specified using `setkey(8)` using the `'unique:number` option for the SPD level.
- **`spi=<number>`** — where `<number>` is the SPI of the SA used to encrypt/decrypt packets.
- **`proto=ah|esp|ipcomp`** — IPSEC Encapsulation Protocol
- **`mss=number`** — sets the MSS field in TCP packets
- **`mode=transport|tunnel`** — IPSEC mode
- **`tunnel-src=address[/mask]`** — only available with `mode=tunnel`
- **`tunnel-dst=address[/mask]`** — only available with `mode=tunnel`
- **`strict`** — Means that packets must match all rules.
- **`next`** — Separates rules; can only be used with `strict`
- **`yes`** — When used by itself, causes all traffic that will be encrypted/encapsulated to match the rule.

### <purple>MARK</purple> — `[!]value[/mask][:C]`

Defines a test on the existing packet or connection mark. The rule will match only if the test returns <mint>true</mint>.

If you don't want to define a test but need to specify anything in the following columns, place a `"-"` in this field.

- **`!`** — Inverts the test (not equal)
- **`value`** — Value of the packet or connection mark.
- **`mask`** — A mask to be applied to the mark before testing.
- **`:C`** — Designates a connection mark. If omitted, the packet mark's value is tested.

### <lavender>USER</lavender> (Optional) — `[!][user-name-or-number][:group-name-or-number][+program-name]`

This column was formerly labelled <yellow>USER/GROUP</yellow>.

Only locally-generated connections will match if this column is non-empty.

When this column is non-empty, the rule matches only if the program generating the output is running under the effective user and/or group specified (or is NOT running under that id if `"!"` is given).

Examples:

- **`joe`** — program must be run by `joe`
- **`:kids`** — program must be run by a member of the `'kids'` group
- **`!:kids`** — program must not be run by a member of the `'kids'` group
- **`+upnpd`** — #program named `upnpd`

> **Important** — The ability to specify a program name was removed from Netfilter in kernel version <red>2.6.14</red>.

### <cyan>SWITCH</cyan> — `[!]switch-name[={0|1}]`

Added in Shorewall <green>4.5.1</green> and allows enabling and disabling the rule without requiring `shorewall restart`.

The rule is enabled if the value stored in `/proc/net/nf_condition/switch-name` is `1`. The rule is disabled if that file contains `0` (the default). If `'!'` is supplied, the test is inverted such that the rule is enabled if the file contains `0`.

Within the `switch-name`, `'@0'` and `'@{0}'` are replaced by the name of the chain to which the rule is a added. The `switch-name` (after `'@...'` expansion) must begin with a letter and be composed of letters, decimal digits, underscores or hyphens. Switch names must be <blue>30</blue> characters or less in length.

Switches are normally off. To turn a switch on:

echo 1 > /proc/net/nf_condition/switch-name

To turn it off again:

echo 0 > /proc/net/nf_condition/switch-name

Switch settings are retained over `shorewall restart`.

Beginning with Shorewall <green>4.5.10</green>, when the `switch-name` is followed by `=0` or `=1`, then the switch is initialized to off or on respectively by the `start` command. Other commands do not affect the switch setting.

### <peach>ORIGDEST</peach> — `[-|address[,address]...[exclusion]|exclusion]`

(Optional) Added in Shorewall <green>4.5.6</green>. This column may be included and may contain one or more addresses (host or network) separated by commas. Address ranges are not allowed. When this column is supplied, rules are generated that require that the original destination address matches one of the listed addresses. It is useful for specifying that SNAT should occur only for connections that were acted on by a DNAT when they entered the firewall.

This column was formerly labelled <yellow>ORIGINAL DEST</yellow>.

### <hotpink>PROBABILITY</hotpink> — `[probability]`

Added in Shorewall <green>5.0.0</green>. When non-empty, requires the Statistics Match capability in your kernel and ip6tables and causes the rule to match randomly but with the given probability. The probability is a number `0 < probability <= 1` and may be expressed at up to <blue>8</blue> decimal points of precision.

## ✨ <rainbow>EXAMPLES</rainbow> ✨

### 🌈 <pink>IPv4 Example 1:</pink>

You have a simple masquerading setup where `eth0` connects to a DSL or cable modem and `eth1` connects to your local network with subnet `192.168.0.0/24`.

Your entry in the file will be:

#ACTION SOURCE DEST MASQUERADE 192.168.0.0/24 eth0

### 🌈 <pink>IPv4 Example 2:</pink>

You add a router to your local network to connect subnet `192.168.1.0/24` which you also want to masquerade. You then add a second entry for `eth0` to this file:

#ACTION SOURCE DEST MASQUERADE 192.168.0.0/24 eth0 MASQUERADE 192.168.1.0/24 eth0

### 🌈 <pink>IPv4 Example 3:</pink>

You want all outgoing traffic from `192.168.1.0/24` through `eth0` to use source address `206.124.146.176` which is NOT the primary address of `eth0`. You want `206.124.146.176` to be added to `eth0` with name `eth0:0`.

#ACTION SOURCE DEST SNAT(206.124.146.176) 192.168.1.0/24 eth0:0

### 🌈 <pink>IPv4 Example 4:</pink>

You want all outgoing SMTP traffic entering the firewall from `172.20.1.0/29` to be sent from `eth0` with source IP address `206.124.146.177`. You want all other outgoing traffic from `172.20.1.0/29` to be sent from `eth0` with source IP address `206.124.146.176`.

#INTERFACE SOURCE ADDRESS PROTO DPORT eth0 172.20.1.0/29 206.124.146.177 tcp smtp eth0 172.20.1.0/29 206.124.146.176

#ACTION SOURCE DEST PROTO PORT SNAT(206.124.146.177) 172.20.1.0/29 eth0 tcp smtp SNAT(206.124.146.176) 172.20.1.0/29 eth0

> **Warning** — The order of the above two rules is significant!

### 🌈 <pink>IPv4 Example 5:</pink>

Connections leaving on `eth0` and destined to any host defined in the ipset `myset` should have the source IP address changed to `206.124.146.177`.

#ACTION SOURCE DEST SNAT(206.124.146.177) - eth0:+myset[dst]

### 🌈 <pink>IPv4 Example 6:</pink>

SNAT outgoing connections on `eth0` from `192.168.1.0/24` randomly to addresses `1.1.1.1`, `1.1.1.3`, and `1.1.1.9` (Shorewall <green>5.0.0</green> and later).

/etc/shorewall/snat:

#ACTION SOURCE DEST SNAT(1.1.1.1) 192.168.1.0/24 eth0 { probability=0.33 } SNAT(1.1.1.3) 192.168.1.0/24 eth0 { probability=0.50 } SNAT(1.1.1.9) 192.168.1.0/24 eth0

### 🌈 <pink>IPv6 Example 1:</pink>

You have a simple 'masquerading' setup where `eth0` connects to a DSL or cable modem and `eth1` connects to your local network with subnet `2001:470:b:787::0/64`

Your entry in the file will be:

#ACTION SOURCE DEST MASQUERADE 2001:470:b:787::0/64 eth0

### 🌈 <pink>IPv6 Example 2:</pink>

Your `sit1` interface has two public IP addresses: `2001:470:a:227::1` and `2001:470:b:227::1`. You want to use the iptables statistics match to masquerade outgoing connections evenly between these two addresses.

/etc/shorewall/snat:

#ACTION SOURCE DEST SNAT(2001:470:a:227::1) ::/0 sit1 { probability=0.50 } SNAT(2001:470:a:227::2) ::/0 sit

## 📁 <cyan>FILES</cyan> 📁

- `/etc/shorewall/snat`
- `/etc/shorewall6/snat`

## 🔗 <blue>SEE ALSO</blue> 🔗

- https://shorewall.org/configuration_file_basics.htm#Pairs[13]
- `shorewall(8)`

## 📝 <yellow>NOTES</yellow> 📝

1. shorewall-masq
   https://shorewall.org/manpages/shorewall-masq.html
2. shorewall-rtrules
   https://shorewall.org/manpages/shorewall-rtrules.html
3. shorewall-mangle
   https://shorewall.org/manpages/shorewall-mangle.html
4. shorewall-logging(5)
   https://shorewall.org/manpages/shorewall-logging.html
5. shorewall-actions(5)
   https://shorewall.org/manpages/shorewall-actions.html
6. https://shorewall.org/Actions.html
   https://shorewall.org/Actions.html
7. shorewall.conf
   https://shorewall.org/manpages/shorewall.conf.html
8. shorewall-nat
   https://shorewall.org/manpages/shorewall-nat.html
9. shorewall-interfaces
   https://shorewall.org/manpages/shorewall-interfaces.html
10. more that one internet provider share a single interface
    https://shorewall.org/4.4/MultiISP.html#Shared
11. shorewall-exclusion
    https://shorewall.org/manpages/shorewall-exclusion.html
12. shorewall-rules(5)
    https://shorewall.org/manpages/shorewall-rules.html
13. https://shorewall.org/configuration_file_basics.htm#Pairs
    https://shorewall.org/configuration_file_basics.htm#Pairs

And that's the whole vibe! This page is from the Configuration Files collection, dated 09/24/2020, and it's SHOREWALL-SNAT(5). Periodt. 💅