Windows Command Prompt Setup

There are several different operations that can be performed by executing the inmation executable using the Windows Command Prompt. All inmation components can be installed and removed by providing the right command line options. Also, the status of any inmation service can be queried. An overview of different operations is provided below.

Table 1. Overview of service operations
Operation	Precondition	Postcondition
Service Installation	The service is not installed and therefore not listed in the Windows Service Manager.	The service is installed and listed in the Windows Service Manager.
Service Removal	The service is installed and listed in the Windows Service Manager.	The service is not installed and therefore not listed in the Windows Service Manager.
Service Status Query	The status of the service is unknown, or needs to be double-checked for any reason.	In case the service is installed, a full status report is provided.

Any service operation can be applied to a single inmation service or any combination of multiple different services. The typical structure of a command is shown below, where C:\inmation.root is the root_directory.

C:\inmation.root\bin\inmation.exe [Option1] [Argument1] [Option2] [Argument2] …

Command Line Options

All the different command line options are shown in the table below.

Table 2. Overview of inmation command line options
Name	Option Short	Option Long	Description
CoreRole	-c	--corerole	Specify the role of the Core Service
Database	-d	--database	Initial database connection string for the Core Service
Execute	-e	--execute	Execute a single service without installing it
Firewall	-f	--firewall	Configure the firewall settings to be adjusted automatically
Help	-h	--help	Show the command-line help screen
Install	-i	--install	Install one or multiple services
Launch	-l	--launch	Launch service(s) after successful installation
Owner	-o	--owner	Specifies the system owner (with --install Core' option only). Include domain and system owner name. Use quotes to enter system owner name that includes spaces.
Query	-q	--query	Query the status of one or multiple services
Remove	-r	--remove	Remove one or multiple services
Silent	-s	--silent	Execute the command silently (no output)
Connect	N/A	--connect	Actively initiate connections to the Core service specified in corehost argument
ConnectorPort	N/A	--connectorport	Initial Connector Service TCP listener port
CoreHost	N/A	--corehost	Hostname of the Core that the service should be connected to
CorePort	N/A	--coreport	Initial Core Service TCP listener port
Environment	N/A	--environment	Override OS environment variables
Instance	N/A	--instance	Individual instances allow the use of multiple services of the same type on the same machine.
Peer Certificate Name	N/A	--peer-certificate-name	Identify the authentication certificate for "--security-mode TLS_X509"
Port	N/A	--port	Overrides the --coreport argument as the Initial Core Service listener port
RelayPort	N/A	--relayport	Initial Relay Service TCP listener port
Reset	N/A	--reset	Resets the image file and the sqlite database for persisted dynamic property values, and creates a new default image. Possible value is "image".
Script	N/A	--script	Specify the path to a Lua script which is executed immediately after the image was fully loaded (but before any objects are activated).
Security Mode	N/A	--security-mode	Set Component Authentication method. Possible values are TLS_PSK (default) or TLS_X509.
ServerPort	N/A	--serverport	Initial Server Service TCP listener port

The short and long versions of the option parameters are equivalent. Some options can only be used in combination with other options (Mode Option). Each option parameter is discussed separately within the following sections, including all associated arguments and several examples. In the end of this section more complex examples are provided - with multiple option parameters used at the same time.

Most service operations require the Windows Command Prompt to be run in elevated mode. For example, service installation/removal always needs to be performed with elevated rights.

Core Role Option

Short: -c
Long: --corerole
Default Argument: primary_master
Mode Option: Install, Execute
Compatible Options: Database, Firewall, Launch, Silent
Short Description: Specifies the role of the Core service.

The following table shows all arguments to be used together with the corerole option.

Table 3. CoreRole Option Argument Overview
Argument	Description
primary_master	Installs the inmation Core Service as primary_master
local	Installs the Core as a local Core - requires that a corehost and coreport are also specified.
secondary	Installs the Core as a Secondary Core - requires that a corehost and coreport are also specified.
secondary_local	Installs the Core as a Secondary Local Core - requires that a corehost and coreport are also specified.

Example

<root_directory>\bin\inmation.exe -i core -c primary_master

#OR

<root_directory>\bin\inmation.exe -i core -c local --corehost masterhost --coreport 6512

#OR

<root_directory>\bin\inmation.exe -i core -c secondary --corehost masterhost --coreport 6512

#OR

<root_directory>\bin\inmation.exe -i core -c secondary_local --corehost localcorehost --coreport 6512

Database Option

Short: -d
Long: --database
Default Argument: 127.0.0.1:27017
Mode Option: Install, Execute
Compatible Options: Firewall, Launch, Silent
Short Description: Initial database connection string for the Core service.

The database option requires an argument of one of the following syntaxes.

<IpAddress>:<TcpPort> <DnsName>:<TcpPort>

Examples

<root_directory>\bin\inmation.exe -i core -d 127.0.0.1:27017

The authentication type for database connections can also be specified and configured where "a" is the authentication type. It uses the following arguments:

Table 4. Database Authentication Types - Argument Overview
Argument	Description
1	No Authentication
3	SCRAM-SHA-1 Authentication
6	SCRAM-SHA-256 Authentication

The user name and password for the database connection authentication can also be configured where:

u - MongoDB User Name
p - MongoDB Password

Example with no authentication

<root_directory>\bin\inmation.exe -i Core -d 127.0.0.1:27017;a=1

Example with SCRAM-SHA-1 authentication

<root_directory>\bin\inmation.exe -i Core -d 127.0.0.1:27017;a=3;u=TestUser;p=TestPassword

Execute Option (Mode Option)

Short: -e
Long: --execute
Default Argument: None
Compatible Options: Database, Firewall, Silent
Short Description: Executes a single service in the console without installing it.

The following table shows all arguments to be used together with the execute option.

Table 5. Execute Option Argument Overview
Argument	Description
Connector	Executes the inmation Connector Service
Core	Executes the inmation Core Service
Relay	Executes the inmation Relay Service
Server	Executes the inmation Server Service

Only one service can be executed in a single command shell at a time.

Examples

<root_directory>\bin\inmation.exe -e Connector

Firewall Option

Short: -f
Long: --firewall
Default Argument: 1
Mode Option: Install, Execute, Remove
Compatible Options: Database, Launch, Silent
Short Description: Adjusts Windows Firewall settings automatically.

The following table shows all arguments to be used together with the firewall option.

Table 6. Firewall Option Argument Overview
Argument	Description
0	Adjust Windows Firewall settings manually
1	Adjust Windows Firewall settings automatically

The Windows Firewall must be enabled in order to allow the services to add/remove firewall rules automatically.

Examples

<root_directory>\bin\inmation.exe -i core -f 1

Help Option

Short: -h
Long: --help
Default Argument: None
Mode Option: None
Compatible Options: None
Short Description: Shows the command-line help screen.

The help option does not require any argument.

Examples

<root_directory>\bin\inmation.exe -h

Install Option (Mode Option)

Short: -i
Long: --install
Default Argument: None
Compatible Options: Database, Firewall, Launch, Silent
Short Description: Installs one or multiple services.

The following table shows all arguments to be used together with the install option.

Table 7. Install Option Argument Overview
Argument	Description
Connector	Installs the inmation Connector Service
Core	Installs the inmation Core Service
Relay	Installs the inmation Relay Service
Server	Installs the inmation Server Service
IP.21 Server	Installs the inmation IP.21 Server Service

In order to execute this command for multiple services, a space-separated list of arguments can be provided (see example).

Examples

<root_directory>\bin\inmation.exe -i Connector

# OR

<root_directory>\bin\inmation.exe -i Connector Core Relay

Launch Option

Short: -l
Long: --launch
Default Argument: 1
Mode Option: Install
Compatible Options: Database, Firewall, Silent
Short Description: Launches all services directly after installation.

The following table shows all arguments to be used together with the launch option.

Table 8. Launch Option Argument Overview
Argument	Description
0	Does not launch service after successful installation
1	Launches service after successful installation

Examples

<root_directory>\bin\inmation.exe -i Connector -l 1

Query Option

Short: -q
Long: --query
Default Argument: None
Compatible Options: None
Short Description: Queries the status of one or multiple services.

The following table shows all arguments to be used together with the query option.

Table 9. Query Option Argument Overview
Argument	Description
Connector	Queries the status of the inmation Connector Service
Core	Queries the status of the inmation Core Service
Relay	Queries the status of the inmation Relay Service
Server	Queries the status of the inmation Server Service

In order to execute this command for multiple services, a space-separated list of arguments can be provided (see example).

Examples

<root_directory>\bin\inmation.exe -q Connector

# OR

<root_directory>\bin\inmation.exe -q Connector Core Relay

Remove Option (Mode Option)

Short: -r
Long: --remove
Default Argument: None
Compatible Options: None
Short Description: Removes one or multiple services.

The following table shows all arguments to be used together with the remove option.

Table 10. Remove Option Argument Overview
Argument	Description
Connector	Removes the inmation Connector Service
Core	Removes the inmation Core Service
Relay	Removes the inmation Relay Service
Server	Removes the inmation Server Service

In order to execute this command for multiple services, a space-separated list of arguments can be provided (see example).

Examples

<root_directory>\bin\inmation.exe -r Connector

# OR

<root_directory>\bin\inmation.exe -r Connector Core Relay

Silent Option

Short: -s
Long: --silent
Mode Option: Install, Remove
Default Argument: 0
Compatible Options: Database, Firewall, Launch
Short Description: Executes the command silently (No Output).

The silent option can only be used with the install and remove options. The following table shows all arguments that can be used with the silent option.

Table 11. Silent Option Argument Overview
Argument	Description
0	Command is executed normally
1	Command is executed silently with no output

Connect Option

Short: N/A
Long: --connect
Mode Option: Install, Execute
Default Argument: 0 (1 if installing Server service)
Short Description: Actively initiates connections to the Core service specified in corehost argument. Necessary to create Active connectors and Relays

The connect option requires a boolean argument of 0 or 1

Examples

<root_directory>\bin\inmation.exe -i Connector --connect 1 --corehost localhost

# OR

<root_directory>\bin\inmation.exe -i relay --relayport 6511 --corehost 168.0.0.1 --coreport 6512 --connect 1

Connector Port Options

Short: N/A
Long: --connectorport
Mode Option: Install, Execute
Default Argument: 6510
Compatible Options: Database, Firewall, Launch, Silent
Short Description: Specifies the initial TCP listener port of the Connector service.

The connectorport option requires an argument of one of the following syntax.

<TcpPort>

Examples

<root_directory>\bin\inmation.exe -i Connector--connectorport 6010

# OR

<root_directory>\bin\inmation.exe -i Connector Relay Core Server --connectorport 6010

Core Host Option

Short: N/A
Long: --corehost
Mode Option: Install, Execute
Default Argument: None
Compatible Options: Database, Firewall, Launch, Silent
Short Description: Specifies the Core service to which the service being installed (for example, an active connector) will be connected to.

The corehost option requires an argument of one of the following syntax.

<hostname>
#OR
<IP address>

Examples

<root_directory>\bin\inmation.exe -i Connector --connect 1 --corehost localhost

# OR

<root_directory>\bin\inmation.exe -i relay --relayport 6511 --corehost 168.0.0.1 --coreport 6512 --connect 1

Core Port Option

Short: N/A
Long: --coreport
Mode Option: Install, Execute
Default Argument: 6512
Compatible Options: Database, Firewall, Launch, Silent
Short Description: Specifies the initial TCP listener port of the (Master)Core service.

For the (Master) Core service, this option sets the port on which it shall listen for requests from other inmation services.
For all other inmation services, including the Local Core service (i.e. a Core service with the corerole option set to 'local'), this option provides the information on which port the (Master) Core is listening.
To set the listener port of a Local Core service , use the port option.

The coreport option requires an argument of one of the following syntax.

<TcpPort>

Examples

<root_directory>\bin\inmation.exe -i Connector --coreport 6012

# OR

<root_directory>\bin\inmation.exe -i Connector Relay Core Server --coreport 6012

# OR

<root_directory>\bin\inmation.exe -i Relay --relayport 6011 --corehost COREHOST --coreport 6012

# OR

<root_directory>\bin\inmation.exe -i Core --corerole local --port 6612 --corehost MASTERCOREHOST--coreport 6012

Environment Option

Short: N/A
Long: --environment
Mode Option: Install, Execute
Default Argument: None
Short Description: Specifies OS environment variable overrides. Individual overrides must be specified as key=value pairs, separated by spaces.

In the example below, the COMPUTERNAME environment variable is overridden. In case of an ACTIVE Connector service or a Server service being installed, the value specified in the COMPUTERNAME environment variable will be used for the initial connection and as the initial name of the corresponding object generated in I/O model (or Server model, respectively).

Examples

<root_directory>\bin\ inmation.exe -i connector --connect 1 --environment COMPUTERNAME=SOME_NAME

Instance Option

Short: N/A
Long: --instance
Mode Option: Install, Execute
Default Argument: none
Short Description: When multiple Services of the same type are to be used on the same machine, each of them requires an individual value for the instance option.

The instance option requires a string without white space.

Examples

<root_directory>\bin\inmation.exe -i Connector --connectorport 6210 --instance another_instance_name

Passphrase-clear Option

Short: N/A
Long: --passphrase-clear
Default Argument: none
Short Description: Set the passphrase for Inter-component Communication. Make sure to follow the Password Policy.

Examples

<root_directory>\bin\inmation.exe -i connector --security-mode TLS_PSK --passphrase-clear "ABcd12"

Peer Certificate Name Option

Short: N/A
Long: --peer-certificate-name
Mode Option: None
Default Argument: None
Compatible Options: None
Short Description: Identifies the certificate for X.509 certificate authentication being set in the security mode option.

Port Option

Short: N/A
Long: --port
Mode Option: Install, Execute
Default Argument: 6515
Compatible Options: Database, Firewall, Launch, Silent
Short Description: Specifies the initial TCP listener port of a Local Core service. For Local Core services the coreport option sets the port on which the Master Core is listening.

The port option requires an argument of one of the following syntax.

<TcpPort>

Examples

<root_directory>\bin\inmation.exe -i Core --corerole local --port 6612 --corehost MASTERCOREHOST --coreport 6512

Relay Port Option

Short: N/A
Long: --relayport
Mode Option: Install, Execute
Default Argument: 6511
Compatible Options: Database, Firewall, Launch, Silent
Short Description: Specifies the initial TCP listener port of the Relay service.

The relayport option requires an argument of one of the following syntax.

<TcpPort>

Examples

<root_directory>\bin\inmation.exe -i Relay --relayport 6011

# OR

<root_directory>\bin\inmation.exe -i Connector Relay Core Server --relayport 6011

Reset Option

Short: N/A
Long: --reset
Mode Option: Execute
Default Argument: N/A
Short Description: Resets the image file and the sqlite database for persisted dynamic property values, and creates a new default image. Possible value is "image".

Examples

<root_directory>\bin\inmation.exe -e Connector --reset image

Script Option

Short: N/A
Long: --script
Mode Option: None
Default Argument: None
Compatible Options: None
Short Description: Specifies the initial Lua script to be executed at service startup

If specified, a command line startup script is executed after all the objects are loaded/initialized for the respective component, before functional object activation. The script option requires an argument specifying the path to the Lua script to be executed.

Additionally, an inmation component/object specific startup script can be also specified via the StartupScript object property, available for : Root, Core, Connector, System and Server objects.

Examples

<root_directory>\bin\inmation.exe -e Server --script D:\workspace\startup_server.lua

Security Mode Option

Short: N/A
Long: --security-mode
Mode Option: None
Default Argument: Component dependant
Compatible Options: None
Short Description: Set Component Authentication method.

Table 12. Security Mode Option Argument Overview
Argument	Description
none	no security mode applied
passphrase	uses Passphrase authentication
TLS_PSK	uses Pre-shared Key authentication
TLS_X509	uses X.509 certificate authentication

By default the communication modes 'none' and 'passphrase' are disabled due to security reasons. This restriction can be lifted by disabling the 'Encrypted Connections Only' option in Communication section of the Root Object configuration.

Configure the security mode for the component being installed/executed. For more information on security modes and to see which security modes are available for each component please visit the Secure Communication - Intercomponent Communication.The default security modes for each component are specified here.

Examples

<root_directory>\bin\inmation.exe -i connector --connect 1 --corehost CORESVR --security-mode TLS_PSK

# OR

<root_directory>\bin\inmation.exe -i connector --connect 1 --corehost CORESVR --security-mode TLS_X509 --peer-certificate-name CERTIFICATE-NAME

Server Port Option

Short: N/A
Long: --serverport
Mode Option: Install, Execute
Default Argument: 6515
Compatible Options: Database, Firewall, Launch, Silent
Short Description: Specifies the initial TCP listener port of the Server service.

The serverport option requires an argument of one of the following syntax.

<TcpPort>

Examples

<root_directory>\bin\inmation.exe -i Server --serverport 6015

Changing command line of already installed services

It might be necessary to change the command line options of a windows service that is already running. The following powershell script is an example on how to change it without completely reinstalling the service.

# Change the following variables as necessary and then run the script with administrator privileges
$ServiceName = "inmation Core Service"
$NewCmdLine = '\"<root_directory>\bin\inmation.exe\" --service 1 --execute Core --environment COMPUTERNAME=SOME_NAME'

sc.exe config $ServiceName binpath= $NewCmdLine
Net stop $ServiceName
Net start $ServiceName

Changing the port of a running Core Service

The command line parameters can be used to change the Common Server Port on the Core object in DataStudio whilst the service is running.

Similarly to the previous section, the command line for the service needs to be changed. In the following PowerShell script, the <root_directory> should be replaced with the name of the folder configured as the root directory using either the Windows Installer Setup or the command line. The <TcpPort> should be replaced with the new port for the Core Service.

$ServiceName = "inmation Core Service"
$NewCmdLine = '<root_directory>\bin\inmation.exe --service 1 --execute Core --coreport <TcpPort>'

Then, run the following script in PowerShell as an administrator.

sc.exe config $ServiceName binpath= $NewCmdLine
Net stop $ServiceName
Net start $ServiceName

The above script will change the configuration for the Core service and then restart the service using the new parameters. If DataStudio is used to connect to the Core whilst the service is restarted, the connection will stop. As the Core service will now be assigned to a different port, disconnect from DataStudio by selecting System Disconnect, then change the Port on the DataStudio authentication window and select Ok to reconnect to the Core. Now, in DataStudio, the new port for the Core service will be reflected in the Common Server Port property on the Core object.

Other Components

Local and Secondary Cores, as well as any active components, configured under the Master Core will be affected when the Core service is restarted. The Web API Server object in the Server Model will also be affected when the port for the Core service is changed.

This section explains the expected behavior of different components, configured below the Master Core, in DataStudio as a result of changing the Server Port on the Master Core.

Local and Secondary Cores

When connected to the Master Core in DataStudio, any Local or Secondary Cores under the Master Core will be shown in a 'bad' state after changing the Server Port for the Master Core as communication between the Cores is interrupted. To re-enable communication between a Master and Local/Secondary Core, the command line for the Local/Secondary Core service must be changed on the host machine where the associated Core service is installed.

$ServiceName = "inmation Core Service"
$NewCmdLine = '<root_directory>\bin\inmation.exe --service 1 --execute Core --corerole <COREROLE> --corehost <MASTERCOREHOST>
--coreport <TcpPort>'

sc.exe config $ServiceName binpath= $NewCmdLine
Net stop $ServiceName
Net start $ServiceName

The <root_directory> is the directory configured during the installation of the Core service using either the Windows Installer Setup or the Windows Command Prompt Setup.
The <COREROLE> is the type of Core installed on the current host machine, e.g. local or secondary
The <MASTERCOREHOST> is the name or IP address of the host machine where the Master Core service is installed.
The <TcpPort> is the newly configured port for the Master Core service.

This will restart the Local/Secondary Core service using the new configuration. If DataStudio is used to connect to the Local/Secondary Core whilst the script is running, the connection to the Local/Secondary Core service will be briefly interrupted but should automatically reconnect (unlike when restarting the Master Core service after changing the port).

Servers

As the Server service is always installed as an active component, any servers configured under the Master Core will be affected when the port of the Master Core service is changed. In DataStudio, the object associated with the Server service will be shown in a 'bad' state.

The command line for the Server service needs to be updated to re-enable communication between the Core and Server services. The command line for each Server service is dependent on how the service was installed. For example, if the service was installed using the Node Installer or the command line, additional parameters, such as instance or environment, may also be included.

To ensure that all the required parameters are included in the new command line, the current command can be found in the Windows Services app. Navigate to the respective service and right-click on the service to open the context menu. In this context menu, select Properties and in the Properties window, the value of the Path to executable is the command line that we want to update.

The following script is an example of how to change the command line parameters without reinstalling the Server service. It will also stop and restart the service to implement the new command line. The script must be run in Powershell as an administrator and should be adjusted to match your system:

$ServiceName = "inmation Server Service",
$NewCmdLine =  '<root_directory>\bin\inmation.exe --service 1 --execute Server --corehost <MASTERCOREHOST> --coreport <TcpPort>'

sc.exe config $ServiceName binpath= $NewCmdLine
Net stop $ServiceName
Net start $ServiceName

The root_directory is the directory configured during the installation of the Server service using either the Windows Installer Setup, Node Installer or the Windows Command Prompt Setup.
The <MASTERCOREHOST> is the name of the host machine where the Core service for the Master Core is installed.
The <TcpPort> is the newly configured port of the Master Core service.

Once the service has been restarted, the corresponding object in DataStudio should return to a 'good' state as communication between the Master Core and Server service is restored.

Active Connectors and Relays

Any active components (such as Relays or Connectors) configured directly below the Master Core will be shown in a 'bad' state in DataStudio whilst connected to the Master Core when the port of the Master Core service using the command line.

The command line for each service associated with an active component needs to be updated to re-enable communication between the Core and the active component. The command line for these active components is dependent on how the service was installed. For example, if the Node Installer or command line was used to install the service, additional parameters such as instance or environment may be used.

The following script is an example of how to change the command line parameters for an active component without reinstalling the corresponding service. It will also stop and restart the service to implement the new command line. The script must be run in Powershell as an administrator and should be edited to match your system:

$ServiceName = "<Service Name>"
$NewCmdLine = '<root_directory>\bin\inmation.exe --service 1 --execute <component_type> --connect 1 --corehost <MASTERCOREHOST> --coreport <TcpPort>'

sc.exe config $ServiceName binpath= $NewCmdLine
Net stop $ServiceName
Net start $ServiceName

The <ServiceName> is the name assigned to the service associated with the active component, e.g., inmation Relay Service or inmation Connector Service.
The <root_directory> is the directory configured during the installation of the service using either the Windows Installer Setup, Node Installer or the Windows Command Prompt Setup.
The <component_type> is the name of the component type, e.g. Relay or Connector.
The <MASTERCOREHOST> is the name or IP address of the host machine where the Master Core service is installed. If the service for the component is installed on the same machine, then this will be 'localhost'.
The <TcpPort> is the newly configured port for the Master Core service