From ea486b226d9e272c84b8fc9e3b7ddb4b748199e6 Mon Sep 17 00:00:00 2001 From: Pascal Vizeli Date: Tue, 10 Nov 2020 17:53:54 +0100 Subject: [PATCH] New network API doc (#721) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * New network API doc * Apply suggestions from code review Co-authored-by: Joakim Sørensen Co-authored-by: Franck Nijhof * Add VLAN payload * Update docs/api/supervisor/endpoints.md Co-authored-by: Joakim Sørensen * Apply suggestions from code review Co-authored-by: Joakim Sørensen Co-authored-by: Joakim Sørensen Co-authored-by: Franck Nijhof --- docs/api/supervisor/endpoints.md | 106 ++++++++++++++++++++++--------- docs/api/supervisor/models.md | 48 ++++++++++++-- 2 files changed, 118 insertions(+), 36 deletions(-) diff --git a/docs/api/supervisor/endpoints.md b/docs/api/supervisor/endpoints.md index b5ed1025..936e322e 100644 --- a/docs/api/supervisor/endpoints.md +++ b/docs/api/supervisor/endpoints.md @@ -1404,25 +1404,31 @@ Get network information. | key | description | | ---------- | ---------------------------------------------------------------------- | -| interfaces | A dictionary of [Network interface models](api/supervisor/models.md#network-interface) | +| interfaces | A list of [Network interface models](api/supervisor/models.md#network-interface) | | docker | Information about the internal docker network | **Example response:** ```json { - "interfaces": { - "eth0": { + "interfaces": [ + { "interface": "eth0", - "ip_address": "192.168.1.100/24", - "gateway": "192.168.1.1", - "id": "Wired connection 1", - "type": "802-3-ethernet", - "nameservers": ["192.168.1.1"], - "method": "static", - "primary": true + "type": "ethernet", + "primary": true, + "enabled": true, + "connected": true, + "ipv4": { + "method": "static", + "ip_address": "192.168.1.100/24", + "gateway": "192.168.1.1", + "nameservers": ["192.168.1.1"], + }, + "ipv6": null, + "wifi": null, + "vlan": null, } - }, + ], "docker": { "interface": "hassio", "address": "172.30.32.0/23", @@ -1434,49 +1440,89 @@ Get network information. - + Returns a [Network interface model](api/supervisor/models.md#network-interface) for a specific network interface. - - + Update the settings for a network interface. **Payload:** | key | type | optional | description | | ------- | ------ | -------- | ---------------------------------------------------------------------- | -| address | string | True | The new IP address for the interface in the X.X.X.X/XX format | -| dns | list | True | List of DNS servers to use | -| gateway | string | True | The gateway the interface should use | -| method | string | True | Set if the interface should use DHCP or not, can be `dhcp` or `static` | +| enabled | bool | True | Enable/Disable an ethernet interface / VLAN got removed with disabled | +| ipv4 | dict | True | A struct with ipv4 interface settings | +| ipv6 | dict | True | A struct with ipv6 interface settings | +| wifi | dict | True | A struct with Wireless connection settings | -**You need to supply at least one key in the payload.** +**ipv4 / ipv6:** -:::warning -If you change the `address` or `gateway` you may need to reconnect to the new address -::: +| key | type | optional | description | +| ----------- | ------ | -------- | ------------------------------------------------------------------------------------- | +| method | string | True | Set if the interface should use DHCP or not, can be `dhcp`, `static` or `disabled` | +| address | list | True | The new IP address for the interface in the X.X.X.X/XX format as list | +| nameservers | list | True | List of DNS servers to use | +| gateway | string | True | The gateway the interface should use | -When the call is complete it returns the changed [Network interface model](api/supervisor/models.md#network-interface). +**wifi:** + +| key | type | optional | description | +| ------ | ------ | -------- | ------------------------------------------------------------------------------ | +| mode | string | True | Set the mode `infrastructure` (default), `mesh`, `adhoc` or `ap` | +| auth | string | True | Set the auth mode: `open` (default), `web`, `wpa-psk` | +| ssid | string | True | Set the SSID for connect into | +| psk | string | True | The shared key which is used with `web` or `wpa-psk` | + + + + + +Return a list of available [Access Points](api/supervisor/models.md#access-points) on this Wireless interface. + +**This function only works with Wireless interfaces!** + +**Returned data:** + +| key | description | +| ------------ | ---------------------------------------------------------------------- | +| accesspoints | A list of [Access Points](api/supervisor/models.md#access-points) | **Example response:** ```json { - "ip_address": "192.168.1.100/24", - "gateway": "192.168.1.1", - "id": "Wired connection 1", - "type": "802-3-ethernet", - "nameservers": ["192.168.1.1"], - "method": "static", - "primary": true + "accesspoints": [ + { + "mode": "infrastructure", + "ssid": "MY_TestWifi", + "mac": "00:00:00:00", + "frequency": 24675, + "signal": 90 + } + ] } ``` + + +Create a new VLAN *id* on this network interface. + +**This function only works with ethernet interfaces!** + +**Payload:** + +| key | type | optional | description | +| ------- | ------ | -------- | ---------------------------------------------------------------------- | +| ipv4 | dict | True | A struct with ipv4 interface settings | +| ipv6 | dict | True | A struct with ipv6 interface settings | + + + ### Observer diff --git a/docs/api/supervisor/models.md b/docs/api/supervisor/models.md index a514f2e4..a54689a4 100644 --- a/docs/api/supervisor/models.md +++ b/docs/api/supervisor/models.md @@ -95,13 +95,49 @@ These models are describing objects that are getting returned from the superviso | key | type | description | | ----------- | ------- | ---------------------------------------------------------------------------- | | interface | string | The interface name i.e eth0. | -| ip_address | string | The IP address and the netmask in a X.X.X.X/XX format. | -| gateway | string | The IP address of the gateway. | -| id | string | The ID of the interface. | -| type | string | The interface type. | -| nameservers | list | A list containing the IP addresses of the configured nameservers as strings. | -| method | string | The method used to set the IP can be "static" or "dhcp". | +| type | string | The interface type: `ethernet`, `wireless` or `vlan`. | +| enabled | boolean | Return True if the interface is enabled. | +| connected | boolean | Return True if the interface is connected to the network. | | primary | boolean | `true` if it's the primary network interface. | +| ipv4 | struct or null | An IP config struct with IPv4 connection details. | +| ipv6 | struct or null | An IP config struct with IPv6 connection details. | +| wifi | struct or null | An Wifi config struct with wireless connection details. | +| vlan | struct or null | An Vlan config struct with details about the vlan. | + +### IP configuration + +| key | type | description | +| ----------- | ------- | ---------------------------------------------------------------------------- | +| method | string | The method used to set the IP can be `static`, `dhcp` or `disabled`. | +| address | list | A list with IP address and the netmask in a X.X.X.X/XX format. | +| gateway | string | The IP address of the gateway. | +| nameservers | list | A list containing the IP addresses of the configured nameservers as strings. | + +### Wifi configuration + +| key | type | description | +| ----------- | ------- | ---------------------------------------------------------------------------- | +| mode | string | Set the mode `infrastructure`, `mesh`, `adhoc` or `ap`. | +| auth | string | Set the auth mode: `open`, `web` or `wpa-psk`. | +| ssid | string | Set the SSID for the Wireless. | +| signal | integer | Percentage of signal strength. | + +### VLAN configuration + +| key | type | description | +| ------- | ------- | ---------------------------------------------------------------------------- | +| id | integer | The VLAN ID. | +| parent | string | Parent interface which is the vlan attached. | + +## Access-Points + +| key | type | description | +| ---------- | ------- | ---------------------------------------------------------------------------- | +| mode | string | One of: `infrastructure`, `mesh` or `adhoc`. | +| ssid | string | Wireless network ID. | +| frequency | integer | The operating frequency of this Access Point. | +| signal | integer | Percentage of signal strength. | +| mac | string | MAC Address of the Access Point. | ## Panel