Skip to main content

Network settings API

This API is based on the Device Configuration API framework. For guidance on how to use these APIs, please refer to Device Configuration APIs.

Description​

The Network settings API makes it possible to configure the network settings on the device.

info

This API includes operations on sensitive data. You must use a secured channel for the communication transmissions.

Authentication​

For detailed information on how to authenticate requests to this API, please refer to Authentication.

Use cases​

Manage system settings​

The system settings contains a configuration for the hostname and resolver configuration. The hostname configuration is essential when assigning an identity to a device. It can either be assigned statically or assigned by DHCP. The resolver configuration is essential for allowing the device to resolve names into IP addresses. It can either be assigned statically or assigned by DHCP.

Get system settings​

The hostname and resolver configuration are part of the system entity network-settings.v2.system. Fetching it will return all settings under system, including the current hostname and resolver settings:

  • hostname - Indicates which hostname the device is currently using.
  • staticHostname - Indicates the statically assigned hostname, used if useDhcpHostname is set to false, or if no hostname could be obtained from DHCP.
  • useDhcpHostname - Indicates whether any hostname assigned via DHCP should be automatically used.
  • nameServers - Indicates which nameservers the device is currently using to do lookups to resolve DNS queries.
  • staticNameServers - Indicates the statically assigned nameservers, which are used either if useDhcpResolver is set to false, or if no nameservers were obtained from DHCP.
  • searchDomains - Indicates which search domains the device is currently using to do lookups to resolve DNS queries. If the looked up name does not exist, the resolver will attempt to lookup the name with each suffixed search domain specified.
  • staticSearchDomains - Indicates the statically assigned search domains, which are used either if useDHCPResolver is set to false, or if no search domains were obtained from DHCP.
  • useDhcpResolver - Indicates if any resolver configuration assigned via DHCP should be automatically assigned.
curl --request GET \
  --anyauth \
  --user "<username>:<password>" \
  --http1.1 \
  --header "Content-Type: application/json" \
  http://my-device/config/rest/network-settings/v2beta/system
200 OK
Content-Type: application/json
{
    "status": "success",
    "data": {
        "hostname": "realhostname",
        "staticHostname": "testhostname",
        "useDhcpHostname": true,
        "nameServers": [
            "192.168.0.1",
            "192.168.1.2",
            "1234::77"
        ],
        "searchDomains": [
            "axis.com",
            "example.com"
        ],
        "staticSearchDomains": [
            "axis.com",
            "example.com"
        ],
        "useDhcpResolver": true
    }
}

Set hostname settings​

To configure the hostname settings, use the following parameters:

  • staticHostname - Specifies the static hostname to use.
  • useDhcpHostname - Specifies whether any hostname assigned via DHCP should be applied.
{
    "request": {
        "operation": "SET",
        "path": "network-settings.v2.system",
        "data": {
            "staticHostname": "myhostname",
            "useDhcpHostname": false
        }
    },
    "response": {
        "status": "success"
    }
}

Set resolver settings​

  • Use the staticNameServers parameter to configure the static nameservers.
  • Use the staticSearchDomains parameter to configure the static search domains.
  • Use the useDhcpResolver parameter to configure if DHCP assigned resolver configuration should be used.

Example:

curl --request PATCH \
  --anyauth \
  --user "<username>:<password>" \
  --http1.1 \
  --header "Content-Type: application/json" \
  http://my-device/config/rest/network-settings/v2beta/system \
  --data '{
    "data": {
        "staticNameServers": [
            "192.168.0.1",
            "192.168.1.2",
            "1234::77"
        ],
        "staticSearchDomains": [
            "axis.com",
            "example.com"
        ],
        "useDhcpResolver": false
    }
}'
200 OK
Content-Type: application/json

{
    "status": "success"
}

Manage switch settings​

Some devices have built-in switches that allow additional products to be connected for network connectivity. Switch support is dynamic and not always available. Use switch_supported to check switch support on the device.

Get switch configuration​

The switch entity network-settings.v2.switch will return the current switch configuration if switch_supported is true, otherwise not available.

{
    "request": {
        "operation": "GET",
        "path": "network-settings.v2.switch"
    },
    "response": {
        "status": "success",
        "data": [
            {
               "port": [
                    {
                        "lowerState": "UP",
                        "portId": "1",
                        "remoteAddresses": [
                            "55:72:97:5a:c7:cf"
                        ],
                        "security_supported": false,
                        "enabled": true,
                        "security": {
                            "macSecState": "SECURED",
                            "authServerEnabled": true,
                            "authServerEnforced": "MACSEC_SECURED",
                            "authState": "AUTHENTICATED"
                        }
                    },
                    {
                        "lowerState": "DOWN",
                        "portId": "2",
                        "remoteAddresses": [],
                        "security_supported": true,
                        "enabled": true,
                        "security": {
                            "macSecState": "UNKNOWN",
                            "authServerEnabled": true,
                            "authServerEnforced": "AUTHENTICATED",
                            "authState": "UNKNOWN"
                        }
                    }
                ]
            }
        ]
    }
}

Get switch port settings​

Retrieve individual port settings from the collection of switch ports with portId.

The switch port security settings are dynamically supported. Check security_supported for availability. security will be excluded if it is not supported.

{
    "request": {
        "operation": "GET",
        "path": "network-settings.v2.switch.port['1']"
    },
    "response": {
        "status": "success",
        "data": {
                    "lowerState": "UP",
                    "portId": "1",
                    "remoteAddresses": [
                        "55:72:97:5a:c7:cf"
                    ],
                    "security_supported": true,
                    "enabled": true,
                    "security": {
                        "macSecState": "SECURED",
                        "authServerEnabled": true,
                        "authServerEnforced": "MACSEC_SECURED",
                        "authState": "AUTHENTICATED"
                    }
                }
    }
}

Set switch port settings​

Set portId to configure individual port settings on the collection of switch ports.

  • To enable a port, set enabled to true, which is the default value.
  • To disable a port, set enabled to false.

The switch port security settings are dynamically supported. Check security_supported for availability. You can't set security if security settings are not supported.

{
    "request": {
        "operation": "SET",
        "path": "network-settings.v2.switch.port['1']",
        "data": {
            "enabled": true,
            "security": {
                "authServerEnabled": false,
                "authServerEnforced": "NONE"
            }
        }
    },
    "response": {
        "status": "success"
    }
}

API definition​

Structure​

network-settings.v2 (Root Entity)
    ├── switch_supported (Property)
    ├── system (Entity)
        ├── hostname (Property)
        ├── nameServers (Property)
        ├── searchDomains (Property)
        ├── staticHostname (Property)
        ├── staticNameServers (Property)
        ├── staticSearchDomains (Property)
        ├── useDhcpHostname (Property)
        ├── useDhcpResolver (Property)
    ├── switch (Entity)
        ├── port (Entity Collection)
            ├── enabled (Property)
            ├── lowerState (Property)
            ├── portId (Property)
            ├── remoteAddresses (Property)
            ├── security_supported (Property)
            ├── security (Entity)
                ├── authServerEnabled (Property)
                ├── authServerEnforced (Property)
                ├── authState (Property)
                ├── macSecState (Property)

Entities​

network-settings.v2​

  • Description: System wide network configurations
  • Type: Singleton
  • Operations
    • GET
  • Attributes
    • Dynamic Support: No
Properties​
switch_supported​
  • Description: Indicates if switch is supported.
  • Datatype: boolean
  • Operations
    • GET
  • Attributes
    • Nullable: No
    • Dynamic Support: No / Dynamic Enum: No / Dynamic Range: No

network-settings.v2.system​

  • Description: The global network configuration
  • Type: Singleton
  • Operations
    • GET
    • SET
  • Attributes
    • Dynamic Support: No
Properties​
hostname​
  • Description: The currently used hostname
  • Datatype: Hostname
  • Operations
    • GET
  • Attributes
    • Nullable: No
    • Dynamic Support: No / Dynamic Enum: No / Dynamic Range: No
nameServers​
  • Description: The name servers currently in use.
  • Datatype: NameServers
  • Operations
    • GET (Permissions: admin)
  • Attributes
    • Nullable: No
    • Dynamic Support: No / Dynamic Enum: No / Dynamic Range: No
searchDomains​
  • Description: The search domains currently in use.
  • Datatype: SearchDomains
  • Operations
    • GET (Permissions: admin)
  • Attributes
    • Nullable: No
    • Dynamic Support: No / Dynamic Enum: No / Dynamic Range: No
staticHostname​
  • Description: The statically configured hostname. It is used if useDhcpHostname is set to false, or if no hostname was obtained by DHCP.
  • Datatype: Hostname
  • Operations
    • GET
    • SET (Permissions: admin)
  • Attributes
    • Nullable: No
    • Dynamic Support: No / Dynamic Enum: No / Dynamic Range: No
staticNameServers​
  • Description: The statically configured name servers. It is used if useDhcpResolver is set to false, or if no name servers were obtained by DHCP.
  • Datatype: NameServers
  • Operations
    • GET (Permissions: admin)
    • SET
  • Attributes
    • Nullable: No
    • Dynamic Support: No / Dynamic Enum: No / Dynamic Range: No
staticSearchDomains​
  • Description: The statically configured search domains. It is used if useDhcpResolver is set to false, or if no search domains were obtained by DHCP.
  • Datatype: SearchDomains
  • Operations
    • GET (Permissions: admin)
    • SET
  • Attributes
    • Nullable: No
    • Dynamic Support: No / Dynamic Enum: No / Dynamic Range: No
useDhcpHostname​
  • Description: Checks which DHCP-assigned hostname should be used. If set to false, the staticHostname will be used.
  • Datatype: boolean
  • Operations
    • GET
    • SET (Permissions: admin)
  • Attributes
    • Nullable: No
    • Dynamic Support: No / Dynamic Enum: No / Dynamic Range: No
useDhcpResolver​
  • Description: Checks if any DHCP-assigned resolver information should be used. If set to false, the static resolver values will be used.
  • Datatype: boolean
  • Operations
    • GET (Permissions: admin)
    • SET
  • Attributes
    • Nullable: No
    • Dynamic Support: No / Dynamic Enum: No / Dynamic Range: No

network-settings.v2.switch​

  • Description: Global switch configurations
  • Type: Singleton
  • Operations
    • GET
  • Attributes
    • Dynamic Support: Yes

network-settings.v2.switch.port​

  • Description: Switch port configurations
  • Type: Collection (Key Property: portId)
  • Operations
    • GET
    • SET
  • Attributes
    • Dynamic Support: No
Properties​
enabled​
  • Description: Specifies if a network interface device is enabled.
  • Datatype: boolean
  • Operations
    • GET
    • SET (Permissions: admin)
  • Attributes
    • Nullable: No
    • Dynamic Support: No / Dynamic Enum: No / Dynamic Range: No
lowerState​
  • Description: Indicates if the network interface device status is UP or DOWN.
  • Datatype: State
  • Operations
    • GET
  • Attributes
    • Nullable: No
    • Dynamic Support: No / Dynamic Enum: No / Dynamic Range: No
portId​
  • Description: Switch port ID
  • Datatype: string
  • Operations
    • GET
  • Attributes
    • Nullable: No
    • Dynamic Support: No / Dynamic Enum: No / Dynamic Range: No
remoteAddresses​
  • Description: List all stored remote MAC addresses observed on the switch port.
  • Datatype: RemoteAddresses
  • Operations
    • GET
  • Attributes
    • Nullable: No
    • Dynamic Support: No / Dynamic Enum: No / Dynamic Range: No
security_supported​
  • Description: Indicates if security is supported.
  • Datatype: boolean
  • Operations
    • GET
      • SET (Permissions: admin)
  • Attributes
    • Nullable: No
    • Dynamic Support: No / Dynamic Enum: No / Dynamic Range: No

network-settings.v2.switch.port.security​

  • Description: Switch port security configurations
  • Type: Singleton
  • Operations
    • GET
    • SET
  • Attributes
    • Dynamic Support: Yes
Properties​
authServerEnabled​
  • Description: Indicates if the authentication server is enabled.
  • Datatype: boolean
  • Operations
    • GET
    • SET (Permissions: admin)
  • Attributes
    • Nullable: No
    • Dynamic Support: No / Dynamic Enum: No / Dynamic Range: No
authServerEnforced​
  • Description: Indicates if the authentication server is enforced
  • Datatype: AuthServerEnforced
  • Operations
    • GET
    • SET (Permissions: admin)
  • Attributes
    • Nullable: No
    • Dynamic Support: No / Dynamic Enum: No / Dynamic Range: No
authState​
  • Description: Indicates the authentication state of the port
  • Datatype: AuthState
  • Operations
    • GET
  • Attributes
    • Nullable: No
    • Dynamic Support: No / Dynamic Enum: No / Dynamic Range: No
macSecState​
  • Description: Indicates the MACSec state of the port
  • Datatype: MacSecState
  • Operations
    • GET
  • Attributes
    • Nullable: No
    • Dynamic Support: No / Dynamic Enum: No / Dynamic Range: No

Data types​

DomainName​

  • Description: Domain name type.
  • Type: string

Hostname​

  • Description: Hostname type
  • Type: string
  • MinLength: 1
  • MaxLength: 63
    • Pattern: ^[a-zA-Z]$|^[a-zA-Z0-9][a-zA-Z0-9.-]*[a-zA-Z0-9]$

IpAddress​

  • Description: IPv4 or IPv6 address type.
  • Type: string

AuthServerEnforced​

  • Description: Authentication server enforcement level
  • Type: string
  • Enum Values: NONE, AUTHENTICATED, MACSEC_SECURED

AuthState​

  • Description: Authentication state type
  • Type: string
  • Enum Values: UNKNOWN, AUTHENTICATED, AUTHENTICATING, STOPPED, FAILED

MacAddress​

  • Description: MAC address type
  • Type: string
  • Pattern: ^([0-9A-Fa-f]{2}[:]){5}([0-9A-Fa-f]{2})$

MacSecState​

  • Description: MACsec state type
  • Type: string
  • Enum Values: UNKNOWN, SECURED, CONNECTING, STOPPED, FAILED

NameServers​

  • Description: Name servers type.
  • Type: array
  • Element type: IpAddress
  • Null Value: No
  • Minimum item number: 0
  • Maximum item number: 3

RemoteAddresses​

  • Description: Remote addresses type
  • Type: array
  • Element type: MacAddress
  • Null Value: No

SearchDomains​

  • Description: Search domains type.
  • Type: array
  • Element type: DomainName
  • Null Value: No
  • Minimum item number: 0
  • Maximum item number: 6

State​

  • Description: Link state type
  • Type: string
  • Enum Values: UP, DOWN