4. Configuration

4.1. What is DynFi’s configuration?

In order to start as fully functioning service, DynFi needs some configuration. E.g. to establish a database connection, DynFi needs “to know” where the database is located, what are authentication credentials, etc. Such information has to be provided before DynFi starts, i.e. changes made to configuration are not taken into account until the next start.

4.2. Sources of configuration

DynFi obtains its configuration from three sources:

  1. configuration file located /etc/dynfi.conf (default),
  2. configuration file pointed by --config parameter,
  3. environment variables.

If none of them are specified, DynFi will try to start with embedded defaults.

First, DynFi tries to read the configuration from a file. If --config parameter is specified and pointing to readable file, this custom configuration file will be read instead of the default configuration file (being /etc/dynfi.conf). Please note, that if custom configuration file is specified using --config, then the default file (/etc/dynfi.conf) is totally ignored.

This is very handy in case one would like to:

  • test new configuration without changing default configuration file,
  • run more than one DynFi instance at single host,
  • run DynFi when cannot update /etc/dynfi.conf (e.g. due to lack of write permissions).

Second, DynFi is checking if any configuration options are available as the environment variables. This mechanism is additive. This means that specifying a single configuration option as environment variable sets only the value of this option, whereas the other options remain unchanged (so they come from configuration file or embedded defaults).

This is very handy in case:

  • only one option needs temporary change for one run,
  • configuration cannot be stored in any configuration file (due to whatever reason),
  • OS configuration mechanism supports that (e.g. like systemd).

4.3. Format of the configuration file

Configuration file of DynFi must follow the Java Properties file format (for version 8).

In short:

  • the format of the line is optionName=optionValue,
  • values cannot contain characters other that ISO-8859-1 (use “unicode escaping” in such case).

More on the format: Wikipedia.

4.4. Examining effective configuration

The flexibility of configuring DynFi might make some users confused a bit about actual configuration being used by DynFi. However, examining what exactly is seen by DynFi in its configuration is easy. To tell DynFi to output its configuration to standard output (“console”), please add --print-config parameter. Moreover, adding another one --exit-after-config-print will tell DynFi to exit immediately after printing the effective configuration. Please note, that these parameters can also be added when DynFi is using configuration from environment variables or custom configuration file specified by --config parameter. Thus it is perfectly correct to run DynFi in the following way:

java -jar /path/to/dynfi.jar --config /my/custom/dynfi.config --print-config --exit-after-config-print

In the output DynFi will print:

  1. all possible configuration options with their current values (coming e.g. from the embedded defaults),
  2. all environment variables,
  3. all system variables (more).

Knowing all possible configuration options (even the ones not specified so far in explicit configuration) allows setting a customised configuration option in the /etc/dynfi.conf file or in any other way specified above.

The example output of the command listed above may look like this (note, that your config will be somewhat different):

Running DynFi. For other commands run help.
Version: 17.4.1-SNAPSHOT (commit: 77428ea56ab3e9226b2e174502001507417bc102)
Going to read configuration from default file /etc/dynfi.conf.
This is DynFi's config:
bcryptCost=12
beatEverySeconds=30
beatStartAfterSeconds=30
corsAllowOrigin=*
deviceCommandTimeoutInSeconds=3600
deviceConnectionTimeoutInSeconds=30
deviceTaskWorkers=2
encryptionPassword=null
googleMapsApiKey=BRzaSyCowU6PxCE_0Nv3X6y4CMv_MqUX_8RAaI
ipAndPort=192.168.215.130:9090
jwtKey=fixed32428yfsbbigk
keepLogsForDays=366
keystoreLocation=null
keystorePassword=[Ljava.lang.Character;@794cb805
mailEverySeconds=1
mailMaxSendingAttempts=3
mailSendingEmailsDisabled=false
mailStartAfterSeconds=5
minutesForRebootCheck=5
mongoClientUri=mongodb://localhost
mongoDatabase=dynfitest
periodicTasksDisabled=false
useHttps=false

These are environment properties:
PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/usr/games:/usr/local/games
LESSCLOSE=/usr/bin/lesspipe %s %s
LESSOPEN=| /usr/bin/lesspipe %s
SHELL=/bin/bash
SSH_TTY=/dev/pts/2
SSH_CLIENT=10.0.19.10 50388 22
TERM=xterm-256color
USER=tester
LANG=en_US.UTF-8
XDG_SESSION_ID=51735
SSH_CONNECTION=10.0.19.10 50388
MAIL=/var/mail/tester
LOGNAME=tester
XDG_RUNTIME_DIR=/run/user/1048
PWD=/home/tester
HOME=/home/tester
SHLVL=1
_=/usr/bin/java

These are system properties:
sun.cpu.isalist=
sun.io.unicode.encoding=UnicodeLittle
sun.cpu.endian=little
java.vendor.url.bug=http://bugreport.sun.com/bugreport/
file.separator=/
java.vendor=Oracle Corporation
sun.boot.class.path=/usr/lib/jvm/java-8-openjdk-amd64/jre/lib/resources.jar:/usr/lib/jvm/java-8-openjdk-amd64/jre/lib/rt.jar:/usr/lib/jvm/java-8-openjdk-amd64/jre/lib/sunrsasign.jar:/usr/lib/jvm/java-8-openjdk-amd64/jre/lib/jsse.jar:/usr/lib/jvm/java-8-openjdk-amd64/jre/lib/jce.jar:/usr/lib/jvm/java-8-openjdk-amd64/jre/lib/charsets.jar:/usr/lib/jvm/java-8-openjdk-amd64/jre/lib/jfr.jar:/usr/lib/jvm/java-8-openjdk-amd64/jre/classes
java.ext.dirs=/usr/lib/jvm/java-8-openjdk-amd64/jre/lib/ext:/usr/java/packages/lib/ext
java.version=1.8.0_151
java.vm.info=mixed mode
awt.toolkit=sun.awt.X11.XToolkit
user.language=en
java.specification.vendor=Oracle Corporation
sun.java.command=/usr/local/dynfi/lib/dynfi.jar --print-config --exit-after-config-print
java.home=/usr/lib/jvm/java-8-openjdk-amd64/jre
sun.arch.data.model=64
java.vm.specification.version=1.8
java.class.path=/usr/local/dynfi/lib/dynfi.jar
user.name=tester
file.encoding=UTF-8
java.specification.version=1.8
java.awt.printerjob=sun.print.PSPrinterJob
user.timezone=Etc/UTC
user.home=/home/tester
os.version=4.13.4-1-pve
sun.management.compiler=HotSpot 64-Bit Tiered Compilers
java.specification.name=Java Platform API Specification
java.class.version=52.0
java.library.path=/usr/java/packages/lib/amd64:/usr/lib/x86_64-linux-gnu/jni:/lib/x86_64-linux-gnu:/usr/lib/x86_64-linux-gnu:/usr/lib/jni:/lib:/usr/lib
sun.jnu.encoding=UTF-8
os.name=Linux
java.vm.specification.vendor=Oracle Corporation
java.io.tmpdir=/tmp
line.separator=

java.endorsed.dirs=/usr/lib/jvm/java-8-openjdk-amd64/jre/lib/endorsed
os.arch=amd64
java.awt.graphicsenv=sun.awt.X11GraphicsEnvironment
java.runtime.version=1.8.0_151-8u151-b12-0ubuntu0.16.04.2-b12
java.vm.specification.name=Java Virtual Machine Specification
user.dir=/home/tester
user.country=PL
sun.java.launcher=SUN_STANDARD
sun.os.patch.level=unknown
java.vm.name=OpenJDK 64-Bit Server VM
file.encoding.pkg=sun.io
path.separator=:
java.vm.vendor=Oracle Corporation
java.vendor.url=http://java.oracle.com/
sun.boot.library.path=/usr/lib/jvm/java-8-openjdk-amd64/jre/lib/amd64
java.vm.version=25.151-b12
java.runtime.name=OpenJDK Runtime Environment

4.5. Creating initial configuration file

It is possible to create configuration file containing very basic settings running DynFi’s embedded configuration wizard. For example:

java -jar /pat/to/dynfi.jar generateConfig --path /path/to/my/custom.dynfi.conf

will ask for very basic settings and write them to the file pointed by --path parameter.

4.6. Mostly used configuration options

4.6.1. ipAndPort

Default value 0.0.0.0:9090. Allows specifying to which IP and port DynFi should bind when starting.

Note

It depends on your operating system but in most cases using 0.0.0.0 in ipAndPort option means that DynFi’s server will bind to all IP addresses available on the host DynFi is started on.

4.6.2. mongoClientUri

Default value mongodb://localhost. Specifies how DynFi should connect to the database. Please note, that this URI should also include username and password. For more, refer to MongoDB documentation.

4.6.3. mongoDatabase

Default value dynfitest. Specifies the name of the database DynFi should use.

4.6.4. useHttps

Default value true. Specifies if DynFi should run its web server using HTTPS. Disabling HTTPS can be required e.g. in case DynFi is used behind HTTPS-enabled proxy or always in safe VPN. When DynFi can be accessed directly by web browsers it is not recommended to disable HTTPS.

4.6.5. keystoreLocation

If not specified, DynFi will use the embedded (default) key store, which is not recommended. Allows specifying path to own / custom keystore, which has to be valid Java Keystore. For more, refer to Oracle documentation or Oracle’s blog.

4.6.6. keystorePassword

Password needed to open the keystore specified by keystoreLocation.

4.6.7. deviceConnectionTimeoutInSeconds

Default value 30. Specifies how long DynFi will wait when trying to connect to a device.

4.6.8. deviceCommandTimeoutInSeconds

Default value 3600. Specifies the maximum duration of a command run by DynFi at a device. Important: do not set too low value, as this may break valid tasks when running.

4.6.9. rebootCheckInMinutes

Default value 5. Specifies how long DynFi will wait for device to reboot after upgrade procedure.

4.6.10. periodicTasksDisabled

Default value false. Allows disabling all scheduled tasks, only requested tasks (e.g. in the web browser) will be run.

4.6.11. beatStartAfterSeconds

Default value 30. Specifies the initial delay (after DynFi’s start) after which scheduled tasks will be run.

4.6.12. beatEverySeconds

Default value 30. Specifies how often DynFi will check if some tasks need to be scheduled.

4.6.13. deviceTaskWorkers

Default value 2. Specifies the maximum number or parallel workers handling devices’ task. This setting should be related to number of available CPU cores: the more cores are available, the higher the number of device task workers can be.

4.6.14. keepLogsForDays

Default value 366. Specifies how long DynFi will keep its internal logs in the database.

4.6.15. jwtKey

Default value is random each time DynFi starts. Key used to verify the JSON Web Tokens used for user authentication from the web browser. Set static value in order not to be forced to log-in again after each DynFi restart.

4.6.16. corsAllowOrigin

No default value. Specifies value used by CORS headers. More.

4.6.17. mailSendingEmailsDisabled

Default value false. Allows overriding and disabling sending e-mails by DynFi. If set to true, DynFi will not send notification e-mails, even if allowed in the UI.

4.6.18. mailStartAfterSeconds

Default value 5. Defines initial delay after which DynFi starts sending e-mail notifications.

4.6.19. mailEverySeconds

Default value 1. Defines how often DynFi will try to see if there are any e-mail notifications to be sent.

4.6.20. mailMaxSendingAttempts

Default value 3. Defines how many times DynFi will try to send each e-mail notification before giving up.

4.6.21. bcryptCost

Default value 12. Specifies the cost factor of password hashing bcrypt algorithm. Important: already hashed passwords will not be re-hashed after changing this value. To do so, each user needs to set new password. For more refer to Wikipedia.

4.6.22. encryptionPassword

No default value. If set, enables encryption of secrets stored by DynFi. For more, refer to Storing secrets in DynFi database chapter.

4.6.23. encryptionCachingEnabled

Default value true. When enabled and when encryptionPassword is set (thus the encryption of passwords is enabled) improves the performance of the encryption mechanism by keeping decrypted secrets in memory cache.

4.6.24. directViewConnectTimeoutInMilliseconds

Default value 30000 (30 seconds). Specifies the timeout when trying to connect to a device using Direct View.

4.6.25. directViewConnectionRequestTimeoutInMilliseconds

Default value -1 (unlimited). Specifies the timeout for waiting to obtain a connection from the Direct View connection pool.

4.6.26. directViewMaxOutgoingConnections

Default value 20. Specifies the size of connection pool used by the Direct View. For many users accessing many devices using Direct View at the same time, this value has to be increased.

4.6.27. directViewSocketTimeoutInMilliseconds

Default value -1 (unlimited). Specifies the timeout of “socket’s life” used in Direct View. In other words: how log the socket will remain active when no packets are flowing through it.

4.6.28. sshBindAddress

Unspecified by default. Allows specifying the local IP address (and thus de facto network interface) which will be used for binding by sockets used by SSH to connect to managed devices.

4.6.29. tryGoingBackToMainConnectionAddressEveryMinutes

Default value 30. Tells DynFi Manager after what period it should try to switch back to main connection connection address when using a backup connection address. Please set to -1 to deactivate.

4.6.30. cleanStaleSshConnectionsEveryMinutes

Default value 5. Specifies after what period DynFi Manager should disconnect SSH connection when it is not used and not going to be used (e.g. when the backup connection should be disconnected when going back to the main connection). It is not recommended to switch to low values.

4.7. Tuning environment options in Ubuntu

If you run DynFi in Ubuntu and it was installed using DEB file / APT repository, then setting individual configuration options in environment variables can be done after running:

sudo systemctl edit dynfi.service

This is oped text editor and allow editing configuration used by systemd to start DynFi. Various options can be set like this:

[Service]
Environment='option=value'
Environment='anotherOption=anotherValue'

Make sure your file starts with [Service] and that you restarted DynFi to make the changes visible.

Note

Using /etc/dynfi.conf file to configure DynFi is recommended, as tuning systemd environment variables might be more difficult to maintain.