Networking

Start with net status to see whether an interface has joined a network, which profile it uses, and whether it has an address and a default route. On the desktop, open Network Manager from the launcher by typing network.

net status
resolv status

net reports interface configuration; resolv reports the name servers actually in use. For a firewall change, an administrator also checks net policy. A route, a DNS answer and permission to reach a service are separate checks.

Choose the next check #

The net command reference explains its output and access rights. The diagnostic tools guide covers probes available in Experimental.

The registry is the truth #

Network settings live under Machine\System\Network. Change them through Network Manager or the profile and rule keys. netd reads those settings and applies them live; there is no interface configuration file or reload command.

Do not add an address by hand to a joined interface: netd removes addresses that its profile does not request. Routes added by another program are left alone unless they carry netd's own routing-protocol tag. The kernel's IPv6 link-local address is left alone too. The exact ownership and apply order are in Reconciliation.

The netd loop and startup and restart chapters describe how registry, kernel, lease and timer changes are reconciled.

Rules say which, profiles say how #

A rule under Rules\Interface selects an interface and gives it one of three outcomes:

• JOIN(profile) uses a profile under Profiles\.
• IGNORE leaves the interface as it is, including existing settings.
• DOWN keeps the interface administratively down.

A profile supplies settings such as Address.Static, Route.Gateway and Dns.Servers. Each Offered value decides whether to accept that part of the network's offer. An offer is a claim from the network, not proof that it is trustworthy. A child profile inherits its parents' settings and replaces only the values it names.

A profile can serve several interfaces at once; there is no separate activation step. Rules can match stable interface identity or the network's name and trust label. A shipped wired rule at priority 10 assigns all wired interfaces to default, which accepts offered addresses, routes and DNS and enables link-local fallback. A bare profile accepts none of those offers. No matching rule means IGNORE.

See Configuring profiles for examples and Network policy for exceptions, priorities and conflicts.

The inventory and the networks #

Use net status for the current link, address, lease and network. The interface id remains stable for the same card in the same slot even if its kernel name changes across boots.

The registry also keeps records under Interfaces\<id> and Networks\<id>. netd's findings are in their protected Status subkeys; hand edits there are refused. On a network record, you can set Name and Trust. Rules for both profiles and the firewall use those labels, so changing one can change connectivity.

Network identification currently uses the DHCP server and subnet, or an advertising router and prefix. It does not prove a network's identity. The inventory and network records chapters list the persisted fields; lease timers and current offered configuration are live daemon state, not a lease to restore from the registry.

Addresses #

Choose these in a profile, then check the result in net status:

An expired DHCP lease is dropped by default. Address.OnExpiry = Keep trades address-conflict risk for continuity. A network's RequestedAddress is only the address to ask for first next time; the server can refuse it.

A deprecated IPv6 address remains for existing connections but is not chosen for new ones; it is removed when its valid lifetime ends. Stable address derivation, temporary-address rotation and the protective two-hour lifetime rule are documented in IPv6 addresses. See DHCPv4 for acquisition, renewal and fallback details.

Readiness is a level, not a boolean #

The machine reports the highest level among joined interfaces. Readiness is also published on Machine\System\Network and each joined interface's Status for scripts and services.

net wait routed waits for a default route. A service may declare Requires = ["network:routed"]. These waits differ: net wait accepts at least the requested level, while peinit matches the published service level exactly. See Readiness before depending on network:addressed.

What netd does not do #

• Answer DNS. resolvd receives netd's live server and domain information; use name resolution to configure and diagnose it. netd writes neither /etc/resolv.conf nor /etc/hosts.
• Filter traffic. The kernel enforces PNP's packet layers. DHCP and router-discovery traffic need the baseline's visible, deletable rules.
• Grant port ownership. Port reservations decide who may bind a port; the firewall decides who may reach it.
• Associate Wi-Fi. A supplicant must bring up a wireless link before netd can configure it. Wi-Fi is unfinished: wireless is absent from the baseline, Network Manager shows it as Not managed, and wireless networks are not yet identified by name.

Where to start #

• Configure a profile, apply it through a matching rule, and read back the accepted settings.
• Use Network Manager for desktop configuration, change previews and its documented rollback flow.
• Troubleshoot a symptom.
• Look up exact settings in regman 'Machine\System\Network' or the network policy reference.
• Use the netd technical reference manual for daemon algorithms, protocol exchanges, timers and limits.

Network configuration is two kinds of key under Machine\System\Network. A profile, a subkey of Profiles, says how an interface stands on a network: what to take from the network's offer and what to dictate. A rule, a subkey of Rules\Interface, says which interfaces stand in which profile. netd watches the subtree, so a change takes effect within a moment of the write — no restart, no reload command.

Follow this order: inspect the active interface, prepare the profile, select it with a rule, then read back the accepted state. For desktop changes, use Network Manager, whose profile editor shows inherited values and the interfaces a change affects.

Every value is documented on the machine, regman 'Machine\System\Network', and in the reference.

Before you change anything #

• You need write access to the particular registry keys. Reading status does not grant permission to change configuration; protected Status keys are netd's output, not settings to edit.
• Record the current rule, profile and values so you can restore them. Keep local console access or another recovery path if this network carries your remote session.
• Profile and rule writes take effect live. Changing a profile's resolved values restarts its interfaces' clients, even for a DNS-only profile edit. No reboot or daemon reload is required.
• Use a derived profile for one interface. Editing default affects every interface using it and descendants that inherit the edited value.
• The commands below are examples. Replace addresses, names, ids and bus paths with your own. The vpn, office, laptop, untrusted and home profile examples assume those profiles already exist.

See what you have #

net status
net rules
net profiles

Keep this output for comparison after the change. net status shows each interface with its verdict: the rule that spoke and the profile it stands in. An image's baseline is a profile default that takes the network's address, way out and name servers, and a rule wired that puts every wired interface in it at priority 10.

A static address #

Create the profile before a rule names it. This example derives default/db1 from default, so values not listed here remain inherited, including Dns.Offered and Address.LinkLocal. Lists replace inherited lists; they do not append. An absent value inherits, while a present empty value means none.

Confirm that 10.0.0.5/24 is appropriate and available on your network and that 10.0.0.1 is its gateway before adapting these example writes:

reg new Machine/System/Network/Profiles/default/db1
reg set Machine/System/Network/Profiles/default/db1 Address.Offered dword:0
reg set Machine/System/Network/Profiles/default/db1 Address.Static multi:10.0.0.5/24
reg set Machine/System/Network/Profiles/default/db1 Route.Offered dword:0
reg set Machine/System/Network/Profiles/default/db1 Route.Gateway 10.0.0.1

Then a rule naming the interface by its bus path (from net status, stable across boots), as an exception under the baseline's wired rule so it is judged only for wired interfaces:

reg new Machine/System/Network/Rules/Interface/wired/db1
reg set Machine/System/Network/Rules/Interface/wired/db1 Interface.Path.Equal pci-0000:00:03.0
reg set Machine/System/Network/Rules/Interface/wired/db1 Actions 'multi:JOIN(default/db1)'

The exception is more specific than wired, so it selects default/db1 for that interface and stops offered address acquisition. Check for JOIN(default/db1) by wired/db1 and the intended address and gateway in net status; readiness routed appears once both a usable address and the default route are in place.

Inherited Dns.Offered is a setting, not evidence that a server is available after address acquisition stops. Check resolv status. To pin DNS as well, set Dns.Offered = 0 and Dns.Servers on this derived profile. The inherited link-local setting does not add a fallback beside a static address. See desired state.

Verify the accepted settings #

net rules
net profiles
net status
resolv status

1. Confirm the rule names the intended profile and matches the intended interface. net profiles lists each profile's own values, not a flattened result; account for inherited values.
2. Check that net status has no policy REFUSED line. Read the active verdict, rule and profile, then the address, gateway, lease and warnings.
3. Check the servers and domains in resolv status, and test a relevant name with resolv query <name>.
4. Test the service you actually need. Readiness routed proves a default route exists, not that a remote service or the Internet answers.

If you also changed firewall rules or a network's Name or Trust, an administrator should run net policy wait and check net policy. That verifies the kernel's packet policy; it does not substitute for checking netd's accepted profile in net status.

If the result is wrong, restore the values you recorded and repeat the checks. net reconcile requests another pass; it does not undo a write. net renew <interface> asks to renew an existing DHCP lease without releasing it first. Both need NETWORK_CONTROL, granted to SYSTEM and Administrators by default.

Facts a rule can name #

Every <Fact>.<Operator> value present must hold. Comparison is exact; Equal takes a list for any of.

Prefer Interface.Path or Interface.Id for a specific card and Interface.Kind or Interface.Driver for a class. Interface (the name) is the least stable: the kernel may call the same card something else after a hardware change. A fact the interface lacks — a tunnel has no Path — makes the condition false, never an error.

Taking the offer, with adjustments #

default believes the network about the address, the way out and the name servers. To keep the address but pin DNS, override two values in a derived profile and point a rule at it — or, if the whole machine should behave so, edit default itself:

reg set Machine/System/Network/Profiles/default Dns.Offered dword:0
reg set Machine/System/Network/Profiles/default Dns.Servers multi:1.1.1.1,9.9.9.9

Three more Dns values decide which names an interface's servers are asked for, which matters the moment a second interface appears — typically a VPN:

reg set Machine/System/Network/Profiles/vpn Dns.Domains multi:corp.example
reg set Machine/System/Network/Profiles/vpn Dns.Default dword:1
reg set Machine/System/Network/Profiles/vpn Dns.Exclusive dword:1

Dns.Domains sends names under corp.example to this interface's servers. Dns.Default sends every other name there too (unset, an interface claims that only when it carries the default route). Dns.Exclusive takes all queries only while the interface is at least addressed and supplies a DNS server. Without those conditions it does not prevent another interface from being chosen. Verify the VPN's addresses and server lines before relying on it to keep names off another network. See name resolution.

To hold an offered address across a server outage:

reg set Machine/System/Network/Profiles/default Address.OnExpiry Keep

Keep trades the risk of an address conflict for continuity; the default Drop is the safe choice.

IPv6 #

Address.Offered covers both families: on a network with router advertisements the interface gets a stable-privacy address per advertised prefix, and with Route.Offered and Dns.Offered the advertised default route and DNS from RDNSS or stateless DHCPv6. Three values change that:

reg set Machine/System/Network/Profiles/office Address.Families multi:ipv4
reg set Machine/System/Network/Profiles/laptop Address.Temporary dword:1
reg set Machine/System/Network/Profiles/office Route.Gateway multi:10.0.0.1,fe80::1

Address.Families = ipv4 stops router discovery on interfaces in the profile and drops IPv6 entries from Address.Static. Address.Temporary adds daily-rotating temporary addresses beside the stable one, for machines whose traffic should not correlate over days; the stable address remains for inbound. An IPv6 entry in Route.Gateway — usually a link-local address — pins the default router instead of believing advertisements.

The stable address survives reboots and reinstalls that keep /var/state/netd; it is not derived directly from the MAC, and a different network sees an unrelated address. The IPv6 address chapter documents derivation, lifetimes and rotation.

Prefer a cable over WiFi #

When both interfaces have default routes, the metric decides which is used. Wired defaults to 100 and wireless to 600, so no configuration is needed. To invert it, set Route.Metric on the profiles. This describes route preference once links exist; Wi-Fi association is not implemented by netd, wireless is not in the baseline, and Network Manager currently shows wireless as Not managed.

Name a network, and behave differently on it #

Once an interface has stood on a network, net status shows the record's id. Give it a name and your word on it:

reg set Machine/System/Network/Networks/<id> Name palfrey-home
reg set Machine/System/Network/Networks/<id> Trust home

Changing either label can change both the selected profile and firewall access. Check the active interface and packet policy afterwards.

The following illustrates choosing a profile by network. It is not a Wi-Fi setup procedure: a supplicant must supply the link, and wireless network-name identification is unfinished. Create the untrusted and home profiles before a rule names them:

reg new Machine/System/Network/Rules/Interface/radio
reg set Machine/System/Network/Rules/Interface/radio Interface.Kind.Equal wireless
reg set Machine/System/Network/Rules/Interface/radio Actions 'multi:JOIN(untrusted)'
reg new Machine/System/Network/Rules/Interface/radio/home
reg set Machine/System/Network/Rules/Interface/radio/home Network.Name.Equal palfrey-home
reg set Machine/System/Network/Rules/Interface/radio/home Actions 'multi:JOIN(home)'

Until a network has been identified on the link, the Network.* facts are absent, so the radio stands in untrusted first and moves to home once the network is known. Trust is your label, not verified evidence of network identity: a rule that conditions on it is stating that you accept the identification. The same word reaches the firewall: a Flow rule with Network.Trust.Equal = home sees the network the radio is on, so what you open at home stays shut at the cafe (see the network context).

Hand an interface to something else #

An IGNORE verdict leaves a matched interface alone: no new addresses, routes, link changes or DHCP. If it was previously joined, existing addresses and routes remain; IGNORE is not a cleanup action:

reg new Machine/System/Network/Rules/Interface/leave-alone
reg set Machine/System/Network/Rules/Interface/leave-alone Interface.Equal tap0
reg set Machine/System/Network/Rules/Interface/leave-alone Actions multi:IGNORE

Take an interface down #

A DOWN verdict keeps a matched interface administratively down. DOWN wins equal-priority ties, but a higher-priority rule still wins. Check existing priorities before using the example priority 100:

reg new Machine/System/Network/Rules/Interface/dead-card
reg set Machine/System/Network/Rules/Interface/dead-card Interface.Id.Equal <id>
reg set Machine/System/Network/Rules/Interface/dead-card Priority dword:100
reg set Machine/System/Network/Rules/Interface/dead-card Actions multi:DOWN

The interface id is in net status. Delete the rule, or set Enabled = 0 on it, to let the remaining rules decide again. Verify that they select the intended profile; removing DOWN alone does not guarantee a JOIN.

Ask for the same address #

The address a network last leased is on its record, and netd asks for it first. Write it yourself for a soft reservation — a request the server may refuse, unlike a static address:

reg set Machine/System/Network/Networks/<id> RequestedAddress 10.0.2.50

Set the hostname #

reg set Machine/System/Network Hostname workshop

netd applies it on the next pass. A profile with Hostname.Offered on adopts a network-supplied name when this value is unset; Hostname.Announce tells DHCP servers the name so their DNS can register it. Both are off in a bare profile.

Each change netd makes to the machine's name is recorded in the event log as netd.hostname.changed, with the name before and after (config.text-previous and config.text). The netd manual's hostname chapter says exactly when.

netd sets whatever is written, but a network carries the name as one label: letters, digits and hyphens, at most 63 of them, not beginning or ending with a hyphen, and not localhost. System Settings holds it to that as it is typed: in its About section, Machine Name says what is wrong with a name before it can be applied, and shows the name the machine has now if netd hasn't applied the new one yet; Apply appears once the name has been changed. The About section also shows what the machine is and runs: the system and its edition, the kernel, how long it has been up, the hardware, and the disks.

When netd refuses #

An unknown fact, a JOIN naming a missing profile, or an unknown profile value refuses the whole new interface generation. netd keeps the last good one and net status reports policy REFUSED with the reason. Fix the named entry, then verify the next write was accepted; the registry listing alone does not tell you what is active.

Two equal-priority rules selecting different profiles also refuse a runtime reload when the conflict affects an existing interface. At startup, or for an interface that appears later, the tied interface is instead ignored and its warning names both rules. Make one rule unambiguously win. The generation and interface judgment chapters describe that distinction.

A JOIN naming an existing but disabled profile abstains; its parent, another rule or the backstop answers. Disabling a profile does not exempt malformed values in it from validation.

Where to go next #

• The net command — read back what netd did.
• Networking — the model behind these keys.
• Network policy reference — every fact, verdict and profile value.
• The interface layer as netd runs it, in the netd technical reference manual — how netd reads these keys, builds a generation from them and judges each interface.

Use net status first. It shows what netd accepted and what is present on each interface. Use net rules and net profiles to compare that state with the registry configuration. On the desktop, the same starting point is Network Manager's Overview.

net status
net rules
net profiles

net does not write profile or rule configuration. Follow Configuring profiles to change it, then return here to verify the result.

After a change #

• Profile or interface rule: check net status for the intended verdict, rule and profile, no policy REFUSED line, and the expected addresses and gateway. net profiles shows each profile's own values, so inherited settings still matter.
• DNS: check resolv status and a relevant resolv query <name>.
• Firewall rule or network label: as an administrator, run net policy wait, then net policy. A returned registry write is not yet proof that the kernel accepted it.
• Connectivity: test the required service. routed means there is a usable address and a default route, not a successful Internet probe.

The interface and packet policy are accepted independently. A successful net policy wait does not prove that netd accepted a profile; a good net status does not prove that the firewall accepted a rule.

Reading net status #

hostname   workshop
readiness  routed

enp0s3  [3f2a1b8e-…]
  verdict    JOIN(default) by wired
  state      up, carrier
  readiness  routed
  hardware   52:54:00:12:34:56 pci-0000:00:03.0 virtio_net
  network    palfrey-home [9c0d4e21-…] trust home
  address    10.0.2.15/24
  gateway    10.0.2.2
  dns        10.0.2.3
  lease      bound from 10.0.2.2, 86395s left

verdict is what the interface layer said and who said it: the verdict, the profile (for JOIN), and the rule path that spoke — backstop when no rule did. readiness is absent (down or no carrier), link, addressed or routed, shown for joined interfaces; the machine's is the highest among them. network is the record under Machine\System\Network\Networks identified on the link, with the Name and Trust you gave it.

The bracketed value after the name is the interface id — the inventory key under Machine\System\Network\Interfaces.

Read the interface block, not just the machine's readiness: another interface can make the machine routed while this one is unusable. An IPv4 link-local address counts as addressed; IPv6 link-local alone does not. Only joined interfaces contribute to machine readiness.

A warning line can mean DHCP discovery went unanswered or two rules tied and this interface is ignored. policy REFUSED: means the newest interface generation was rejected and the last good one stands. Correct the named rule or profile and read status again. A listed registry write is not proof it took effect.

Commands #

Choose renew or reconcile carefully #

net renew <interface> asks a DHCPv4 client holding a lease to renew it without releasing its current address first. A client with no lease is left as it is; a successful request alone does not prove a new lease arrived. Check the lease afterwards. The argument may be a kernel name or the stable interface id shown by net status.

net reconcile asks netd to apply the configured desired state now. It does not reload a different configuration, undo a write, or make an invalid gateway reachable. Neither operation requires a reboot.

Do not substitute a daemon restart for these commands: the restart chapter describes leased addresses and routes disappearing until DHCP responds, and IPv6 autoconfiguration waiting for advertisements again.

Who may run it #

status, wait, renew and reconcile reach netd through /run/netd/control.sock. The control object is a security descriptor: Machine\System\Network\ControlSecurity, or a compiled default when that is unset. status and wait need NETWORK_QUERY, which the default grants to everyone. renew and reconcile need NETWORK_CONTROL, which the default grants to SYSTEM and Administrators. rules and profiles read the registry directly and need only read access to it. policy and policy wait ask the kernel through /dev/peios-ntfe, which ordinary users may not open. A denied request reports access denied.

Exit status #

See also #

• Networking
• Configuring profiles
• regman 'Machine\System\Network' on the machine, for every key netd reads and writes.
• netd's control socket, in the netd technical reference manual: the requests behind every net command, and their replies.

Start with the symptom below. Run read-only checks before changing profiles, firewall rules or service state, and keep the output that explains the failure. The tools retain your native identity and access restrictions; installing a tool does not grant network or capture privileges.

Start with the symptom #

For daemon errors, use the service logs:

evctl 'LOGS FROM netd SINCE 1h ago TAKE 40'
evctl 'LOGS FROM resolvd SINCE 1h ago TAKE 40'

If a profile or rule is wrong, follow the safe change checklist and verify it afterwards. Restarting netd can remove offered addresses and routes while it acquires them again; it is not the first connectivity test. The netd failure modes and resolvd failure modes give the detailed failure paths.

Choose a tool #

Experimental includes these tools alongside net, resolv and trust:

These are command examples, not an instruction to scan or capture an unrelated network. Test hosts and traffic you are authorized to inspect. The documentation addresses above are examples; replace them with the host you want to test. net remains the interface to netd for network configuration and status. The iproute2 package supplies ss; it does not add ip or tc as alternative configuration tools.

Echo and network policy #

Ordinary IPv4 and IPv6 echo datagram sockets are available to every principal. ping needs neither a privileged executable nor a raw socket for its ordinary echo operation. Peios does not use Linux's POSIX group-range setting to decide who may open these echo sockets.

PNP still evaluates the resulting packets. Rules can block requests and replies, inbound or outbound, including loopback traffic. A missing reply can mean filtering, routing trouble or a host that does not answer echo; it does not by itself prove that the host is down. Ordinary echo never receives the bypass reserved for refusal packets generated by PNP itself.

Raw sockets remain subject to the existing kernel authority checks. Options that require raw sockets can therefore fail for an ordinary caller. The package grants no raw-packet privilege and does not change the caller's token.

Routes, capture and scanning #

Ordinary UDP traceroute and echo-datagram probes do not require raw-socket authority. MTR uses the ordinary echo-datagram fallback when raw sockets are unavailable. Other probe modes can require enabled SeTcbPrivilege, the existing Peios authority for raw and packet sockets. This applies to live tcpdump capture, ARP probes and Nmap's raw scanning modes. arping is part of iputils and operates on the local IPv4 link; it does not trace routed paths.

Nmap selects its default probing behaviour from the caller's enabled native privilege, rather than its projected Unix UID. Use -sT -Pn for ordinary TCP connect scans that skip raw host discovery. --privileged and NMAP_PRIVILEGED only select behaviour; they grant no authority. Nmap includes its NSE scripts and data, but this package does not install Ncat or Nping. NSE scripts run with the invoking principal's access. User data lookup uses an absolute $HOME/.nmap, with normal FACS checks.

All these tools retain the invoking token. There are no set-ID helpers, file capabilities, automatic privilege grants or new PNP exceptions. tcpdump's Unix -Z privilege-drop option is rejected because changing a projected UID does not reduce native authority. Launch capture with the intended native authority from the outset. Probe traffic remains subject to PNP; a capture filter only selects what is recorded and is not a firewall rule. Seeing a packet in a capture does not prove that a later policy check allowed delivery.

Named libpcap savefiles, including tcpdump -w output, and Nmap's named scan logs are created with an atomic, protected owner-only FACS descriptor. An existing output must be a regular file with one hard link, owned by the effective principal and protected by an owner-only descriptor. Shared destinations, symlinks and special files are refused before truncation or append. Capture rotation creates each new file under the same rule. Choose a directory you control: private file contents do not stop another principal with directory authority from replacing entries.

Reading captures requires ordinary FACS read access, without raw-socket privilege. Output to -, shell redirection, caller-supplied libpcap streams and NSE scripts' own file operations follow the destination's existing policy. They are not converted into private named logs by these patches.

Socket and terminal relays #

socat supports TCP, UDP, Unix sockets, files, PTYs, program execution and OpenSSL TLS. It starts listeners or programs only when explicitly requested. They retain the caller's native identity, port authority and PNP restrictions. Unix ownership, mode, umask, identity-switch, chroot and network-namespace address options are rejected during option parsing; those options cannot establish native isolation. Configure FACS and native launch authority separately.

Regular relay files use the destination's normal FACS policy. Place sensitive output in a private directory. TLS uses OpenSSL trust handling; supply the intended peer name and trust anchors when using an explicit private service. TUN, POSIX message queues, readline and libwrap support are not included in this build.

DNS and socket inspection #

resolv asks resolvd about Peios name resolution. dig sends a DNS query directly, which is useful for inspecting the local stub or comparing an explicitly named server. Use @127.0.0.53 to query resolvd's local stub. Direct DNS requests still traverse PNP and do not change the system's DNS configuration.

ss reports the socket information the kernel exposes to the caller. Any numeric Unix UID shown is a compatibility projection, not a Peios SID or proof of the effective principal. Use PNP's identity information when investigating native ownership or policy decisions.

Transfers and saved state #

curl uses OpenSSL's system trust paths, maintained by trustd. Its cookie jar, HSTS cache and Alt-Svc cache are created atomically with a protected FACS descriptor belonging to the effective principal. A second principal does not gain access merely because it has the same projected Unix UID. Failure to create that descriptor does not fall back to Unix mode bits.

Normal downloaded documents use the destination's usual FACS policy. Shared writable directories can still allow another principal to remove or replace directory entries; save sensitive state in a directory you control. curl's saved-state files must be regular writable file destinations rather than special devices.

nc is the OpenBSD implementation with Debian's portability patches. This package does not supply its optional TLS mode. It listens only when explicitly invoked in a listening mode; installing it starts no service. Listeners and connections remain subject to native port reservations and PNP.

Registration queries and throughput #

whois queries remote registration servers. The package includes the query client, without the separate mkpasswd program. Domain names must be ASCII or already converted to their punycode form; this build does not include an IDN conversion library. The optional /etc/whois.conf compatibility file can override server selection. Queries and any referrals remain subject to PNP.

Start iperf3 -s on the receiving host, then run iperf3 -c HOST on the sending host. Add -u for UDP, -R to reverse the data direction, or -P 2 for two parallel streams. The default server port is 5201. The invoking principal must have the necessary port authority, and PNP must allow both the control connection and the test traffic. Installing the package starts no service and grants no port reservation, privilege or policy exception.

iperf3 uses anonymous in-memory files for its stream buffers. Received -F files and PID files are created with a protected, owner-only FACS descriptor for the effective principal. An existing destination must be a regular file with one hard link, owned by that principal and already protected by an owner-only descriptor; shared files, symlinks and special files are refused before truncation. Send-side -F files and authentication inputs use ordinary FACS access checks. Log files and redirected output follow their destination's usual policy, so choose a private directory when results are sensitive.

Optional RSA authentication restricts who may run a measurement against that server; it does not create a Peios logon or encrypt the measured traffic. Authentication debug output omits decoded credentials. Protect the server's private key and authorized-user file with FACS and use a directory you control for saved state.

Use rsync -rlt for content synchronization and an explicit verification mode for TLS diagnostics. Before either, choose a destination you control and confirm the identity and access the command will use.

Synchronizing contents with rsync #

The Peios rsync port synchronizes contents between local directories or over SSH. Replace the example paths, account and server; an existing destination file may be replaced:

rsync -rlt source/ destination/
rsync -rlt source/ alice@server:destination/

-rlt copies directories recursively, carries symbolic links and preserves modification times. Add -X to copy ordinary user.* extended attributes. Security descriptors, signatures, capabilities and other security attributes are excluded from ordinary xattr synchronization, including when explicit xattr filters are supplied.

A new regular file receives the destination directory's native inheritance. An updated regular file retains the destination's complete security descriptor. Source Unix modes, UID and GID do not define the destination's Peios access policy. Archive/security-preservation requests such as -a, -p, -o, -g, ACL preservation, --chmod and --fake-super are rejected. Native cp -a requests supported preservation attributes, with component and error-reporting limits; it does not establish a complete security backup either. rsync is not yet a native security backup/restore tool.

Ordinary replacement stages a private inode in the destination filesystem. Publishing a replacement requires permission to read and restore the destination's full security, including audit metadata. If those rights are unavailable, the transfer fails without publishing a replacement. rsync does not silently drop inaccessible descriptor components or change to in-place writing. It checks for destination inode and descriptor changes before publication, but that check and the final rename are not a single security transaction. Coordinate concurrent permission changes separately.

For an existing file you are authorized to write, you can explicitly choose:

rsync -rlt --inplace source/ destination/

An in-place update retains the original inode and its security descriptor, and also affects its other hardlinks. It is not atomic: interruption can leave partially updated contents. Use it only when that tradeoff is appropriate.

This initial port rejects alternate staging/partial/backup modes, delayed updates, hardlink preservation, basis-directory optimization, special-file preservation, batch mode and insecure symlink traversal. It also refuses replacements that would delete an existing object to change its type or symbolic-link target, since that would discard its destination security. Explicit deletion remains a separate operation. Filesystems must support unnamed temporary files for ordinary staged transfers; there is no insecure staging fallback.

Rsync daemon serving is disabled, including daemon mode invoked over a remote shell. Ordinary SSH --server transfers remain supported. The receiving process uses the identity supplied by SSH; installing rsync creates no service and grants no extra authority. Security-sensitive symlink ownership checks use native SIDs rather than cosmetic Unix UID zero. A client password file must have a protected owner-only native DACL.

After a transfer, check that the intended contents arrived and that the destination's native security is still the policy you intended. If staged replacement is refused for insufficient security rights, read that failure before considering --inplace; it is a different interruption and hardlink tradeoff, not an equivalent retry.

OpenSSL and private outputs #

OpenSSL uses trustd's generated /etc/ssl/cert.pem and hashed /etc/ssl/certs by default. Use trust to manage machine trust. Explicit CA-file, CA-directory and environment overrides select trust for that invocation; they do not modify the machine's trust store. openssl rehash is for directories you manage yourself, not trustd's generated directory.

Named secret outputs are private to the effective Peios principal from creation. This includes private keys, secret-bearing PKCS12 exports, session files, TLS key logs, derived/random key material, RNG seed files and decrypted plaintext. Public certificate and public-key outputs use ordinary destination policy, except mixed exports, which are treated as potentially secret.

An existing secret destination must be a regular file owned by the effective principal, with a protected owner-only DACL. Shared files, symbolic links, multiply linked files and policies the tool cannot prove private are refused before data is overwritten. This intentionally does not reinterpret Unix 0600 as a native access policy. Configure intentional service-key sharing separately through Peios security tools after generation. Ordinary administrative privileges and mandatory controls still apply.

Output to stdout or a pipe remains supported. Shell redirection creates its own file: openssl ... > key.pem does not receive the tool's named-output protection. For private named files use the command's -out, -keyout, -secret, -sess_out, -keylogfile or other named-output option as appropriate. A shared directory may still permit someone to remove or replace directory entries; use a directory you control for durable keys.

TLS diagnostics and network policy #

openssl s_client retains its diagnostic behavior: certificate errors are reported but do not necessarily abort the connection. For a strict server check, request both fatal verification errors and the expected identity:

openssl s_client -connect example.org:443 -servername example.org \
  -verify_return_error -verify_hostname example.org

Use -verify_ip for an IP identity. SNI (-servername) alone is not hostname verification. Explicitly selected TLS diagnostic behavior never bypasses PNP: connections and listeners remain subject to native network policy and port reservations.

A successful TLS check establishes the requested certificate checks for that peer. It does not change system trust or grant access through PNP. If verification fails, inspect the reported certificate, peer name and trust anchors rather than disabling the check to declare success.

Use resolv to check which DNS settings Peios is using and where an answer came from. On the desktop, use DNS in Network Manager.

Network-supplied DNS belongs to an interface's profile. Machine-wide fallback servers, extra search domains and static names live under Machine\System\Network\Dns. Do not edit /etc/hosts, /etc/resolv.conf or nsswitch.conf to configure Peios name resolution.

Check a name first #

resolv status
resolv query example.org
resolv lookup example.org

Replace example.org with the name that fails. query shows the outcome, source, server and interface; lookup shows addresses as getaddrinfo sees them. For a fresh network answer, use:

resolv query example.org --no-cache

This skips cache lookup but still stores the new answer. If only an IP connection works, use the result to choose the next check under Not found versus unavailable. If the IP connection also fails, start with connectivity.

Where the servers come from #

resolv status shows netd's connection and the scopes currently in use. A scope is an interface's servers, domains and addresses:

hostname   workshop
netd       connected
cache      12 entries

eth0  metric 100  [default-route]
  server   10.0.2.3
  domain   lan
  subnet   10.0.2.15/24

netd sends that live information to resolvd; offered server lists are not written to a resolver configuration file. Match the scope against the interface and profile in net status.

To change an interface's DNS, use its profile's Dns.Offered, Dns.Servers, Dns.Domains, Dns.Default and Dns.Exclusive settings in Configuring profiles. A profile edit can restart address clients, so use that guide's recovery checklist even for a DNS change.

For machine-wide settings, use FallbackServers and ExtraSearchDomains on Machine\System\Network\Dns, or Network Manager's DNS Settings:

• FallbackServers is used only when no up interface supplies a server. It is not failover for an interface whose servers time out.
• ExtraSearchDomains adds domains after the applicable interface domains. It is not applied while an exclusive scope takes all queries.
• These registry changes apply live to later questions. Check the new fallback-server list in resolv status and repeat the lookup. Extra search domains are not listed in that status output: verify them with a lookup of the intended bare name. No restart is normally needed. A failed registry watch or a malformed value can prevent the expected change; the registry chapter describes the log messages.

Verify which interface gets a name #

A query goes to one interface's servers, never to all interfaces at once. The operator-relevant order is:

1. An exclusive scope, if it has a server and is at least addressed.
2. The scope with the most-specific matching search domain.
3. For a reverse lookup, a scope whose subnet contains the address.
4. A scope that claims the default route, otherwise the lowest-metric eligible scope.
5. Fallback servers only when no up scope has a server.

A single-label name such as printer is asked only after a search domain is appended. With no applicable domain it is not found locally and no query leaves the machine. A name with a dot between labels is not expanded. Use a fully qualified name to check whether the problem is the search list. The scope-routing and single-label expansion chapters contain the full selection and tie-breaking algorithms.

Static names #

For a name that this machine should answer without DNS, add a value under Hosts. You need registry write access. Replace this example name and address with the intended host:

reg new Machine/System/Network/Dns/Hosts
reg set Machine/System/Network/Dns/Hosts printer 10.0.2.9

Then verify both directions:

resolv query printer
resolv reverse 10.0.2.9

An exact static name wins over DNS at every resolver entry point, including programs using the DNS stub. Static-name changes are live and need no cache flush. localhost, the machine's own hostname and their reverses are answered without configuration. The synthetic-name chapter documents precedence, record types and reverse-name collisions.

.local names are not sent upstream. mDNS is not implemented and LLMNR is never used. An explicitly configured static .local name can still answer locally.

The resolv command #

Queries and status need RESOLVER_QUERY, granted to everyone by the default control descriptor. Flush is granted to SYSTEM and Administrators by default. Machine\System\Network\Dns ControlSecurity can change those grants. Registry edits require separate write access.

Exit 0 means found or a successful status/flush, 2 means notfound, and 3 means unavailable. Exit 1 includes an unreachable daemon, access denial, protocol error or bad type/address; unrecognized usage exits 64. See the command reference for accepted record types and exact output.

Unlike dig, resolv query reports cache use and the chosen interface. Every network answer currently says unvalidated; this version performs no DNSSEC validation.

Not found versus unavailable #

On restart, resolvd removes its stale socket and binds a new one. Its directory and socket descriptors retain full access for its own service identity so this replacement can succeed. See the socket chapter. If startup reports a permission error, inspect the actual descriptors and logs; do not delete the runtime directory merely because a restart occurred.

For comparison with the local DNS stub, Experimental includes dig @127.0.0.53 example.org A. A direct query to some other server tests that server, not Peios's normal scope selection. All DNS traffic still meets PNP.

Three doors #

resolvd is Peios's stub resolver: a DNS client forwarding to upstream servers, not a recursive or authoritative server. Its shared policy and cache are reached through libc's getaddrinfo, DNS on 127.0.0.53, or the native socket /run/resolvd/resolv.sock used by resolv.

The glibc hosts database is fixed to libnss_peios_net.so.2, without files or dns fallbacks. The constant /etc/resolv.conf points other DNS clients, including Go and musl programs, at the stub. A bare name gets the same search-domain treatment through each route. Native replies also carry TTLs, source and validation state. See the resolver overview and name-resolution interface for the entry-point contracts.

What is not there yet #

DNSSEC validation, DNS over TLS, mDNS and per-program resolution policy are not implemented in this version. Native query access is checked, but allowed callers use the same resolution policy.

Going deeper #

• Name resolution interface: requests, outcomes and entry-point contracts.
• resolvd technical reference manual: cache behavior, routing, server demotion, retries, wire handling and limits.
• netd's resolver channel: which profile and offered DNS facts reach resolvd.

Use Peios Network Policy (PNP) to decide which connections the machine allows and which interfaces join a network. Settings are registry keys under Machine\System\Network; there is no iptables configuration. The kernel's Network Traffic Filtering Engine (NTFE) enforces packet policy, while netd applies interface rules and profiles.

For desktop changes, open Network Manager and use Rules or Profile rules. The policy reference lists exact values and examples. Experimental also includes the PNP viewer, with important access risks.

Check and change policy safely #

1. Identify the symptom. For a service that cannot be reached, confirm that it is listening and has permission to bind its port. A firewall allow does not create a listener or grant a port reservation.
2. Check what is active. As an administrator, run net policy to see enforcement, generation and refusals. Use net status separately for interface rules. A refused update leaves the previous accepted policy active.
3. Preview the smallest change. In Network Manager, use Test a connection and What this changes. Its firewall exposure and activity displays currently include labeled example data; a preview is not evidence that a real connection worked.
4. Keep a recovery path. Record the old rule values and retain local access before changing the path used by a remote session. A rule or network-label change can cut an existing connection on its next packet.
5. Apply, then verify. After a registry edit, run net policy wait, then net policy, and test the intended connection. Check net status too if interface rules, profiles or network labels changed.

net policy and net policy wait require access to the kernel device; ordinary users cannot open it. Editing rules requires registry write access. A successful write is not yet proof that the kernel ingested it; net policy wait fails on a refused generation or timeout.

Rules are keys #

A rule's path identifies it in diagnostics, such as no-inbound/ssh-from-lan. Its values specify:

• Conditions: <Fact>.<Operator> values, such as DstPort.Equal = 22. Every condition must hold. A rule with no conditions matches everything.
• Actions: a list such as PASS, DROP, REJECT(Prohibited) or COUNT(dns).
• Priority: a number, inherited by children and defaulting to 0 at a root. Enabled = 0 disables a rule and its entire subtree.

Create a child key for an exception. The child must satisfy its parent's conditions as well as its own, so no-inbound can drop inbound traffic while a child allows SSH from a particular subnet. Order in the editor or registry does not decide which rule wins. Independent rule trees compete by priority and strictness, allowing local and organization policy to coexist without merging their trees.

Three layers, and a fourth #

Choose the layer for the question you need to answer:

Allowing a flow does not override a drop in another layer. A fact absent at a layer cannot make its condition match. Check the layer table before moving a rule between layers.

The kernel's exact inbound/outbound order, bridge and non-IP fallback checks, and untracked-packet handling are in Seats and dispatch.

Flows and sentences #

A sentence is the flow's cached verdict. Normally the first packet is judged and later packets use it. The rule's direction is the originator's: a connection this machine opened remains out, including its replies.

Two changes can trigger a fresh judgment:

• Policy or network context changes. The next packet is judged against the new generation. A newly forbidden existing connection stops then; REJECT on an established TCP connection tears down both ends.
• A consulted Time.* condition changes. Time.Hour.Equal = 9-17 can stop an existing connection at 18:00 UTC, on its next packet. Use Start.Hour if only new connections should be restricted; it is fixed for the flow's life.

A loopback flow has two local endpoints and two judgments. Both must allow it. COUNT and REPORT effects at this layer run when a flow is judged, including a re-judgment, rather than on every packet.

See The Flow layer for caching, time expiry and the cases where no sentence can be retained.

Who is speaking #

Use Flow identity facts for a local program or service. For example, Local.Service.Equal = resolvd with DstPort.Equal = 53 matches the resolver service's traffic to that port. Identity comes from the native token stamped on the socket, not a program path or a claimed name.

Local.User.Present = 0 means no attributable program user is present. The endpoint can instead be the kernel, a shared receiver or no listener. On loopback, Remote.* also describes the other local endpoint. Check the PNP viewer's Listeners and Flows when a service rule does not match; an unresolved identity is reported rather than guessed.

The identity facts describes socket stamping and exactly when each identity is available.

Joining a network #

For addresses and routes, use Configuring profiles. An interface is the hardware or virtual link; the network is what is on the other side. The address, route, DNS and hostname it offers are claims, not verified trust.

An interface rule selects by Interface.Kind, Interface.Path, Interface.Id, or an identified network's Name and Trust. Its verdict is JOIN(profile), IGNORE or DOWN; no matching verdict leaves the interface ignored. Each interface has one profile or one of those other outcomes. Profiles contain settings, while rules contain the selection.

A child profile inherits all parent values and replaces what it names. A bare profile accepts no offers; the shipped default profile supplies the friendly wired defaults. Network-dependent profile examples describe selection once the link and identity exist, not Wi-Fi association, which remains unfinished.

The interface and firewall read the same network labels, so naming or reclassifying a network can change both. Identification is not proof: writing Trust = home is your decision to accept that identification. netd's protected Status records report its findings; do not edit them.

netd and the kernel accept their own layers independently. A missing JOIN target can leave netd on its last good configuration while firewall changes still apply. DHCP and router discovery also need ordinary PNP allows; the baseline's rules are visible and deletable.

The interface-layer chapters cover parsing, generation validation, judgment and reconciliation.

Verdicts and effects #

REJECT works inbound and outbound. An outbound refusal can fail the local operation promptly instead of leaving it to time out. Where no refusal can be sent, it degrades to a counted drop; see Where a REJECT can speak.

Effects do not grant access. TAG marks a flow, COUNT contributes to a counter stream, and REPORT writes an audit event at its configured level. PROMPT currently has no handler transport and takes its fallback immediately. A rule containing only effects abstains from the verdict.

The laws #

Use these checks when a rule behaves unexpectedly:

• Backstop: an ingested empty packet forest drops everything, attributed to backstop; the interface backstop is IGNORE. Before any policy is loaded, generation 0 is permissive and reported as such.
• Absent facts: a condition on a missing fact is false, including missing tags and counter cells. Present is the explicit existence test.
• Exceptions: a matching child shadows its parent within that tree. Trees never shadow one another.
• Abstention: a triggered rule without a verdict hands the decision to the nearest ancestor with a direct verdict. That ancestor's full action list runs once; intervening abstainers do not run.
• Priority: highest wins. At equal priority, DROP beats REJECT beats PASS, and Refused beats Prohibited. An interface's verdict order is DOWN, IGNORE, JOIN; conflicting profile selections need correction rather than relying on rule order.
• Effects: triggered rules' effects run even when another rule wins. Matching uses the snapshot from before those writes. A count does not affect the same evaluation's threshold; a later packet can see it.
• Whole generations: malformed packet policy keeps the previous generation active. A registry write returning is not acceptance; run net policy wait before depending on the new rule.
• Tags: reads can only go upward through RawPacket < Packet < Flow. Downward reads are refused. Tags remain on a flow across policy changes.
• Flow scope: a flow is judged per local endpoint, then cached until a policy change or consulted time condition makes it stale. Loopback has two endpoints.
• Refusals: PNP does not filter its own generated refusal packets. Ordinary traffic, including echo, has no such bypass.

The full evaluation algorithm, generation ingestion and stores belong in the kernel technical reference; the reference keeps the authoring vocabulary and limits.

Rate limiting without a throttle verb #

PNP expresses a rate limit using a count, a view of that count, and a verdict. This example observes DNS queries and rejects queries from a source whose preceding count exceeds the threshold:

Rules\Packet\dns-watch     Protocol.Equal = udp, DstPort.Equal = 53
                           Actions = COUNT(dns)
Rules\Packet\dns-flood     Protocol.Equal = udp, DstPort.Equal = 53
                           Counter.dns(10s, SrcAddr).GreaterThan = 20
                           Actions = REJECT(Prohibited)

dns-watch counts and abstains. dns-flood reads the ten-second view before the current packet's count lands. Windows are approximations; check the counter view and its observed counts rather than treating this as an exact throttle. As counts age out, the condition stops matching.

Where things are visible #

• net status: interface verdict, selected rule/profile and refusal.
• net policy and net policy wait: kernel acceptance and enforcement.
• Network Manager: configuration and connection tests; read its Example data disclosures for firewall displays.
• PNP viewer: live verdict attribution, flows, listeners and counter tables on Experimental, with its safety warning observed.
• Event Viewer: ntfe.verdict.reported events requested by REPORT effects.

A packet using a cached sentence has no new evaluation event. Missing events are not proof that traffic passed; check the sentence and surfaced drop/refusal counters. The event-stream chapter describes the kernel records and loss accounting.

Use this page while editing profiles or rules. It covers the kernel's packet layers and netd's interface layer. Start with the safe profile workflow or firewall workflow if you are making a change rather than looking up syntax.

Writes take effect live and can interrupt remote access. Record the old values before editing. Check net status for accepted interface settings; for packet-policy changes, an administrator runs net policy wait and net policy. These are separate acceptance checks.

Profiles #

Profiles\<path> is how an interface stands on a network, named by a JOIN. A profile is a key with flat dotted values and no match block.

Inheritance. A subkey inherits every value of its ancestors and overrides those it names — per value name, wholesale: a list replaces a list, never appends. A present-but-empty value means none; an absent value means inherit. This is the same law as in Rules\: a subkey specialises its parent. A locally written profile may nest under one pushed by policy. Enabled = 0 makes a key and its subtree invisible.

Vocabulary. Bundles are the claims a network can make; each has an Offered that says whether to believe it. Every compiled default is "believe nothing, do nothing": a bare profile brings the link up and nothing else. Unknown value names refuse the generation.

The Dns bundle is provisional. Verify the effective scope with resolv status; see name resolution for exclusivity and fallback conditions.

The laws of JOIN, whatever the profile says: the executor owns every IPv4 and non-link-local IPv6 address on a joined interface, and only routes carrying its own protocol tag; the kernel's IPv6 link-local address is left alone; exactly one place decides what a router advertisement means (the executor; the kernel's own handling is off); a link-local address is dropped the moment a real lease arrives; IPv6 lifetimes follow the RFCs with the two-hour floor; Route.Metric defaults by kind; the network's RequestedAddress is asked for first; a manual change to a joined interface lasts until the next reconcile; the executor re-derives state on restart.

Registry layout #

Machine\System\Network
    Hostname                     REG_SZ           operator
    Readiness                    REG_SZ           netd: absent | link | addressed | routed
    Duid                         REG_SZ           shared: DHCPv6 identifier, hex
    Rules\
        CurrentReportingLevel    REG_DWORD 1..6   (optional; absent = 1)
        RawPacket\               the wire-side layer's forest
            <rule>\
        Packet\                  the per-packet layer's forest
            <rule>\              one tree root
                <exception>\     a subkey: narrower region, same laws
                    ...
        Flow\                    the flow layer's forest
            <rule>\
        Interface\               the interface layer's forest (netd's)
            <rule>\
    Profiles\                    how an interface stands on a network
        <profile>\               flat dotted values, see Profiles
            <derived>\           a subkey inherits and overrides
    Interfaces\<id>\             the inventory, one key per interface seen
        ClientId                 REG_SZ           shared: DHCPv4 client identifier
        Status\                  netd-only: Name, Kind, Mac, Path, Driver,
                                 Verdict, Rule, Profile, Readiness,
                                 Network, LastNetwork
    Networks\<id>\               one key per network stood on
        Name, Trust              REG_SZ           operator
        RequestedAddress         REG_SZ           shared: IPv4 to ask for next
        Status\                  netd-only: Kind, Server, Gateway, Router,
                                 Prefixes, DnsServers, LastSeen, LastInterface
    Dns\                         name resolution's machine values, see name resolution

A rule key's name is its attribution handle and may not contain \ or /. The kernel reads RawPacket, Packet and Flow; Interface is read by netd, the interface layer's executor (see Layers); any other layer key is ignored by both. The kernel also reads the inventory — each interface's Status Network and the Name and Trust on the record it names — as the network context of the packet layers. Shared values are written by netd when absent and may be set by the operator; Status keys carry a descriptor that lets only netd write, so a hand edit is refused rather than silently reverted.

Rule values #

The Rules key's own value #

Conditions #

A condition is a value named <Fact>.<Operator>. A rule matches when every condition holds; a condition over a fact the packet lacks is false (the absent-fact law).

Operators #

Integer values may be written as REG_DWORD, REG_QWORD, or as decimal strings; a list of integers is a REG_MULTI_SZ of decimal strings and ranges. Applying an operator a family does not support (GreaterThan on an address, Has on a port) refuses the generation.

Facts #

Address families are strict: an IPv4 pattern never matches an IPv6 address and vice versa, so 0.0.0.0/0 does not swallow IPv6.

A Flow fact is one that is identical for every packet of the flow. The per-packet facts marked "not a Flow fact" are legal in a Flow rule but never present there, so the condition never holds; the viewer flags it. Related, Start.* and the identity facts are the reverse: never present outside Flow. Interface.* facts are for the Interface layer. Network.Id, Network.Name and Network.Trust are also available in the packet layers, as the table above and network context describe. A packet-only fact in an Interface rule cannot match. For the kinds netd currently reports, see its interface classification. Tag.* and Counter.* do not exist at the Interface layer at all — there is no store behind them — and refuse the generation.

Who is at this end #

Local says what answers at this machine's end of a flow: a program (a socket some process owns — the identity the kernel stamped on it at the last act that committed it: creation, bind, listen, connect, accept, or an explicit restamp), the kernel itself (resets, ICMP errors, neighbour discovery, tunnel outers, kernel sockets), shared (inbound multicast or broadcast, delivered to every socket bound to the port — one flow, many receivers), or none (nothing listens; the stack will refuse it). Only a program has Local.* facts, so Local.User.Present = 0 is "no program stands here".

Identity is decided once, at the flow's first judgment, and kept for the flow's life. A service thread acting for a client is the client (the effective identity governs, as it does for files); a listener handed to another program is governed by the program that last committed it. SIDs are written as S-1-…; a user or group may instead be a well-known name, a service its name — the name is turned into the service's SID exactly as the service's token was minted, so the rule matches the token, not a string. A misspelt name refuses the generation rather than quietly matching nothing.

Counter views #

Counter.<name> reads the stream <name> that some rule's COUNT writes. In parentheses, in any order, at most one of each:

Examples: Counter.dns (total, global); Counter.dns(10s) (last ten seconds, global); Counter.dns(SrcAddr) (total, per source); Counter.dns(1h, SrcAddr+DstAddr) (last hour, per source–destination pair). A view over a stream that no rule anywhere writes refuses the generation; a stream nobody reads is fine. Windows are approximated by eight buckets, so a value can be up to an eighth of a window stale.

Actions #

Actions is a list of expressions. Names are case-insensitive; whitespace is ignored. A rule's actions may contain any mix; at most one verdict results (the strictest listed).

The three interface verdicts are legal only in the Interface layer, and that layer speaks nothing but them, NULL and REPORT; either way round refuses the generation. Their strictness order is DOWN > IGNORE

JOIN. JOIN must name a profile that exists (a path that names no key refuses the generation); naming a disabled profile makes the rule abstain, as if its action were NULL.

Unknown action names, wrong argument counts, negative or non-integer operands, unminted REJECT kinds, and a TAG operation other than the three above all refuse the generation.

Where a REJECT can speak #

Everywhere, for IP traffic. Inbound, the refusal goes back to the peer. Outbound, the answer the peer would have sent is delivered to the local socket, so the program fails at once — a TCP connect, or the next call on a connected UDP socket — with connection refused for Refused (a reset for TCP, a port unreachable for UDP and the rest), and for Prohibited with host unreachable over IPv4 or permission denied over IPv6. Only a packet with no refusal vocabulary — ARP and other non-IP frames, a broadcast or multicast destination, a fragment — is applied as a DROP and counted as degraded; the verdict event still says REJECT and names the kind. The refusals PNP sends pass its own seats unjudged.

In the Flow layer a REJECT sentence answers every later packet of the flow the same way, so a retransmitted SYN gets its reset too — from the sentence, or, where refusing the first packet took the new flow with it, from a fresh judgment of the retransmit as a new flow. When the refused packet belongs to an established TCP connection (a flow re-judged after a policy change or at a time edge), the other end is torn down as well: the refused packet is turned into a reset and sent where it was going, so both sockets fail at once. New flows and UDP have no far end to tear down.

Layers #

A rule conditioned on a fact its layer never has is legal but can never match; the viewer flags it. A Packet or RawPacket rule that reads a tag a Flow rule writes is a downward read and refuses the generation.

The interface layer #

Rules\Interface is the fourth layer, and the one the kernel does not read. Its subject is an interface, not a packet: a rule is judged for each interface (loopback excepted) whenever an interface appears or changes, whenever a network is identified on it, and whenever a generation lands. Its executor is netd, which builds and judges the forest with the same engine the kernel uses, so a rule means the same thing in every layer.

The collation laws are the packet layers': highest priority wins, ties go to the strictest verdict, a subkey is an exception, an abstaining rule hands up its parentage. One case has no packet-layer analogue: two rules tied on priority naming different profiles for one interface. That is a conflict, not a choice. On a runtime reload, a tie affecting an existing interface refuses the generation; net status names both rules. At startup, or when a new interface appears, that interface is ignored with a tie warning instead. See netd's conflict handling.

Executor independence. A generation is one registry state read by two executors. Each validates and refuses its own layers on its own: a dangling JOIN keeps netd on its last good interface forest and never stalls the firewall, and a bad Flow rule never stops an interface joining.

The executor's own traffic. Joining needs netd to send and receive DHCP and router discovery, and PNP grants that nothing implicitly: the permission is the dhcp-client, icmpv6-housekeeping and dhcpv6-client rules of the baseline below, ordinary and deletable. netd cannot yet read the verdict stream to name a rule that refused it (the stream has one reader, the viewer); net status reports an unanswered request as a warning.

Sentences #

A sentence caches the Flow verdict. Later packets use it without a new evaluation event until the policy generation changes or a consulted Time.* condition changes. A fresh judgment runs the effects again. Start.* stays fixed and does not expire the sentence. Loopback has one sentence per local endpoint and must pass both.

For exact expiry rules (including daily reevaluation of calendar fields), cache-allocation failure and event behavior, see The Flow layer and Evaluation. Those chapters retain the implementation detail; use this section to choose live-time versus connection-start conditions.

The network context #

Which network the machine is on is one fact, told once. netd identifies the network on a link and writes the record's id to the interface's Status Network; the kernel reads that, and the Name and Trust on the record it names, into a table keyed by interface, and every traversal carries its interface's entry as Network.Id, Network.Name and Network.Trust. So the three facts the interface layer conditions on to choose a profile are the same three a packet rule conditions on to open or close a door, read from the same record:

Rules\Flow\no-ssh               Direction.Equal = in
                                 Protocol.Equal = tcp, DstPort.Equal = 22
                                 Actions = DROP
Rules\Flow\no-ssh\home          Network.Trust.Equal = home
                                 Actions = PASS

is "SSH answers only on the network I called home", and it is true on every interface at once: a wired card at home and a radio at a cafe each carry their own context, and a flow sees the context of the interface it actually uses.

The facts are absent on an interface no network has been identified on — before the first offer, after the carrier goes, on the loopback, on an IGNOREd or DOWN interface — so a rule about a network is simply false there and the rules that say nothing about networks apply unchanged: an unrecognised network gets the baseline, never a door opened for a network that is not there. Network.Id.Present = 0 is the honest "not on any known network".

A change of network is a change of policy. When the context of any interface changes — a network identified, the carrier lost, the operator editing Trust — the kernel publishes a new generation, and every flow is re-judged on its next packet exactly as after a rule change: a connection the new context forbids is refused then, with the same REJECT teardown, and one it now permits goes through. netd rewriting an interface's Status without changing its network costs nothing; a generation is published only when the table differs. The context is not policy and cannot refuse a generation: a record the kernel could not read is an interface without a context.

Trust is the operator's word, exactly as written, with no vocabulary yet: home, corporate, untrusted are conventions, and a rule that conditions on it is stating that the operator accepts the identification. It is not evidence that the network has been authenticated.

Limits #

These kernel limits can cause a refused generation or a counted refusal. netd has its own registry-read depth limit; do not assume a packet-layer limit describes every executor.

The development baseline #

The rules below illustrate the baseline seed policy, not the complete policy of every image. The compiled-in backstop is DROP in every layer; each allow rule is a visible, deletable exception.

Service-specific seeds add their own rules. The Experimental edition's gxwi-network seed admits GXWI on TCP 7780; see the desktop quick start. Inspect the configured rules and verify kernel acceptance with the policy-checking workflow before deciding which services a machine exposes. The development PNP viewer uses port 8081 and needs its own restricted access path.

Rules\RawPacket:

Rules\Packet — passes every tracked packet through to Flow, and the untracked housekeeping a host needs:

Rules\Flow — the decisions:

An inbound flow with no matching allow rule meets the Flow backstop, once, on its first packet; untracked inbound packets with no matching allow rule meet the Packet backstop.

Profiles and Rules\Interface — every wired interface joins the network it is plugged into, taking what it offers:

Wireless is not in the baseline until a supplicant exists. An interface no rule speaks for meets the Interface backstop, IGNORE.

Worked examples #

These blocks describe registry layouts, not shell commands or complete replacement policies. Adapt the addresses, ports, names, priorities and profile paths to your machine. A JOIN target must already exist; examples are evaluated alongside every existing rule, so inspect the baseline and competing priorities before applying them. Preserve a recovery path, then verify accepted policy and an actual connection afterwards.

An exception under a broad rule — drop all inbound except SSH from the LAN, and tell other SSH sources that policy said no:

Rules\Packet\no-inbound            Direction.Equal = in
                                   Actions = DROP
Rules\Packet\no-inbound\ssh        DstPort.Equal = 22
                                   Actions = REJECT(Prohibited)
Rules\Packet\no-inbound\ssh\lan    SrcAddr.Equal = 10.0.0.0/8
                                   Actions = PASS

A flow tag read on the reply — mark DNS queries, report on the replies of marked flows:

Rules\Packet\tag-dns        Protocol.Equal = udp, DstPort.Equal = 53
                            Actions = TAG(dnsq, Add)
Rules\Packet\tagged-reply   Protocol.Equal = udp, SrcPort.Equal = 53
                            Tag.dnsq.GreaterThan = 0
                            Actions = REPORT(4)

Byte accounting per interface — count outbound bytes and refuse a source that pushes more than 100 MB in a minute:

Rules\Packet\egress-bytes   Direction.Equal = out
                            Actions = COUNT(egress, Length)
Rules\Packet\egress-cap     Direction.Equal = out
                            Counter.egress(1m, SrcAddr).GreaterThan = 104857600
                            Actions = DROP

A connection-level allow — let the machine connect out, accept SSH in from the LAN, and refuse every other inbound connection with a reset, each decided once per flow:

Rules\Flow\outbound-ok      Direction.Equal = out
                            Actions = PASS
Rules\Flow\inbound          Direction.Equal = in
                            Actions = REJECT
Rules\Flow\inbound\ssh-lan  Protocol.Equal = tcp, DstPort.Equal = 22
                            SrcAddr.Equal = 10.0.0.0/8
                            Actions = PASS

A curfew that lets downloads finish — no new outbound connections between 22:00 and 06:00 UTC, existing ones run on:

Rules\Flow\curfew           Direction.Equal = out
                            Start.Hour.Equal = 22-23, 0-5
                            Priority = 10
                            Actions = REJECT(Prohibited), REPORT(3)

Written with Time.Hour instead of Start.Hour, the same rule cuts every running outbound connection at 22:00 — on its next packet, with an ICMP admin-prohibited — and the report says which rule did it.

A static server as an exception — every wired interface takes what the network offers, except the card in slot 3, which stands in a derived profile that changes only the address and the way out:

Profiles\default                 Address.Offered = 1, Address.LinkLocal = 1
                                 Route.Offered = 1, Dns.Offered = 1
Profiles\default\db1             Address.Offered = 0, Address.Static = 10.0.0.5/24
                                 Route.Offered = 0, Route.Gateway = 10.0.0.1
Rules\Interface\wired            Interface.Kind.Equal = wired
                                 Actions = JOIN(default)
Rules\Interface\wired\db1        Interface.Path.Equal = pci-0000:00:03.0
                                 Actions = JOIN(default/db1)

default/db1 still inherits Dns.Offered, but that does not prove a server is available after offered address acquisition stops. Check resolv status and pin Dns.Servers if this configuration needs it.

The laptop — a network-dependent selection example, not a working Wi-Fi association procedure. A supplicant and wireless network-name identification are unfinished; the baseline leaves wireless unmanaged. Once the link and identity exist, rules can choose among three profiles:

Rules\Interface\radio            Interface.Kind.Equal = wireless
                                 Actions = JOIN(untrusted)
Rules\Interface\radio\home       Network.Name.Equal = palfrey-home
                                 Actions = JOIN(home)
Rules\Interface\radio\office     Network.Trust.Equal = corporate
                                 Actions = JOIN(corp)

Network.Name and Network.Trust are what the operator wrote on the record under Networks\; until a network has been identified on the link they are absent, so the radio stands in untrusted first. The same two facts open the doors, in the flow layer:

Rules\Flow\no-inbound           Direction.Equal = in
                                 Actions = DROP
Rules\Flow\no-inbound\at-home   Network.Trust.Equal = home
                                 Protocol.Equal = tcp
                                 DstPort.Equal = 22, 5900
                                 Actions = PASS

Walk into the cafe and the record on the other side of the radio is a different one, with no Trust written: the exception is false, the parent drops the SSH traffic on its next packet. DROP is silent; the reset behavior described for REJECT does not apply to this example.

A card that stays dark, and one another program owns:

Rules\Interface\dead-card        Interface.Id.Equal = 3f2a1b8e-…
                                 Priority = 100
                                 Actions = DOWN
Rules\Interface\tap              Interface.Equal = tap0
                                 Actions = IGNORE

Connection rate limiting — count connections, not packets, by counting in the flow layer:

Rules\Flow\conn-count       Direction.Equal = in, Protocol.Equal = tcp
                            Actions = COUNT(conns)
Rules\Flow\conn-flood       Direction.Equal = in, Protocol.Equal = tcp
                            Counter.conns(1m, SrcAddr).GreaterThan = 100
                            Actions = DROP

Experimental editions run pnpd, the observation and authoring surface of Peios Network Policy (PNP). Browse to port 8081 on a running machine and you are looking at its network life five ways at once: every frame on the wire, the firewall engine's verdict on every evaluation, the policy that produced those verdicts — editable in place — every live flow with the sentence the flow layer gave it, and the counters that policy is keeping.

pnpd is development-phase tooling, and deliberately not part of enforcement: the kernel reads its policy from the registry itself. pnpd watches, explains, and writes the registry like any other author.

The Experimental edition is a development-machine image, not a production deployment profile. Its pnpd service listens on every interface and does not authenticate viewers; a viewer can inspect captured traffic and change network policy. Run it only on a trusted development network, and expose port 8081 to the host through a loopback-only forward. Do not deploy the Experimental image or expose pnpd to an untrusted network.

Reaching it #

On QEMU user-mode networking, forward the port: make boot NET='-nic user,hostfwd=tcp:127.0.0.1:8081-:8081', or drive.py --hostfwd tcp:127.0.0.1:8081-:8081, then open http://localhost:8081.

Start with the question #

After narrowing the interface, protocol, address or port, compare the flow's rule with the policy and the native listener identity. Do not infer delivery from a captured packet alone. Read Honesty rules before treating a missing frame or badge as evidence.

The wire tab #

Every frame on every interface, both directions, decoded in the browser: Ethernet, ARP, IPv4/IPv6, TCP, UDP, ICMP, ICMPv6 (router and neighbor discovery spelled out), DNS, DHCP and DHCPv6. Each packet expands into a per-layer field view and a hex dump; filter by protocol or free text.

Packets carry a verdict badge — PASS, DROP, or REJECT — painted from the engine's own event stream (/dev/peios-ntfe), never inferred: each badge names the rule that decided, as a registry path like no-inbound/ssh-from-lan, plus the layer and standing seat. A REJECT badge also names the story it told the sender: REJECT·Refused (nothing is listening — a TCP reset or ICMP port-unreachable) or REJECT·Prohibited (policy refused you — ICMP admin-prohibited). A verdict with no matching tap packet renders as its own row, slotted into the timeline by its timestamp — for an outbound drop that row is the only possible trace, because the transmit tap stands after the filter and never saw the packet.

A packet answered by a flow's cached sentence carries no badge of its own: there was no evaluation. The sentence is on the flows tab.

The header shows the engine itself: the policy generation, whether it is enforcing (generation 0 boots loudly permissive), the running pass/drop/reject counts, and the machinery stores' own accounting — tag writes, counter emissions, reports emitted to the KMES event stream, live counter cells, the active reporting level, flows judged, and refusals sent. Hover a count for what the store refused or what it did instead (a flow past its tag tripwire, a table at its key cap, a packet lacking a view's key fact, packets answered from a cached sentence, flows re-judged after a policy change or at a time edge, a REJECT with nothing to send): refusals are counted, never silent. A failed policy ingestion shows as a banner: the previous generation stays active. Correct the named failure and verify a new generation rather than assuming the saved edit is active.

The policy tab #

The rule forest under Machine\System\Network\Rules, rendered as nested cards: conditions, actions, priority, exceptions indented under their parents. Rules can be edited, given exceptions, created, and deleted in place; every save commits in one registry transaction, the kernel re-walks the subtree, and the generation bump — or the refusal — appears in the header within a second. The backstop is compiled-in DROP, so everything in the tree is a visible, deletable permissive statement.

The flows tab #

Each flow shows its owner: the program at this machine's end — its comm and pid, and the service or principal it runs as — or what stood there instead (the kernel, a shared receiver, nobody). A loopback flow shows both ends. Service names are resolved from the service definitions in the registry; a SID the viewer cannot name is shown as is. Hover a verdict badge to see the same for the judgment that produced it.

Every flow conntrack is tracking, refreshed while the tab is open: the protocol and both ends (originator first), which side opened it, the interface it was judged on, conntrack's state and remaining lifetime, the flow's age, packets and bytes in each direction, and the flow layer's sentence — the cached verdict, the rule that gave it (resolved from the policy by the same hash the kernel keys it by), the generation that judged it, and a ⏱ when a consulted time condition will expire it. A loopback flow shows two sentences, one per local endpoint. Tags the flow carries are listed by name where the policy mentions them.

A missing sentence can mean permissive operation or no Flow policy, but it can also mean the kernel could not allocate storage for the sentence and judges each packet instead. Check flow_uncached; see The Flow layer.

The listeners tab #

What the machine is prepared to receive right now, without waiting for a packet: every TCP socket that is listening and every UDP socket that is bound, by protocol, address and port, with the program that owns it — comm, pid, and the service or principal it runs as — or "kernel" for a socket the kernel opened. Wildcards show as *; a member of a SO_REUSEPORT group is marked as one. This is the attack surface as a list, and the first place to look when a rule about a service does not match: the stamp shown here is the one the Flow layer will read.

The counters tab #

Every cell of every counter table the policy materialized, refreshed while the tab is open. COUNT(name) in a rule emits into a stream; every Counter.name(window, key) some rule reads is a table here — one block per (stream, key), one row per key the wire has produced, one column per window the table answers plus the cumulative total and the age of the last write. Windows are eight-bucket sliding approximations, so a value can run up to an eighth of a window stale. A stream nobody views has no table and nothing to show.

Honesty rules #

The viewer never silently lies:

• Drops are confessed — both the tap's kernel drop count and the verdict ring's overwrite count are surfaced.
• Its own traffic is counted, not vanished. pnpd excludes its own HTTP flow from the packet ring and shows how many frames that hid. The viewer description says its verdicts remain visible, while the kernel manual's event-stream chapter says pnpd hides and counts its own-port verdict events too. Do not rely on complete visibility of the viewer's own connection when diagnosing it.
• Placement is stated. Inbound frames are captured before the IP stack; outbound as handed to the driver. Verdicts come from the engine's seats, which stand elsewhere — the two views disagreeing is a diagnostic, not a bug to hide.

Network Manager lets you inspect and change this machine's networking and firewall. Open the launcher and type network. Start in Overview to find the affected interface and the profile it uses. Down the side are three groups:

• Network: Overview, Networks, Profiles, Profile rules and DNS.
• Firewall: Exposure, Rules and Activity.
• System: Port reservations, Auditing and Advanced.

What it shows comes from netd, resolvd, the kernel and the registry under Machine\System\Network. What it changes it writes to the registry, as you, the same as you could with reg. Nothing else holds the network's settings: see Networking for how they become real.

Choose a task #

Read the change and access rules below before applying a change, especially through a remote desktop connection. A Connected summary reports a route; it does not prove the Internet or a particular service is reachable.

Making a change #

Every change is checked before it is written. If the machine would refuse it, nothing is written, and the status line says why.

A change that would block a connection to this desktop that is open now, yours or anyone else's, asks first: This change would disconnect you, with the connections it would cut. Cancel is the safe answer. Apply anyway makes it.

Some changes are kept only when you say so. A bar across the top asks Keep this change?, with Keep and Undo, and undoes the change by itself after 30 seconds unless you keep it. The countdown runs on the machine, not in your browser, so if the change did cut you off, you need do nothing: the previous settings come back when it ends. The bar follows:

• saving or deleting a firewall rule or a profile rule;
• changing a cell on Exposure;
• applying a profile that an interface carrying a desktop connection uses;
• renaming a network, or changing its trust level, while a desktop connection is on it;
• any change made with Apply anyway.

Making another of these while the bar is up keeps the change before it. Other changes, such as DNS settings, static names, port reservations, the audit level and new profiles, are made at once, and there is no Undo. Record their previous values before editing if you may need to restore them. These changes are live; no reboot is needed.

After applying, read Overview for the actual interface result and test the name or connection you intended to use. The status line along the bottom says what the last change did, and that the firewall's policy is in force, with its generation. If the kernel refused the newest rules, it says so, and that the previous generation still stands.

What you may see and change #

What you may change is what the registry lets you write, key by key, so it is asked of the machine, not guessed from your groups. Where you may not, a section is shown read-only, with the reason said once at the top: You can see these settings. Changing them needs an administrator. Exposure and Activity are for administrators only, and say so instead.

Permissions… opens the permissions editor. It shows the same things read-only to anyone who may not change them.

Network Manager reads the machine again every two seconds, and its settings whenever something else changes them in the registry.

Overview #

Along the top is a summary: whether the machine is Connected (it has a way out), Local network only, Connecting or Offline, and its IPv4 address, gateway, DNS servers and hostname.

Under that is a map. Each interface is a line from this machine to the network it is on, with the profile it uses on the wire between them, and the internet at the end when there is a route out. An interface no rule assigns a profile to is Not managed. Wi-Fi isn't supported yet, so a wireless interface is always shown that way.

Select an interface to see it in full:

• its state and speed, with Renew lease to ask the DHCP server for a fresh lease, and Reapply to make every interface match its profile again;
• its Addresses, each with where it came from: DHCP, Static, SLAAC, Temporary (an IPv6 privacy address) or Link-local, and Deprecated for one kept only for connections already using it;
• its gateway and route metric, its DNS servers and search domains, its MTU and MAC address;
• its Traffic, received and sent, over the last minute;
• its Configuration: the profile it uses, the rule that chose it, and the network it is on;
• its Routes;
• its DHCP lease, as a bar from when it was obtained to when it expires, marked where the machine starts to renew it and then to rebind. Older versions of netd don't report a lease's times, and then the lease is shown as three stages instead, Bound, Renewing and Rebinding, with the current one lit.

An interface that isn't managed has Assign a profile, which starts a profile rule for it.

If netd isn't answering, the page says so and shows what netd last recorded. If netd refused the newest profile rules, it says why, and that the last rules that worked still apply.

Networks #

Networks lists every network this machine has connected to: its name, its trust level, what identifies it (its DHCP server or router), its subnet, and when it was last connected. A network seen for the first time is marked New network until you give it a name and a trust level.

Select one to change:

• its Name;
• its Trust level: Private, a network you control, or Public, any other network. A network never given one is offered as Public;
• its Preferred address, an IPv4 address the machine asks for first. The DHCP server may give another.

Rules can name a network and its trust level, so changing either can change what is reachable or which profile an interface uses. Before you save, What this changes lists each listening service and interface that would be treated differently.

Profiles #

A profile says how an interface stands on a network: what it takes from the network and what it sets for itself. A profile inside another inherits every setting from it and changes only what it sets. See Configuring profiles for what each setting means.

On the left is the tree of profiles, with the interfaces using each. Under it, New profile makes one at the top, Inside makes one inside the selected profile, and Delete removes the selected profile and the profiles inside it. A profile a rule still names can't be deleted.

On the right, the selected profile is summed up in five boxes, Addressing, Gateway, DNS, Hostname and MTU, each coloured by whether it comes from the network, is set here, or both. Below them is every setting, with a column for each profile from the top of the tree down to the selected one. The selected profile's column can be changed; the others show what it inherits. Result gives the value that applies, and which profile it comes from, or built in when none sets it. Choose Inherit (or Default at the top of the tree) to stop setting a value here.

Changes wait in a bar, 1 change not applied, with Discard and Apply. The bar says which interfaces the change will apply to at once, or why the machine would refuse it. Review that list before Apply. Changing an active profile's resolved settings restarts its interfaces' address clients, so a change can interrupt connectivity even when the setting edited is DNS. Check live Overview afterwards.

Profile rules #

Profile rules says which profile each interface uses. Now lists each interface, the profile it uses, and the rule that chose it. Under that are the rules. The most specific rule that matches an interface applies; priority breaks ties. An interface no rule matches is left unmanaged.

A profile rule's action is Use profile (with the profile), Unmanaged (leave the interface exactly as it is), Disabled (keep it switched off) or None. Rules are written and changed as on the firewall's Rules page. Before you save, What this changes lists each interface that would use a different profile, and a rule that would tie with another at the same priority is marked.

DNS #

Look up a name asks resolvd for an IPv4 (A) or IPv6 (AAAA) address, and shows the way the question went: the static names, the cache, the interface it was routed to and why, the server that answered, and the answer, or No such name or No answer.

Where names go shows which interface's servers each name is sent to. Check exclusive scopes, matching search domains and the default route; use the actual lookup result to confirm the choice. An exclusive scope needs an address and at least one server to take all queries. Since resolvd started counts the questions asked, how many the cache answered, and how many went to servers and failed. Flush cache empties the cache.

Under Settings are the Fallback servers, used only when no up interface has DNS servers, and extra Search domains, tried after each interface's own. Static names are answered before DNS is asked. See Name resolution for how resolvd decides.

Exposure #

Exposure answers one question: which services on this machine can be reached, and from where. Each listening service is a row, with Any other port at the end for everything else. The columns are Private networks, Public networks and This machine. Each cell is Allowed, Limited (allowed, with exceptions that block some of it), Blocked, or Not listening when the service only takes connections from this machine. Under each is the rule that decided it.

Each cell is judged by your real rules, as a new connection from a network of that trust level. Which services are listening is example data for now.

Select a cell to see why: the same explanation as Test a connection on Rules. Its button changes it in one step, Allow from public networks or Block from private networks, for example, by the smallest change to the rules that does it: narrowing a rule to the other trust level, turning it off, or adding a rule that allows the port. Where no one rule decides a cell alone, you are told to change it in Rules.

Rules #

Rules holds the firewall's rules, in three tabs:

• Connections, judged once per connection. Most rules belong here.
• Packets, every packet, after connection tracking.
• Frames, before connection tracking. Rarely needed.

Exceptions sit under the rule they narrow. Order has no effect: the highest priority wins, and a tie goes to the stricter action. Traffic no rule allows is blocked. Rules that come with Peios or its packages are marked Built-in. Network policy explains how rules decide.

Select a rule, or New rule, to write one:

• its Name, Priority and whether it is On;
• what it Matches, as conditions on facts such as the source address, the port or the network's trust level;
• its Action: Allow, Block (discard without a reply, so the sender sees a timeout), Reject (refuse, and reply "connection refused" or "administratively prohibited") or None (decide nothing and let the rule it is inside decide);
• Also: Count, Tag, Audit and Prompt, which run alongside the action;
• its Exceptions, with Add exception.

The rule is checked as you write it. A condition that can never match, a missing value, and anything the machine would refuse are marked where they are, and it can't be saved until they are fixed. What this changes lists each service whose reachability would change.

Test a connection describes a connection, incoming or outgoing, its protocol, the other machine's address, the port, the network and the service, and shows what the firewall would do with it: each layer it passes, in the order the kernel judges them, which rule decides, and every rule's part in it. There are ready-made examples, such as Your session and SSH from a café. A blocked incoming connection offers Make an allow rule….

Activity #

Activity shows what the firewall has been deciding: a chart of new connections a minute over the last fifteen minutes, allowed, rejected and blocked. Under it, Connections lists the connections open now, in or out, with the network, the result and the rule that decided it; a connection to this desktop is marked Your session. Select one to see how it was decided. Counters shows each count a rule with a Count action keeps, which rules write and read it, and, by source, whether it is over a rule's limit.

All of it is example data for now, judged by your real rules.

Port reservations #

A port reservation says who may listen on a port. Each port uses its narrowest reservation, and a port without one uses the default. A bar draws the reservations across the ports from 1 to 65,535. The table lists each, with who can listen; Permissions… changes that. To add one, write it as protocols and ports, such as tcp:8443 or tcp,udp:5000-5100. A new reservation starts with only SYSTEM and Administrators allowed to listen.

Check a port says whether a program running as SYSTEM, an administrator, a standard user or one of Peios's services could listen on a port, and which reservation decides. Who may connect to the port is the firewall's to say, on Exposure. See Port reservations for how the kernel checks them.

Auditing #

A rule with an Audit action writes an event each time it decides, at a level from 1 to 5. Record events from level chooses the lowest level recorded: 1 records everything, 5 only the most severe, and Off nothing. Rules that audit lists each such rule, its level, and whether it is recorded.

Recorded events are in Event Viewer, as ntfe.verdict.reported events. Recent events here is example data for now.

Advanced #

DHCP identity shows the DUID this machine gives DHCP servers, and each interface's Client ID, which is derived from the DUID when it is empty. A client ID is written as bytes in hex, such as 01:52:54:00:12:34:56.

Access says who may look at and who may change netd's and resolvd's settings. Permissions… beside each opens it in the permissions editor. The hostname is shown here, and changed in System Settings.