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?

Config structure

Package configuration happens via a config.ini file that follows INI-style syntax. Copy examples/config.ini.example to config.ini to get started:

[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

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

With config_check_after_change

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 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. 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) 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 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.
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" 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 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 is one occasion where you'll want to deviate and unset state to an empty value. See "state" extension man page in iptables docs for reference.
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 in which case ip6tables will not have a DOCKER-USER or similar Docker-related chains. In this default setup having update-firewall-source.py generate an otherwise unused DOCKER-USER chain and adding rules to it clutters your rule set. Consider setting this to true if and when your Docker install uses IPv6.

If this is true IPv6 addresses found or resolved in addr in a [section] will be discarded.

Development

Conventional Commits

We use Conventional Commits.

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