Add information for new role API access on Hass.io (#89)

* Add information for new role API access on Hass.io

* Update hassio_addon_communication.md

* Update hassio_addon_config.md

* Update hassio_addon_security.md

* Update hassio_addon_security.md

docs/hassio_addon_communication.md

@@ -25,7 +25,7 @@ We have severals services for Hass.io inside Home Assistant to run tasks. To sen
 
 ## Hass.io API
 
-To enables calls to the [Hass.io API][hassio-api], add `hassio_api: true` to `config.json` and read the environment variable `HASSIO_TOKEN`. Now you can use the API over the URL: `http://hassio/`. Use the `HASSIO_TOKEN` with header `X-HASSIO-KEY`.
+To enables calls to the [Hass.io API][hassio-api], add `hassio_api: true` to `config.json` and read the environment variable `HASSIO_TOKEN`. Now you can use the API over the URL: `http://hassio/`. Use the `HASSIO_TOKEN` with header `X-HASSIO-KEY`. It could be that you need also change the Hass.io API role like `hassio_role: default`.
 
 Add-ons can call some API commands without need set `hassio_api: true`:
 - `/homeassistant/info`

docs/hassio_addon_config.md

@@ -113,12 +113,14 @@ The config for an add-on is stored in `config.json`.
 | host_network | bool | no | If that is True, the add-on run on host network.
 | host_ipc | bool | no | Default False. Allow to share the IPC namespace with others.
 | host_dbus | bool | no | Default False. Map Host dbus service into add-on.
+| host_pid | bool | no | Default False. Allow to run container on host PID namespace. Work only for not protected add-ons.
 | devices | list | no | Device list to map into the add-on. Format is: `<path_on_host>:<path_in_container>:<cgroup_permissions>`. i.e. `/dev/ttyAMA0:/dev/ttyAMA0:rwm`
 | auto_uart | bool | no | Default False. Auto mapping all UART/Serial device from host into add-on.
+| hassio_role | str | no | Default `default`. Role based access to Hass.io API. Available: `default`, `homeassistant`, `manager`, `admin`.
 | hassio_api | bool | no | This add-on can access to Hass.io REST API. It set the host alias `hassio`.
 | homeassistant_api | bool | no | This add-on can access to Hass.io Home-Assistant REST API proxy. Use `http://hassio/homeassistant/api`.
 | docker_api | bool | no | Allow read-oly access to docker API for add-on. Work only for not protected add-ons.
-| privileged | list | no | Privilege for access to hardware/system. Available access: `NET_ADMIN`, `SYS_ADMIN`, `SYS_RAWIO`, `SYS_TIME`, `SYS_NICE`, `S40-DFS-P01`
+| privileged | list | no | Privilege for access to hardware/system. Available access: `NET_ADMIN`, `SYS_ADMIN`, `SYS_RAWIO`, `SYS_TIME`, `SYS_NICE`, `SYS_RESOURCE`, `SYS_PTRACE`.
 | full_access | bool | no | Give full access to hardware like the privileged mode in docker. Work only for not protected add-ons.
 | apparmor | bool/string | no | Enable or disable AppArmor support. If it is enable, you can also use custom profiles with the name of the profile.
 | map | list | no | List of maps for additional Hass.io folders. Possible values: `config`, `ssl`, `addons`, `backup`, `share`. Defaults to `ro`, which you can change by adding `:rw` to the end of the name.

docs/hassio_addon_security.md

@@ -4,6 +4,19 @@ title: "Add-on security"
 
 Hass.io rates every add-on based on the wanted rights. An add-on with a rating of 6 is very secure. If an add-on has a rating of 1, you shouldn't run this add-on unless you are 100% sure that you can trust the source.
 
+## API Role
+
+For access to Hass.io API you need define a role or you run in default mode. This is only required for Hass.io API not Home Assistant proxy. Any of the role have also the default API calls inheret for that are no settings are required.
+
+### Available Roles
+
+| Role | Description |
+|------|-------------|
+| default | Have access to all `info` calls |
+| homeassistant | Can access to all Home Assistant API endpoints |
+| manager | Is for Add-ons they run CLIs and need extended rights |
+| admin | Have access to every API call. That is the only one they can disable/enable the Add-on protection mode |
+
 ## Protection
 
 Default, all add-ons run in protection enabled mode. This mode prevents the add-on from getting any rights on the system. If an add-on requires more rights, you can disable this protection via the API add-on options for that add-on. But be carful, an add-on with disabled protection can destroy your system!
@@ -15,3 +28,4 @@ As a developer, follow the following best practices to make your add-on secure:
 - Don't run on host network
 - Create an AppArmor profile
 - Map folders read only if you don't need write access
+- If you need any API access, make sure you that you not grant to highest permission if you don't need it