Advanced networking

Eryph provides enterprise-grade virtual networking through OpenVSwitch and OVN, supporting overlay networks, VLANs, and advanced configurations on all Windows versions.

Network Architecture

CopyPhysical Adapters → Network Providers → Virtual Networks → VM Connections

Network providers define physical connectivity and IP pools. Virtual networks (configured per project) use these providers for isolation. See Project Networks for virtual network configuration.

Network Provider Types

NAT Overlay - Perfect for development. Zero configuration, automatic NAT, built-in services. Catlets only accessible from host.

Overlay - Enterprise virtual networking. Full isolation between projects, built-in DHCP/DNS per project, VLAN support. Small performance overhead from encapsulation.

Flat - Direct Hyper-V networking at full speed with no overhead. Best when you have existing DHCP/DNS infrastructure or need maximum performance. Trade-off: you manage all network dependencies, no project isolation.
Without a subnet on the provider, catlets get their IP configuration from an external DHCP server. With a subnet default on the provider, eryph assigns static IPs from its pool default and configures them in the catlet with cloud-init (see flat network).

Configuration Commands

Copy# Import new network configuration
eryph-zero networks import --inFile network-config.yaml

# Sync/repair network state  
eryph-zero networks sync

Import validates configuration, creates OVS bridges, configures Hyper-V switches, and sets up NAT. Sync repairs drift and reconnects adapters.

Add --json to get the output in JSON lines format for automation; this also implies --non-interactive.

Network Provider Configuration

Default NAT Overlay (Zero Config)

Copynetwork_providers:
- name: default
  type: nat_overlay
  bridge_name: br-nat
  subnets:
  - name: default
    network: 10.249.248.0/22
    gateway: 10.249.248.1
    ip_pools:
    - name: default
      first_ip: 10.249.248.10
      last_ip: 10.249.251.241

Overlay Network

Copynetwork_providers:
- name: production
  type: overlay
  bridge_name: br-pif
  adapters: ['Ethernet 2']
  subnets:
  - name: default
    network: 172.16.20.0/24
    gateway: 172.16.20.1
    ip_pools:
    - name: default
      first_ip: 172.16.20.10
      last_ip: 172.16.20.240

Flat Network (native Hyper-V)

Copynetwork_providers:
- name: datacenter
  type: flat
  switch_name: dc-switch
  # no adapters 
  # optional: without subnets, catlets use an external DHCP server
  subnets:
  # eryph assigns static IPs from the default pool
  - name: default
    network: 172.16.15.0/24
    gateway: 172.16.15.1
    dns_servers: ['172.16.15.1']
    dns_domain: dc.local
    mtu: 1500
    ip_pools:
    - name: default
      first_ip: 172.16.15.10
      last_ip: 172.16.15.240

With static IP assignment, only the subnet default and its pool default are used. The pool must not overlap the range of a DHCP server on the same network. The configuration is applied by cloud-init in the catlet, so the catlet's operating system needs cloud-init (or a compatible agent).

Network Security on Flat Networks

On flat networks, catlets are connected directly to the physical network. By default, eryph therefore enables the Hyper-V DHCP guard and router guard on their adapters, so a catlet cannot act as DHCP server or router on the network, and MAC address spoofing is disabled.
Catlets which need these functions, e.g. a router, firewall or DHCP server catlet, can change these settings on their network adapters, as long as the network provider allows it:

Copy# network provider (eryph-zero allows all three by default)
network_providers:
- name: datacenter
  type: flat
  switch_name: dc-switch
  mac_address_spoofing: true
  disable_dhcp_guard: true
  disable_router_guard: true

Copy# catlet configuration of a router catlet
network_adapters:
- name: eth0
  dhcp_guard: false
  router_guard: false
  mac_address_spoofing: true

If a provider no longer allows one of these settings, existing catlets keep their current adapter settings and have to be updated manually; eryph-zero networks import shows a warning in this case.

Configuration Options

Multiple IP Pools - Separate ranges for different purposes:

Copysubnets:
- name: default
  network: 172.16.0.0/24
  gateway: 172.16.0.1
  ip_pools:
  - name: web
    first_ip: 172.16.0.10
    last_ip: 172.16.0.50
  - name: database
    first_ip: 172.16.0.100
    last_ip: 172.16.0.120

VLAN Configuration

Copyvlan: 100                          # Provider VLAN
bridge_options:
  bridge_vlan: 200                 # Bridge VLAN (if different)
  vlan_mode: native_tagged         # access | native_untagged | native_tagged

The provider VLAN is for traffic from the VMs and the default VLAN for the bridge. If you use the bridge for host traffic you can change the VLAN of the bridge with bridge_vlan and vlan_mode.

Single Adapter Mode - When using one adapter for management and overlay:

Copybridge_options:
  default_ip_mode: dhcp            # Required for single adapter

Bonding (Windows Server with SET only):

Copybridge_options:
  bond_mode: balance_slb           # active_backup | balance_slb
adapters: ['Ethernet 2', 'Ethernet 3']

When multiple adapters are configured, Eryph automatically creates a SET—no manual setup required.

Managing Networks

Copy# Get catlet IPs
Get-CatletIP                      # External IPs
Get-CatletIP -InternalIp          # Internal IPs

# View VM switches (standard Hyper-V)
Get-VMSwitch -Name "eryph_overlay"

# Check NAT configuration  
Get-NetNat | Where Name -like "eryph_*"

Common Scenarios

Team Access - Enable network access to catlets:

Copynetwork_providers:
- name: team
  type: overlay
  bridge_name: br-team
  adapters: ['Team Network']
  subnets:
  - name: default
    network: 10.50.0.0/24
    gateway: 10.50.0.1
    ip_pools:
    - name: shared
      first_ip: 10.50.0.20
      last_ip: 10.50.0.200

DMZ with VLAN - Isolated network segment:

Copynetwork_providers:
- name: dmz
  type: overlay
  bridge_name: br-dmz
  vlan: 50
  bridge_options:
    vlan_mode: access
  adapters: ['DMZ Port']
  subnets:
  - name: public
    network: 172.16.50.0/24
    gateway: 172.16.50.1

Troubleshooting

Catlets not accessible: Verify IP pool availability, check firewall rules, ensure gateway reachability, run eryph-zero networks sync

Bridge adapter missing: Wait 30 seconds after configuration, verify OVS service running, check Windows event logs

VLAN issues: Verify switch port trunk configuration, check VLAN ID matches, ensure correct vlan_mode

Advanced diagnostics: OVS/OVN tools are available but require finding the eryph runtime directory. Contact support for guidance on using these diagnostic tools.

Network import fails with an overlapping IP range: Since eryph-zero 0.5, networks import and networks sync fail if the IP range of a NAT overlay or overlay provider overlaps a network route or a NAT on the host which is not managed by eryph, e.g. a route added by a VPN client:
The IP range '…' of the provider '…' overlaps the IP range '…' of a network route which is not managed by eryph.
Change the network and ip_pools of the provider to a range that is not used on the host.

Single adapter disconnection: Temporary disconnection is normal during configuration. Always set default_ip_mode: dhcp and have console access.

Switching network types: Export catlet configs first, import new network provider, recreate catlets. Direct migration not supported.

See Also

• Project Networks - Virtual networks within projects
• Network Isolation - Project isolation details
• Configuration Reference - Network schemas
• PowerShell Reference - Network cmdlets