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 \\.
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
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) | same | 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/ | REST service URL's base address Deprecated since v1.2.392.0! Use RestAddress instead. | |
HttpsAddress (deprecated) | https://+:11005/ | REST service URL's base address for https Deprecated since v1.2.392.0! Use RestAddress instead. | |
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 (since v1.2.392.0) (deprecated) | REST connection address with port, using a "+" placeholder for the host itself. Can either be a secure (https) or insecure (http) address. Mind this and parameter SocketAddress must both be either secure or insecure. Example: https://+:11005/ Deprecated since v1.5.512.0! Use WebServerPort / WebServerSecure instead. | ||
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 (since v1.2.392.0) (deprecated) | Web socket connection address with port, using a "0.0.0.0" placeholder for the host itself. Can either be a secure (wss) or insecure (ws) address. Mind this and parameter RestAddress must both be either secure or insecure. Example: wss://0.0.0.0:11006 Deprecated since v1.5.512.0! Use WebServerPort / WebServerSecure instead. | ||
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) | WebServerAdditionalUrls (only v2! since v2.0.22.0) | Optional list of additional http addresses to be served. Several addresses can be provided, separated by semicolons. Example: “https://+:80; myhost:1234“ Each can be a complete URL like https://mymachine.com:11005 If the protocol is omitted, the default from parameter WebServerSecure will be amended. If the port is omitted, the default from parameter WebServerPort will be amended. To serve all incoming requests, “+” can be used instead of the machine or domain name. | |
(not in v1) | WebServerFiles (only v2!) | Path to file system directory (relative or 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) | same | 11003 / 11005 | Web server port used for incoming REST and web socket connections. |
WebServerSecure (since v1.5.512.0) | same | 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) | |
WsAddress (deprecated) | ws://0.0.0.0:11004 | Web socket connection address with port. Deprecated since v1.2.392.0! Use SocketAddress instead. | |
WssAddress (deprecated) | wss://0.0.0.0:11006 | Secure web socket connection address with port. If this parameter is missing, wss support is switched off. Note you have to configure a certificate for wss, see parameter WssCertificateFilePath. Deprecated since v1.2.392.0! Use SocketAddress instead. | |
WssCertificateFilePath (deprecated) | Complete file path to a .pfx file, which is a valid certificate used for securing the wss (secure web socket) connections | ||
WssCertificatePassword (deprecated) | Password for the above certificate file |
Mind to double backslashes as JSON request escaping!