Skip to content

Wired Network Settings Architecture

Jump to bottom
Loh, Shao Boon edited this page Jun 10, 2026 · 4 revisions

This document describes the architecture introduced by the wired network settings feature in Console. It lets an operator read and update the IPv4 configuration (DHCP or static IP) of the wired Ethernet port on an Intel® AMT managed device without having to read or rewrite the combined networkSettings payload.

1. High-level architecture

Two systems are involved: Console (the management application) and the AMT Device (the managed endpoint). Console exposes a user-facing REST API on one side and talks to the device over WS-Management (WSMAN) on the other, using the Intel® AMT SDK semantics implemented by the go-wsman-messages library.

flowchart LR
    Client[REST client] -->|GET / PATCH networkSettings/wired/:guid| ConsoleAPI[Console REST API]
    subgraph Console
        ConsoleAPI --> UseCase[Devices Use Case]
        UseCase --> WSMAN[wsman.Management adapter]
    end
    WSMAN -->|SOAP / XML over HTTPS| EthPort
    subgraph Device[Intel® AMT Device]
        EthPort[AMT_EthernetPortSettings]
    end
Loading

2. Console interfaces and data

2.1 User-facing API (north-bound)

Console has exactly two external interfaces relevant to this feature.

Method Path Payload Handler Success response
GET /api/v1/amt/networkSettings/wired/:guid N/A getWiredNetworkSettings 200 OK + wired network info
PATCH /api/v1/amt/networkSettings/wired/:guid WiredNetworkConfigRequest patchWiredNetworkSettings 204 No Content

WiredNetworkConfigRequest fields:

Field (JSON) Type Binding tag Validation note
dhcpEnabled *bool required Mandatory. true selects DHCP mode; false selects static IP mode.
ipSyncEnabled *bool — Static mode only. true syncs IP settings with the host OS; defaults to the device's current value when omitted.
ipAddress string omitempty,ipv4 Required for manual static IP; must be a valid IPv4 address.
subnetMask string omitempty,ipv4 Required for manual static IP; must be a valid IPv4 address.
defaultGateway string omitempty,ipv4 Required for manual static IP; must be a valid IPv4 address.
primaryDNS string omitempty,ipv4 Required for manual static IP; must be a valid IPv4 address.
secondaryDNS string omitempty,ipv4 Optional for static IP; must be a valid IPv4 address when present.
ieee8021x *WiredIEEE8021xConfig — Forward-looking; supplying it returns 501 Not Implemented.

2.2 Device interface (south-bound) — Intel AMT SDK

Console talks to the device through the wsman.Management interface in internal/usecase/devices/wsman/interfaces.go, implemented by ConnectionEntry in internal/usecase/devices/wsman/message.go. Each method is a thin wrapper over a go-wsman-messages call. The wired-relevant operations added by this feature:

Method Purpose SDK / class
GetEthernetPortSettings() enumerate/pull ethernet port settings AMT_EthernetPortSettings
GetNetworkSettings() call GetEthernetPortSettings() for raw ethernet port settings and sanitize it before return AMT_EthernetPortSettings
PutEthernetPortSettings(req, instanceID) overwrite a port's settings with ethernetport.SettingsRequest AMT_EthernetPortSettings.Put

The table below lists every field of the ethernetport.SettingsRequest and where its value translated from. Fields not driven by the request are copied verbatim from the current ethernetport.SettingsResponse so the Put does not clobber them.

AMT SDK request field Source
XMLName, ElementName, InstanceID Copied from current settings
SharedMAC Copied from current settings
DHCPEnabled dhcpEnabled = true → true; otherwise false
IpSyncEnabled DHCP → forced true; static → ipSyncEnabled if supplied, else current settings value
SharedStaticIp Always tracks the resolved IpSyncEnabled (DHCP → false; static → same as IpSyncEnabled); AMT cannot share a static IP without host sync
IPAddress Static manual mode → request ipAddress; cleared when IpSyncEnabled or DHCPEnabled is set
SubnetMask Static manual mode → request subnetMask; cleared when IpSyncEnabled or DHCPEnabled is set
DefaultGateway Static manual mode → request defaultGateway; cleared when IpSyncEnabled or DHCPEnabled is set
PrimaryDNS Static manual mode → request primaryDNS; cleared when IpSyncEnabled or DHCPEnabled is set
SecondaryDNS Static manual mode → request secondaryDNS (optional); cleared when IpSyncEnabled or DHCPEnabled is set

3. Business logic layer (Devices Use Case)

Implemented in internal/usecase/devices/network.go.

GET flow — GetWiredNetworkSettings reuses GetNetworkSettings to read the full network settings, then returns just the Wired portion. If the device reports no wired interface it returns ErrNotFound (404):

sequenceDiagram
    participant C as REST client
    participant API as Console API
    participant UC as Devices Use Case
    participant W as wsman.Management
    participant D as AMT Device

    C->>API: GET networkSettings/wired/:guid
    API->>UC: GetWiredNetworkSettings(guid)
    UC->>UC: GetNetworkSettings(guid)
    UC->>W: GetNetworkSettings()
    W->>D: Enumerate + Pull AMT_EthernetPortSettings
    D-->>W: settings list
    UC->>UC: select wired port / build WiredNetworkInfo
    alt no wired interface
        UC-->>API: ErrNotFound
        API-->>C: 404 Not Found
    else wired interface found
        UC-->>API: WiredNetworkInfo
        API-->>C: 200 OK + wired network info
    end
Loading

PATCH flow — PatchWiredNetworkSettings loads the device by GUID, opens a WSMAN client, calls GetEthernetPortSettings, finds the wired port, and builds the Put request by overlaying the requested change onto the current settings (buildWiredSettingsRequest), then issues a single PutEthernetPortSettings:

sequenceDiagram
    participant C as REST client
    participant API as Console API
    participant UC as Devices Use Case
    participant W as wsman.Management
    participant D as AMT Device

    C->>API: PATCH networkSettings/wired/:guid
    API->>UC: PatchWiredNetworkSettings(guid, req)
    UC->>UC: reject ieee8021x (501) / validate combo rules
    UC->>W: GetEthernetPortSettings()
    W->>D: Enumerate + Pull AMT_EthernetPortSettings
    D-->>W: settings list
    UC->>UC: buildWiredSettingsRequest(current, req)
    UC->>W: PutEthernetPortSettings(req, instanceID)
    W->>D: AMT_EthernetPortSettings.Put
    D-->>W: response
    UC-->>API: nil
    API-->>C: 204 No Content
Loading

Other flows:

  • Validation — validateWiredNetworkConfig enforces the DHCP/static-IP combination rules (Validation failure return ErrValidationUseCase, 400 Bad Request):
    • static IP fields must not be supplied when DHCP is enabled;
    • static IP fields must not be supplied when IP sync is enabled;
    • at least one of DHCP, IP sync, or static IP settings must be requested;
    • in manual static IP mode, ipAddress, subnetMask, defaultGateway and primaryDNS are required (validateStaticIPFields); secondaryDNS is optional.
  • Not-yet-supported guard — PatchWiredNetworkSettings rejects requests that carry an ieee8021x block with ErrNotSupportedUseCase (→ 501 Not Implemented) rather than silently ignoring them, keeping behavior unambiguous.

4. Key files

Area File
HTTP handlers internal/controller/httpapi/v1/network.go
Route registration internal/controller/httpapi/v1/devicemanagement.go
OpenAPI / Fuego declaration internal/controller/openapi/devicemanagement.go
DTOs (request/response) internal/entity/dto/v1/network.go
Use case (business logic) internal/usecase/devices/network.go
WS layer interface internal/controller/ws/v1/interface.go
Use case interface internal/usecase/devices/interfaces.go
WSMAN interface internal/usecase/devices/wsman/interfaces.go
WSMAN adapter (SDK calls) internal/usecase/devices/wsman/message.go
Error → HTTP status mapping internal/controller/httpapi/v1/error.go
AMT SDK dependency go.mod — go-wsman-messages/v2 v2.47.2
API collection MPS Postman collection (console_mps_apis.postman_collection.json)
Use case tests internal/usecase/devices/network_test.go

Console Wiki

ADRs

Clone this wiki locally