network

GET /network/config/bonds

List LACP bonds

Retrieves all LACP bonds on the host with health classification

Status Codes:
Response JSON Object:

  • bonds[].active_aggregator (integer)

  • bonds[].admin_state (string)

  • bonds[].carrier (boolean)

  • bonds[].health (string) – healthy|degraded_no_partner|degraded_slave_down|down

  • bonds[].ip_addresses[] (string)

  • bonds[].lacp_rate (string) – “fast” | “slow”

  • bonds[].mac_address (string)

  • bonds[].mode (string) – “IEEE 802.3ad …”

  • bonds[].mtu (integer)

  • bonds[].name (string) – “bond0”

  • bonds[].oper_state (string)

  • bonds[].partner_mac (string) – switch-side; zero = not negotiated

  • bonds[].slaves[].aggregator_id (integer)

  • bonds[].slaves[].link_failures (integer)

  • bonds[].slaves[].mii_status (string) – “up” | “down”

  • bonds[].slaves[].name (string)

  • bonds[].slaves[].speed_mbps (integer)

  • bonds[].slaves_total (integer)

  • bonds[].slaves_up (integer)

  • bonds[].xmit_hash_policy (string) – “layer3+4” etc

  • count (integer)

  • metrics.degraded_no_partner (integer)

  • metrics.degraded_slave_down (integer)

  • metrics.down (integer)

  • metrics.healthy (integer)

  • metrics.total (integer)

GET /network/config/bonds/{name}

Get bond status

Retrieves detailed LACP + per-slave state for one bond

Parameters:

  • name (string) – Bond name (e.g. bond0)

Status Codes:
Response JSON Object:

  • active_aggregator (integer)

  • admin_state (string)

  • carrier (boolean)

  • health (string) – healthy|degraded_no_partner|degraded_slave_down|down

  • index (integer)

  • ip_addresses[] (string)

  • lacp_rate (string) – “fast” | “slow”

  • mac_address (string)

  • mode (string) – “IEEE 802.3ad …”

  • mtu (integer)

  • name (string) – “bond0”

  • oper_state (string)

  • partner_mac (string) – switch-side; zero = not negotiated

  • slaves[].aggregator_id (integer)

  • slaves[].link_failures (integer)

  • slaves[].mii_status (string) – “up” | “down”

  • slaves[].name (string)

  • slaves[].speed_mbps (integer)

  • slaves_total (integer)

  • slaves_up (integer)

  • stats.collisions (integer)

  • stats.multicast (integer)

  • stats.rx_bytes (integer)

  • stats.rx_compressed (integer)

  • stats.rx_crc_errors (integer)

  • stats.rx_dropped (integer)

  • stats.rx_errors (integer)

  • stats.rx_fifo_errors (integer)

  • stats.rx_frame_errors (integer)

  • stats.rx_length_errors (integer)

  • stats.rx_missed_errors (integer)

  • stats.rx_over_errors (integer)

  • stats.rx_packets (integer)

  • stats.tx_aborted_errors (integer)

  • stats.tx_bytes (integer)

  • stats.tx_carrier_errors (integer)

  • stats.tx_compressed (integer)

  • stats.tx_dropped (integer)

  • stats.tx_errors (integer)

  • stats.tx_fifo_errors (integer)

  • stats.tx_heartbeat_errors (integer)

  • stats.tx_packets (integer)

  • stats.tx_window_errors (integer)

  • xmit_hash_policy (string) – “layer3+4” etc

GET /network/config/bridges

List network bridges

Retrieves a list of all network bridges

Status Codes:
Response JSON Object:

  • bridges[].admin_state (string)

  • bridges[].bucket (string)

  • bridges[].carrier (boolean)

  • bridges[].flags[] (string)

  • bridges[].ip_addresses[] (string)

  • bridges[].mac_address (string)

  • bridges[].members[] (string)

  • bridges[].mtu (integer)

  • bridges[].name (string)

  • bridges[].offloads (object)

  • bridges[].oper_state (string)

  • bridges[].tx_qlen (integer)

  • count (integer)

  • metrics.active_bridges (integer)

  • metrics.admin_down_count (integer)

  • metrics.highest_error_bridge (string)

  • metrics.highest_error_bridge_errors (integer)

  • metrics.highest_mtu (integer) – Highest MTU

  • metrics.highest_mtu_owner (string)

  • metrics.inactive_bridges (integer)

  • metrics.most_members_bridge (string)

  • metrics.most_members_count (integer)

  • metrics.most_used_bridge (string)

  • metrics.most_used_bytes (integer)

  • metrics.oper_down_count (integer)

  • metrics.total_bridges (integer)

  • metrics.total_errors (integer) – Error tracking

  • metrics.total_members (integer) – Members

  • metrics.total_rx_bytes (integer) – Aggregate traffic

  • metrics.total_tx_bytes (integer)

  • metrics.worst_oper_state (string)

  • metrics.worst_state_bridge (string) – Worst state

GET /network/config/bridges/{name}

Get bridge status

Retrieves the status of a specific network bridge

Parameters:

  • name (string) – Bridge name

Status Codes:
Response JSON Object:

  • admin_state (string)

  • allmulticast (boolean)

  • carrier (boolean)

  • flags[] (string)

  • index (integer)

  • ip_addresses[] (string)

  • mac_address (string)

  • master (string)

  • members[] (string)

  • mtu (integer)

  • name (string)

  • offloads (object)

  • oper_state (string)

  • promiscuous (boolean)

  • raw_flags (integer)

  • stats.collisions (integer)

  • stats.multicast (integer)

  • stats.rx_bytes (integer)

  • stats.rx_compressed (integer)

  • stats.rx_crc_errors (integer)

  • stats.rx_dropped (integer)

  • stats.rx_errors (integer)

  • stats.rx_fifo_errors (integer)

  • stats.rx_frame_errors (integer)

  • stats.rx_length_errors (integer)

  • stats.rx_missed_errors (integer)

  • stats.rx_over_errors (integer)

  • stats.rx_packets (integer)

  • stats.tx_aborted_errors (integer)

  • stats.tx_bytes (integer)

  • stats.tx_carrier_errors (integer)

  • stats.tx_compressed (integer)

  • stats.tx_dropped (integer)

  • stats.tx_errors (integer)

  • stats.tx_fifo_errors (integer)

  • stats.tx_heartbeat_errors (integer)

  • stats.tx_packets (integer)

  • stats.tx_window_errors (integer)

  • tx_queue_len (integer)

  • type (string) – always “bridge”

GET /network/config/bridges/{name}/qos

Get QoS state for a bridge

Retrieves the live qdisc/class/filter tree for a bridge

Parameters:

  • name (string) – Bridge name

Status Codes:
Response JSON Object:

  • cake (any) – Cake carries CAKE’s full config + per-tin runtime stats, decoded directly from raw netlink attributes (see qos_cake_read.go — the vendored netlink library has no typed Cake qdisc and drops TCA_STATS_APP for every qdisc kind, so this is not reachable through Qdiscs above). Populated only when RootQdisc == “cake”; nil otherwise.

  • classes[].backlog (integer)

  • classes[].bytes (integer)

  • classes[].ceil_bytes_per_sec (integer)

  • classes[].class_id (string)

  • classes[].drops (integer)

  • classes[].overlimits (integer)

  • classes[].packets (integer)

  • classes[].parent (string)

  • classes[].prio (integer)

  • classes[].qlen (integer)

  • classes[].rate_bytes_per_sec (integer)

  • classes[].requeues (integer)

  • classes[].type (string)

  • device (string)

  • device_class (string) – bridge|virtual|nic

  • effective_device (string) – A Linux bridge never carries the egress shaper itself — a CAKE/HTB shaper lives on its enslaved physical UPLINK (the device the golden karios-cake-egress script and apply_qos_step target), not on the bridge. So a bare read of a bridge reports Profile “none” while its uplink is shaped. For a bridge, EffectiveDevice names that uplink and EffectiveQoS carries the uplink’s full QoS (incl. CAKE detail), so a consumer can show the REAL policy instead of a misleading “none”. Both empty/nil for non-bridges and for a bridge with no physical uplink yet (collapsed/flat).

  • effective_qos (object) – Self-referencing ‘utils.DeviceQoSInfo’ child — recursion broken so the docs renderer (sphinxcontrib-openapi) does not infinite-loop. See raw spec for full self-referential type.

  • filters[].parent (string)

  • filters[].priority (integer)

  • filters[].type (string)

  • profile (string) – Profile is the best-effort match against the named profile catalogue (QoSProfile* constants above), or QoSProfileUnmanaged if the live tree shape matches none of them. Never rounded to the nearest known profile.

  • qdiscs[].backlog (integer)

  • qdiscs[].bytes (integer)

  • qdiscs[].drops (integer)

  • qdiscs[].handle (string)

  • qdiscs[].overlimits (integer)

  • qdiscs[].packets (integer)

  • qdiscs[].parent (string)

  • qdiscs[].qlen (integer)

  • qdiscs[].requeues (integer)

  • qdiscs[].type (string)

  • root_handle (string)

  • root_qdisc (string) – kind of the root qdisc, e.g. “mq”, “htb”, “fq_codel”, “noqueue”

GET /network/config/interfaces

List network interfaces

Retrieves a list of all network interfaces

Status Codes:
Response JSON Object:

  • count (integer)

  • interfaces[].admin_state (string)

  • interfaces[].allmulticast (boolean)

  • interfaces[].carrier (boolean)

  • interfaces[].code (string) – machine reason code (constants.Code*)

  • interfaces[].current_speed (integer)

  • interfaces[].flags[] (string)

  • interfaces[].hardware.bus_info (string) – PCI/USB bus address (e.g., “0000:01:00.0”)

  • interfaces[].hardware.device_type (string) – “physical”, “virtual”, “bridge”, “vlan”, etc.

  • interfaces[].hardware.driver (string) – Kernel driver name (e.g., “e1000e”, “ixgbe”)

  • interfaces[].hardware.driver_version (string) – Driver version

  • interfaces[].hardware.firmware_version (string) – Firmware version

  • interfaces[].hardware.is_sriov_pf (boolean) – true if SR-IOV physical function

  • interfaces[].hardware.is_sriov_vf (boolean) – true if SR-IOV virtual function

  • interfaces[].hardware.mac_vendor (string) – Human-readable vendor name derived from PCI vendor ID

  • interfaces[].hardware.modalias (string) – Device modalias string

  • interfaces[].hardware.pci_device (string) – PCI device ID

  • interfaces[].hardware.pci_subsystem (string) – PCI subsystem ID

  • interfaces[].hardware.pci_vendor (string) – PCI vendor ID (e.g., “8086” for Intel)

  • interfaces[].ip_addresses[] (string)

  • interfaces[].last_state_change_secs (integer) – State change tracking

  • interfaces[].mac_address (string)

  • interfaces[].master (string)

  • interfaces[].max_speed (integer)

  • interfaces[].mtu (integer)

  • interfaces[].name (string)

  • interfaces[].offloads (object)

  • interfaces[].oper_state (string)

  • interfaces[].overall_state (string) – Computed display fields

  • interfaces[].ownership (string) – system|user|available|quarantine — see netconstants.Bucket*

  • interfaces[].promiscuous (boolean)

  • interfaces[].raw_flags (integer)

  • interfaces[].reason (string) – human-readable reason

  • interfaces[].ring_rx_current (integer) – Ring buffer sizes (ethtool -g) — current + hardware max, so the detail page can show the live value next to the editable ring_rx/ring_tx control.

  • interfaces[].ring_rx_max (integer)

  • interfaces[].ring_tx_current (integer)

  • interfaces[].ring_tx_max (integer)

  • interfaces[].sdwan_type (string)

  • interfaces[].status (string) – Eligibility classification (net-new). Stamped node-local by ClassifyNICs so the values survive the control-node proxy and reach the UI as-is. The owning bridge is carried by the existing master field — no separate owner field.

  • interfaces[].throughput_rx_mbps (number) – Throughput — 1-minute rolling average computed by the interface poller

  • interfaces[].throughput_tx_mbps (number)

  • interfaces[].traffic_role (string) – public|guest|management|”” - CS traffic-type via agent.properties

  • interfaces[].tx_queue_len (integer)

  • interfaces[].type (string)

  • metrics.active_nics (integer)

  • metrics.admin_down_count (integer)

  • metrics.highest_error_nic (string) – NIC with the most errors

  • metrics.highest_error_nic_errors (integer)

  • metrics.highest_mtu (integer) – Highest MTU

  • metrics.highest_mtu_owner (string)

  • metrics.inactive_nics (integer)

  • metrics.most_used_bytes (integer)

  • metrics.most_used_nic (string)

  • metrics.oper_down_count (integer)

  • metrics.top_talker_nic (string)

  • metrics.total_errors (integer) – Error tracking

  • metrics.total_nics (integer)

  • metrics.total_rx_bytes (integer) – Aggregate traffic

  • metrics.total_tx_bytes (integer)

  • metrics.worst_oper_state (string)

  • metrics.worst_state_nic (string) – Worst state — the NIC with the worst oper_state (down > lowerlayerdown > unknown > up)

POST /network/config/interfaces

Create a dummy interface

Creates a dummy interface (kernel link + karios-managed ifupdown fragment) synchronously

Request JSON Object:

  • address_cidr (string)

  • dns[] (string)

  • gateway (string)

  • mode (string) – IP config — mapped into a configuremodels.VLANIPConfig, validated with the shared ValidateVLANIPConfig, applied live via applyL3Local, and persisted into the ifupdown fragment (a dummy is often created for a stable IP that must survive reboot). Mode nil or “” means manual (L2-only), same semantics as a VLAN create.

  • mtu (integer)

  • name (string) – (required)

Status Codes:
GET /network/config/interfaces/{name}

Get network interface status

Retrieves the status of a specific network interface

Parameters:

  • name (string) – Interface name

Status Codes:
Response JSON Object:

  • address_cidr (string)

  • admin_state (string)

  • alias (string)

  • allmulticast (boolean)

  • autoneg (boolean) – nil = could not read (unknown); tri-state so the UI never shows a guessed value

  • carrier (boolean)

  • current_speed (integer) – Enriched fields — populated ON DEMAND by EnrichInterfaceDetail in the HTTP detail handler path only (network/handlers/monitoring.go), NOT by the light GetInterfaceStatus the 60s poller calls per interface. The detail page and Edit panel show the LIVE value next to each editable control. Best-effort: a NIC without ethtool support (e.g. a dummy) leaves speed/ring/duplex zero, Autoneg nil, and Offloads nil, which the UI treats as “state unknown” (toggles disabled) rather than lying that it is off.

  • dns[] (string)

  • duplex (string) – “half” | “full” | “” (unknown), ethtool link settings

  • flags[] (string)

  • gateway (string)

  • index (integer)

  • ip_addresses[] (string)

  • mac_address (string)

  • master (string)

  • max_mtu (integer) – MaxMTU is the NIC’s hardware MTU ceiling (sysfs max_mtu), so the Edit panel can bound the MTU field. 0/absent when the kernel doesn’t expose it.

  • max_speed (integer)

  • mode (string) – Declared L3 config parsed from this interface’s karios-owned interfaces.d/<name>.cfg fragment (via ReadInterfaceDeclared), so the Edit panel can prefill the IP form with what will actually persist across a reboot — distinct from IPAddresses, which are the live kernel addresses. Empty when no fragment declares an L3 config. Enriched on demand alongside the ethtool fields above.

  • mtu (integer)

  • name (string)

  • offloads (object)

  • offloads_fixed (object) – OffloadsFixed carries an entry (always true) for every offload key the driver reports [fixed] in ethtool -k - not user-settable on this hardware, distinct from merely being off. A key’s ABSENCE means settable; only fixed keys are listed, so the UI greys out exactly the toggles that would otherwise fail with “Could not change any device features” (checkOffloadSettable enforces this same fact server-side - interface_lifecycle.go). Populated from the SAME ethtool -k read as Offloads (getInterfaceOffloadState, dashboard.go) - no extra exec.

  • oper_state (string)

  • ownership (string) – system|user|available|quarantine — see netconstants.Bucket*

  • perm_hw_addr (string)

  • promiscuous (boolean)

  • raw_flags (integer)

  • ring_rx_current (integer)

  • ring_rx_max (integer)

  • ring_tx_current (integer)

  • ring_tx_max (integer)

  • stats.collisions (integer)

  • stats.multicast (integer)

  • stats.rx_bytes (integer)

  • stats.rx_compressed (integer)

  • stats.rx_crc_errors (integer)

  • stats.rx_dropped (integer)

  • stats.rx_errors (integer)

  • stats.rx_fifo_errors (integer)

  • stats.rx_frame_errors (integer)

  • stats.rx_length_errors (integer)

  • stats.rx_missed_errors (integer)

  • stats.rx_over_errors (integer)

  • stats.rx_packets (integer)

  • stats.tx_aborted_errors (integer)

  • stats.tx_bytes (integer)

  • stats.tx_carrier_errors (integer)

  • stats.tx_compressed (integer)

  • stats.tx_dropped (integer)

  • stats.tx_errors (integer)

  • stats.tx_fifo_errors (integer)

  • stats.tx_heartbeat_errors (integer)

  • stats.tx_packets (integer)

  • stats.tx_window_errors (integer)

  • suggested_test_target (string) – SuggestedTestTarget is the IP the connectivity-safety gate WOULD DF-ping to verify a breaking change on this interface (the gateway reachable via this interface, else the node default gateway). The Edit panel prefills its “test target” field with it so an operator can accept or override the probe destination. Best-effort; empty when no target resolves. Enriched on demand alongside the ethtool/L3 fields above.

  • traffic_role (string) – public|guest|management|”” - CS traffic-type via agent.properties

  • tx_queue_len (integer)

  • type (string)

PUT /network/config/interfaces/{name}

Update an interface

Applies an admin-state/MTU/flag change on an existing interface synchronously

Parameters:

  • name (string) – Interface name

Request JSON Object:

  • address_cidr (string)

  • admin_state (string) – “up” | “down”

  • allmulticast (boolean)

  • autoneg (boolean) – autonegotiation on/off

  • confirm (boolean) – Confirm must be true to proceed when the interface is enslaved to a bridge (ErrConfirmMissing / 409) — protects against an operator accidentally disabling/re-MTU-ing a live bridge member.

  • dns[] (string)

  • duplex (string) – “half” | “full”

  • gateway (string)

  • mac_address (string) – MACAddress — netlink LinkSetHardwareAddr (unicast only).

  • mode (string) – IP config — mapped into a configuremodels.VLANIPConfig and applied via the shared L3 helper. Mode nil or “” leaves the interface’s IP unchanged (same semantics as a VLAN update); a set Mode replaces it.

  • mtu (integer)

  • offloads (object) – Offloads — ethtool -K short keys (constants.SettableOffloadKeys) -> on/off.

  • promiscuous (boolean)

  • qos (any) – QoS — nil leaves the device’s QoS profile unchanged, same semantics as every other optional field above. Validated (utils.ValidateQoSSpec) but not yet applied — see QoSSpec’s doc comment.

  • ring_rx (integer) – Ring buffers — ethtool -G <dev> rx N tx M.

  • ring_tx (integer)

  • speed (integer) – Link parameters — applied together via ethtool -s.

  • test_target (string) – TestTarget overrides the IP the connectivity-safety gate DF-pings when it verifies a breaking change (see network/utils/interface_safety.go). When set it MUST parse as a valid IP (else 400); when empty the gate resolves the gateway reachable VIA this interface, else the node default gateway. It lets an operator point the probe at a known-good far-end when the auto-resolved target is wrong for the interface under test (e.g. an off-path NIC whose reachable peer is not the default gateway).

  • tx_queue_len (integer) – TxQueueLen — netlink LinkSetTxQLen.

Status Codes:
POST /network/config/interfaces/{name}/connectivity-test

Test connectivity for a proposed interface change

Dry-runs the connectivity-safety gate for a proposed MTU change (applies it, egress-bound DF-probes, then reverts) and reports pass/fail WITHOUT committing - the UI’s “Test” button.

Parameters:

  • name (string) – Interface name

Request JSON Object:

  • address_cidr (string)

  • admin_state (string) – “up” | “down”

  • allmulticast (boolean)

  • autoneg (boolean) – autonegotiation on/off

  • confirm (boolean) – Confirm must be true to proceed when the interface is enslaved to a bridge (ErrConfirmMissing / 409) — protects against an operator accidentally disabling/re-MTU-ing a live bridge member.

  • dns[] (string)

  • duplex (string) – “half” | “full”

  • gateway (string)

  • mac_address (string) – MACAddress — netlink LinkSetHardwareAddr (unicast only).

  • mode (string) – IP config — mapped into a configuremodels.VLANIPConfig and applied via the shared L3 helper. Mode nil or “” leaves the interface’s IP unchanged (same semantics as a VLAN update); a set Mode replaces it.

  • mtu (integer)

  • offloads (object) – Offloads — ethtool -K short keys (constants.SettableOffloadKeys) -> on/off.

  • promiscuous (boolean)

  • qos (any) – QoS — nil leaves the device’s QoS profile unchanged, same semantics as every other optional field above. Validated (utils.ValidateQoSSpec) but not yet applied — see QoSSpec’s doc comment.

  • ring_rx (integer) – Ring buffers — ethtool -G <dev> rx N tx M.

  • ring_tx (integer)

  • speed (integer) – Link parameters — applied together via ethtool -s.

  • test_target (string) – TestTarget overrides the IP the connectivity-safety gate DF-pings when it verifies a breaking change (see network/utils/interface_safety.go). When set it MUST parse as a valid IP (else 400); when empty the gate resolves the gateway reachable VIA this interface, else the node default gateway. It lets an operator point the probe at a known-good far-end when the auto-resolved target is wrong for the interface under test (e.g. an off-path NIC whose reachable peer is not the default gateway).

  • tx_queue_len (integer) – TxQueueLen — netlink LinkSetTxQLen.

Status Codes:
Response JSON Object:

  • egress (string)

  • message (string)

  • mtu (integer)

  • passed (boolean)

  • target (string)

  • tested (boolean)

GET /network/config/interfaces/{name}/qos

Get QoS state for a network interface

Retrieves the live qdisc/class/filter tree for a physical NIC or virtual interface

Parameters:

  • name (string) – Interface name

Status Codes:
Response JSON Object:

  • cake (any) – Cake carries CAKE’s full config + per-tin runtime stats, decoded directly from raw netlink attributes (see qos_cake_read.go — the vendored netlink library has no typed Cake qdisc and drops TCA_STATS_APP for every qdisc kind, so this is not reachable through Qdiscs above). Populated only when RootQdisc == “cake”; nil otherwise.

  • classes[].backlog (integer)

  • classes[].bytes (integer)

  • classes[].ceil_bytes_per_sec (integer)

  • classes[].class_id (string)

  • classes[].drops (integer)

  • classes[].overlimits (integer)

  • classes[].packets (integer)

  • classes[].parent (string)

  • classes[].prio (integer)

  • classes[].qlen (integer)

  • classes[].rate_bytes_per_sec (integer)

  • classes[].requeues (integer)

  • classes[].type (string)

  • device (string)

  • device_class (string) – bridge|virtual|nic

  • effective_device (string) – A Linux bridge never carries the egress shaper itself — a CAKE/HTB shaper lives on its enslaved physical UPLINK (the device the golden karios-cake-egress script and apply_qos_step target), not on the bridge. So a bare read of a bridge reports Profile “none” while its uplink is shaped. For a bridge, EffectiveDevice names that uplink and EffectiveQoS carries the uplink’s full QoS (incl. CAKE detail), so a consumer can show the REAL policy instead of a misleading “none”. Both empty/nil for non-bridges and for a bridge with no physical uplink yet (collapsed/flat).

  • effective_qos (object) – Self-referencing ‘utils.DeviceQoSInfo’ child — recursion broken so the docs renderer (sphinxcontrib-openapi) does not infinite-loop. See raw spec for full self-referential type.

  • filters[].parent (string)

  • filters[].priority (integer)

  • filters[].type (string)

  • profile (string) – Profile is the best-effort match against the named profile catalogue (QoSProfile* constants above), or QoSProfileUnmanaged if the live tree shape matches none of them. Never rounded to the nearest known profile.

  • qdiscs[].backlog (integer)

  • qdiscs[].bytes (integer)

  • qdiscs[].drops (integer)

  • qdiscs[].handle (string)

  • qdiscs[].overlimits (integer)

  • qdiscs[].packets (integer)

  • qdiscs[].parent (string)

  • qdiscs[].qlen (integer)

  • qdiscs[].requeues (integer)

  • qdiscs[].type (string)

  • root_handle (string)

  • root_qdisc (string) – kind of the root qdisc, e.g. “mq”, “htb”, “fq_codel”, “noqueue”

GET /network/config/vlan-interfaces

List VLAN sub-interfaces

Retrieves all 802.1Q VLAN sub-interfaces on the host with health classification

Status Codes:
Response JSON Object:

  • count (integer)

  • metrics.configured_not_present (integer)

  • metrics.degraded_mtu_exceeds_parent (integer)

  • metrics.degraded_no_carrier (integer)

  • metrics.down (integer)

  • metrics.healthy (integer)

  • metrics.total (integer)

  • vlan_interfaces[].address_cidr (string) – static

  • vlan_interfaces[].admin_state (string)

  • vlan_interfaces[].carrier (boolean)

  • vlan_interfaces[].configured_only (boolean) – cfg fragment exists but kernel device is absent

  • vlan_interfaces[].dns[] (string)

  • vlan_interfaces[].gateway (string) – static

  • vlan_interfaces[].health (string) – healthy|degraded_no_carrier|degraded_mtu_exceeds_parent|down|configured_not_present

  • vlan_interfaces[].ip_addresses[] (string)

  • vlan_interfaces[].mac_address (string)

  • vlan_interfaces[].master_bridge (string) – “cloudbr1” if enslaved

  • vlan_interfaces[].mode (string) – Declared L3 config, parsed from the KARIOS-VLAN cfg (managed interfaces only; empty for unmanaged/platform). This is the INTENT (mode + declared address/gateway/DNS) — distinct from IPAddresses, which is the live kernel state. The UI edits against these.

  • vlan_interfaces[].mtu (integer)

  • vlan_interfaces[].name (string) – “bond0.2005”

  • vlan_interfaces[].offloads (object)

  • vlan_interfaces[].oper_state (string)

  • vlan_interfaces[].ownership (string) – user|platform|unmanaged — see netconstants.VLANOwnership*

  • vlan_interfaces[].parent (string) – “bond0” | “eth4”

  • vlan_interfaces[].parent_mtu (integer)

  • vlan_interfaces[].suggested_test_target (string) – SuggestedTestTarget is the IP the connectivity-safety gate WOULD DF-ping to verify a breaking change on this VLAN sub-interface (the gateway reachable via it, else the node default gateway). The Edit panel prefills its test target field with it. Best-effort; populated on the single-interface detail read (GetVLANInterfaceStatus) only, empty when none resolves.

  • vlan_interfaces[].vlan_tag (integer) – 2005

POST /network/config/vlan-interfaces

Create VLAN sub-interface

Request JSON Object:

  • address_cidr (string) – static only, e.g. “10.20.0.5/24”

  • dns[] (string)

  • gateway (string) – static only, optional

  • mode (string) – L3 configuration. Mode “” or “manual” = L2-only (default, prior behavior). “static” requires AddressCIDR; Gateway/DNS optional. “dhcp” takes no address fields — the server provides them.

  • mtu (integer) – 0 = inherit parent MTU

  • parent (string) – (required)

  • vlan_id (integer) – (required)

Status Codes:
GET /network/config/vlan-interfaces/{name}

Get VLAN sub-interface status

Retrieves detailed state for one VLAN sub-iface incl. parent + master bridge

Parameters:

  • name (string) – VLAN iface name (e.g. bond0.2005)

Status Codes:
Response JSON Object:

  • address_cidr (string) – static

  • admin_state (string)

  • carrier (boolean)

  • configured_only (boolean) – cfg fragment exists but kernel device is absent

  • dns[] (string)

  • gateway (string) – static

  • health (string) – healthy|degraded_no_carrier|degraded_mtu_exceeds_parent|down|configured_not_present

  • index (integer)

  • ip_addresses[] (string)

  • mac_address (string)

  • master_bridge (string) – “cloudbr1” if enslaved

  • mode (string) – Declared L3 config, parsed from the KARIOS-VLAN cfg (managed interfaces only; empty for unmanaged/platform). This is the INTENT (mode + declared address/gateway/DNS) — distinct from IPAddresses, which is the live kernel state. The UI edits against these.

  • mtu (integer)

  • name (string) – “bond0.2005”

  • offloads (object)

  • oper_state (string)

  • ownership (string) – user|platform|unmanaged — see netconstants.VLANOwnership*

  • parent (string) – “bond0” | “eth4”

  • parent_mtu (integer)

  • stats.collisions (integer)

  • stats.multicast (integer)

  • stats.rx_bytes (integer)

  • stats.rx_compressed (integer)

  • stats.rx_crc_errors (integer)

  • stats.rx_dropped (integer)

  • stats.rx_errors (integer)

  • stats.rx_fifo_errors (integer)

  • stats.rx_frame_errors (integer)

  • stats.rx_length_errors (integer)

  • stats.rx_missed_errors (integer)

  • stats.rx_over_errors (integer)

  • stats.rx_packets (integer)

  • stats.tx_aborted_errors (integer)

  • stats.tx_bytes (integer)

  • stats.tx_carrier_errors (integer)

  • stats.tx_compressed (integer)

  • stats.tx_dropped (integer)

  • stats.tx_errors (integer)

  • stats.tx_fifo_errors (integer)

  • stats.tx_heartbeat_errors (integer)

  • stats.tx_packets (integer)

  • stats.tx_window_errors (integer)

  • suggested_test_target (string) – SuggestedTestTarget is the IP the connectivity-safety gate WOULD DF-ping to verify a breaking change on this VLAN sub-interface (the gateway reachable via it, else the node default gateway). The Edit panel prefills its test target field with it. Best-effort; populated on the single-interface detail read (GetVLANInterfaceStatus) only, empty when none resolves.

  • vlan_tag (integer) – 2005

PUT /network/config/vlan-interfaces/{name}

Update VLAN sub-interface

Parameters:

  • name (string) – VLAN sub-interface name (<parent>.<vid>)

Request JSON Object:

  • address_cidr (string)

  • admin_state (string) – “up” | “down” | “” (leave unchanged)

  • dns[] (string)

  • gateway (string)

  • mode (string) – “” leaves IP unchanged; manual|static|dhcp changes it

  • mtu (integer)

  • offloads (object)

  • qos (any) – QoS — nil leaves the sub-interface’s QoS profile unchanged. See QoSSpec’s doc comment on InterfaceUpdateRequest for the shared-struct rationale.

  • test_target (string) – TestTarget overrides the IP the connectivity-safety gate DF-pings when it verifies a breaking change (MTU / admin-down / IP) on a management-path VLAN sub-interface. Must parse as an IP (else 400); empty lets the gate resolve the gateway reachable via this interface, then the node default gateway. Mirrors InterfaceUpdateRequest.TestTarget.

Status Codes:
GET /network/config/vlan-interfaces/{name}/qos

Get QoS state for a VLAN sub-interface

Retrieves the live qdisc/class/filter tree for a VLAN sub-interface

Parameters:

  • name (string) – VLAN iface name (e.g. bond0.2005)

Status Codes:
Response JSON Object:

  • cake (any) – Cake carries CAKE’s full config + per-tin runtime stats, decoded directly from raw netlink attributes (see qos_cake_read.go — the vendored netlink library has no typed Cake qdisc and drops TCA_STATS_APP for every qdisc kind, so this is not reachable through Qdiscs above). Populated only when RootQdisc == “cake”; nil otherwise.

  • classes[].backlog (integer)

  • classes[].bytes (integer)

  • classes[].ceil_bytes_per_sec (integer)

  • classes[].class_id (string)

  • classes[].drops (integer)

  • classes[].overlimits (integer)

  • classes[].packets (integer)

  • classes[].parent (string)

  • classes[].prio (integer)

  • classes[].qlen (integer)

  • classes[].rate_bytes_per_sec (integer)

  • classes[].requeues (integer)

  • classes[].type (string)

  • device (string)

  • device_class (string) – bridge|virtual|nic

  • effective_device (string) – A Linux bridge never carries the egress shaper itself — a CAKE/HTB shaper lives on its enslaved physical UPLINK (the device the golden karios-cake-egress script and apply_qos_step target), not on the bridge. So a bare read of a bridge reports Profile “none” while its uplink is shaped. For a bridge, EffectiveDevice names that uplink and EffectiveQoS carries the uplink’s full QoS (incl. CAKE detail), so a consumer can show the REAL policy instead of a misleading “none”. Both empty/nil for non-bridges and for a bridge with no physical uplink yet (collapsed/flat).

  • effective_qos (object) – Self-referencing ‘utils.DeviceQoSInfo’ child — recursion broken so the docs renderer (sphinxcontrib-openapi) does not infinite-loop. See raw spec for full self-referential type.

  • filters[].parent (string)

  • filters[].priority (integer)

  • filters[].type (string)

  • profile (string) – Profile is the best-effort match against the named profile catalogue (QoSProfile* constants above), or QoSProfileUnmanaged if the live tree shape matches none of them. Never rounded to the nearest known profile.

  • qdiscs[].backlog (integer)

  • qdiscs[].bytes (integer)

  • qdiscs[].drops (integer)

  • qdiscs[].handle (string)

  • qdiscs[].overlimits (integer)

  • qdiscs[].packets (integer)

  • qdiscs[].parent (string)

  • qdiscs[].qlen (integer)

  • qdiscs[].requeues (integer)

  • qdiscs[].type (string)

  • root_handle (string)

  • root_qdisc (string) – kind of the root qdisc, e.g. “mq”, “htb”, “fq_codel”, “noqueue”