Quico/update-firewall-source
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity
update-firewall-source/README.md

339 lines
16 KiB
Markdown
Raw Blame History

# update-firewall-source
Update a firewall rule that relies on dynamic DNS names
# What
* This script assumes exclusive ownership of the `firewalld` direct rules file `/etc/firewalld/direct.xml` or whereever configured
* List of address can be empty, direct file will then be removed
* After every execution script will trigger systemd firewalld service restart
* No subnet, will simply not be validated
* Include example systemd unit file and install instructions
* firewall-cmd --check-config
* default location for config file and default name for config file
* we should deduplicate list
* is intended to help with just docker-user
* man page https://ipset.netfilter.org/iptables.man.html we do iptables
* added in order
* related, established? needed?
* section names as comments?
* Comment max 256 chars
# Prep
Python dependencies aside make sure that your OS has headers and static libraries for D-Bus GLib bindings installed as well as generic D-Bus development files. On a Rocky Linux 8 installation for example these come via:
```
dnf -y install dbus-glib-devel dbus-devel
```
# Config structure
Package configuration happens via a `config.ini` file that follows INI-style syntax. Copy [examples/config.ini.example](examples/config.ini.example) to `config.ini` to get started:
<!-- [[[cog
import os
examples_dir = "examples"
config_ini_example = "config.ini.example"
config_ini_example_abs = os.path.join(examples_dir, config_ini_example)
try:
with open(config_ini_example_abs) as config_ini_example_handle:
config_ini_example_content = config_ini_example_handle.read()
except OSError:
pass
else:
cog.out(f"```\n"
f"{config_ini_example_content.rstrip()}\n"
f"```")
]]] -->
```
[DEFAULT]
target = ACCEPT
addr =
ports = 80, 443
proto = tcp
state = NEW
do_ipv6 = false
firewalld_direct_file_abs = /etc/firewalld/direct.xml
restart_firewalld_after_change = true
[anyone-can-access-website]
# Unsetting 'proto' while having a 'ports' value results in an invalid section
# [these-guys-can-dns]
# addr = google.li, 142.251.36.195, lowendbox.com, 2606:4700:20::ac43:4775
# ports = 53
# proto =
# do_ipv6 = true
[maybe-a-webserver]
addr = 2606:4700:20::681a:804, lowendtalk.com
ports = 80, 443
do_ipv6 = true
[allow-anyone-to-access-mail-services]
ports = 143, 993, 110, 995, 25, 465, 587
[deny-all]
target = DROP
addr =
ports =
proto =
state =
do_ipv6 = true
```
<!-- [[[end]]] -->
# Layout
A config file can have an optional `[DEFAULT]` section and must have at least one `[section]` other than `[DEFAULT]`. Any `[DEFAULT]` option that's undefined retains its default value. Feel free to delete the entire `[DEFAULT]` section from your file. A setting changed in `[DEFAULT]` section affects all sections. A setting changed only in a custom `[section]` overwrites it for only the section.
Custom sections such as `[maybe-a-webserver]` in above example file are treated as organizational helper constructs. You can but don't have to group IP address rules by sections. Technically nothing's stopping you from adding all IP allow list entries into a single section.
# Example explanation
Setting `restart_firewalld_after_change` controls if you want the `firewalld` systemd unit to be restarted
In above example file note that `[anyone-can-access-website]` makes `[maybe-a-webserver]` irrelevant, the latter one could easily be deleted. `[anyone-can-access-website]` does not overwrite defaults, it's an empty section. With it `firewalld` will create a rule that - following all default settings - allows access from any source address on TCP ports 80 and 443. In section `[maybe-a-webserver]` we do the same and additionally limit source addresses. Rules are added in `config.ini` order so the first rule permitting access to TCP ports 80 and 443 from anywhere makes the second one irrelevant.
We strongly recommend you do keep the very last example section:
```
[deny-all]
target = DROP
addr =
ports =
proto =
state =
do_ipv6 = true
```
If a packet has traversed rules this far without being accepted it will be dropped. Note that if any of your custom `[sections]` use `do_ipv6 = true` your final `DROP` rule should do the same. Otherwise you'll just get `DROP` rule in `iptables` but not in `ip6tables`.
# Options
## Globals
In `[DEFAULT]` section the following settings are called globals. They're only valid in `[DEFAULT]` context. Adding them to a custom `[section]` (see [Locals](#locals) below) won't do anything, in a custom `[section]` the following settings are ignored.
* `firewalld_direct_file_abs`, __*optional*__, defaults to `/etc/firewalld/direct.xml`: Location of `firewalld`'s direct rules file. This is where new XML rule content is written.
* `restart_firewalld_after_change`, __*optional*__, defaults to `true`: After putting a new `/etc/firewalld/direct.xml` file in place restart the `firewalld` systemd service unit.
## Locals
A custom `[section]` has the following options. We're calling them locals most of which are optional.
* `target`, __*mandatory*__, defaults to `ACCEPT`, can be any valid `iptables` target. Must not be empty nor unset. A string specifying the fate of a packet that matched this rule. See "TARGETS" section in [iptables man page](https://ipset.netfilter.org/iptables.man.html). You're most likely going to want to stick to either `ACCEPT` or `DROP`. By default matching packets are accepted. We do not do our own validation of what you write here. By default (see [Globals](#globals)) `do_config_check` equals to true in which case we let `firewalld` do a config check to catch nonsense rules.
* `addr`, __*optional*__, defaults to an empty string: A comma-separated list of any combination of IPv4 addresses, IPv6 addresses and domain names. When `update-firewall-source.py` constructs `firewalld` rules these addresses are allowed to access the server. If left undefined `addr` defaults to an empty list meaning rules apply to any and all source address.
Subnets are unsupported, both as subnet masks (`142.251.36.195/255.255.255.248`) and in [CIDR](https://en.wikipedia.org/wiki/Classless_Inter-Domain_Routing) notation (`142.251.36.195/29`). Do not single- nor double-quote list entries. Do feel free to separate entries with comma-space instead of just a comma.
```
# Valid example:
addr = 2606:4700:20::681a:804, lowendtalk.com
# Also valid (this is the default):
addr =
```
* `ports`, __*optional*__, defaults to `80, 443`: A comma-separated list of ports that should be accessible from `addr`. If empty `addr` may access all ports. See [iptables-extensions man page, section "multiport"](https://ipset.netfilter.org/iptables-extensions.man.html#lbBM) for syntax reference. All port-based rules use `iptables ... --match multiport` even if you're only allowing access to a single port. In essence construct your ports list with any combination of single ports (`80, 443, 8080`) and port ranges (`6660:7000, 61000:65535`).
```
# Valid example:
ports = 80, 443, 6660:7000, 8080
```
* `proto`, __*optional*__, defaults to `tcp`: A singular protocol that should be allowed for `addr` on `ports`. Can be set to an empty value in which case all protocols are allowed. Since `firewalld` direct rules use `iptables` syntax the list of possible protocol names is largely identical to what the [iptables man page](https://ipset.netfilter.org/iptables.man.html) says about its `--protocol` argument:
> The specified protocol can be one of `tcp`, `udp`, `udplite`, `icmp`, `icmpv6`, `esp`, `ah`, `sctp`, `mh` or the special keyword `all`, or it can be a numeric value, representing one of these protocols or a different one. A protocol name from `/etc/protocols` is also allowed. A `!` argument before the protocol inverts the test. The number zero is equivalent to `all`.
Your mileage may vary depending on which specific OS flavor and version you're running.
**Implementation details:**
* `proto` is treated as a string, not a list. To for example allow access via both TCP and UDP create two `[sections]` like so:
```
[tcp-rule]
addr = 1.1.1.1
ports =
proto = tcp
[udp-rule]
addr = 1.1.1.1
ports =
proto = udp
```
Since `proto = tcp` is default you can leave it out of the top section. Side note, in this specific example you would want to set the `[DEFAULT]` value `ports =` instead of repeating it in each `[section]`. Alternatively set `proto =` to allow all protocols in which case a single `[section]` is enough to cover that use case:
```
[permit-port-53-via-all-protocols]
addr = 1.1.1.1
ports =
proto =
```
Make sure that when `proto` is unset you also unset `ports`. See next bullet point for details on that.
* Unsetting `proto` while at the same time leaving at least one `ports` value in place (which is the default with `ports = 80, 443`) is an error.
It will result in a rule that `firewalld` cannot load into `ip(6)tables`. It will report it as such in its systemd journal visible e.g. via `journalctl -fu firewalld.service`. This is because having at least one port configured will always result in adding a `--match multiport` which is only valid when also giving a `--protocol` such as `--protocol tcp`.
```
[DEFAULT]
ports = 80, 443
proto = tcp
[valid]
addr = example.net
ports = 22, 80, 443
[invalid]
addr = example.com
proto =
# Without 'ports' there will be no '--match multiport'
# and without /that/ you can safely unset 'proto':
[also-valid]
addr = example.org
ports =
proto =
```
* `state`, __*optional*__, defaults to `NEW`: Comma-separated list of connection tracking states against which a packet is matched. Most of the time your rules will want to use the default `NEW`. The final `DROP` rule present in the example `config.ini` file at [examples/config.ini.example](examples/config.ini.example) is one occasion where you'll want to deviate and unset `state` to an empty value. See ["state" extension man page in iptables docs](https://ipset.netfilter.org/iptables-extensions.man.html#lbCC) for reference.
```
# Valid example:
state =
```
* `do_ipv6`, __*optional*__, defaults to `false`: Decide if you want `firewalld` to generate `ip6tables` rules in addition to `iptables` rules. A default install of Docker Engine will have its IPv6 support disabled in `/etc/docker/daemon.json`. You may still want your machine to handle incoming IPv6 traffic. If your machine truly doesn't use IPv6 feel free to leave this at `false`. Otherwise `update-firewall-source.py` generates unused rules that clutter your rule set.
If this is `true` IPv6 addresses found or resolved in `addr` in a `[section]` will be discarded.
```
# Valid example:
do_ipv6 = true
```
## iptables behind the scenes
In an `iptables` rule set in the `filter` table by default you'll see something like this. We're only focusing on `INPUT` and `FORWARD` chains here as these are the ones relevant to Docker.
```
Chain INPUT (policy ACCEPT 140 packets, 10115 bytes)
num pkts bytes target prot opt in out source destination
Chain FORWARD (policy ACCEPT 0 packets, 0 bytes)
num pkts bytes target prot opt in out source destination
...
```
Once you install a moderately modern Docker Engine it changes things up to this:
```
Chain INPUT (policy ACCEPT 1027 packets, 78370 bytes)
num pkts bytes target prot opt in out source destination
Chain FORWARD (policy ACCEPT 0 packets, 0 bytes)
num pkts bytes target prot opt in out source destination
1 0 0 DOCKER-USER all -- * * 0.0.0.0/0 0.0.0.0/0
2 0 0 DOCKER-ISOLATION-STAGE-1 all -- * * 0.0.0.0/0 0.0.0.0/0
3 0 0 ACCEPT all -- * docker0 0.0.0.0/0 0.0.0.0/0 ctstate RELATED,ESTABLISHED
4 0 0 DOCKER all -- * docker0 0.0.0.0/0 0.0.0.0/0
5 0 0 ACCEPT all -- docker0 !docker0 0.0.0.0/0 0.0.0.0/0
6 0 0 ACCEPT all -- docker0 docker0 0.0.0.0/0 0.0.0.0/0
...
Chain DOCKER-USER (1 references)
num pkts bytes target prot opt in out source destination
1 0 0 RETURN all -- * * 0.0.0.0/0 0.0.0.0/0
```
With UFS you're extending this into a configuration where UFS' `FILTERS` chain is called from both Docker's `DOCKER-USER` chain **_and_** the host OS `INPUT` chain. Ideally `FILTERS` ends with a `DROP` target to make sure nothing accesses your services that's not supposed to access them.
```
Chain INPUT (policy ACCEPT 56 packets, 4596 bytes)
num pkts bytes target prot opt in out source destination
1 2910 207K ACCEPT all -- lo * 0.0.0.0/0 0.0.0.0/0
2 1309 111K FILTERS all -- * * 0.0.0.0/0 0.0.0.0/0
Chain FORWARD (policy ACCEPT 0 packets, 0 bytes)
num pkts bytes target prot opt in out source destination
1 0 0 DOCKER-ISOLATION-STAGE-1 all -- * * 0.0.0.0/0 0.0.0.0/0
2 0 0 DOCKER-USER all -- * * 0.0.0.0/0 0.0.0.0/0
3 0 0 ACCEPT all -- * docker0 0.0.0.0/0 0.0.0.0/0 ctstate RELATED,ESTABLISHED
4 0 0 DOCKER all -- * docker0 0.0.0.0/0 0.0.0.0/0
5 0 0 ACCEPT all -- docker0 !docker0 0.0.0.0/0 0.0.0.0/0
6 0 0 ACCEPT all -- docker0 docker0 0.0.0.0/0 0.0.0.0/0
...
Chain FILTERS (2 references)
num pkts bytes target prot opt in out source destination
1 1267 107K ACCEPT all -- * * 0.0.0.0/0 0.0.0.0/0 state RELATED,ESTABLISHED
2 0 0 ACCEPT tcp -- * * 1.2.3.4 0.0.0.0/0 state NEW multiport dports 22,80,443 /* My home */
3 1 162 DROP all -- * * 0.0.0.0/0 0.0.0.0/0 /* deny-all */
Chain DOCKER-USER (1 references)
num pkts bytes target prot opt in out source destination
1 0 0 FILTERS all -- ens3 * 0.0.0.0/0 0.0.0.0/0
2 0 0 RETURN all -- * * 0.0.0.0/0 0.0.0.0/0
...
```
## Rule comments
The `[section]` name is used as `ip(6)tables` rule comment. The `[section]` name is truncated to the first 256 characters to fit into an `ip(6)tables` comment if needed.
Example:
```
[My home]
addr = some.dyndns.host.net
ports = 22, 80, 443
[deny-all]
target = DROP
addr =
ports =
proto =
state =
```
Results in `ip(6)tables` rules:
```
Chain FILTERS (2 references)
num pkts bytes target prot opt in out source destination
1 1267 107K ACCEPT all -- * * 0.0.0.0/0 0.0.0.0/0 state RELATED,ESTABLISHED
2 0 0 ACCEPT tcp -- * * 1.2.3.4 0.0.0.0/0 state NEW multiport dports 22,80,443 /* My home */
3 0 0 DROP all -- * * 0.0.0.0/0 0.0.0.0/0 /* deny-all */
```
# Development
## Conventional Commits
We use [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/#summary).
### Scopes
The following **_scopes_** are known for this project. A Conventional Commits commit message may optionally use one of the following scopes or none:
* `config`: Structure or content of a `config.ini` file
* `dbus`: Deals with functionality to restart the `firewalld.service` unit
* `systemd`: Deals with lifecycle as a systemd unit
* `meta`: Affects the project's repo layout, readme content, file names etc.
* `dns`: Resolution of DNS records
* `xml`: XML content handling for `firewalld` direct rules, includes segues into `ip(6)tables` territory
* `netdev`: Network devices
* `debug`: Deals with debuggability, concise messages to end user
### Types
The following **_types_** are known for this project in addition to Conventional Commits default types `fix` and `feat`. A Conventional Commits commit message must use either one of the two default types or optionally a type from this list:
* `build`: Project structure, directory layout, build instructions for roll-out
* `refactor`: Keeping functionality while streamlining or otherwise improving function flow
* `test`: Working on test coverage
* `docs`: Documentation for project or components
Reference in New Issue View Git Blame Copy Permalink