-
Notifications
You must be signed in to change notification settings - Fork 3
qtoggleserver.conf
qToggleServer is normally started (indirectly, usually) with the following:
qtoggleserver -c /path/to/qtoggleserver.conf
The qtoggleserver.conf file represents the main configuration of qToggleServer, although many other options are managed via the web app.
If running qToggleOS, see the Configuration page to locate the qtoggleserver.conf file.
You can use qtoggleserver.conf.sample as an example or as a starting point for your configuration.
The qtoggleserver.conf.sample file provides a minimal configuration file with the default values. You can also find it in your share/qtoggleserver/extra folder (whose location depends on the way you installed qToggleServer).
The most common configuration file formats these days are either YAML, JSON or TOML (like .ini files). qtoggleserver.conf uses HOCON which could be seen as a very relaxed cousin of JSON.
You can basically write JSON in your configuration file but you can omit commas (,) and quotation marks ("); you can also use the equal sign (=) instead of colon (:) for property name - value separators.
You can always find the definitions of all options that can go into qtoggleserver.conf in settings.py in the source tree. It's Python but you can easily see what you can use as options.
This is a boolean flag that enables or disables general debugging when running qToggleServer. You should not run a production setup with this flag set to true.
Defaults to false.
This is an optional string that indicates the fully qualified domain name of your qToggleServer setup. This option is used to create full paths to the web app.
Defaults to null.
This option is a dictionary that configures logging throughout the entire server. See logging-config-dictschema for details on what you can put into this dictionary.
You probably don't need to change this option, unless you're doing some serious debugging or you need to alter the log format and/or destination.
Groups options that control the functionality of qToggleServer's core, mostly dealing with qToggle API tweakable parameters.
Sets a command to be run to obtain the current device name. The command is expected to write the device name to standard output, in the following format:
QS_NAME=<name>
Defaults to null, which disables external device name control support and uses the internal name.
Sets a command to be run when device name is updated via API. The command is expected to update the device name, passed to the command via the QS_NAME environment variable.
Defaults to null, which disables external device name control support and uses the internal name.
Sets a command to be run when a password is updated via API. The command will be the QS_USERNAME and QS_PASSWORD environment variables.
Defaults to null.
Indicates how often to poll the registered ports, reading their values and updating associated expressions. It is specified as a number of milliseconds. Don't change this option unless you know what you're doing.
Defaults to 50
Indicates how often to save changed port values to the database. It is specified as a number of milliseconds. You may want to decrease this number if your system is prone to power failures and you want to reduce port value losses.
Defaults to 2000
Sets the maximum number of events that can be kept in a session queue. Increase this number if your setup generates a large bursts of events.
Defaults to 256
Sets the maximum accepted difference between a client's time and own time, when performing authentication. It is specified as a number of seconds. Only change this option if you know your clients can't keep a synchronized real/date time.
Defaults to 300
Enables or disables backup & restore support. You probably don't want to disable this option.
Defaults to true.
Enables or disables history support. Keep in mind that the persistence driver must also support history. Leave this enabled unless you want to explicitly disable history support.
Defaults to true.
Configures the interval, in seconds, at which the history janitor routine will run. The routine will clean up samples that are older than the retention limit. Decrease the value of this setting if your system generates a large number of samples that need to be cleaned up when expired.
Defaults to 3600.
Enables or disables listening support. You probably don't want to disable this option.
Defaults to true.
Enables or disables sequences support. You probably don't want to disable this option.
Defaults to true.
Enables or disables HTTPS (TLS) support. You probably don't want to disable this option.
Defaults to true.
Sets the maximum number of virtual ports. Setting this to 0 effectively disables virtual ports. Increase this value if the default value simply isn't enough for your setup.
Defaults to 1024.
Groups options that control the HTTP server.
Sets the listening IP address. You probably don't want to change this value, unless you want to make your server listen only on localhost (127.0.0.1) and access it via a local reverse proxy.
Defaults to 0.0.0.0, which enables listening on all network interfaces, regardless of their IP addresses.
Sets the listening TCP port. You can change it to 80 if you want to use the default HTTP port (you'll have to run qToggleServer as root, though). You can and should change it to 443 if you want HTTPS support.
Defaults to 8888.
Enables or disables gzip compression of the HTTP responses. Disable this option if you plan to apply compression later (on a reverse proxy) or if one of the clients you're using does not support HTTP gzip compression.
Defaults to true.
Sets the path to the HTTPS certificate file. Specifying a certificate file effectively enables HTTPS support. You'll want to also set a server.https.key_file and the server.port to 443.
Defaults to null.
Sets the path to the HTTPS key file.
Defaults to null.
Groups options that control the persistence layer (the data storage engine).
Sets the persistence driver. It is given as a Python path to the driver class. Any extra fields under persist are supplied as parameters to the driver.
qToggleServer comes with the following drivers (although others may be provided via add-ons):
-
JSON file (
qtoggleserver.drivers.persist.JSONDriver)Use a JSON flat file as persistence if you have a very small setup with few ports and that doesn't need to write persisted data too often.
JSON driver accepts the following options:
-
persist.file_path- the path to the JSON file, defaults toqtoggleserver-data.json -
persist.pretty_format- whether to format the JSON or not, defaults to whateverdebugis set to -
persist.use_backup- whether to use a backup file, defaults totrue
-
-
Redis (
qtoggleserver.drivers.persist.RedisDriver)Redis driver accepts the following options:
-
persist.host- the Redis server hostname, defaults to127.0.0.1 -
persist.port- the Redis server port, defaults to6379 -
persist.db- the Redis database number, defaults to0 -
persist.samples_support- enables samples support (used for history), defaults tofalse(use with care)
-
-
MongoDB (
qtoggleserver.drivers.persist.MongoDriver)MongoDB driver accepts the following options:
-
persist.host- the MongoDB server hostname (could also be used for connection URL), defaults to127.0.0.1 -
persist.port- the MongoDB server port, defaults to27017 -
persist.db- the MongoDB database name, defaults toqtoggleserver
-
-
Postgres (
qtoggleserver.drivers.persist.PostgresDriver)PostgreSQL driver accepts the following options:
-
persist.host- the Postgres server hostname (could also be used for connection URL), defaults to127.0.0.1 -
persist.port- the Postgres server port, defaults to5432 -
persist.db- the Postgres database name, defaults toqtoggleserver -
persist.username- the username used for authentication, unset by default -
persist.password- the password used for authentication, unset by default
-
Defaults to qtoggleserver.drivers.persist.JSONDriver.
Groups options that control the way qToggleServer interacts with the underlying OS.
Sets a command to be run to check whether the system is in setup mode or not. The command is expected to exit with code 0 if the system is in setup mode and a non-zero exit code otherwise.
Defaults to null, which disables setup mode functionality.
Sets a command to be run when date is updated via API. The command is expected to update the system date. The date will be passed to the command via the QS_DATE environment variable. The date format is indicated by system.date.set_format.
Defaults to null, which disables date support.
Sets the format of the date passed via QS_DATE environment variable to the command specified by system.date.set_cmd.
Defaults to %Y-%m-%dT%H:%M:%SZ.
Sets a command to be run to obtain the current system timezone. The command is expected to write the timezone name to standard output, in the following format:
QS_TIMEZONE=<timezone_name>
Defaults to null, which disables timezone support.
Sets a command to be run when timezone is updated via API. The command is expected to update the system timezone. The timezone name will be passed to the command via the QS_TIMEZONE environment variable (e.g. Europe/Berlin).
Defaults to null, which disables timezone support.
Sets a command to be run to obtain the current Wi-Fi settings. The command is expected to write the settings to standard output, in the following format:
QS_SSID=<ssid>
QS_PSK=<psk>
QS_BSSID=<bssid>
QS_BSSID_CURRENT=<current_bssid>
QS_RSSI_CURRENT=<current_rssi>
If field QS_SSID is empty, Wi-Fi connection is considered disabled.
Defaults to null, which disables Wi-Fi support.
Sets a command to be run when Wi-Fi settings are updated via API. The command is expected to update the Wi-FI settings. The settings will be passed to the command via the QS_SSID, QS_PSK and QS_BSSID environment variables.
If field QS_SSID is empty, Wi-Fi connection will be disabled.
Defaults to null, which disables Wi-Fi support.
Sets a command to be run to obtain the current IP configuration. The command is expected to write the configuration to standard output, in the following format:
QS_ADDRESS=<ip_addr>
QS_NETMASK=<netmask_length>
QS_GATEWAY=<gateway_addr>
QS_DNS=<dns_server>
QS_ADDRESS_CURRENT=<current_ip_addr>
QS_NETMASK_CURRENT=<current_netmask_length>
QS_GATEWAY_CURRENT=<current_gateway_addr>
QS_DNS_CURRENT=<current_dns_server>
If any of QS_ADDRESS, QS_NETMASK, QS_GATEWAY and QS_DNS is empty, a dynamic (DHCP) IP configuration is assumed.
Defaults to null, which disables IP configuration support.
Sets a command to be run when IP configuration is updated via API. The command is expected to update the IP configuration, passed to the command via the QS_ADDRESS, QS_NETMASK, QS_GATEWAY and QS_DNS environment variables.
If any of the variables is empty, a dynamic (DHCP) IP configuration is set.
Defaults to null, which disables IP configuration support.
Sets the path on disk/flash that will be monitored for usage.
Defaults to null, which disables storage monitoring.
Sets a command to be run to obtain the current core temperature. The command is expected to write the configuration to standard output, in the following format:
QS_VALUE=<temp_celsius>
Defaults to null, which disables reading temperature using a command.
Configures the sensor name to read the temperature from, as indicated by /sys/class/hwmon/hwmon*/name.
Defaults to null, which disables temperature reading from sensors exposed by /sys/class/hwmon.
Configures the sensor number to read the temperature from, as indicated by /sys/class/hwmon/hwmon*/temp*_input. Sensor index starts at 0, while temp*_input file starts at 1.
Defaults to 0.
Sets the minimum possible temperature. If null, disables minimum limit.
Defaults to 0.
Sets the maximum possible temperature.
Defaults to 100. If null, disables maximum limit.
Sets a command to be run to obtain the current battery state of charge. The command is expected to write the configuration to standard output, in the following format:
QS_LEVEL=<soc_percent>
Defaults to null, which disables reading temperature using a command.
Controls the firmware update support.
Sets the firmware update driver. It is given as a Python path to the driver class. Any extra fields under persist are supplied as parameters to the driver.
Defaults to null, which disables firmware updating.
Groups options that control the web app frontend (user interface).
Enables or disables the frontend. You shouldn't disable the frontend unless you're planning on using qToggleServer only via API.
Defaults to true.
Enables frontend debug mode. You shouldn't enable this unless you're doing frontend development and you're running an unpacked (development) variant of the frontend.
Defaults to false.
Indicates the URL (prefix) where the static files are found. By default, value is automatically set internally to a path relative to the frontend URL.
Change this setting if you serve the entire frontend at a separate URL (such as a CDN server).
Defaults to null.
Configures the display name used by the frontend (including the PWA manifest file).
Defaults to "qToggleServer".
Configures the optional short version of the display name used by the frontend (including the PWA manifest file).
Defaults to null.
Configures the description used by the frontend (including the PWA manifest file).
Defaults to "An application to control qToggleServer".
Groups options that control the master/slave operating mode.
Enables or disables the master/slave operating mode. You could disable this if you're not using qToggleServer as a master for other slaves, but rather as a simple device exposing only its peripherals.
Defaults to true.
Sets the timeout, in seconds, to use when communicating with slave devices via regular API calls. Increase this value if you have a slow network or your slave devices take a large amount of time to prepare the API responses.
Defaults to 10.
Sets the timeout, in seconds, to use when communicating with slave devices via API calls that are known to take a relatively longer time.
Defaults to 60.
Sets the timeout, in seconds, to use when listening for slave device notifications. Lower values offer a better offline detection time but increase the unnecessary traffic, especially when dealing with many slave devices.
Defaults to 10.
Sets the interval, in seconds, at which a failed API call to slave devices is retried.
Defaults to 5.
Sets the maximum number of API call retries to slave devices before the API call is considered failed.
Defaults to 5.
Configures the slave device discovery mechanism.
Sets the timeout when querying potential slave devices via API requests.
Defaults to 5.
Sets the timeout when waiting for a DHCP reply for the local network's DHCP server.
Defaults to 10.
Configures the interface for DHCP requests. By default, the interface corresponding to default route (gateway) is used.
Defaults to null.
Configures the access point used to discover slave devices.
Sets the network interface to use for AP. AP discover mechanism is disabled When set to null.
Defaults to null.
Sets a command to be run to obtain the AP interface. This option will be used only if slaves.discover.ap.interface is null. The command is expected to write the AP interface name to standard output, in the following format:
QS_INTERFACE=<name>
Defaults to null.
Sets the AP's SSID. Don't change this unless you're customizing your slave devices as well.
Defaults to qToggleSetup.
Sets the AP's PSK. Don't change this unless you're customizing your slave devices as well.
Defaults to null.
Configures the IP of the hub used for the temporary discovery network. You normally don't need to change this.
Defaults to "192.168.43.1".
Configures the network mask length used for the temporary discovery network. You normally don't need to change this.
Defaults to 24.
Configures the start IP of the DHCP range used for the temporary discovery network. You normally don't need to change this.
Defaults to "192.168.43.250".
Configures the stop IP of the DHCP range used for the temporary discovery network. You normally don't need to change this.
Defaults to "192.168.43.250".
Sets the full path to the hostapd binary. By default, it is automatically detected from PATH.
Defaults to null.
Sets the full path to the hostapd_cli binary. By default, it is automatically detected from PATH.
Defaults to null.
Sets the location of the hostapd log file.
Defaults to "/tmp/hostapd.log".
Sets the full path to the dnsmasq binary. By default, it is automatically detected from PATH.
Defaults to null.
Sets the location of the dnsmasq log file.
Defaults to "/tmp/dnsmasq.log".
Determines for how long the discovery AP will be kept up, in seconds.
Defaults to 300.
Groups options that control the webhooks functionality.
This functionality is currently not implemented in qToggleServer.
Enables or disables the webhooks functionality.
Defaults to false.
Groups options that control the reverse API calls mechanism.
This functionality is currently not implemented in qToggleServer.
Enables or disables the reverse API calls mechanism.
Defaults to false.
Sets the interval, in seconds, at which a reverse session is reopened in case of an error.
Defaults to 5.
This is a list of dictionaries containing event handlers to be added to the qToggleServer events system.
Each dictionary contains at least one mandatory option named driver, representing the Python path to the event handler class. The rest of the options are passed as arguments to the class constructor.
Defaults to [].
This is a list of dictionaries containing peripherals to be added to qToggleServer.
Each dictionary contains at least one mandatory option named driver, representing the Python path to the peripheral class. The rest of the options are passed as arguments to the class constructor.
Defaults to [].
This is a list of dictionaries containing ports to be added to qToggleServer.
Each dictionary contains at least one mandatory option named driver, representing the Python path to the port class. The rest of the options are passed as arguments to the class constructor.
Defaults to [].
This is a dictionary that allows assigning ports a different identifier than their original one. For example, a port named gpio13 can be mapped to kitchen_light using:
port_mappings = {
gpio13 = kitchen_light
}