Network and firewall

FAQ › EUZOS Server › Network and firewall · Nederlands

What is it?

Three things decide how an EUZOS Server is reachable:

the network setup per adapter: DHCP or a static address, plus an optional external address (public IP or DNS name when the server is behind NAT) that is passed on when registering;
the inbound firewall: always on, closed by default, with signed rules that only Server Admin can change on a production server;
the SSH policy: a production server has no SSH; only a test build (the SBX images) can run sshd, for development.

IPv4 only: the network stack does not know IPv6 yet.

How do I…?

How do I see the network setup?

network on the console (or network in Server Admin). Per adapter: number, name, MAC address, link, the configured mode (dhcp or the static address), and the address in use now; a public static address gets a note; the last line shows the external address.

How do I give an adapter a static address?

network <adapter> static <ip>/<prefix> <gateway|-> <dns1> [<dns2>]

<adapter> is the name (for example bcm0), the number from network, or the MAC address. The netmask may also be written as 255.255.255.0 instead of /<prefix>. A gateway - means no gateway (only the own network). The change is written to the network file and applied right away. This is also allowed on a production server's console (network management).

How do I switch an adapter back to DHCP?

network <adapter> dhcp.

How do I set the external address?

network external <address> (an IP address or DNS name) or network external none to remove it.

How do I see the firewall?

firewall on the console, or firewall in Server Admin: the rules in order (the admin protocol rule and the development SSH rule are marked), a suggestion from Workplace management to open the cache port if it is not open yet, and the number of blocked packets.

How do I open a port, for example the cache for the LAN?

With Server Admin: serveradmin <server> firewall-open allow tcp 8445 lan. On a production server's console you can only view the firewall; in a test build the console can also do it: firewall open <rule> / firewall close <rule>.

How do I allow ping?

ICMP echo is closed by default. Open it with a rule such as allow icmp - lan.

Why can I not remove the admin protocol rule?

A rule list without any rule that allows TCP 8446 is refused: the server would no longer be manageable ("without a rule that allows the admin protocol (tcp 8446), the server can no longer be managed").

Why does SSH not work on my server?

On a production build sshd never starts and the firewall drops any rule that allows port 22. On a test build sshd starts only when AUTHKEYS.TXT is present, SSHD.TXT does not say off (legacy uit), and — on a workplace server — the role file has dev-ssh=yes (legacy ontwikkel-ssh=ja). Otherwise: "sshd: not on a workplace server (only test build with dev-ssh=yes in WORKPLC.TXT)".

Details

Network file

The kernel reads \EOS\FW\NETWORK.TXT (and, as a legacy fallback, NETWERK.TXT). At boot and on every link an adapter with a static line gets that address (never renewed by DHCP); the others use DHCP on the first adapter with a cable. Invalid lines are ignored with a message in the log. Static addresses are checked: valid IPv4, not 0.0.0.0, loopback, multicast, class E or link-local; not the network or broadcast address; the gateway inside the subnet; one or two DNS servers. At most 16 adapters and 2 DNS servers; an external address at most 253 characters (an IPv6 address is allowed there, it is only a hint for the profile server).

Firewall

crate::net::firewall filters inbound packets on EUZOS's own network stack (euzos_ip::firewall). Always allowed are replies to what the server opens itself, looked up in the kernel's own state: a TCP segment without SYN only when a connection exists for its addresses and ports; UDP only from an address and port that an open socket sent to (DNS, NTP; DHCP accepts any server on port 67 while it runs); and ICMP error messages and echo replies. A TCP segment to a closed port without a connection is dropped silently (no RST). Everything else must match a rule; rules are checked in order, the first match decides (allow or deny), no match means closed. At most 64 rules. lan is the subnet of the adapter the packet comes in on; a source address from the subnet of another adapter is dropped (reverse path). Blocked packets are counted (firewall) and logged per source in net log: the first packet of a source at once, then a sum per minute, at most 20 lines a minute.

Defaults (no valid file):

Rule	Default
Admin protocol of Server Admin, TCP 8446	open from the own subnet (`allow tcp 8446 lan`)
SSH, TCP 22	test build only: open from the own subnet (the development rule); a production build has neither SSH nor this rule
ICMP echo (ping)	closed until the admin opens it
Backup, TCP 8448 (Backup)	closed; the package suggests `allow tcp 8448 lan`
Workplace management cache, TCP 8445, and every other port	closed; the package only suggests opening it

The rules live in \EOS\FW\FIREWALL.TXT, signed with the server's key (WPKEY.TXT, Ed25519). A changed or unreadable file, or one without WPKEY.TXT to check it, does not count: then the defaults apply and the log says so. Every change is written to the server's log. While the rules are being changed only replies get through.

SSH policy

Build	Server role	sshd
production (`-prod` images)	any	never; the firewall removes any allow rule for port 22
test (`-sbx` images)	no workplace role	allowed (starts at boot if `AUTHKEYS.TXT` exists and `SSHD.TXT` is not `off`)
test	workplace role	only with `dev-ssh=yes` in `WORKPLC.TXT`

The graphical server installer writes dev-ssh=yes in every test build; the text installer and workplace setup only when sshd is running at that moment. A test build may still talk to the PROD environment: the SSH rule depends on the build, not on the environment.

Large transfers over SSH are not cut off: sshd renews its keys (rekey, RFC 4253 §9) when the client asks (OpenSSH after about 1 GiB) and by itself after 2^28 packets, 1 GiB or an hour, without closing the session.

Reference

Console commands

Command	Arguments	What it does
`network`	–	show adapters, modes and the external address
`network`	`<adapter> dhcp`	DHCP for that adapter
`network`	`<adapter> static <ip>/<prefix> <gateway\|-> <dns1> [<dns2>]`	static address (`statisch` is also accepted, it is the file word)
`network`	`external <address>` \| `external none`	set or clear the external address (legacy aliases `extern`, `geen`; also `-`)
`firewall`	–	show the rules, suggestions and blocked count
`firewall`	`open <rule>`	test build only: add a rule at the front
`firewall`	`close <rule>` (legacy `sluit`)	test build only: remove exactly that rule
`sshd`	`[start\|stop\|status]`	the SSH server (refused where the policy above forbids it)
`ip`, `dhcp [renew] [adapter]`, `ping`, `dns`		shared network commands, see Desktop network

netwerk is the legacy alias of network.

Functions and modules

Item	Role
`crate::net::static_ip::{config, apply, set_now, set, change, text, external_address, command}`	the network file and the `network` command
`euzos_ip::static_ip::{Network, Mode, Static, read_external, read_mac}`	parse, check and write the network file
`crate::net::firewall::{init, allows, open, close, set, close_ports, text, command}`	the firewall in the kernel
`euzos_ip::firewall::{Rule, Rules, defaults, without_ssh, ADMIN_PORT, DEV_SSH}`	rule syntax, matching, signing
`crate::workplace::{public_key, sign, ssh_allowed}`	key for checking/signing the firewall file; SSH rule of the role
`crate::net::sshd::{command, role_allows}`	sshd and its policy check
`crate::network_services` (`main.rs`)	starts NTP and (if allowed) sshd when an address is up

Config files

File	Line / key	Values	Meaning
`\EOS\FW\NETWORK.TXT` (legacy `NETWERK.TXT`)	`<MAC> dhcp`		DHCP for the adapter with that MAC address
	`<MAC> statisch <ip>/<prefix> [<gateway>\|-] <dns1> [<dns2>]`	mask also as `a.b.c.d`	static address
	`extern <address>`	IP or DNS name	external address behind NAT
`\EOS\FW\FIREWALL.TXT`	first line	`EUZOS-firewall-v1`	header
	`regel=<rule>`	see below	one rule, in order
	`handtekening=`	128 hex	Ed25519 signature by the server key
`\EOS\FW\SSHD.TXT`	whole file	`off` (legacy `uit`)	do not start sshd
`\EOS\FW\AUTHKEYS.TXT`	OpenSSH lines	`ssh-ed25519 …`	allowed SSH keys (test build)
`\EOS\FW\WORKPLC.TXT`	`dev-ssh` (legacy `ontwikkel-ssh`)	`yes` (legacy `ja`)	SSH on a test-build workplace server

The file words of NETWORK.TXT (statisch, dhcp, extern) are on-disk format and stay Dutch. FIREWALL.TXT is written in English since version 2 (rule=, signature=, allow, deny, anywhere); a signed version 1 file (regel=, handtekening=, toestaan, weigeren, overal) is still read. The graphical server installer and network write NETWORK.TXT; the legacy name NETWERK.TXT is still read when NETWORK.TXT is missing.

Protocol messages and formats

allow (legacy toestaan, open), deny (legacy weigeren, dicht);
port 1–65535 or from-to; for icmp the port is -;
source lan (the own subnet of the adapter the packet comes in on), anywhere (legacy overal; including the internet), or an IPv4 address or subnet.

Firewall file example (generic), version 2:

EUZOS-firewall-v2
version=7
rule=allow tcp 8446 lan
rule=allow tcp 8445 lan
rule=allow icmp - lan
signature=<128 hex>

The signature covers the domain EUZOS-firewall-v2\0 and the text as rewritten from the parsed rules, including the version= line (File::to_sign). The counter goes up with every change and is shown by firewall (file version:), so an older signed file put back on the disk is visible; preventing it needs storage an attacker with the disk cannot write (TPM, not yet). A version 1 file (EUZOS-firewall-v1, regel=, handtekening=, Dutch words, domain EUZOS-firewall-v1\0) is still valid; the next change writes version 2.

Fixed gateway MAC (NETWORK.TXT, recommended on a server): gateway-mac <adapter MAC> <gateway MAC>, or on the console network <adapter> gateway-mac <mac>|none. ARP can then no longer change the gateway's address. Without it, an ARP entry only changes on a reply to the server's own request (asked again every minute while in use) or after 10 minutes without confirmation; an unsolicited change is refused and logged as ARP ALARM in net log.