Network

Resources for network configuration.

The network configuration on a Real Presence Platform server can be adjusted in two ways:

1. Modification of the network configuration scripts followed by a restart of the network service (or reboot)

In this approach, the changes made to the configuration will not take effect immediately -- only after a
restart of the network service will they become effective. There are some exceptions such as DNS settings
which take effect as soon as the configuration file has been saved.

The changes are applied to the scripts used by the operating system for configuring network behavior
and therefore the availability of settings that can be applied is limited to the options provided by
the operating system configuration files. For example, it isn't possible to immediately change the state
(UP/DOWN) of an interface using this approach. It is possible, however, to configure an interface to
be brought up (or prevented from being brought up) when the network service is restarted.

2. Application of the various network configuration tools (ip, ethtool, etc.)

This approach attempts to apply immediate changes to the live network configuration without persisting the
change in the network configuration files. It is intended for changes that are short term in nature or that
are appropriate under conditions that can only be detected at application runtime. As with the first approach,
the availability of settings is limited to the operations available by the network configuration tools. For
example it is possible to immediately change the operational state of an interface (UP/DOWN) but it isn't
possible to change the boot protocol using this approach.

The documentation of this API will distinguish between the configuration that has been stored in the scripts
(but perhaps not yet applied) and the live configuration that is currently in use for GET methods that retrieve
configuration data. When retrieving configuration, clients might have the opportunity to specify whether the "live"
configuration or the "saved" configuration is to be returned through the use of a config-type query parameter.
Valid values are "DYNAMIC" for the live and "STATIC" for the persisted configuration. In some cases, the returned
configuration might only be of one type, in which case, the query parameter is omitted.

Likewise the documentation will distinguish between configuration changes that are intended to be persisted across
restarts/reboots and changes that are intended to be short term for methods that update the network configuration.
The method documentation will indicate which approach the method will use.

[tags: DMA]

Resource Root

https://localhost:8443/api/rest/network

Summary

Resources	Methods
https://localhost:8443/api/rest/network	GET Returns the current network configuration based on the query parameter. PUT Stores the given network configuration appropriately.
https://localhost:8443/api/rest/network/restart	POST Requests a restart of the network service(s).

Resources

https://localhost:8443/api/rest/network

Methods

GET

Returns the current network configuration based on the query parameter.

[tags: DMA]

Request

Query Parameters

Name	Type	Description
config-type	xs:string	Specifies whether the live (operational) or saved configuration of the network is to be returned. The value STATIC returns the saved configuration, the value DYNAMIC returns the live configuration.

Response

Status	Representation	Description
403	application/vnd.plcm.plcm-error+json application/vnd.plcm.plcm-error+xml	The user is not authorized to retrieve the network configuration
200	application/vnd.plcm.plcm-network-configuration+json application/vnd.plcm.plcm-network-configuration+xml	The configuration returned by the server will contain values consistent with the value of the query parameter that was sent with the request. For example, if the query parameter specifies STATIC configuration, the values for the interfaces will not contain the current state of the interface, but will contain the boot protocol. Conversely, if the query is for DYNAMIC values, the state will be returned but the boot protocol will not.

PUT

Stores the given network configuration appropriately. Any changes will become effective with the next restart of
the network service or reboot of the server. The exceptions to this are the DNS configuration and the system host
table, for which changes become effective immediately.

[tags: DMA]

Request

Representations

application/vnd.plcm.plcm-network-configuration+json

application/vnd.plcm.plcm-network-configuration+xml

Response

Status	Representation	Description
403	application/vnd.plcm.plcm-error+json application/vnd.plcm.plcm-error+xml	The user is not authorized to change the network configuration. Changing the network configuration requires administrative privileges.
409		If the network settings cannot be applied (e.g. inconsistencies, missing or incorrect values, etc.) or an unexpected error is encountered.
204		This response indicates that the provided network configuration has been saved (but not yet applied).

https://localhost:8443/api/rest/network/restart

Methods

POST

Requests a restart of the network service(s). Note that this does not reboot the system, nor does the
method wait for the services to be restarted before returning a response. Because changes to the stored
configuration might include changes for IEEE 802.1x secure LAN authentication, the supplicant service
might also be restarted after the network service has been restarted.

[tags: DMA]

Request

Response

Status	Representation	Description
204		This response indicates that the request to restart the network service has been successfully submitted. It does not mean the network service was actually restarted successfully, just that the request to restart was received and will be subsequently attempted by the server.
403	application/vnd.plcm.plcm-error+json application/vnd.plcm.plcm-error+xml	The user is not authorized to restart the network service(s). Restarting the network service(s) requires administrative privileges.