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:
- configuration file located
/etc/dynfi.conf
(default), - configuration file pointed by
--config
parameter, - 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:
- all possible configuration options with their current values (coming e.g. from the embedded defaults),
- all environment variables,
- 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.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.