Unattended Setup
This page is about automatizing the installation of ROAD.
Motivation
"Unattended setup" refers to running the setup (installer) without user interaction. This can be the desirable way of rolling out a product on a great number of clients. It is the only way if the product should automatically to tests.
Passing a Command Line
The following instructions require you to pass command line parameters and options to the installer. To do so, either create a Windows Explorer shortcut where you can supply all required parameters, or launch the installer's exe file from a command line window.
To open a command line window, Press Windows+R, then type cmd and press ENTER. Since the installer requires elevated execution, it makes sense to start the command line windows as elevated process. To do so, do not press ENTER. Instead, press Ctrl+Shift+ENTER.
The easiest was to create the command that launches the installer is to right click the file RoadSetup.exe with the shift key held down, and then pick "Copy as path" from the pop-up menu, and then right-click into the command window. You can then continue to type the command line.
Level of Interactivity
The ROAD installer, like all msi-based installers, knows four levels of interactivity which are controlled by the /q command line option:
/qf– fully interactive; this is the default when you omit the /q option./qr– reduced interaction; you will see a progress dialog with status messages like this:
/qb– basic UI, a bit less information compared to/qr:
/qn– no UI at all. Even in the case of an error, no message is displayed.
Setting Properties
Properties are (among other) the data which the user would normally enter into the installer's GUI. Properties come as pairs of name and value. You can set properties for unattended setup on the command line by adding value=name pairs after all command line switches.
| Property name | Explanation | Example | Type | Allowed values | Default value |
|---|---|---|---|---|---|
APPDIR | The directory where ROAD is to be installed. | C:\ROAD | string | a valid folder | C:\Program Files\ROAD\ |
DBCONNECTION | URI of the database server. MongoDB connection string | mongodb://mymachine | string | mongodb://[username:password@]host1[:port1] | (empty) |
DBCONNECTIONTIMEOUT | Timeout of the database connection, in milliseconds | 60000 | 5000 | ||
DBNAME | Name of the database | database | ROAD | ||
HOSTALIAS | Alias name of this computer, or empty to use %COMPUTERNAME% | workstation-123 | (empty) | ||
SERVICE_USER | Name of user account under which the ROAD service should run. | domain\username | LocalSystem | ||
| SERVICE_PASSWORD | Password of the service user | mypassword | (empty) | ||
| START_ROAD_SERVICE | Start service after installation. (empty) means START_ROAD_SERVICE="" | (empty) | Checked | ||
CONNECTION_REST_ADDRESS (deprecated) | The address under which the REST service is reachable When you use secure https protocol, a the certificate is mandatory | https://+:11035 | url | regex
CPP
| http://+:11003 |
CONNECTION_SOCKET_ADDRESS (deprecated) | The url used for the socket connection When you use secure web service protocol, a the certificate is mandatory | url | regex
CPP
| ||
| CONNECTION_DNS_NAME | The connection DNS name is only required if secure protocols are used. In that case the DNS name must match the certificates subject name or one of the subject alternative names (SAN). | roadhost.davidsystems.com | string | Fully qualified domain name. | (empty) |
CERTIFICATE_PATH (deprecated) | Path to a X.509 SSL certificate (.pfx file) | C:\mywildcardcert.pfx | string | Path to a pfx file. | (empty) |
CERTIFICATE_PASSWORD (deprecated) | Password for the X.509 SSL certificate | **** | string | (empty) | |
| DPE_DEFAULT_URL | Url of DPE | http://dpehost | url | (empty) | |
| DPE_DEFAULT_USER | Name of default DPE user, which is used when no specific credentials are provided | username | string | (empty) | |
| DPE_DEFAULT_PASSWORD | Password of default DPE user | **** | string | (empty) | |
CONNECTION_USE_SECURE_PROTOCOLS | If "SecureProtocols", use secure protocols (https, wss), else use unsecure protocols (http, ws) | SecureProtocols | string | SecureProtocols, UnsecureProtocols | UnsecureProtocols |
| CONNECTION_WEBSERVER_PORT | The port number used for http and websocket connections. Both protocols use the same port since 1.5.512.0. | 11005 | integer | An unused integer port number. | 11003 (for secure protocols), 11005 (for unsecure protocols) |
| CERTIFICATE_THUMBPRINT | The thumbprint of the valid SSL certificate. | 111122223333444455556666777788889999aaaa | string | (empty) | |
| WORKER_LOG_MINIMAL_SEVERITY | The minimum severity/level for the ROAD Worker. | D | string | D = Debug, I = Information, S = Success, W = Warning, E = Error, V = Severe, F = Fatal | I |
| SERVICE_LOG_MINIMAL_SEVERITY | The minimum severity/level for the ROAD Service. | W | string | D = Debug, I = Information, S = Success, W = Warning, E = Error, V = Severe, F = Fatal | I |
Note: Environment variables can be used e.g., "%ProgramFiles%\My Road" would expand to "C:\Program Files\My Road"
Choosing Components
Unfortunately, it is not possible to determine the selection of installed components from the command line. In other words, unattended setup will always install ROAD and the VC++ runtime, but not LogExpert.
Creating a Log File
Things do go wrong when they can go wrong, and when they do go wrong, you want to know why. You will need a log file to research.
To create a log file, add the following command line option before or after the /q option: /L*V logfile.log (of course you can use a different file name). The file is by created in the directory of the RoadSetup.exe file unless you explicitly specify a directory.
The setup optionally starts (default) the RoadService.exe, which is a window service. If the Service failed to start, information about the root cause can be found in the log file. The log files for the service are stored in %Programdata%/ROAD/Logging/Service.
Case Insensitivity
The command line is not case sensitive. In other words, instead of /qb, you can also write /QB or /Qb or /qB; similarly, /l*v logfile.log also works. Property names are case insensitive, too.
Detecting the End
When you launch the installation process from the command line, the command line prompt reappears immediately; there is no way to find out when the installer has finished its work. However, this is not true when you run the same command line from within a batch file. If you do that, batch execution will stop until installation is finished. You can then check %errorlevel% – a value of 0 indicates success, anything above 0 failure.
Example
The following command line contains all options and properties. Please not that this is one line – line breaks may be inserted by the web browser!
A complete example
ROAD Unattended Setup
RoadSetup.exe /L*V setup.log /qn ^
APPDIR="C:\Program Files\ROAD\" ^
DBCONNECTION="mongodb://vm-d-32-mongo" ^
DBCONNECTIONTIMEOUT=60000 ^
DBNAME="ROAD" ^
HOSTALIAS="ROADAlias" ^
SERVICE_USER="<domain\user>" ^
SERVICE_PASSWORD="<password>" ^
START_ROAD_SERVICE="Checked" ^
CONNECTION_USE_SECURE_PROTOCOLS_BOOL="True" ^
CERTIFICATE_THUMBPRINT="111122223333444455556666777788889999aaaa" ^
CONNECTION_WEBSERVER_PORT="11003" ^
CONNECTION_DNS_NAME="roadhost.davidsystems.com" ^
DPE_DEFAULT_URL="https://dpe.davidsystems-test.com/" ^
DPE_DEFAULT_USER="<dpe_user>" ^
DPE_DEFAULT_PASSWORD="<dpe_password>" ^
WORKER_LOG_MINIMAL_SEVERITY="D" ^
SERVICE_LOG_MINIMAL_SEVERITY="D"
Links
How do I create a silent installation package?