diff --git a/docs/references/rest-apis/rest-network-configuration-api.md b/docs/references/rest-apis/rest-network-configuration-api.md new file mode 100644 index 00000000000..cc2963262fa --- /dev/null +++ b/docs/references/rest-apis/rest-network-configuration-api.md @@ -0,0 +1,349 @@ +# Network Configuration V1 REST APIs + +This section describes the `networkConfiguration/v1` REST APIs, that allow to retrieve information about the network configuration of the running system. The services `pid` for which it's possible to obtain and update the configurations are: + +- `org.eclipse.kura.net.admin.NetworkConfigurationService`: which manages the network configuration of the system, so the network interfaces along with their network configuration (Ip4/Ip6 settings, DHCP, Nat, and so on) +- `org.eclipse.kura.net.admin.FirewallConfigurationService`: which manages the Ip4 firewall configurations (open ports, port forwarding and masquerading for IPv4 protocol) +- `org.eclipse.kura.net.admin.ipv6.FirewallConfigurationServiceIPv6`: which manages the Ip6 firewall configurations (open ports, port forwarding and masquerading for IPv6 protocol) + +To access these REST APIs, an identity with `rest.network.configuration` permission assigned is required. + +- [Request definitions](#request-definitions) + - [GET/configurableComponents](#getconfigurablecomponents) + - [GET/configurableComponents/configurations](#getconfigurablecomponentsconfigurations) + - [POST/configurableComponents/configurations/byPid](#postconfigurablecomponentsconfigurationsbypid) + - [POST/configurableComponents/configurations/byPid/_default](#postconfigurablecomponentsconfigurationsbypid_default) + - [PUT/configurableComponents/configurations/_update](#putconfigurablecomponentsconfigurations_update) +- [JSON definitions](#json-definitions) + - [BatchFailureReport](#batchfailurereport) + - [ComponentConfigurationList](#componentconfigurationlist) + - [GenericFailureReport](#genericfailurereport) + - [PidSet](#pidset) + - [UpdateComponentConfigurationRequest](#updatecomponentconfigurationrequest) + +## Request definitions +#### GET/configurableComponents + * **REST API path** : `/services/networkConfiguration/v1/configurableComponents` + * **description** : Returns the list of the available services that manages the network configurations on the system. + * **responses** : + * **200** + * **description** : The request succeeded. + * **response body** : + * [PidSet](#pidset) + * **500** + * **description** : An unexpected internal error occurred. + * **response body** : + * [GenericFailureReport](#genericfailurereport) + +#### GET/configurableComponents/configurations + * **REST API path** : `/services/networkConfiguration/v1/configurableComponents/configurations` + * **description** : Returns all of network component configurations available on the system. This request will return the `pid`, `ocd` and `properties`. + * **responses** : + * **200** + * **description** : The request succeeded. + * **response body** : + * [ComponentConfigurationList](#componentconfigurationlist) + * **500** + * **description** : An unexpected internal error occurred. + * **response body** : + * [GenericFailureReport](#genericfailurereport) + +#### POST/configurableComponents/configurations/byPid + * **REST API path** : `/services/networkConfiguration/v1/configurableComponents/configurations/byPid` + * **description** : Returns a user selected set of network configurations. This request will return the `pid`, `ocd` and `properties`. + * **request body** : + * [PidSet](#pidset) + * **responses** : + * **200** + * **description** : The request succeeded. If the network configuration for a given pid cannot be found, it will not be included in the result. + * **response body** : + * [ComponentConfigurationList](#componentconfigurationlist) + * **400** + * **description** : The request body is not valid JSON or it contains invalid parameters. + * **response body** : + * [GenericFailureReport](#genericfailurereport) + * **500** + * **description** : An unexpected internal error occurred. + * **response body** : + * [GenericFailureReport](#genericfailurereport) + +#### POST/configurableComponents/configurations/byPid/_default + * **REST API path** : `/services/networkConfiguration/v1/configurableComponents/configurations/byPid/_default` + * **description** : Returns the default network configuration for a given set of network component pids. The default configurations are generated basing on component definition only, user applied modifications will not be taken into account. This request will return the `pid`, `ocd` and `properties`. + * **request body** : + * [PidSet](#pidset) + * **responses** : + * **200** + * **description** : The request succeeded. If the network configuration for a given pid cannot be found, it will not be included in the result. + * **response body** : + * [ComponentConfigurationList](#componentconfigurationlist) + * **400** + * **description** : The request body is not valid JSON or it contains invalid parameters. + * **response body** : + * [GenericFailureReport](#genericfailurereport) + * **500** + * **description** : An unexpected internal error occurred. + * **response body** : + * [GenericFailureReport](#genericfailurereport) + +#### PUT/configurableComponents/configurations/_update + * **REST API path** : `/services/networkConfiguration/v1/configurableComponents/configurations/_update` + * **description** : Updates a given set of network component configurations. This request can be also used to apply a network configuration snapshot. + * **request body** : + * [UpdateComponentConfigurationRequest](#updatecomponentconfigurationrequest) + * **responses** : + * **200** + * **description** : The request succeeded. + * **400** + * **description** : The request body is not valid JSON or it contains invalid parameters. + * **response body** : + * [GenericFailureReport](#genericfailurereport) + * **500** + * **description** : In case of processing errors, the device will attempt to return a detailed error response containing a message describing the failure reason for each operation. The operation ids are the following: `update:$pid` for component update operations, where `$pid` is the pid of the instance, and `snapshot`, for the snapshot creation operation. In case of an unexpected failure, a generic error response will be returned. + * **response body** : + + **Variants**: + + * **object** + * [GenericFailureReport](#genericfailurereport) + * **object** + * [BatchFailureReport](#batchfailurereport) + + +## JSON definitions + +#### BatchFailureReport +An object that is returned by requests that involve multiple operations, when at least one operation failed. + This object report an error message for each of the operations that failed. The operations are identified by an id, see request documentation for more details. + If an operation is not listed by this object, then the operation succeeded. +
**Properties**: + +* **failures**: `array` + The list of operations that failed. + * array elements: `object` + An object reporting details about an operation failure. +
**Properties**: + + * **id**: `string` + An identifier of the failed operation. + * **message**: `string` + A message describing the failure. + +```json +{ + "failures": [ + { + "id": "create:testComponent", + "message": "Invalid parameter. pid testComponent already exists" + }, + { + "id": "create:otherComponent", + "message": "Invalid parameter. pid otherComponent already exists" + } + ] +} +``` + +#### ComponentConfigurationList +Represents a list of component configurations. +
**Properties**: + +* **configs**: `array` + The component configurations + * array elements: `object` + * [ComponentConfiguration](../../core-services/configuration-service-rest-v2.md#componentconfiguration) + +```json +{ + "configs": [ + { + "pid": "org.eclipse.kura.net.admin.FirewallConfigurationService", + "definition": { + "ad": [ + { + "name": "firewall.open.ports", + "description": "The list of firewall opened ports.", + "id": "firewall.open.ports", + "type": "STRING", + "cardinality": 0, + "defaultValue": "", + "isRequired": true + }, + { + "name": "firewall.port.forwarding", + "description": "The list of firewall port forwarding rules.", + "id": "firewall.port.forwarding", + "type": "STRING", + "cardinality": 0, + "defaultValue": "", + "isRequired": true + }, + { + "name": "firewall.nat", + "description": "The list of firewall NAT rules.", + "id": "firewall.nat", + "type": "STRING", + "cardinality": 0, + "defaultValue": "", + "isRequired": true + } + ], + "name": "FirewallConfigurationService", + "description": "Firewall Configuration Service", + "id": "org.eclipse.kura.net.admin.FirewallConfigurationService" + }, + "properties": { + "firewall.open.ports": { + "value": "22,tcp,0.0.0.0/0,eth0,,,,#;22,tcp,0.0.0.0/0,wlan0,,,,#;443,tcp,0.0.0.0/0,eth0,,,,#;443,tcp,0.0.0.0/0,wlan0,,,,#;4443,tcp,0.0.0.0/0,eth0,,,,#;4443,tcp,0.0.0.0/0,wlan0,,,,#;1450,tcp,0.0.0.0/0,eth0,,,,#;1450,tcp,0.0.0.0/0,wlan0,,,,#;5002,tcp,127.0.0.1/32,,,,,#;53,udp,0.0.0.0/0,eth0,,,,#;53,udp,0.0.0.0/0,wlan0,,,,#;67,udp,0.0.0.0/0,eth0,,,,#;67,udp,0.0.0.0/0,wlan0,,,,#;8000,tcp,0.0.0.0/0,eth0,,,,#;8000,tcp,0.0.0.0/0,wlan0,,,,#", + "type": "STRING" + }, + "firewall.port.forwarding": { + "value": "", + "type": "STRING" + }, + "firewall.nat": { + "value": "", + "type": "STRING" + }, + "kura.service.pid": { + "value": "org.eclipse.kura.net.admin.FirewallConfigurationService", + "type": "STRING" + }, + "service.pid": { + "value": "org.eclipse.kura.net.admin.FirewallConfigurationService", + "type": "STRING" + } + } + }, + { + "pid": "org.eclipse.kura.net.admin.ipv6.FirewallConfigurationServiceIPv6", + "definition": { + "ad": [ + { + "name": "firewall.ipv6.open.ports", + "description": "The list of firewall opened ports.", + "id": "firewall.ipv6.open.ports", + "type": "STRING", + "cardinality": 0, + "defaultValue": "", + "isRequired": true + }, + { + "name": "firewall.ipv6.port.forwarding", + "description": "The list of firewall port forwarding rules.", + "id": "firewall.ipv6.port.forwarding", + "type": "STRING", + "cardinality": 0, + "defaultValue": "", + "isRequired": true + }, + { + "name": "firewall.ipv6.nat", + "description": "The list of firewall NAT rules.", + "id": "firewall.ipv6.nat", + "type": "STRING", + "cardinality": 0, + "defaultValue": "", + "isRequired": true + } + ], + "name": "FirewallConfigurationServiceIPv6", + "description": "Firewall Configuration Service IPV6", + "id": "org.eclipse.kura.net.admin.ipv6.FirewallConfigurationServiceIPv6" + }, + "properties": { + "firewall.ipv6.port.forwarding": { + "value": "", + "type": "STRING" + }, + "firewall.ipv6.nat": { + "value": "", + "type": "STRING" + }, + "firewall.ipv6.open.ports": { + "value": "1234,tcp,0:0:0:0:0:0:0:0/0,,,,,#", + "type": "STRING" + }, + "kura.service.pid": { + "value": "org.eclipse.kura.net.admin.ipv6.FirewallConfigurationServiceIPv6", + "type": "STRING" + }, + "service.pid": { + "value": "org.eclipse.kura.net.admin.ipv6.FirewallConfigurationServiceIPv6", + "type": "STRING" + } + } + } + ] +} +``` + +#### GenericFailureReport +An object reporting a failure message. +
**Properties**: + +* **message**: `string` + A message describing the failure. + +```json +{ + "message": "An unexpected error occurred." +} +``` + +#### PidSet +Represents a set of pids or factory pids. +
**Properties**: + +* **pids**: `array` + The set of pids + * array elements: `string` + The pid + +```json +{ + "pids": [ + "org.eclipse.kura.net.admin.ipv6.FirewallConfigurationServiceIPv6", + "org.eclipse.kura.net.admin.NetworkConfigurationService", + "org.eclipse.kura.net.admin.FirewallConfigurationService" + ] +} +``` + +#### UpdateComponentConfigurationRequest +An object that describes a set of configurations that need to be updated. +
**Properties**: + +* **configs**: `array` + The configurations to be updated. The `ocd` field can be omitted, it will be ignored if specified. + * array elements: `object` + * [ComponentConfiguration](../../core-services/configuration-service-rest-v2.md#componentconfiguration) +* **takeSnapshot**: `bool` + * **optional** The `true` value will be used as default if not explicitly specified + Defines whether a new snapshot should be created after that the component configurations have been applied. + +```json +{ + "configs": [ + { + "pid": "org.eclipse.kura.net.admin.ipv6.FirewallConfigurationServiceIPv6", + "properties": { + "firewall.ipv6.open.ports": { + "value": "1234,tcp,0:0:0:0:0:0:0:0/0,,,,,#", + "type": "STRING" + } + } + }, + { + "pid": "org.eclipse.kura.net.admin.NetworkConfigurationService", + "properties": { + "net.interface.eth0.config.ip6.status": { + "value": "netIPv6StatusUnmanaged", + "type": "STRING" + } + } + } + ], + "takeSnapshot": true +} +``` \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml index 6098c883004..ef75b553924 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -155,6 +155,7 @@ nav: - Deploy: references/rest-apis/rest-deploy-api.md - Identity: references/rest-apis/rest-identity-api.md - Inventory: references/rest-apis/rest-inventory-api.md + - Network Configuration: references/rest-apis/rest-network-configuration-api.md - Position: references/rest-apis/rest-position-api.md - Security: references/rest-apis/rest-security-api.md - Service Listing: references/rest-apis/rest-service-listing-api.md