Wired Network Settings Architecture

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

AMT SDK in use: github.com/device-management-toolkit/go-wsman-messages/v2 (pinned at v2.47.2 in go.mod). This is the Go implementation of the Intel® AMT WS-Management class model; the wired feature drives the AMT_EthernetPortSettings class for the wired interface (Intel(r) AMT Ethernet Port Settings 0).

2. Console interfaces

Console has exactly two external interfaces relevant to this feature.

2.1 User-facing API (north-bound)

REST/JSON endpoints registered in internal/controller/httpapi/v1/devicemanagement.go, handled in internal/controller/httpapi/v1/network.go:

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

Request binding and validation:

• Read response type WiredNetworkInfo and patch payload type WiredNetworkConfigRequest are defined in internal/entity/dto/v1/network.go.
• Field-level validation is enforced by Gin binding tags on WiredNetworkConfigRequest: dhcpEnabled is required, and ipAddress, subnetMask, defaultGateway, primaryDNS and secondaryDNS are validated as IPv4 addresses when present (omitempty,ipv4).
• Cross-field rules that cannot be expressed with binding tags (the DHCP vs static-IP combination rules) are enforced in the use case by validateWiredNetworkConfig.
• The OpenAPI/Fuego contract is declared in internal/controller/openapi/devicemanagement.go; the network routes were split out into registerNetworkRoutes (from the former combined registerNetworkAndFeatureRoutes) and the two wired endpoints added there. The PATCH route declares 204 No Content as its default status code.

Forward-looking contract: the patch DTO carries an optional ieee8021x (WiredIEEE8021xConfig) block for future wired 802.1X support. It is not yet implemented — supplying the object returns 501 Not Implemented so the API contract is stable now and the later implementation is purely additive.

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
PutEthernetPortSettings(req, instanceID)	overwrite a port's settings	AMT_EthernetPortSettings.Put
GetNetworkSettings()	enumerate/pull all ethernet port settings (reused by GET)	AMT_EthernetPortSettings

GetEthernetPortSettings enumerates then pulls AMT_EthernetPortSettings and returns the list of ethernetport.SettingsResponse items. PutEthernetPortSettings issues a single AMT.EthernetPortSettings.Put for the given instanceID.

Transport: WS-Management (SOAP/XML) over HTTPS to the device, established via SetupWsmanClient before each operation.

3. Business logic layer (Devices Use Case)

Implemented in internal/usecase/devices/network.go. Responsibilities that sit between the API and the SDK:

• Read — 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).
• Interface selection — wired vs wireless interfaces are matched by InstanceID substring using the named constants wiredEthernetInstanceID (Intel(r) AMT Ethernet Port Settings 0) and wirelessEthernetInstanceID (Intel(r) AMT Ethernet Port Settings 1).
• 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.
• Validation — validateWiredNetworkConfig enforces the DHCP/static-IP combination rules:
  • 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. Validation failures return ErrValidationUseCase (→ 400 Bad Request).
• Read-modify-write apply — the use case 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.
• AMT firmware rules — buildWiredSettingsRequest mirrors AMT semantics:
  • DHCP mode forces IpSyncEnabled = true, SharedStaticIp = false, and clears the explicit IP fields.
  • Static IP mode sets DHCPEnabled = false; SharedStaticIp always follows IpSyncEnabled (AMT does not support sharing a static IP without host sync).
  • Whenever IpSyncEnabled or DHCPEnabled is set, the explicit IPv4 fields are cleared because AMT rejects explicit IP fields in those modes.

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

4. AMT Device side

The device exposes the WS-Management class model the SDK targets:

• AMT_EthernetPortSettings — one instance per Ethernet interface. The wired interface is Intel(r) AMT Ethernet Port Settings 0; the wireless interface is Intel(r) AMT Ethernet Port Settings 1. The wired feature reads and writes only the wired instance.
• The instance holds the IPv4 configuration: DHCPEnabled, IpSyncEnabled, SharedStaticIp, IPAddress, SubnetMask, DefaultGateway, PrimaryDNS and SecondaryDNS.

AMT firmware constraints honored by Console:

• When DHCP is enabled, AMT acquires IP settings and the host/ME stay in sync; explicit IP fields are not accepted.
• When IP sync is enabled, the IP settings are synchronized with the host OS; explicit static IP fields are not accepted, and SharedStaticIp must track IpSyncEnabled.
• A full Put overwrites the instance, so Console performs a read-modify-write to preserve fields it does not change (e.g. SharedMAC, ElementName).

5. 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