AtomOS Docs

Appearance

Networking, firewall, and certificates ​

AtomOS guests attach to a Linux bridge (default name br0) so virtual NICs share the same L2 segment as your physical or VLAN-tagged network. Management traffic — SSH, Electros HTTPS to the host APIs, storage client paths, and cluster services — should use clear, documented paths that survive bridge changes.

This page covers bridge design, NetworkManager behavior, firewalls, multi-NIC layouts, TLS trust, and troubleshooting. For 802.1Q tagging, see VLANs. For port numbers, see Install & CLI reference.

Concepts ​

TermMeaning in AtomOS deployments
Management NICInterface (or VLAN) used for SSH, patching, and Electros → host HTTPS
Guest / data NICPhysical port enslaved to br0 (or your chosen bridge) for VM traffic
Bridge (br0)Linux bridge; guest vNICs connect here
Default routeMust remain valid after bridge work; cloud broken IPv6 routes are a common install failure

AtomOS 0.9 and HTTPS

From the published AtomOS 0.9 milestone, host services speak HTTPS by default. Plan certificate SANs, Electros fingerprint trust, and peer --get-certificate flows before production cutover — Feature availability.

When hardware provides two or more NICs, prefer:

  1. Management — stable IP for SSH and Electros targets; not moved onto the bridge unless you have out-of-band recovery.
  2. Guest / data — NIC (or bond) attached to br0 for VM traffic.
  3. Storage / BMC (optional) — dedicated networks for iSCSI/NFS, replication, or IPMI/iDRAC/iLO.
mermaid
flowchart TB
  subgraph host["AtomOS host"]
    MGMT[mgmt NIC — SSH / Electros HTTPS]
    BR[br0 — guest bridge]
    VM1[VM vNIC]
    VM2[VM vNIC]
    BR --> VM1
    BR --> VM2
  end
  SW1[To admin / Electros subnet]
  SW2[To guest VLAN / access switch]
  MGMT --> SW1
  PHY[Physical NIC enslaved to br0] --> BR
  PHY --> SW2

Electros typically registers the IP address it uses to reach the host — often management, sometimes an address on the guest segment if that is your standard. Document which address is in the TLS certificate SAN list.

Bridge setup (atomos-cli) ​

Initial install may prompt for a NIC and create br0 via NetworkManager. To run the wizard later:

bash
sudo atomos-cli --bridge-setup
sudo atomos-cli --verify-network

Remove or rework a bridge only with a plan:

bash
sudo atomos-cli --delete-bridge

Bridge safety (read before running) ​

SSH drop risk

Enslaving the only NIC that carries your SSH session to br0 without moving the management IP correctly can disconnect you immediately. Always have BMC/console access and a tested rollback before bridge changes on production hosts.

RiskMitigation
Lost SSHUse BMC; keep management on a separate NIC or confirmed bridge IP
Wrong default gatewayCapture ip route and nmcli connection show before changes; validate after with --verify-network
BMC on shared portSome servers share NICs with BMC — confirm cabling and which port is enslaved
Cloud IPv6 default routeRun --verify-network; fix broken provider routes before install/update
Guest outageSchedule bridge work; expect brief L2 disruption

Validate before:

bash
ip -br addr
ip route
nmcli device status
nmcli connection show

Validate after:

bash
sudo atomos-cli --verify-network
ip -br addr
ip route
ping -c2 GATEWAY_IP

Recovery (generic Linux): from console, use NetworkManager to revert the bridge connection or restore a known-good connection profile; then restart networking cautiously. Exact profile names depend on your host — compare with pre-change notes.

NetworkManager principles ​

AtomOS bridge wizards on RHEL-family hosts typically use NetworkManager (nmcli). Principles:

  • A bridge connection owns the IP address that guests share at L2; the slave NIC is often no IP (or legacy patterns vary — inspect nmcli).
  • Do not hand-edit connection files while atomos-cli --bridge-setup or install wizards are running.
  • Prefer atomos-cli --bridge-setup for the initial AtomOS bridge; use labeled nmcli examples below only when you understand the resulting profile names on your host.

Labeled examples only

The nmcli snippets in this guide are illustrative AlmaLinux/RHEL patterns. Interface names (eno1, br0) differ by machine. Run nmcli connection show first; wrong names can isolate the host.

Example — inspect existing bridge (safe, read-only):

bash
nmcli device status
nmcli connection show br0 2>/dev/null || nmcli connection show | grep -i bridge
bridge link show

For VLAN creation on an existing bridge, see VLANs — coordinate switch port mode (access vs trunk) with host tagging.

Firewall ​

AtomOS exposes service listeners documented in Application ports. Restrict inbound to:

  • Electros and operator subnets (HTTPS client/cluster/compute/storage TCP paths you use)
  • Peer AtomOS hosts (cluster UDP/TCP and storage replication paths on your topology)
  • Backup infrastructure (if it pulls from vault paths over the network)
bash
sudo atomos-cli --fw-info

Use firewalld (or your site standard) to default deny and allow only required sources. UDP cluster/compute ports are not substitutes for TCP APIs — open both only when traffic analysis or ss -tulpn shows listeners you need externally.

Guest traffic through br0 is usually forwarded/filtered at the hypervisor or upstream switch, not by reusing the same rules as management SSH.

Multi-NIC and routing ​

PatternUse case
Mgmt + guestDefault recommendation
Mgmt + guest + storageSeparate iSCSI/NFS/replication
Single NICLab only; bridge bears management + guest — highest risk
Bond on guestLACP to switch for guest uplink; management stays off bond

Policy routing (multiple default routes, VRF, source-based routing) is site-specific. If Electros must use a non-default source IP, ensure that IP is in the TLS certificate and registered as the target address.

TLS certificates, fingerprints, and peer trust ​

From AtomOS 0.9, generate a certificate that includes every IP and DNS name clients and peers use:

bash
sudo atomos-cli --generate-cert
sudo atomos-cli -ra

Show the local fingerprint:

bash
sudo atomos-cli --show-fingerprint

Electros trust ​

Electros (from v3.1.6+) exposes a trust host action on Cloud Targets when fingerprint approval is required. Compare the UI value with --show-fingerprint on the host before accepting. New targets prompt on first contact. Details: VMs & Electros.

Trust between AtomOS hosts ​

Peers that call each other over HTTPS must mutually trust certificates. On the host that must trust a remote peer:

bash
# Replace with the peer address you reach over the intended network path
PEER_IP="10.0.0.11"
# Use compute or storage to match the peer service role
sudo atomos-cli --get-certificate "$PEER_IP" compute

Confirm the fingerprint, save when prompted, and repeat for each IP peers use (management, storage network, cluster network). Use storage when pinning storage-service certificates.

Certificate verification should remain enabled in production (--set-cert-verify). Disabling verification is a break-glass diagnostic only.

Cloud and provider networking ​

On CSP instances:

bash
sudo atomos-cli --verify-network

Confirm IPv4 (and IPv6, if used) default routes reach package mirrors and Elemento endpoints. A provider-injected broken IPv6 default route is a common failure mode during install and --update.

Use cloud install type when prompted — Install AtomOS.

Troubleshooting quick reference ​

SymptomChecks
Electros cannot connectTarget IP, HTTPS cert SANs, fingerprint trust, firewall TCP to client/compute ports
Guest has no DHCPBridge slaves, upstream switch port, VLAN mismatch (VLANs)
Host unreachable after bridgeConsole in; restore NM profile; see bridge safety table
Peer storage/compute errors--get-certificate both directions; --status; cluster secret consistency (Security)
Works on loopback onlycurl -vkI https://127.0.0.1:7701/ — then compare with external path and firewall

Structured runbooks: Troubleshooting. Command cheat sheet: Diagnostic commands.