From def821d29ce8adb07d3a27f90b312447019f5650 Mon Sep 17 00:00:00 2001 From: Fabian Affolter Date: Fri, 3 Jul 2020 15:41:43 +0200 Subject: [PATCH] Update table content (#593) --- docs/add-ons/configuration.md | 96 +++++++++++++++++------------------ 1 file changed, 48 insertions(+), 48 deletions(-) diff --git a/docs/add-ons/configuration.md b/docs/add-ons/configuration.md index 187211e3..14d057b3 100644 --- a/docs/add-ons/configuration.md +++ b/docs/add-ons/configuration.md @@ -22,7 +22,7 @@ addon_name/ As with every Docker container, you will need a script to run when the container is started. A user might run many add-ons, so it is encouraged to try to stick to Bash scripts if you're doing simple things. -All our Images have also [bashio][bashio] installed. It contains a set of commonly used operations and can be used to be included in add-ons to reduce code duplication across add-ons and therefore making it easier to develop and maintain add-ons. +All our images have also [bashio][bashio] installed. It contains a set of commonly used operations and can be used to be included in add-ons to reduce code duplication across add-ons and therefore making it easier to develop and maintain add-ons. When developing your script: @@ -45,9 +45,9 @@ then there will be a variable `TARGET` containing `beer` in the environment of y [bashio]: https://github.com/hassio-addons/bashio -## Add-on Docker file +## Add-on Dockerfile -All add-ons are based on latest Alpine Linux. Hass.io will automatically substitute the right base image based on the machine architecture. Add `tzdata` if you need run in a different timezone. `tzdata` Is is already added to our base images. +All add-ons are based on latest Alpine Linux image. Home Assistant will automatically substitute the right base image based on the machine architecture. Add `tzdata` if you need run in a different timezone. `tzdata` Is is already added to our base images. ```dockerfile ARG BUILD_FROM @@ -85,7 +85,7 @@ We support the following build arguments by default: ## Add-on config -The config for an add-on is stored in `config.json`. +The configuration for an add-on is stored in `config.json`. ```json { @@ -94,7 +94,7 @@ The config for an add-on is stored in `config.json`. "slug": "folder", "description": "long description", "arch": ["amd64"], - "url": "website with more information about add-on (ie a forum thread for support)", + "url": "website with more information about add-on (e.g., a forum thread for support)", "startup": "application", "boot": "auto", "ports": { @@ -109,60 +109,60 @@ The config for an add-on is stored in `config.json`. | Key | Type | Required | Description | | --- | ---- | -------- | ----------- | -| name | string | yes | Name of the add-on -| version | string | yes | Version of the add-on -| slug | string | yes | Slug of the add-on. This needs to be unique in scope to the [repository](repository.md) that the add-on is published in, and URI friendly. -| description | string | yes | Description of the add-on +| name | string | yes | Name of the add-on. +| version | string | yes | Version of the add-on. +| slug | string | yes | Slug of the add-on. This needs to be unique in the scope of the [repository](repository.md) that the add-on is published in and URI friendly. +| description | string | yes | Description of the add-on. | arch | list | yes | List of supported arch: `armhf`, `armv7`, `aarch64`, `amd64`, `i386`. | machine | list | no | Default it support any machine type. You can select that this add-on run only on specific machines. -| url | url | no | Homepage of the addon. Here you can explain the add-ons and options. -| startup | string | yes | `initialize` will start addon on setup of Hass.io. `system` is for things like databases and not dependent on other things. `services` will start before Home Assistant, while `application` is started afterwards. Finally `once` is for applications that don't run as a daemon. -| webui | string | no | A URL for web interface of this add-on. Like `http://[HOST]:[PORT:2839]/dashboard`, the port needs the internal port, which will be replaced with the effective port. It is also possible to bind the proto part to a config options with: `[PROTO:option_name]://[HOST]:[PORT:2839]/dashboard` and he lookup if they is True and going to `https`. -| boot | string | yes | `auto` by system and manual or only `manual` -| ports | dict | no | Network ports to expose from the container. Format is `"container-port/type": host-port`. If host-port is `null`, the mapping is disabled. +| url | url | no | Homepage of the add-on. Here you can explain the add-ons and options. +| startup | string | yes | `initialize` will start add-on on setup of Home Assistant. `system` is for things like databases and not dependent on other things. `services` will start before Home Assistant, while `application` is started afterwards. Finally `once` is for applications that don't run as a daemon. +| webui | string | no | An URL for web interface of this add-on. Like `http://[HOST]:[PORT:2839]/dashboard`, the port needs the internal port, which will be replaced with the effective port. It is also possible to bind the protocol part to a configuration options with: `[PROTO:option_name]://[HOST]:[PORT:2839]/dashboard` and it's looked up if it is `true` and it's going to `https`. +| boot | string | yes | `auto` by system and manual or only `manual`. +| ports | dict | no | Network ports to expose from the container. Format is `"container-port/type": host-port`. If host-port is `null` then the mapping is disabled. | ports_description | dict | no | Network ports description mapping. Format is `"container-port/type": "description of this port"`. -| 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: `::`. i.e. `/dev/ttyAMA0:/dev/ttyAMA0:rwm` -| udev | bool | no | Default False. Set this True, if your container runs a udev process of its own. -| auto_uart | bool | no | Default False. Auto mapping all UART/Serial device from host into add-on. -| homeassistant | string | no | Pin a minimum required Home Assistant Core version for such Add-on. Value is a version string like `0.91.2`. -| hassio_role | str | no | Default `default`. Role-based access to Supervisor API. Available: `default`, `homeassistant`, `backup`, `manager`, `admin`. -| hassio_api | bool | no | This add-on can access to Hass.io REST API. Use `http://supervisor`. -| homeassistant_api | bool | no | This add-on can access to Hass.io Home-Assistant REST API proxy. Use `http://supervisor/core/api`. +| 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 the host D-Bus service into the 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: `::`. E.g., `/dev/ttyAMA0:/dev/ttyAMA0:rwm` +| udev | bool | no | Default `false`. Set this `true`, if your container runs an udev process of its own. +| auto_uart | bool | no | Default `false`. Auto mapping all UART/serial device from host into add-on. +| homeassistant | string | no | Pin a minimum required Home Assistant Core version for the add-on. Value is a version string like `0.91.2`. +| hassio_role | str | no | Default `default`. Role-based access to Supervisor API. Available: `default`, `homeassistant`, `backup`, `manager` or `admin` +| hassio_api | bool | no | This add-on can access the Supervisor's REST API. Use `http://supervisor`. +| homeassistant_api | bool | no | This add-on can access to the Home Assistant REST API proxy. Use `http://supervisor/core/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`, `SYS_RESOURCE`, `SYS_PTRACE`, `SYS_MODULE`, `DAC_READ_SEARCH`. +| 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`, `SYS_MODULE` or `DAC_READ_SEARCH` | 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. -| environment | dict | no | A dict of environment variable to run add-on. -| audio | bool | no | Boolean. Mark this add-on to use internal an audio system. We map a working PulseAudio setup into container. If you application did not support PulseAudio, you need maybe install: Alpine `alsa-plugins-pulse` or debian/ubunut `libasound2-plugins`. -| video | bool | no | Boolean. Mark this add-on touse internal an video system. All available devices will be mapped into addon. -| gpio | bool | no | Boolean. If this is set to True, `/sys/class/gpio` will map into add-on for access to GPIO interface from kernel. Some library need also `/dev/mem` and `SYS_RAWIO` for read/write access to this device. On system with AppArmor enabled, you need disable AppArmor or better for security, provide you own profile for the add-on. +| map | list | no | List of maps for additional Home Assistant folders. Possible values: `config`, `ssl`, `addons`, `backup` or `share`. Defaults to `ro`, which you can change by adding `:rw` to the end of the name. +| environment | dict | no | A dictionary of environment variable to run add-on. +| audio | bool | no | Boolean. Mark this add-on to use internal an audio system. We map a working PulseAudio setup into container. If you application did not support PulseAudio, you need maybe install: Alpine Linux `alsa-plugins-pulse` or Debian/Ubuntu `libasound2-plugins`. +| video | bool | no | Boolean. Mark this add-on to use the internal video system. All available devices will be mapped into the add-on. +| gpio | bool | no | Boolean. If this is set to `true`, `/sys/class/gpio` will map into add-on for access to GPIO interface from kernel. Some library need also `/dev/mem` and `SYS_RAWIO` for read/write access to this device. On system with AppArmor enabled, you need disable AppArmor or better for security, provide you own profile for the add-on. | devicetree | bool | no | Boolean. If this is set to True, `/device-tree` will map into add-on. | kernel_modules | bool | no | Map host kernel modules and config into add-on (readonly). -| stdin | bool | no | Boolean. If that is enable, you can use the STDIN with Hass.io API. -| legacy | bool | no | Boolean. If the docker image have no hass.io labels, you can enable the legacy mode to use the config data. -| options | dict | yes | Default options value of the add-on -| schema | dict | yes | Schema for options value of the add-on. It can be `False` to disable schema validation and use custom options. +| stdin | bool | no | Boolean. If that is enable, you can use the STDIN with Home Assistant API. +| legacy | bool | no | Boolean. If the Docker image have no `hass.io` labels, you can enable the legacy mode to use the config data. +| options | dict | yes | Default options value of the add-on. +| schema | dict | yes | Schema for options value of the add-on. It can be `false` to disable schema validation and use custom options. | image | string | no | For use with Docker Hub and other container registries. -| timeout | integer | no | Default 10 (second). The timeout to wait until the docker is done or will be killed. -| tmpfs | string | no | Mount a tmpfs file system in `/tmpfs`. Valide format for this option is : `size=XXXu,uid=N,rw`. Size is mandatory, valid units (`u`) are `k`, `m` and `g` and `XXX` has to be replaced by a number. `uid=N` (with `N` the uid number) and `rw` are optional. -| discovery | list | no | A list of services they this Add-on allow to provide for Home Assistant. Currently supported: `mqtt` -| services | list | no | A list of services they will be provided or consumed with this Add-on. Format is `service`:`function` and functions are: `provide` (this add-on can provide this service), `want` (this add-on can use this service) or `need` (this add-on need this service to work correctly). -| auth_api | bool | no | Allow access to Home Assistent user backend. -| ingress | bool | no | Enable the ingress feature for the Add-on +| timeout | integer | no | Default 10 (second). The timeout to wait until the Docker daemon is done or will be killed. +| tmpfs | string | no | Mount a tmpfs filesystem in `/tmpfs`. Valid format for this option is : `size=XXXu,uid=N,rw`. Size is mandatory, valid units (`u`) are `k`, `m`, `g` and `XXX` has to be replaced by a number. `uid=N` (with `N` the uid number) and `rw` are optional. +| discovery | list | no | A list of services they this add-on allow to provide for Home Assistant. Currently supported: `mqtt` +| services | list | no | A list of services they will be provided or consumed with this add-on. Format is `service`:`function` and functions are: `provide` (this add-on can provide this service), `want` (this add-on can use this service) or `need` (this add-on need this service to work correctly). +| auth_api | bool | no | Allow access to Home Assistant user backend. +| ingress | bool | no | Enable the ingress feature for the add-on. | ingress_port | integer | no | Default `8099`. For Add-ons they run on host network, you can use `0` and read the port later on API. | ingress_entry | string | no | Modify the URL entry point from `/`. -| panel_icon | string | no | Default: mdi:puzzle. MDI icon for the menu panel integration. -| panel_title | string | no | Default add-on name, but can Modify with this options. -| panel_admin | bool | no | Default True. Make menu entry only available with admin privileged. +| panel_icon | string | no | Default: `mdi:puzzle`. MDI icon for the menu panel integration. +| panel_title | string | no | Default add-on name, but can modify with this options. +| panel_admin | bool | no | Default `true`. Make menu entry only available with admin privileged. | snapshot_exclude | list | no | List of file/path with glob support they are excluded from snapshots. -| advanced | bool | no | Default False. Make addon visible on simle mode or not. -| stage | string | no | Default `stable`. Flag add-on with follow attribute: `stable`, `experimental`, `deprecated` -| init | bool | no | Default `True`. Make it possible to disable the docker default system init because the image have his own init system. +| advanced | bool | no | Default `false`. Make addon visible on simle mode or not. +| stage | string | no | Default `stable`. Flag add-on with follow attribute: `stable`, `experimental` or `deprecated` +| init | bool | no | Default `true`. Make it possible to disable the Docker default system init because the image have his own init system. ### Options / Schema @@ -234,6 +234,6 @@ You need this only, if you not use the default images or need additional things. | squash | no | Default `False`. Be careful with this option, as you can not use the image for caching stuff after that! | args | no | Allow to set additional Docker build arguments as a dictionary. -We provide a set of [Base-Images][docker-base] which should cover a lot of needs. If you don't want use the Alpine based version or need a specific Image tag, feel free to pin this requirements for you build with `build_from` option. +We provide a set of [base images][docker-base] which should cover a lot of needs. If you don't want use the Alpine based version or need a specific image tag, feel free to pin this requirements for you build with `build_from` option. [docker-base]: https://github.com/home-assistant/docker-base