EPI Commands

Introduction

This article contains the available commands and flags for the Enhanced Platform Installer (EPI) version of SentryOne.

Table of Commands & Examples

CommandDescriptionEPI Version
addregAdds a connection registration.

Note:  The addreg command is per user connection, and details are saved in the repositories.pref file in the local appdata folder.

so addreg -n <connectionName> --connectionServer <serverName> --connectionDatabase <databaseName>

Note:  See the Managing Connections article for a detailed guide to the connections and their properties in SentryOne.
All
configmpLaunches the SentryOne Portal Configuration Utility.

so configmp
Note:  This command must be run locally on the machine where SentryOne Portal is installed to make changes.
v2020.8.31+
createdbCreates a SentryOne database.

Note:  This is only used during the installation process.

so createdb -n <connectionName>
All
helpDisplays more information on a specific command.

so help <command>
All
installInstalls the SentryOne controller and monitoring service software.

Note:  Starting with version 2020.8, the --IAcceptLicenseTerms switch must be added to the command to acknowledge acceptance of the EULA.

This syntax will prompt you for your password and mask it:

so install --IAcceptLicenseTerms -n <connectionName> -u <serviceAccount>

This syntax allows you to type in your displayed password:

so install --IAcceptLicenseTerms -n <connectionName> -u <serviceAccount> -p <password>
Important:  See the Password section below for information on using non-alphanumeric characters such as spaces or quotes with the -p flag.

The command will stop, and monitoring and controller service installations will fail if these characters are not properly formatted with quotes and the backslash escape character.
Note:  The so install and so uninstall commands are related to installing or uninstalling the local SentryOne controller and monitoring service, and they do not impact SentryOne controllers and monitoring services running on other servers.

Note:  To install only the controller service, add the flag --installmonitoringservice (or just -m) followed by a parameter of 0.

For example:

--installmonitoringservice 0
or

-m 0
All
installmpInstalls SentryOne Portal.

See the Portal Configuration article for additional information.

Note:  Starting with version 2020.8, the --IAcceptLicenseTerms switch must be added to the command to acknowledge acceptance of the EULA.

so installmp --IAcceptLicenseTerms --connectionUseIntegrated false --server <portalServerFQDN> --connectionServer <serverName> --connectionDatabase <databaseName> --connectionUsername <SQLServerUserName> --connectionPassword <SQLServerUserPassword>

The switch -b <ipAddress:port> is not valid in versions 2020.8.31 or later. This version uses the Portal Configuration Utility to make updates after installing.
v20+
installmsInstalls a SentryOne monitoring service to a specified server.

Note:  This command is designed to install the monitoring service on a machine where the controller service is already installed.

Note:  Starting with version 2020.8, the --IAcceptLicenseTerms switch must be added to the command to acknowledge acceptance of the EULA.

so installms --IAcceptLicenseTerms -n <connectionName> -s <monitoringServiceServerFQDN> -u <serviceAccount>
All
listLists information for services, packages, or registrations (determined by the -t (--type) flag).

--type = services

Lists the current services associated with the SentryOne installation.

The following displays the Host (server), Status, SentryOne Version, Service User Account, date and time of the last Heartbeat, the number of targets being monitored, and the FQDN of the Controller Service (potentially an *, indicating that the monitoring service is not managed by a controller service).

Note:  A monitoring service can only be remotely managed if it is managed by a controller service.

so list -t services -n <connectionName>

--type = packages

This is the same as running the listpackage command. See below for an example of the output.

so list -t packages -n <connectionName>
--type = reg

This is the same as running the listreg command. See below for an example of the output.

so list -t reg
v20+
listpackageLists all packages in the SentryOne database.

so listpackage -n <connectionName>
All
listregLists existing connection registrations.

Note:  The listreg command is per user connection, and lists the connections saved in the repositories.pref file in the local appdata folder.

so listreg
All
pushPushes an upgrade package to the SentryOne database.

Using the default path: c:\Program Files\SentryOne Framework\ and default package: current.s1package:

so push -n <connectionName>

If you want to specify a path and package:

so push -n <connectionName> -f <packagePath>
In a simple upgrade scenario, you can combine the push/upgrade steps by adding the -u flag to tell the push to perform the upgrade after pushing the package.

so push -n <connectionName> -f <packagePath> -u
All
removeallregRemoves all connection registrations.

Note:  The removeallreg command is per user connection, and removes the connections saved in the repositories.pref file in the local appdata folder.

so removeallreg
Removing all connection registrations at once:
All
removeregRemoves a connection registration.

Note:  The removereg command is per user connection, and removes the connection saved in the repositories.pref file in the local appdata folder.

so removereg -n <connectionName>
All
startStarts the SentryOne controller.

so start -n <connectionName>
All
startmpStarts the SentryOne Monitor Portal service.

so startmp -n <connectionName> -s <portalServerFQDN>
v20+
startmsStarts a SentryOne monitoring service.

so startms -n <connectionName> -s <monitoringServiceServerFQDN>

Note:  See the Flags section below this table for information on using the --all option.
All
stopStops the SentryOne controller.

so stop -n <connectionName>
All
stopmpStops the SentryOne Monitor Portal service.

so stopmp -n <connectionName> -s <portalServerFQDN>
v20+
stopmsStops a SentryOne monitoring service.

so stopms -n <connectionName> -s <monitoringserviceServerFQDN>
Note:  See the Flags section below this table for information on using the --all option.
All
uninstallUninstalls the SentryOne controller and monitoring service software (and SentryOne Portal service if installed).

Note:  The so uninstall -n <connectionName> command stops the SentryOne controller and monitoring service (and SentryOne Portal service, if installed) that are connected to <connectionName> and uninstalls them from the local machine.

Note:  Use Add/Remove Programs to uninstall the remaining bits of the SentryOne framework.

so uninstall -n <connectionName>
All
uninstallmpUninstalls the SentryOne Portal.

so uninstallmp -n <connectionName> -s <portalServerFQDN>
v20+
uninstallmsUninstalls a SentryOne monitoring service.

so uninstallms -n <connectioName> -s <monitoringServiceServerFQDN> 
All
updateUpdates the password used for SentryOne service accounts. This is designed for use after a password has been changed (i.e. expired due to policy). It goes through all services in the SentryOne database associated with the provided <connectionName> and updates the password for all services with the specified <serviceAccount>.

If you are on version 2020.20.25+, you can update the service logon account using the --replaceWith flag. See the replaceWith section below for examples. Earlier versions cannot update the account associated with the service and require you to uninstall/reinstall the services.

Note:  There is a stop and start of the monitoring services involved in the process in the background during the update.

Note:  This updates the password for the controller and monitoring service if they are both found on a machine running under the <serviceAccount>.

so update -t services -n <connectionName> -u <serviceAccount>
v20+
updateregAllows you to update the connection server or database name in a connection registration.

Example of updating the --connectionServer:

so updatereg -n <connectionName> --connectionServer <newConnectionServerName> --connectionDatabase <databaseName>
This example updates the --connectionServer name from SentryOneHost to MelissaS1.

Example of updating the --connectionDatabase name from SentryOne to SentryOneUpd.
so updatereg -n <connectionName> --connectionServer <ConnectionServerName> --connectionDatabase <databaseName>
 
Note:  The connection details saved in the repositories.pref file in the local appdata folder with the updatereg command are per user.
All
upgradeMarks a SentryOne installation (<connectionName>) for upgrade to a new version (<packageVersionNumber>).

Note:  Starting with version 2020.8, the --IAcceptLicenseTerms switch must be added to the command to acknowledge acceptance of the EULA.

so upgrade --IAcceptLicenseTerms -n <connectionName> -t <packageVersionNumber>
Note:  The <packageVersionNumber> will be in a format such as 20.0.4 for Version 20.0.4.

For example, performing an so listpackage will show you the packages that are available, as well as the current package for your installation:

The current version is 20.0.1 as highlighted by <= CURRENT. To upgrade to Version 20.0.4, the command would look like this:

so upgrade --IAcceptLicenseTerms -n SentryOneEPIDocs -t 20.0.4
Note:  so upgrade is a global command that informs all controller services that an upgrade to version <packageVersionNumber> has been requested. Once this request is detected, any monitoring service connected to the affected SentryOne database will be stopped, upgraded, and then restarted after the upgrade completes. If any client processes are detected, the user will be notified that they have two minutes to exit the client before it is stopped to proceed with the upgrade.
All
upgradedbUpgrades a SentryOne database.

so upgradedb -n <connectionName>
Note:  This option is only used when upgrading a non-EPI database to an EPI version of SentryOne. It is used in the Option 2. First EPI Upgrade instructions on the Upgrade section of this article.
All
versionDisplays the version of the installed SentryOne EPI framework (from the SentryOneSetup installer exe) that is located in C:\Program Files\SentryOne Framework.

so version
All

Flags

All

Some commands, where a server must be specified (e.g. startms, startmp, stopms, stopmp, installms, uninstallms, installmp, and uninstallmp) also have an optional flag -a (--all) to use all servers instead of a specified server.

Note:  It is not recommended that you use this option for installmp as you don't need to install the SentryOne Monitor Portal service across all servers with a monitoring service.

Example of stopping all monitoring services at once:

so stopms -n <connectionName> -a

Note:  This command also works if you only have one monitoring service and do not want to type in the FQDN to specify the server, as shown in the image above.

isGmsa

Some commands (so install, so installms, and so update) have the isGmsa flag available to support using service accounts that are Group Managed Service Accounts (gMSA). Using the isGmsa flag means that you will not be asked to enter a password when running the commands.

Note:  The SentryOne Portal service (so installmp) does not support gMSA.

Enable gMSA

Important:  Support for gMSA must be turned on via the GmsaSupport feature flag in SentryOne before using the isGmsa flag in the EPI commands.

To turn on the GmsaSupport feature flag, execute the following against the SentryOne database:

INSERT INTO Setup.FeatureFlag VALUES ('GmsaSupport', 1);

gMSA Command Examples

so install

Use the isGmsa flag during installation to run the SentryOne monitoring service and controller service under the gMSA.

so install --IAcceptLicenseTerms -n <connectionName> -u <username> --isGmsa

Note:  When a service account is running under gMSA it will appear with a dollar sign at the end of the Log On As account name.

Example of SentryOne monitoring service running under gMSAExample of Log On As appearing with $ to indicate the service account is using gMSA

so installms

Example of using the isGmsa flag with the monitoring service installation command:

so installms -n <connectionName> -u <username> --isGmsa 

so update

The so update command allows you to switch between accounts, including gMSA and domain accounts (non-gMSA). The following examples show so update commands for gMSA-related workflows.

Note:  The so update command will find all services running under the current username (appearing after the -u flag) and update them to run with the new username (appearing after the --replaceWith flag).

  • Switch from a domain account to a gMSA:
    so update -t services -n <connectionName> -u <username> --replaceWith <gmsaUsername> –isGmsa
  • Switch from a gMSA to a different gMSA:
    so update -t services -n <connectionName> -u <gmsaUsername$> --replaceWith <newGmsaUsername> –isGmsa
    Note:  When an account is already running under gMSA, it has the dollar sign after it. For this reason, you must add the $ at the end of the current username (appearing after the -u flag).
  • Switch from a gMSA to a domain account:
    so update -t services -n <connectionName> -u <gmsaUsername$> --replaceWith <domainUsername> -p <passwordForDomainUsername>
    
    Note:  The password is required for the domain account. The -p (or --password) flag may be used as described in the Password section below. When omitting the -p flag from the command, you are prompted to enter a password to complete the execution.

Password

The EPI commands that require a password offer the -p (--password) flag to allow you to type in your unmasked password within the command instead of being prompted to type in your masked password after executing the command. 

Note:  The -p flag is only recommended for when you are scripting commands.

Using the password flag looks like this:

As opposed to leaving the password flag out of the command for a masked prompt:

Password Warnings & Formatting

Warning:  Passwords cannot start with a dash. There is no workaround for this.

Important:  Using non-alphanumeric (i.e. special) characters such as spaces and quotes with the -p flag requires specific formatting around those characters.

Most special characters do not require additional formatting. For example, $$passw0rd is entered as $$passw0rd and $$p@ssw0rd is entered as $$p@ssw0rd.

Spaces

If the password is $$pass w0rd then it must be contained in double quotes: 

"$$pass w0rd"

Double Quotes

If the password is p@ss"w0rd then it must be contained in double quotes and contain an additional " to escape the " in the password:

"p@ss""w0rd"

Single Quotes

If the password is p@ss'w0rd then it must be contained in double quotes:

"p@ss'w0rd"

replaceWith

The --replaceWith (or -r) flag is used with the so update command to update the account used for a monitoring (& controller) service.

Note: 

  • The so update command will find all services running under the current username (appearing after the -u flag) and update them to run with the new username (appearing after the --replaceWith flag).
  • The -p (or --password) flag may be used as described in the Password section above. When omitting the -p flag from the command, you are prompted to enter a password to complete the execution.

To change the monitoring service and controller service login account, run the following:

so update -t services -n <connectionName> -u <username> --replaceWith <newUsername> -p <passwordForNewUsername>

This example switches a domain account to another domain account. If you are are updating a gMSA account to another gMSA account, or switching to/from using gMSA, see the isGmsa flag section above for examples.

Timeout

See the Advanced section of the EPI article for an example of the timeout flag.

Verbose vs. Quiet

The EPI commands offer the following flags -v (verbose, to display all logging output) and -q (quiet, to suppress all summary messages).

V vs. Q Examples

Default example of so stop:

so stop -n <connectionName>

Verbose example of so stop:

so stop -n <connectionName> -v

Quiet example of so stop:

so stop <connectionName> -q