Documentation forSQL Sentry

EPI Commands

Note:  In SQL Sentry Version 2023.2, the .NET Framework Runtime has been upgraded to 4.8. For EPI users upgrading via the command line, you must manually upgrade .NET Framework Runtime to 4.8 for each machine with a SQL Sentry Client or Monitoring Service.
Important:  When you launch the SQL Sentry Client after upgrading via EPI command line for Version 2023.2, you will be prompted to download the .NET Framework Runtime 4.8. Clicking Yes will continue to the .NET Framework Runtime 4.8.1 installation page. You must install .NET Frame Runtime 4.8. The .NET Framework runtime 4.8.1 installation will fail on older versions of Windows Server, such as Windows Server 2016. 

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.

Note:  It is not recommended that you use this option for installmp as you don't need to install the SQL Sentry 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 SQL Sentry Portal service (so installmp) does not support gMSA.

Enable gMSA

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

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.

Example of SentryOne monitoring service running under gMSA

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