Skip to content

Add firewall-related how-to guides & reference guide #39

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
ethanjli merged 6 commits into from
Mar 11, 2026
+747 −112
Merged

Add firewall-related how-to guides & reference guide #39

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
4e249e6
Add various firewall- & security-related how-to guides
ethanjli Mar 5, 2026
7bdb8b9
Add some reference documentation for the firewall
ethanjli Mar 6, 2026
cf3d4f4
Make some names more concise
ethanjli Mar 11, 2026
2bfd4ab
Fix incorrect links
ethanjli Mar 11, 2026
4a195d7
Describe associated systemd services in the firewall reference
ethanjli Mar 11, 2026
8fc705c
Add link to the new page for openUC2 OS
ethanjli Mar 11, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion docs/dev/sw/imswitch/01_Quickstart.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@ The below diagramm visualizes the different modules that are connected to the op
## Getting Started

### Accessing ImSwitch
Refer to our [usage guides](../../../usage/pro/frame/guides/day-1/sw-access/README.md#how-to-access-browser-apps).
Refer to our [usage guides](../../../usage/pro/frame/guides/day-1/sw-access/README.md#browser-apps).

### Modifying ImSwitch Configuration
To adjust settings, edit the configuration file:
Expand Down
2 changes: 2 additions & 0 deletions docs/usage/README.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,7 @@ sidebar_label: Overview
# Usage

Welcome to the openUC2 usage documentation! Here you'll find:

- **Hands-on tutorials** to help you learn how to do things with our products & projects
- **How-to guides** to help you accomplish practical goals with our products & projects
- **Reference** guides which you can consult for technical descriptions about our products & projects and how to use them
Expand Down Expand Up @@ -49,5 +50,6 @@ We also provide usage documentation for operating components included across var

- [Hikrobot Machine Vision Camera](./components/hik-camera/README.md)
- [ImSwitch](./components/imswitch/README.md)
- [openUC2 OS](./components/os/README.md)

For documentation about how to develop functionalities with these components to do things beyond the off-the-shelf functionalities of openUC2 products, please see our [development documentation](../dev/README.md) instead.
1 change: 1 addition & 0 deletions docs/usage/components/os/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
# openUC2 OS
5 changes: 5 additions & 0 deletions docs/usage/components/os/configuration/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
sidebar_label: Configuration
---

# System Configuration
5 changes: 5 additions & 0 deletions docs/usage/components/os/configuration/drop-in-files.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
sidebar_label: Drop-in Files
---

# Drop-in Configuration Files
1 change: 1 addition & 0 deletions docs/usage/components/os/networking/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
# Networking
155 changes: 155 additions & 0 deletions docs/usage/components/os/networking/firewall/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,155 @@
# Firewall

This reference guide describes the firewall system in openUC2 OS.

openUC2 OS uses [firewalld](https://firewalld.org/documentation/) as its firewall.
The firewall is run as the systemd service `firewalld.service`.

firewalld is configured using openUC2 OS's pattern for [drop-in configuration files](../../configuration/drop-in-files.md).
The drop-in configuration file system for firewalld is provided by Forklift package deployment `networking/firewalld`.

## `firewalld.conf`

Configuration variables in [`/etc/firewalld/firewalld.conf`](https://firewalld.org/documentation/configuration/firewalld-conf.html) are set with drop-in files in `/etc/firewalld/firewalld.conf.d`, which are controlled by Forklift package deployments and associated feature flags:

| Setting | ...in drop-in file | ...from | ...is set by default? |
| -------------------------------- | ------------------------------ | --------------------------------------------------- | --------------------- |
| `DefaultZone`:<br />`public` | `20-default-zone.conf` | `networking/firewalld` | yes |
| `StrictForwardPorts`:<br />`yes` | `20-strict-forward-ports.conf` | `networking/firewalld`:<br /> `govern-docker-ports` | |

`/etc/firewalld/firewalld.conf` is generated as follows:
- The systemd service `assemble-firewalld-config.service` concatenates the contents of `/etc/firewalld/firewalld.conf.d/` and writes the output to `/run/overlays/generated/etc/firewalld/firewalld.conf`.
- `/etc/firewalld/firewalld.conf` is a symlink to `/run/overlays/generated/etc/firewalld/firewalld.conf`.

## Services

firewalld is configured with the following [services](https://firewalld.org/documentation/service/), some of which are controlled by Forklift package deployments and associated feature flags:

| Service | ...from | ...exists by default? |
| -------------------- | --------------------------------------------------------------------------------------------- | --------------------- |
| `dhcp` | firewalld | yes |
| `dhcpv6` | firewalld | yes |
| `dhcpv6-client` | firewalld | yes |
| `dns` | firewalld | yes |
| `mdns` | firewalld | yes |
| `cockpit` | firewalld | yes |
| `ssh` | firewalld | yes |
| `http` | firewalld | yes |
| `https` | firewalld | yes |
| `http3` | firewalld | yes |
| `http-untrusted` | `infra/caddy-ingress-untrusted`:<br /> `firewall-allow-direct`,<br /> `firewall-allow-public` | yes |
| `esp32-ota-firmware` | `imswitch`:<br /> `firewall-allow-direct`,<br /> `firewall-allow-public` | yes |
| `imswitch-dev` | `imswitch`:<br /> `firewall-allow-direct`,<br /> `firewall-allow-public` | yes |

File locations:
- Services from firewalld are defined in `/usr/lib/firewalld/services/`.
- Services from Forklift package deployments are defined in `/etc/firewalld/services/`.

These services expose the following ports:

| Service | TCP Ports | UDP Ports |
| -------------------- | ---------- | --------- |
| `dhcp` | | 67 |
| `dhcpv6` | | 547 |
| `dhcpv6-client` | | 546 |
| `dns` | 53 | 53 |
| `mdns` | | 5353 |
| `cockpit` | 9090 | |
| `ssh` | 22 | |
| `http` | 80 | |
| `https` | 443 | |
| `http3` | | 443 |
| `http-untrusted` | 8000 | |
| `esp32-ota-firmware` | 3333 | 3232 |
| `imswitch-dev` | 8001, 8888 | |

## Zones

firewalld is configured with the following [zones](https://firewalld.org/documentation/zone/), which are controlled by Forklift package deployments and associated feature flags:

| Zone | ...from | ...exists by default? |
| ----------- | ------------------------------------------------------- | --------------------- |
| `nm-shared` | `networking/firewalld`'s feature<br /> `zone-nm-shared` | yes |
| `public` | `networking/firewalld`'s feature<br /> `zone-public` | yes |

### `nm-shared`

The `nm-shared` zone is intended to be used as the default firewall zone for NetworkManager connections with internet access sharing, such as direct connections to other devices.
It is configured as a fully-privileged zone where unauthenticated administrative apps and services may be exposed.

The `nm-shared` zone `/etc/firewalld/zones/nm-shared.xml` is defined by drop-in files in `/etc/firewalld/zones.d/nm-shared/`, which are controlled by Forklift package deployments and associated feature flags:

| Setting | ...in drop-in file | ...from | ...is set by default? |
| --------------------------------------- | --------------------------------------- | --------------------------------------------------------------------- | --------------------- |
| interface<br /> `tailscale0` | `20-interface-tailscale0.xml` | `networking/tailscale`:<br /> `firewall-as-direct` | yes |
| protocol<br /> `icmp` | `30-protocol-icmp.xml` | `networking/networkmanager/base`:<br /> `firewall-allow-direct` | yes |
| protocol<br /> `ipv6-icmp` | `30-protocol-icmp.xml` | `networking/networkmanager/base`:<br /> `firewall-allow-direct` | yes |
| service<br /> `dhcp` | `40-service-dhcp.xml` | `networking/networkmanager/base`:<br /> `firewall-allow-direct` | yes |
| service<br /> `dhcpv6` | `40-service-dhcp.xml` | `networking/networkmanager/base`:<br /> `firewall-allow-direct` | yes |
| service<br /> `dhcpv6-client` | `40-service-dhcp.xml` | `networking/networkmanager/base`:<br /> `firewall-allow-direct` | yes |
| service<br /> `dns` | `40-service-dns.xml` | `networking/networkmanager/base`:<br /> `firewall-allow-direct` | yes |
| service<br /> `mdns` | `40-service-mdns.xml` | `networking/avahi/daemon`:<br /> `firewall-allow-direct` | yes |
| service<br /> `cockpit` | `50-service-cockpit.xml` | `admin/cockpit`:<br /> `firewall-allow-direct` | yes |
| service<br /> `ssh` | `50-service-ssh.xml` | `admin/sshd`:<br /> `firewall-allow-direct` | yes |
| service<br /> `http` | `60-service-http.xml` | `infra/caddy-ingress`:<br /> `firewall-allow-direct` | yes |
| service<br /> `https` | `60-service-https.xml` | `infra/caddy-ingress`:<br /> `firewall-allow-direct` | yes |
| service<br /> `http3` | `60-service-http3.xml` | `infra/caddy-ingress`:<br /> `firewall-allow-direct` | yes |
| service<br /> `http-untrusted` | `60-service-http-untrusted.xml` | `infra/caddy-ingress-untrusted`:<br /> `firewall-allow-direct` | yes |
| service<br /> `esp32-ota-firmware` | `70-service-esp32-ota-firmware.xml` | `imswitch`:<br /> `firewall-allow-direct` | yes |
| service<br /> `imswitch-dev` | `70-service-imswitch-dev.xml` | `imswitch`:<br /> `firewall-allow-direct` | yes |
| rule (priority 32767)<br /> reject | `90-rule-default.xml` | `networking/firewalld` | yes |

Naming conventions:
- The numeric prefixes of any additional rules should be at least `20` and less than `90`.
- The prefix `20-` is used for binding interfaces to the zone.
- The prefix `30-` is used for low-level networking protocols.
- The prefix `40-` is used for networking protocols which facilitate device connectivity & access.
- The prefix `50-` is used for administrative services.
- The prefix `60-` is used for general/infrastructural application services.
- The prefix `70-` is used for specific applications.
- Feature flags configuring firewalld to allow access to ports should be named `firewall-allow-direct`.

`/etc/firewalld/zones/nm-shared.xml` is generated as follows:
- The systemd service `assemble-firewalld-config.service` concatenates the contents of `/etc/firewalld/zones.d/nm-shared/` and writes the output to `/run/overlays/generated/etc/firewalld/zones/nm-shared.xml`.
- `/etc/firewalld/zones/nm-shared.xml` is a symlink to `/run/overlays/generated/etc/firewalld/zones/nm-shared.xml`.

### `public`

The `public` zone is intended to be used as the default firewall zone for connections by untrusted strangers.
It is configured as an unprivileged zone.

The `public` zone `/etc/firewalld/zones/public.xml` is defined by drop-in files in `/etc/firewalld/zones.d/public/`, which are controlled by Forklift package deployments and associated feature flags:

| Setting | ...in drop-in file | ...from | ...is set by default? |
| --------------------------------------- | --------------------------------------- | --------------------------------------------------------------------- | --------------------- |
| interface<br /> `tailscale0` | `20-interface-tailscale0.xml` | `networking/tailscale`:<br /> `firewall-as-public` | |
| protocol<br /> `icmp` | `30-protocol-icmp.xml` | `networking/networkmanager/base`:<br /> `firewall-allow-public` | yes |
| protocol<br /> `ipv6-icmp` | `30-protocol-icmp.xml` | `networking/networkmanager/base`:<br /> `firewall-allow-public` | yes |
| service<br /> `dhcp` | `40-service-dhcp.xml` | `networking/networkmanager/base`:<br /> `firewall-allow-public` | yes |
| service<br /> `dhcpv6` | `40-service-dhcp.xml` | `networking/networkmanager/base`:<br /> `firewall-allow-public` | yes |
| service<br /> `dhcpv6-client` | `40-service-dhcp.xml` | `networking/networkmanager/base`:<br /> `firewall-allow-public` | yes |
| service<br /> `dns` | `40-service-dns.xml` | `networking/networkmanager/base`:<br /> `firewall-allow-public` | yes |
| service<br /> `mdns` | `40-service-mdns.xml` | `networking/avahi/daemon`:<br /> `firewall-allow-public` | yes |
| service<br /> `cockpit` | `50-service-cockpit.xml` | `admin/cockpit`:<br /> `firewall-allow-public` | yes |
| service<br /> `ssh` | `50-service-ssh.xml` | `admin/sshd`:<br /> `firewall-allow-public` | yes |
| service<br /> `http` | `60-service-http.xml` | `infra/caddy-ingress`:<br /> `firewall-allow-public` | |
| service<br /> `https` | `60-service-https.xml` | `infra/caddy-ingress`:<br /> `firewall-allow-public` | |
| service<br /> `http3` | `60-service-http3.xml` | `infra/caddy-ingress`:<br /> `firewall-allow-public` | |
| service<br /> `http-untrusted` | `60-service-http-untrusted.xml` | `infra/caddy-ingress-untrusted`:<br /> `firewall-allow-public` | yes |
| forward `:80` to<br /> `127.0.0.1:8000` | `70-forward-http-to-http-untrusted.xml` | `infra/caddy-ingress-untrusted`:<br /> `firewall-forward-http-public` | yes |
| service<br /> `esp32-ota-firmware` | `70-service-esp32-ota-firmware.xml` | `imswitch`:<br /> `firewall-allow-public` | yes |
| service<br /> `imswitch-dev` | `70-service-imswitch-dev.xml` | `imswitch`:<br /> `firewall-allow-public` | yes |

Naming conventions:
- The numeric prefixes of any additional rules should be at least `20` and less than `90`.
- The prefix `20-` is used for binding interfaces to the zone.
- The prefix `30-` is used for low-level networking protocols.
- The prefix `40-` is used for networking protocols which facilitate device connectivity & access.
- The prefix `50-` is used for administrative services.
- The prefix `60-` is used for general/infrastructural application services.
- The prefix `70-` is used for specific applications.
- Feature flags configuring firewalld to allow access to ports should be named `firewall-allow-public`.

`/etc/firewalld/zones/public.xml` is generated as follows:
- The systemd service `assemble-firewalld-config.service` concatenates the contents of `/etc/firewalld/zones.d/public/` and writes the output to `/run/overlays/generated/etc/firewalld/zones/public.xml`.
- `/etc/firewalld/zones/public.xml` is a symlink to `/run/overlays/generated/etc/firewalld/zones/public.xml`.
13 changes: 10 additions & 3 deletions docs/usage/pro/frame/guides/day-1/connectivity/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,8 +7,8 @@ toc_max_heading_level: 4
# Machine Connectivity

The how-to guides here will help you to:
- access your FRAME's software
- make your FRAME's software easy to access
- connect to your FRAME, so that you can [access its software](../sw-access/README.md)
- make your FRAME's software easy to connect to

This process will be less stressful for you if you've already done [the relevant day-0 planning](../../day-0/connectivity/README.md).

Expand Down Expand Up @@ -46,7 +46,7 @@ To choose which of the following methods you will use for connecting to the FRAM

1. On your computer, connect to the FRAME's Wi-Fi hotspot.

:::tip
:::info

By default, the Wi-Fi hotspot's name is `openuc2-{machine name}`, where `{machine name}` is your FRAME's machine name.
For example, if your FRAME's machine name is `great-example-1234`, then the Wi-Fi hotspot's name is `openuc2-great-example-1234`.
Expand All @@ -58,6 +58,7 @@ To choose which of the following methods you will use for connecting to the FRAM
:::tip

By default, the Wi-Fi hotspot's password is `youseetoo`.
You should [change it to a more secure password](../security/README.md#how-to-change-the-wi-fi-hotspots-password).

:::

Expand All @@ -79,6 +80,12 @@ To choose which of the following methods you will use for connecting to the FRAM
1. Connect your FRAME to a Local Area Network (LAN) by following the same procedure you would use to [connect your FRAME to the internet](#how-to-connect-the-frame-to-the-internet) via a network router or external Wi-Fi network.
2. Connect your computer to the same LAN.

:::tip

If you intend to access administrative apps over the LAN, you will need to explicitly [allow access to unauthenticated administrative apps over the LAN](../sw-access/README.md#to-unauthenticated-administrative-apps-over-local-area-networks).

:::

## How to access the FRAME's landing page

The following factors will determine which access methods work for you:
Expand Down
Loading
Loading