New network API doc (#721)

* New network API doc

* Apply suggestions from code review

Co-authored-by: Joakim Sørensen <joasoe@gmail.com>
Co-authored-by: Franck Nijhof <git@frenck.dev>

* Add VLAN payload

* Update docs/api/supervisor/endpoints.md

Co-authored-by: Joakim Sørensen <joasoe@gmail.com>

* Apply suggestions from code review

Co-authored-by: Joakim Sørensen <joasoe@gmail.com>

Co-authored-by: Joakim Sørensen <joasoe@gmail.com>
Co-authored-by: Franck Nijhof <git@frenck.dev>
This commit is contained in:
Pascal Vizeli 2020-11-10 17:53:54 +01:00 committed by GitHub
parent 8d282edc8c
commit ea486b226d
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
2 changed files with 118 additions and 36 deletions

View File

@ -1404,25 +1404,31 @@ Get network information.
| key | description | | 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 | | docker | Information about the internal docker network |
**Example response:** **Example response:**
```json ```json
{ {
"interfaces": { "interfaces": [
"eth0": { {
"interface": "eth0", "interface": "eth0",
"ip_address": "192.168.1.100/24", "type": "ethernet",
"gateway": "192.168.1.1", "primary": true,
"id": "Wired connection 1", "enabled": true,
"type": "802-3-ethernet", "connected": true,
"nameservers": ["192.168.1.1"], "ipv4": {
"method": "static", "method": "static",
"primary": true "ip_address": "192.168.1.100/24",
"gateway": "192.168.1.1",
"nameservers": ["192.168.1.1"],
},
"ipv6": null,
"wifi": null,
"vlan": null,
} }
}, ],
"docker": { "docker": {
"interface": "hassio", "interface": "hassio",
"address": "172.30.32.0/23", "address": "172.30.32.0/23",
@ -1434,49 +1440,89 @@ Get network information.
</ApiEndpoint> </ApiEndpoint>
<ApiEndpoint path="/network/<interface>/info" method="get"> <ApiEndpoint path="/network/interface/<interface>/info" method="get">
Returns a [Network interface model](api/supervisor/models.md#network-interface) for a specific network interface. Returns a [Network interface model](api/supervisor/models.md#network-interface) for a specific network interface.
</ApiEndpoint> </ApiEndpoint>
<ApiEndpoint path="/network/<interface>/update" method="post"> <ApiEndpoint path="/network/interface/<interface>/update" method="post">
Update the settings for a network interface. Update the settings for a network interface.
**Payload:** **Payload:**
| key | type | optional | description | | key | type | optional | description |
| ------- | ------ | -------- | ---------------------------------------------------------------------- | | ------- | ------ | -------- | ---------------------------------------------------------------------- |
| address | string | True | The new IP address for the interface in the X.X.X.X/XX format | | enabled | bool | True | Enable/Disable an ethernet interface / VLAN got removed with disabled |
| dns | list | True | List of DNS servers to use | | ipv4 | dict | True | A struct with ipv4 interface settings |
| gateway | string | True | The gateway the interface should use | | ipv6 | dict | True | A struct with ipv6 interface settings |
| method | string | True | Set if the interface should use DHCP or not, can be `dhcp` or `static` | | wifi | dict | True | A struct with Wireless connection settings |
**You need to supply at least one key in the payload.** **ipv4 / ipv6:**
:::warning | key | type | optional | description |
If you change the `address` or `gateway` you may need to reconnect to the new address | ----------- | ------ | -------- | ------------------------------------------------------------------------------------- |
::: | 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` |
</ApiEndpoint>
<ApiEndpoint path="/network/interface/<interface>/accesspoints" method="get">
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:** **Example response:**
```json ```json
{ {
"ip_address": "192.168.1.100/24", "accesspoints": [
"gateway": "192.168.1.1", {
"id": "Wired connection 1", "mode": "infrastructure",
"type": "802-3-ethernet", "ssid": "MY_TestWifi",
"nameservers": ["192.168.1.1"], "mac": "00:00:00:00",
"method": "static", "frequency": 24675,
"primary": true "signal": 90
}
]
} }
``` ```
</ApiEndpoint> </ApiEndpoint>
<ApiEndpoint path="/network/interface/<interface>/vlan/<id>" method="post">
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 |
</ApiEndpoint>
### Observer ### Observer
<ApiEndpoint path="/observer/info" method="get"> <ApiEndpoint path="/observer/info" method="get">

View File

@ -95,13 +95,49 @@ These models are describing objects that are getting returned from the superviso
| key | type | description | | key | type | description |
| ----------- | ------- | ---------------------------------------------------------------------------- | | ----------- | ------- | ---------------------------------------------------------------------------- |
| interface | string | The interface name i.e eth0. | | 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. | | type | string | The interface type: `ethernet`, `wireless` or `vlan`. |
| gateway | string | The IP address of the gateway. | | enabled | boolean | Return True if the interface is enabled. |
| id | string | The ID of the interface. | | connected | boolean | Return True if the interface is connected to the network. |
| 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". |
| primary | boolean | `true` if it's the primary network interface. | | 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 ## Panel