EPI Commands

• Introduction

• Table of Commands & Examples

• Updating the Service Account

• Flags

Introduction

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

Table of Commands & Examples

Command	Description	EPI Version
addreg	Adds 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 SQL Sentry.	All
configmp	Launches the Portal Configuration Utility. so configmp Note:  This command must be run locally on the machine where SQL Sentry Portal is installed to make changes.	v2020.8.31+
createdb	Creates a SQL Sentry database. Note:  This is only used during the installation process. so createdb -n <connectionName>	All
help	Displays more information on a specific command. so help <command>	All
install	Installs the SQL Sentry controller and monitoring service software. Important:  The account used for the SQL Sentry monitoring service must be a local admin to install the monitoring service. 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 SQL Sentry controller and monitoring service, and they do not impact SQL Sentry 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
installmp	Installs SQL Sentry 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 -n <connectionName> -s <monitoringServiceServerFQDN> -u <serviceAccount>   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+
installms	Installs a SQL Sentry monitoring service to a specified server. Important:  The account used for the SQL Sentry monitoring service must be a local admin to install the monitoring service. 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
list	Lists information for services, packages, or registrations (determined by the -t (--type) flag). --type = services Lists the current services associated with the SQL Sentry installation. The following displays the Host (server), Status, SQL Sentry 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+
listpackage	Lists all packages in the SQL Sentry database. so listpackage -n <connectionName>	All
listreg	Lists 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
push	Pushes an upgrade package to the SQL Sentry 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
removeallreg	Removes 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
removereg	Removes 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
start	Starts the SQL Sentry controller. so start -n <connectionName>	All
startmp	Starts the SQL Sentry Portal service. so startmp -n <connectionName> -s <portalServerFQDN>	v20+
startms	Starts a SQL Sentry monitoring service. so startms -n <connectionName> -s <monitoringServiceServerFQDN>   Note:  See the Flags section below this table for information on using the --all option.	All
stop	Stops the SQL Sentry controller. so stop -n <connectionName>	All
stopmp	Stops the SQL Sentry Portal service. so stopmp -n <connectionName> -s <portalServerFQDN>	v20+
stopms	Stops a SQL Sentry monitoring service. so stopms -n <connectionName> -s <monitoringserviceServerFQDN>   Note:  See the Flags section below this table for information on using the --all option.	All
uninstall	Uninstalls the SQL Sentry controller and monitoring service software (and SQL Sentry Portal service if installed). Note:  The so uninstall -n <connectionName> command stops the SQL Sentry controller and monitoring service (and SQL Sentry 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 SQL Sentry framework. so uninstall -n <connectionName>	All
uninstallmp	Uninstalls the SQL Sentry Portal. so uninstallmp -n <connectionName> -s <portalServerFQDN>	v20+
uninstallms	Uninstalls a SQL Sentry monitoring service. so uninstallms -n <connectioName> -s <monitoringServiceServerFQDN>	All
update	Updates the password used for SQL Sentry 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 SQL Sentry 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+
updatereg	Allows 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
upgrade	Marks a SQL Sentry 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 SQL Sentry 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
upgradedb	Upgrades a SQL Sentry database. so upgradedb -n <connectionName> Note:  This option is only used when upgrading a non-EPI database to an EPI version of SQL Sentry. It is used in the Option 2. First EPI Upgrade instructions on the Upgrade section of this article.	All
version	Displays the version of the installed SQL Sentry 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.

Example of stopping all monitoring services at once:

so stopms -n <connectionName> -a

isGmsa

Some commands (so install, so installms, so update, so installmp) 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.

Enable gMSA

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

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

gMSA Command Examples

so install

Use the isGmsa flag during installation to run the SQL Sentry 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.

so installms

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

so installms --IAcceptLicenseTerms -n <connectionName> -s <monitoringServiceServer> -u <serviceAccount> --isGmsa

so installmp

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

so installmp --IAcceptLicenseTerms -n <connectionName> -s <monitoringServiceServer> -u <serviceAccount> --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.

• 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>

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. 

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

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