-
Notifications
You must be signed in to change notification settings - Fork 168
Configuration
Near the top of the configurator.py file you will find some global variables you can change to customize the configurator. If you are unfamiliar with Python: when setting variables of the type string, you have to write that within quotation marks. The default settings are fine for just checking this out quickly. With more customized setups you will have to change some settings though.
To keep your setting across updates it is also possible to save settings in an external file. In that case copy settings.conf whereever you like and append the full path to the file to the command when starting the configurator. E.g. sudo .configurator.py /home/homeassistant/.homeassistant/mysettings.conf.
This file is in JSON format. So make sure it has a valid syntax (you can set the editor to JSON to get syntax highlighting for the settings). The major difference to the settings in the py-file is, that None becomes null.
Another way of passing settings is by using environment variables. All settings passed via environment variables will overwrite the settings you have set in the settings.conf file. This allows you to provide settings in you systemd service file or the way it is usually done with Docker. The names of the environment variables have to be named exactly like the regular ones, prepended with the prefix HC_. You can customize this prefix in the settings.conf by setting ENV_PREFIX to something you like. ENV_PREFIX can not be set via environment variable. For settings that are usually defined as lists (ALLOWED_NETWORKS etc.) a comma is used as a separator for each value (e.g. HC_ALLOWED_NETWORKS="127.0.0.1,192.168.0.0/16").
The IP address the service is listening on. By default it is binding to 0.0.0.0, which is every IPv4 interface on the system. When using ::, all available IPv6- and IPv4-addresses will be used.
The port the service is listening on. By default it is using 3218, but you can change this if you need to. The former setting LISTENPORT still works but is deprecated. Please change your settings accordingly. When setting this option to 0 a dynamic port will be used and logged at startup. This probably is only useful in standalone mode and without firewall restrictions.
It is possible to place configurator.py somewhere else. Set the BASEPATH to something like "/home/homeassistant/.homeassistant", and no matter where you are running the configurator from, it will start serving files from there. This is needed if you plan on running the configurator with systemd.
Set ENFORCE_BASEPATH to True to lock the configurator into the basepath and thereby prevent it from opening files outside of the BASEPATH
If you're using SSL, set the paths to your SSL files here. This is similar to the SSL setup you can do in Home Assistant.
The configurator fetches some data from your running Home Assistant instance. If the API isn't available through the default URL, modify this variable to fix this. E.g. http://192.168.1.2:8123/api/. If you set this to None, the configurator will start in standalone mode.
The event observer requires direct access to the websocket API of Home Assistant. Use this option to prefill the URL in event observer dialog with the correct address. E.g. wss://hass.example.com/api/websocket. Without this option set the configurator uses the value of HASS_API, which might not always be the correct value.
If you plan on using API functions (reloading stuff, fetching entities and services etc.), you have to set your API password. Calling the API of Home Assistant is prohibited without authentication. Both the old fashioned api_password and the new long-lived access tokens (you can create those on your profile page at http://your-hass-address.com/profile) are supported.
Set IGNORE_SSL to True to disable SSL verification when connecting to the Home Assistant API (while fetching entities etc., not in your browser). This is useful if Home Assistant is configured with SSL, but the configurator accesses it via IP, in which case SSL verification will fail.
If you want to enable HTTP basic authentication you can set the desired username here. The : character is not allowed.
Set the password that should be used for authentication. Only if USERNAME and PASSWORD are set authentication will be enabled. You may provide the password as a SHA256-hash with the prefix {sha256}. For example PASSWORD = "test" is functionally equal to PASSWORD = "{sha256}9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08". The hash will be converted to lower case automatically. Using the hash provides extra security by not exposing the actual password in plaintext in your configuration.
The credentials in the form of "username:password" are now deprecated and should be removed from you configuration. Replace it by specifying USERNAME and PASSWORD. It will still work though to ensure backwards compatibility.
Limit access to the configurator by adding allowed IP addresses / networks to the list, e.g ALLOWED_NETWORKS = ["192.168.0.0/24", "172.16.47.23"]. If you are using the hass.io addon of the configurator, add the docker-network 172.30.0.0/16 to this list.
ALlow access to the configurator to client IP addesses which match the result of DNS lookups for the specified domains.
List of statically banned IP addresses, e.g. BANNED_IPS = ["1.1.1.1", "2.2.2.2"]
Ban IPs after n failed login attempts. Restart service to reset banning. The default of 0 disables this feature. CREDENTIALS has to be set for this to work.
Files and folders to ignore in the UI, e.g. IGNORE_PATTERN = [".*", "*.log", "__pycache__"]
Set this variable to True to enable Git integration. This feature requires GitPython
to be installed on the system that is running the configurator.
To push local commits to a remote repository, you have to add the remote manually: git remote add origin ssh://somehost:/user/repo.git
Verify, that the user that is running the configurator is allowed to push without any interaction (by using SSH PubKey authentication for example).
If set to true, directories will be displayed at the top.
Don't display hidden files (starting with .)
If set to somesecretkeynobodycanguess, you can browse to https://your.configurator:3218/somesecretkeynobodycanguess from any IP, and it will be removed from the BANNED_IPS list (in case it has been banned before) and added to the ALLOWED_NETWORKS list. Once the request has been processed you will automatically be redirected to the configurator. Think of this as dynamically allowing access from untrusted IPs by providing a secret key (open sesame!). Keep in mind, that once the IP has been added, you will either have to restart the configurator or manually remove the IP through the Network status to revoke access.
Instead of or additionally to the SESAME token you may also specify a Base32 encoded string that serves as the token for time based OTP (one time password) IP whitelisting. It works like the regular SESAME, but the request path that whitelists your IP changes every 30 seconds. You can add the SESAME_TOTP_SECRET to most of the available OTP-Apps (Google Authenticator and alike) and just append the 6-digit number to the URI where your configurator is reachable. For this to work the pyotp module has to be installed.
HTTP requests include the hostname to which the request has been made. To improve security you can set this parameter to yourdomain.example.com. This will check if the hostname within the request matches the one you are expecting. If it does not match, a 403 Forbidden response will be sent. As a result attackers that scan your IP address won't be able to connect unless they know the correct hostname. Be careful with this option though, because it prohibits you from accessing the configurator directly via IP.
To modify the default prefix for settings passed as environment variables (HC_) change this setting to another value that meets your demands.
Define a notification service from your Home Assistant setup that should be used to send notifications, e.g. notify.mytelegram. The default is persistent_notification.create. Do NOT change the value of the NOTIFY_SERVICE_DEFAULT variable! You will be notified if your HASS_API_PASSWORD, SESAME or PASSWORD password seems insecure. Additionally a notification with the accessing IP will be sent every time the SESAME token has been used for whitelisting. To disable this feature set the value to False.
Note regarding ALLOWED_NETWORKS, ALLOWED_DOMAINS, BANNED_IPS and BANLIMIT:
The way this is implemented works in the following order:
- (Only if
CREDENTIALSis set) Check credentials- Success: Proceed to UI of the configurator
- Failure: Retry
BANLIMITtimes, after that return error 420 (unless you try again without any authentication headers set, e.g. private tab of your browser)
- Check if client IP address is in
BANNED_IPS- Yes: Return error 420
- No: Continue
- Check if client IP address is in
ALLOWED_NETWORKS- Yes: Proceed to UI of the configurator
- No: Continue
- Check if client IP domain is in
ALLOWED_DOMAINS- Yes: Proceed to UI of the configurator
- No: Return error 420