1# Configuration
2
3##### 10/14/19
4We've begun the migration to a new configuration framework.  The 'old' method (the `sip-communicator.properties` file and program arguments) will be supported throughout the transition and the bridge will be fully backwards-compatible with the old config.  No changes are necessary until we pull the plug on the old config completely, and we'll give ample warning before that time.  It's also worth noting that any new properties will only be supported in the new config files.
5
6Moving forward, we'll be using lightbend's [config library]([https://github.com/lightbend/config](https://github.com/lightbend/config)).  Their GitHub page gives lots of details, but below are the changes most relevant to configuring the JVB.
7
8### Configuration sources
9During the transition, we'll continue to read from the original locations (`sip-communicator.properties` and program arguments) for all configuration properties, falling back to the new `reference.conf` file for defaults.  The `reference.conf` file holds defaults for all configuration properties, and shouldn't be modified in a deployment--though it may be interesting for developers who want to see the defaults.
10
11To override values, users can either put a file named `application.conf` in the classpath or pass a path to a file as a system property via `-Dconfig.file=/path/to/config.conf`.  Values in the file given will override ones in `reference.conf`.  The lightbend docs do a good job of describing [how configuration is loaded]([https://github.com/lightbend/config#standard-behavior](https://github.com/lightbend/config#standard-behavior)), but here's an example of overriding a configuration value for JVB:
12
13### Overriding default values
14Say we want to override some of the default values in `reference.conf`, namely: the XMPP API server values, the health check interval, and whether or not onstage video suspension is enabled.  We'll create an `application.conf` files with the values we want to change:
15
16```
17videobridge {
18    health {
19        // Override the health check interval
20        interval=60 seconds
21    }
22    cc {
23        // Override the onstage video suspension setting
24        onstage-video-suspension-enabled=true
25    }
26}
27```
28You can override just the values you want to change, all others will fallback to the defaults set in `reference.conf`
29
30### Migrating from old config
31Below are the mappings from old property values to new ones.  Note: for new property names, the 'flat paths' are given, i.e. a value of `videobridge.health.interval` corresponds to the setting:
32```
33videobridge {
34  health {
35    interval
36  }
37}
38```
39This list will be updated as properties are migrated:
40
41| Old property name | New property name | Notes |
42| -------- | ------- | ------- |
43| org.jitsi.videobridge.health.INTERVAL | videobridge.health.interval | The new config models this as a duration, rather than an amount of milliseconds |
44| org.jitsi.videobridge.health.TIMEOUT | videobridge.health.timeout | The new config models this as a duration, rather than an amount of milliseconds |
45| org.jitsi.videobridge.health.STICKY_FAILURES | videobridge.health.sticky-failures | |
46| org.jitsi.videobridge.EndpointConnectionStatus.FIRST_TRANSFER_TIMEOUT | videobridge.ep-connection-status.first-transfer-timeout | The new config models this as a duration, rather than an amount of milliseconds |
47| org.jitsi.videobridge.EndpointConnectionStatus.MAX_INACTIVITY_LIMIT | videobridge.ep-connection-status.max-inactivity-limit | The new config models this as a duration, rather than an amount of milliseconds |
48| org.jitsi.videobridge.BWE_CHANGE_THRESHOLD_PCT | videobridge.cc.bwe-change-threshold-pct | |
49| org.jitsi.videobridge.THUMBNAIL_MAX_HEIGHT | videobridge.cc.thumbnail-max-height-px | |
50| org.jitsi.videobridge.ONSTAGE_PREFERRED_HEIGHT | videobridge.cc.onstage-preferred-height-px | |
51| org.jitsi.videobridge.ONSTAGE_PREFERRED_FRAME_RATE | videobridge.cc.onstage-preferred-framerate | |
52| org.jitsi.videobridge.ENABLE_ONSTAGE_VIDEO_SUSPEND | videobridge.cc.enable-onstage-video-suspend | |
53| org.jitsi.videobridge.TRUST_BWE | videobridge.cc.trust-bwe | |
54| org.jitsi.videobridge.PADDING_PERIOD_MS | videobridge.cc.padding-period | The new config models this as a duration, rather than an amount of milliseconds |
55| org.jitsi.videobridge.DISABLE_RTX_PROBING | n/a | This property has been deprecated |
56| org.jitsi.videobridge.rest.COLIBRI_WS_DISABLE | videobridge.websockets.enabled | The semantics of this property have been inverted (disable -> enable) |
57| org.jitsi.videobridge.rest.COLIBRI_WS_DOMAIN | videobridge.websockets.domain | |
58| org.jitsi.videobridge.rest.COLIBRI_WS_TLS | videobridge.websockets.tls | |
59| org.jitsi.videobridge.rest.COLIBRI_WS_SERVER_ID | videobridge.websockets.server-id | |
60| org.jitsi.videobridge.DISABLE_TCP_HARVESTER | videobridge.ice.tcp.enabled | The semantics of this property have been inverted (disable -> enable) |
61| org.jitsi.videobridge.TCP_HARVESTER_SSLTCP | videobridge.ice.tcp.ssltcp | |
62| org.jitsi.videobridge.TCP_HARVESTER_PORT | videobridge.ice.tcp.port | |
63| org.jitsi.videobridge.TCP_HARVESTER_MAPPED_PORT | videobridge.ice.tcp.mapped-port | |
64| org.jitsi.videobridge.SINGLE_PORT_HARVESTER_PORT | videobridge.ice.udp.port | |
65| org.jitsi.videobridge.ICE_UFRAG_PREFIX | videobridge.ice.ufrag-prefix | |
66| org.jitsi.videobridge.KEEP_ALIVE_STRATEGY | videobridge.ice.keep-alive-strategy | |
67
68