Configuration Parameters of ROAD Service
You can manually edit RoadService.exe.config and change parameters as needed (also the ones which were set by the prior ROAD setup). Note that you have to restart the ROAD Service to set changes parameters in effect.
Purging Log Files
As log files' amount tends to become excessive by time, an automatic purging of them is done by the ROAD Service periodically.
Purging either means to shift them to an archive folder or to delete them.
When purging is running, it verifies the count and age of all log files. All files are purged which are older than the PurgeByDays parameter defines and as long as the total amount is more than the PurgeByNumber parameter defines. So logs are purged only if both amount and age apply (configured by parameters ...PurgeByDays and ...PurgeByNumber).
This done twice independently for the Service's and the Workers' log files. That's why there are different parameter settings for them both (ServiceLogFilesPurgeByDays, ServiceLogFilesPurgeByNumber, WorkerLogFilesPurgeByDays, WorkerLogFilesPurgeByNumber).
See Logging for more details about logging and purging log files.
Notes for ROAD Service Version 1.x
All described parameters are part of RoadService.exe.config, which is located in the ROAD Service installation directory.
Please note, that you need to escape certain characters, if you modify a XML file manually.
Original character | Escaped character |
|---|---|
' | ' |
< | < |
> | > |
& | & |
" | " |
Notes for ROAD Service Version 2.x
ROAD Service v2 is not released yet - it is in development and testing phase before it will become available to customers.
All described parameters are part of appsettings.json, which is located in the ROAD Service installation directory.
When ROAD Service is upgraded to version 2.x, the former XML-based RoadService.exe.config is automatically converted to the new appsettings.json. The former file is then renamed to RoadService.exe.converted.config.
In the new JSON format only quote and backslash characters need escaping by preceding a backslash. " becomes \" and \ becomes \\.
We recommend for any file path parameters to use forward slashes / instead of backslashes \. This eleminates the need to escape them.
All time-related parameters are unified in v2 and use one of the following formats:
d.hh:mm:ss.mmm or d:hh:mm:ss.mmm (meaning days:hours:minutes:seconds.milliseconds) - days, hours and milliseconds are optional. So you can just provide minutes and seconds with or without milliseconds.
s.mmm (seconds.milliseconds) - millseconds are optional. So you can just provide seconds.
List of All Parameters
ROAD Backend Parameters
For ROAD v2 these parameters are inside the “Settings” node of appsettings.json.
Parameter in version 1.x | Parameter in version 2.x | Default Value | Description |
|---|---|---|---|
AuthorizationRequired (since v1.5.516.0) | same | false | If set to true, this Service accepts only http and web socket requests with authorization. Note it's not recommended to have mixed usage of this setting inside a ROAD cluster. |
ClientSyncNotificationsPurgeInterval | same | 7:00:00:00 (7 days) | Delay after the last client using an applicationId closed or unsubscribed from ClientSync notifications to clear the notifications cache. This value can be overridden for specific applicationIds by the clientSync API, see api/clientSync |
CrashedWorkerGracePeriod | same name, but new time format | 1000 | Timeout in milliseconds for Worker processes to be terminated after Service startup. While the Service is not running, Workers should terminate by themselves. If they are still running at next Service startup time, they will be terminated after this time. |
DBConnection | same | Connection URI to the MongoDB service to be used for database. (Double check to escape "&" with "&" as described in the chapter above, as it is very common in a MongoDB connection URI.) | |
DBConnectionTimeout | same name, but new time format | 5000 | Timeout for initial database connection (in milliseconds). |
DBName | same | ROAD | Name of the database in the used MongoDB instance. All ROAD data will be placed inside of it. |
DnsName (since v1.2.392.0) | deprecated in v2 See new parameter section Kestrel | Publicly accessible network name of the host machine (like road-dpe.davidsystems.com). If left empty, this defaults to the local network name of the machine, so it will likely only be accessible from inside the LAN/domain. | |
FinishWorkersTimeout | same name, but new time format | 5000 | Timeout applied when Service shutdown initiates finishing all running jobs and workers (in milliseconds). After this time the service stops and won't receive their jobs' status updates. |
HostAlias | same | Optional alias for the service's host name used where references to a host are stored (used as name in the HostInfo data structure, see paragraph "Hosts Data" in api/hosts). If left empty, this defaults to the local network name of the machine.. | |
HttpAddress (deprecated) | http://+:11003/ | ||
HttpsAddress (deprecated) | https://+:11005/ | ||
(not in v1) | Kestrel (only v2! since v2.0.29.0) | Web server configuration as specified by Microsoft. See description in chapter below. | |
LogFilesPurgeInterval | same name, but new time format | 43200 (12 hours) | Time interval to run purging of Service and Workers' log files (in seconds). The actual purging is defined by parameters ServiceLogFilesPurge... and WorkerLogFiles... |
NonVolatileCheck_TransitionsCheckCount | 20 | Minimum amount of transitions in a job to consider doing the non-volatile transitions check | |
NonVolatileCheck_TransitionsCheckTimeMs | NonVolatileCheck_TransitionsCheckTime new time format | 1500 | Non-volatile transitions check: Length of check time period in ms |
NonVolatileCheck_TransitionsMin | same | 50 | Non-volatile transitions check: If this amount of transitions was reached within the check time period, a warning is generated. |
QueryLimitDefault | same | 100 | Default value for all GET requests' limit parameter |
RefreshHostsCacheInterval | same | 00:00:01:00 | Interval of updating the hosts list from database. This is the maximum delay to recognize changes on other hosts. Other hosts are considered for relaying or broadcasting subscriptions inside the cluster. This interval is also used for frequent checks for the connection to the MongoDB service. So this interval is the maximum latency until the ROAD Service reconnects to a formerly broken database connection or to an alternative database location in a MongoDB replica set cluster. |
RestAddress (deprecated) | |||
RunWorkerInAdvance | same | true | If set, one Worker process is being started in advance to be faster when the next job is coming. |
ScheduleRunnerMinFreeTime | same name, but new time format | 5000 | Time period to grant for worker creation and its initialization (in milliseconds) plus the minimal duration left for the job. This time must be there before the planned end of a job - otherwise it won't be launched any more. (Applied value is min. 1000 ms.) |
ScheduleRunnerPeriod | same name, but new time format | 600 | Time period to run the pending schedules' query cyclic (in seconds). (Applied value is min. 10 s.) Scheduled jobs which are pending within this period in future are being created in advance and wait in prepared state until they should start. Higher values reduce the workload, lower values reduce the time while Workers are running in a waiting state. |
ScheduleRunnerQueryTime | same name, but new time format | 15 | Maximum time expected to be spent for each pending schedules' query. If this time is too low, a schedule may be triggered late. |
ServiceLogFilesArchivePath | same | Archive folder to shift older Service's log files to. If this parameter is empty, older log files are deleted. | |
ServiceLogFilesPurgeByDays | ServiceLogFilesPurgeByAge same name, but new time format new default is 7:00:00:00 (7 days) | 7 | Minimum age of Service's log files to be purged. See Logging |
ServiceLogFilesPurgeByNumber | same | 100 | Minimum amount of Service's log files to purge the oldest ones. See Logging |
ServiceLoggingPath | same | C:\ProgramData\ROAD\Logging\Service | File path to place the Service's log files |
ServiceLogMinimalSeverity | same | I | Minimal severity for log messages to appear in the Service's log file Possible values in sequence of rising severity (use either the abbreviation character or the full name, case-insensitive): d=debug, i=info, s=success, w=warning, e=error, v=severe, f=fatal |
ServiceLogRotationSize | same | 10000000 | After exceeding this file size (in bytes), the log file is being finished and a new file is created continuing logging. A note is added to the end of the prior and to the start of the next file. |
SocketAddress (deprecated) | |||
UpdateHostAliveInterval | same | 00:01:00:00 | Interval of updating the own host information in the database periodically, so other hosts and clients can assume if a Service is currently running (minimum is 1 minute). This cycle time is included in the host information. |
(not in v1) | WebServerFiles (only v2!) | Path to file system directory (should be absolute), where files and/or sub-directories are located, which should be available via http/https. By using this, ROAD Service can server web content like client applications. | |
WebServerPort (since v1.5.512.0) | deprecated in v2 See new parameter section Kestrel | 11003 / 11005 | Web server port used for incoming REST and web socket connections. |
WebServerSecure (since v1.5.512.0) | deprecated in v2 See new parameter section Kestrel | false | false for insecure incoming connections (http / ws) true for secure incoming connections (https / wss). A valid certificate needs to be installed for this option. |
WorkerLogFilesArchivePath | same | Archive folder to shift older Workers' log files to. If this parameter is empty, older log files are deleted. | |
WorkerLogFilesPurgeByDays | WorkerLogFilesPurgeByAge new time format new default is 7:00:00:00 (7 days) | 7 | Minimum age of Workers' log files to be purged. See Logging |
WorkerLogFilesPurgeByNumber | same | 100 | Minimum amount of Workers' log files to purge the oldest ones. See Logging |
WorkerLoggingPath | same | C:\ProgramData\ROAD\Logging\Worker | File path to place the Workers' log files |
WorkerLogMinimalSeverity | same | I | Minimal severity for log messages to appear in the Worker's log file Possible values in sequence of rising severity (use either the abbreviation character or the full name, case-insensitive): d=debug, i=info, s=success, w=warning, e=error, v=severe, f=fatal |
WorkerLogRotationSize | same | 10000000 | After exceeding this file size (in bytes), the log file is being finished and a new file is created continuing logging. A note is added to the end of the prior and to the start of the next file. |
WorkerProcessExecutablePath | same | Path to the file system folder where RoadWorker.exe is referenced (empty for the same folder as RoadService.exe runs from). Only v2: This parameter can contain a file name (usually RoadWorker2.exe) | |
WorkerTempDirectory (since v1.11.600.0) | same | Path to folder where temporary files of the RoadWorker will be placed - especially the local files for recordings, for which no specific folder is defined. If not set, the system TMP folder will be used, which is defined for the user account, which the ROAD Service uses. | |
WsAddress (deprecated) | |||
WssAddress (deprecated) | |||
WssCertificateFilePath (deprecated) | |||
WssCertificatePassword (deprecated) |
Mind to use slashes instead of backslashes (otherwise double backslashes as JSON requests escaping)!Web Server Configuration for ROAD v2 (Kestrel)
The Kestrel web server configuration is part of appsettings.json (outside “Settings”) and maintained like specified by Microsoft.
Example:
Kestrel": {
"Endpoints": {
"default": {
"Url": "http://+:11003"
},
"additional": {
"Url": "http://+:80"
},
"https": {
"Url": "https://public-domain.info:443",
"Certificate": {
"Path": "certs/fullchain.pem",
"KeyPath": "certs/privkey.pem"
}
},
}
}Below the “Endpoints”, there is a list of URLs with optional additional parameters. The ROAD Service is capable of serving on several web connections at the same time.
There should always be one endpoint named “default” 
. This one is used inside the ROAD cluster to connect from other ROAD backends as well as clients accessing the ROAD backend via REST API.
Additional endpoints can be configured as required.
It is possible to use the ROAD Service also as a web hosting service to provide access to the web clients. In this case fill the parameter “WebServerFiles” (see table above).
Endpoint’s Parameter “Url”
This parameter is mandatory for every endpoint.
Its value must start with the protocol prefix “http://” or “https://”.
Then comes a path (e.g. “myhostname.info”) or “+” as placeholder for the local computer name (which works fine inside a local network with a DNS).
At the end comes the port (e.g. “:11003”).
More Endpoint Parameters
Further parameters can be provided depending on needs, as defined by Kestrel specifications. For secure connection this is the place to specify a certificate.