9. Configuration

Alls of Homegear’s configuration files are by default located in “/etc/homegear”. There are four general configuration files:

File Description
main.conf Homegear’s main configuration file
rpcclients.conf File to configure RPC event servers (certificates, authentication, ...)
rpcservers.conf RPC and web server configuration file
mqtt.conf MQTT configuration file

In addition each family modules places a configuration file in “/etc/homegear/families” with family specific configuration settings.

9.1. Main Configuration (main.conf)

Parameter Description Possible Values Default Value
runAsUser If specified and Homegear is started as root it will drop privileges to this user name. If specified, runAsGroup needs to be specified, too. Any existing user name unset
runAsGroup If specified and Homegear is started as root it will drop privileges to this group. If specified, runAsUser needs to be specified, too. Any existing group name unset
debugLevel Sets the log level Homegear starts with.
  • 0 = none
  • 1 = critical
  • 2 = error
  • 3 = warning
  • 4 = info
  • 5 = debug
  • >5 more debug information
4
memoryDebugging Enables memory debugging. Should always be enabled. true or false true
devLog Enables debug output to fix specific errors. There is no need to enable this. true or false false
enableCoreDumps Enables the generation of core dumps. This might cause a security problem. Currently to make fixing errors easier, core dumps are enabled by default. true or false true
workingDirectory Homegear’s working directory. If empty the executable path is used. Any valid directory path /var/lib/homegear
socketPath Path where socket files should be placed. If empty the executable path is used. Any valid directory path /var/run/homegear
dataPath Path where Homegear should store it’s data. Any valid directory path /var/lib/homegear
dataPathPermissions Permissions to set on Homegear’s data path. The permissions specified here are set when Homegear is executed with the command line option -pre. Unix permission octet 770
dataPathUser Owner to set on Homegear’s data path. The owner specified here is set when Homegear is executed with the command line option -pre. Any existing user name homegear
dataPathGroup Group to set on Homegear’s data path. The group specified here is set when Homegear is executed with the command line option -pre. Any existing group homegear
databaseMemoryJournal If set database operations are executed in memory. This makes write operations much faster and increases flash memory life time. But it also makes your system more vulnerable to data loss and database corruption. databaseWALJournal and databaseMemoryJournal exclude each other. true or false false
databaseWALJournal If set database operations are faster. This setting is safer than databaseMemoryJournal. databaseWALJournal and databaseMemoryJournal exclude each other. true or false true
databaseSynchronous If set to false database write operations are much faster but it greatly increases the risk of database corruption. true or false true
databaseMaxBackups Homegear automatically creates database backups on startup and reload. This setting specifies the maximum number of backups to create. Any positive number 10
logfilePath Path where Homegear should place its log files. Any valid directory path /var/log/homegear
enableUPnP Making Homegear findable over SSDP. true or false true
uPnPIpAddress IP address or interface name the UPnP server listens on. By default auto discovery is used. IP address to listen on (not “0.0.0.0” or ”::”) or interface name (e. g. eth0) unset
ssdpIpAddress IP address the SSDP server listens on. This server is needed to receive SSDP responses. SSDP is needed for device discovery. By default auto discovery is used. IP address to listen on (not “0.0.0.0” or ”::”) or interface name (e. g. eth0) unset
ssdpPort Port, the SSDP server listens on. Might need to be changed if other services listen on Homegear’s default SSDP port, too. Valid port number 1900
caPath Path to the ca certificate used by all Homegear servers for client certificate authentication. Path to the CA certificate file /etc/homegear/homegearca.crt
certPath Path to the certificate used by all Homegear servers for TLS connections. Path to the certificate file /etc/homegear/homegear.crt
keyPath Path to the private key file used by all Homegear servers for TLS connections. Path to the key file /etc/homegear/homegear.key
loadDHParamsFromFile If set Diffie-Hellman parameters are read from file and not generated at startup. true or false true
dhParamPath Path to the Diffie-Hellman parameter file. Valid path /etc/homegear/dh1024.pem
deviceDescriptionPath Path to device description files. Valid path /etc/homegear/devices
clientSettingsPath Path to RPC clients (event server) settings file. Valid path /etc/homegear/rpcclients.conf
serverSettingsPath Path to RPC server settings file. Valid path /etc/homegear/rpcservers.conf
mqttSettingsPath Path to MQTT settings file. Valid path /etc/homegear/mqtt.conf
familyConfigPath Path to device family configuration files. Valid path /etc/homegear/families
phpIniPath Path to Homegear’s php.ini Valid path /etc/homegear/php.ini
gpioPath Path to the system’s GPIO root directory. This setting is only relevant if one of the communication modules or scripts need access to GPIOs. Valid path /sys/class/gpio
exportGpios Export these GPIOs and set permissions so the Homegear user and scripts running in Homegear can access them. This setting only takes effect when Homegear is started as root or with the command line option “-s”. GPIO numbers seperated by comma. E. g.: 5, 9, 17 unset
scriptPath Path to Homegear scripts. Valid path /var/lib/homegear/scripts
scriptPathPermissions Permissions to set on Homegear’s script path. The permissions specified,here are set when Homegear is executed with the command line option,``-pre``. Unix permission octet 550
scriptPathUser Owner to set on Homegear’s script path. The owner specified here is set when Homegear is executed with the command line option -pre. Any existing user name homegear
scriptPathGroup Group to set on Homegear’s script path. The group specified here is set when Homegear is executed with the command line option -pre. Any existing group name homegear
modulePath Path where Homegear searches for family modules. Valid path /var/lib/homegear/modules
firmwarePath Path to directory with device firmware updates. Valid path /usr/share/homegear/firmware
tempPath Path to directory where Homegear stores temporary data. Valid path /var/lib/homegear/tmp
lockFilePath Path to place lock files. Valid path /var/run/homegear
lockFilePathPermissions Permissions to set on Homegear’s lock file path. The permissions specified here are set when Homegear is executed with the command line option -pre. Unix permission octet 770
lockFilePathUser Owner to set on Homegear’s script path. The owner specified here is set when Homegear is executed with the command line option -pre. Any existing user name homegear
lockFilePathGroup Group to set on Homegear’s script path. The group specified here is set when Homegear is executed with the command line option -pre. Any existing group name homegear
redirectToSSHTunnel Some clients don’t allow to set “localhost” as their event server IP. In these cases it normally is impossible to connect to those clients, if the connection is tunneled. To still be able to connect to these clients’ event server you can specify their IP address or hostname here. Homegear then replaces them with “localhost”. This setting can be set multiple times. Any IPv4, IPv6 address or hostname unset
replaceClientServerAddress This setting allows to fully replace event server address data received from RPC clients. $REMOTEIP is replaced automatically with the remote IP address of the connecting client. This setting can be set multiple times. Address to search for followed by space followed by the address to replace with. xmlrpc_bin://127.0.0.1:1999 xmlrpc_bin://$REMOTEIP:1999

9.2. RPC Server Configuration (rpcservers.con)

9.3. RPC Client (Event Server) Configuration (rpccliensts.conf)

9.4. MQTT (mqtt.conf)

See MQTT.