SQL Sentry Enhanced Platform Installer
Topic Overview
The SQL Sentry Enhanced Platform Installer topic provides instructions for installing new SQL Sentry installations through the Enhanced Platform Installer (EPI). If you want to upgrade your existing SQL Sentry EPI installation, or your unified installation through EPI, see EPI Upgrade.
SolarWinds Note
Starting with version 2021.8, SentryOne SQL Sentry is now SolarWinds SQL Sentry. While logos and names have rebranded, you can expect to see things like SentryOne Framework in the SolarWinds version when using EPI. The latest EPI version of SQL Sentry is available from the SolarWinds Customer Portal. Certain components like service provider names may also reflect the SentryOne name. See the SQL Sentry Components and Architecture article for more details.
Introduction
EPI increases the speed and simplicity of installing and upgrading SQL Sentry implementations with multiple monitoring services or clients, and avoids having to manually run through the original installer on every machine. It allows the automation of upgrades and deployments of the SQL Sentry platform with a command line interface experience. EPI minimizes the downtime required to update the monitoring solution by removing the need to manually shut down monitoring services or close client connections.
Getting Started
Version Availability & Components
To get started with EPI (available in v19.1.1), all installed SQL Sentry components (database, monitoring service, and client) must have the EPI version of SQL Sentry installed, and the SQL Sentry controller service (EPI bootstrapper) must exist on all machines where a monitoring service or client is installed. If you are installing SQL Sentry for the first time, or have removed all SQL Sentry components from your environment, follow the installation instructions in the Install section. If you would like to upgrade an existing SQL Sentry installation to use EPI, follow the Option 2. First EPI Upgrade steps in the Upgrade section.
Run as Administrator
Command Prompt must use the Run as administrator option for all commands.
Case-Sensitivity
The parameters used in commands are case-sensitive.
This means that --connectionserver will not work for --connectionServer.
Parameters & Examples
The instructions include commands with placeholders for parameters specific to your SQL Sentry environment. This section describes all of the placeholders used in the EPI instructions.
For example, you will use the following command to register a new connection:
so addreg -n <connectionName> --connectionServer <serverName> --connectionDatabase <databaseName>When you run it with your parameter values, it might look like this:
so addreg -n SentryOneUS --connectionServer SentryOneHost --connectionDatabase SentryOne| Parameter | Description |
|---|---|
| <connectionName> | Used with -n. The friendly name for this connection which appears on the SQL Sentry Database Connection Management screen (formerly called Repository Connection Management). The <connectionName> labeled with a 1 in the image below, which has SentryOneUS displayed. Important: The name itself is arbitrary, but once you pick one, you must stick with it for all EPI commands associated with this connection.  Note: If you need to see your existing connections using EPI, you can use the listreg command to see the <connectionName>, <serverName>, and <databaseName> as described in the EPI Commands article. |
| <serverName> | Used with --connectionServer. The name of the server hosting the SQL Sentry database or where you will install the SQL Sentry database. This is labeled with a 2 in the image above, which has SentryOneHost as the value. Note: You may use localhost, if applicable. Note: When working with a named instance, the parameter format is serverName\instanceName. Note: When the SQL Sentry database is part of an availability group, it is recommended to use the availability group listener name instead of the SQL Server name. |
| <databaseName> | Used with --connectionDatabase. The name of the SQL Sentry database that will be created or updated. This is labeled with a 3 in the image above which has SentryOne as the value. |
| <SQLServerUserName> | Used with --connectionUsername in the command examples when using SQL Server authentication. The SQL Server authentication user name. Note: This is only needed when using SQL Server authentication. |
| <SQLServerUserPassword> | Used with --connectionPassword in the command examples when using SQL Server authentication. The SQL Server authentication password associated with the SQL Server user name. Warning: Passwords cannot start with a dash. There is no workaround for this. Note: This is only needed when using SQL Server authentication. |
| <SQLServerConnectionPort> | Used with --connectionPort. The SQL Server connection port. The default port is 1433. Note: This is only needed when specifying a different parameter value for the port number. See the Connecting article for more information about the SQL Server Connection Port. |
| <serviceAccount> | Used with -u. The account used to run the SQL Sentry monitoring service. The following command is equivalent to completing the Service Account Information screen as shown below.  Warning: Passwords cannot start with a dash. There is no workaround for this. See the Monitoring Service Security article for additional information on service account requirements. Important: When using EPI, the monitoring service account must be a member of the local administrator group. This is not required for monitoring, but is required during EPI installations and upgrades. |
| <servicePassword> | Used with -p. The password associated with the service account. The service password will be masked in the command line interface. This is the recommended method for entering your password.  If you want the password displayed, use the -p <servicePassword> after the serviceAccount as shown below:Warning: Passwords cannot start with a dash. There is no workaround for this. Important: See the Password section in the EPI Commands article for information on using non-alphanumeric (i.e. special) 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. |
| <packageVersion> | Used with -t. The SQL Sentry version to which you are upgrading (i.e. 19.2.2). |
| <packagePath> | Used with -f. The file path where the SQL Sentry upgrade package is located. |
| <portalServerFQDN> | Used with --server (-s). The server that will host the SQL Sentry Portal service. It must be the Fully Qualified Domain Name (FQDN) of the server. |
Install via EPI
Requirements
Before installing SQL Sentry, review the following articles:
Complete the following steps to install SQL Sentry for the first time. There should be no existing SQL Sentry components on the machines where you complete this install. This process walks you through creating the SQL Sentry database, installing the monitoring service, and launching the client. The .NET Framework 4.7.2 is installed during this process, which may force a reboot.
Note:
- Review the Parameters & Examples section for more information about the <parameters> used in the following commands.
- If you experience any Result = Timeout messages while a command is running, refer to the Advanced section for more information. This does not mean the operation timed out.
Install SQL Sentry
Go to the SolarWinds Customer Portal and download the Enhanced Platform Installer version of SQL Sentry. It will have a file naming convention of SolarWinds-SQLSentry-EPI-{Version}.exe.
1. On the machine that will serve as the monitoring service, double-click SolarWinds-SQLSentry-EPI-{Version}.exe.
2. Run Command Prompt as Administrator and change the directory to SentryOne Framework:
cd c:\Program Files\SentryOne Framework 3. Add a new connection for the server that will host the SQL Sentry database:
Using Integrated Windows Authentication
so addreg -n <connectionName> --connectionServer <serverName> --connectionDatabase <databaseName>Using SQL Server Authentication
so addreg -n <connectionName> --connectionServer <serverName> --connectionDatabase <databaseName> --connectionUseIntegrated false --connectionUsername <SQLServerUserName> --connectionPassword <SQLServerUserPassword> --connectionPort <SQLServerConnectionPort>See the Security topic for more information about security requirements.
4. Use the following command to verify connection registration details:
so listreg5. Create a new SQL Sentry database using the registered connection:
so createdb -n <connectionName>6. Install the SQL Sentry monitoring service (you will be prompted for the <serviceAccount> password):
Starting with version 2020.8, the --IAcceptLicenseTerms switch must be added to the command to acknowledge acceptance of the EULA.
so install --IAcceptLicenseTerms Versions prior to 2020.8 use the following:
so install -n <connectionName> -u <serviceAccount> 7. Launch the SQL Sentry client. You will see a loading dialog as files are downloaded from the SQL Sentry database for the latest version of the client. It may take a few minutes for the files to download. Note that you must do this for each machine where you wish to install the SentryOne client.
Success: SQL Sentry is installed and ready to use. Continue below to install the SQL Sentry Portal or to the Onboarding article for additional assistance.
Install SQL Sentry Portal
Review the System Requirements and Portal Configuration articles before installing SQL Sentry Portal.
After you have ensured that your machine meets the prerequisite requirements, you can begin installing SQL Sentry Portal. Install SentryOne Portal on your machine with EPI by completing the following steps:
1. You must have installed or upgraded SQL Sentry to version 20 or greater using EPI before proceeding.
2. SQL Sentry Portal requires the SQL Sentry controller service on the machine where it is installed. If the machine where you are installing SQL Sentry Portal needs the controller service, follow the Install Additional Monitoring Services instructions below.
3. Run the following command to complete SQL Sentry Portal installation:
Important:
- Integrated Windows Authentication is available in versions 2020.8.31 or later. It is not available in version 2020.8.
- SQL Sentry Portal. SQL Server Authentication works in all versions.
- Starting with version 2020.8, the --IAcceptLicenseTerms switch must be added to the command to acknowledge acceptance of the EULA.
Using Integrated Windows Authentication
so installmp --IAcceptLicenseTerms -n <connectionName> -s <portalServerFQDN> -u <serviceAccount>Using SQL Server Authentication
so installmp --IAcceptLicenseTerms --connectionUseIntegrated false --server <portalServerFQDN>
--connectionServer <serverName> --connectionDatabase <databaseName> --connectionUsername
<SQLServerUserName> --connectionPassword <SQLServerUserPassword>Versions prior to 2020.8 use the following:
so installmp -n <connectionName> -s <portalServerFQDN> -u <serviceAccount> -b <ipAddress:port>
Note:
- The --server (-s) switch is for the server that will host SQL Sentry Portal (<portalServerFQDN>) and must be the Fully Qualified Domain Name (FQDN). If needed, this name can be found by using the list command to view the Controller Service value. See the EPI Commands article for additional information on using list.
so list -t services -n <connectionName>
- 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.
- Prior to that release, it can be omitted if you're using the default value of 0.0.0.0:9991. Prior versions cannot use the Portal Configuration Utility with EPI and must set the binding duirng installation, or uninstall then reinstall to make changes.
- See the Parameters & Examples section for more information on the <parameters> used such as <serverName> and <databaseName>. These are referring to the SQL Sentry database and the SQL Server that hosts it.
Success: SQL Sentry Portal is installed and ready to use. Continue to the Getting Started with SQL Sentry Portal article for additional assistance.
Install Additional Monitoring Services
In many cases, a SQL Sentry installation uses multiple monitoring services for load balancing and monitoring an increased number of targets. See the Installation Recommendations article for advice on the recommended number of monitoring services.
Perform the following steps to install the monitoring service on additional machines:
1. On the machine that will serve as a monitoring service, double-click SolarWinds-SQLSentry-EPI-{Version}.exe. The files are unpacked to C:\Program Files\SentryOne Framework.
2. Run Command Prompt as Administrator and change the directory to SentryOne Framework:
cd c:\Program Files\SentryOne Framework 3. Add a new connection (using the same <connectionName> from the installation process):
Using Integrated Windows Authentication
so addreg -n <connectionName> --connectionServer <serverName> --connectionDatabase <databaseName>Using SQL Server Authentication
so addreg -n <connectionName> --connectionServer <serverName> --connectionDatabase <databaseName>
--connectionUseIntegrated false --connectionUsername <SQLServerUserName> --connectionPassword
<SQLServerUserPassword> --connectionPort <SQLServerConnectionPort>4. Use the following command to verify connection registration details:
so listreg5. Install the SQL Sentry monitoring service (using the same <connectionName> used during the installation). The first option is for the full monitoring service (typical installation), while the second option is for configuring a machine for SQL Sentry Portal.
1. Full monitoring service install option:
Starting with version 2020.8, the --IAcceptLicenseTerms switch must be added to the command to acknowledge acceptance of the EULA:
so install --IAcceptLicenseTerms Versions prior to 2020.8 use the following:
so install -n <connectionName> -u <serviceAccount> Success: The SQL Sentry monitoring service is now installed and running.
2. SQL Sentry Portal / controller service only install option:
Starting with version 2020.8, the --IAcceptLicenseTerms switch must be added to the command to acknowledge acceptance of the EULA:
so install --IAcceptLicenseTerms Versions prior to 2020.8 use the following:
so install --installmonitoringservice 0 -n <connectionName> -u <serviceAccount> Success: The SQL Sentry controller service is now installed and running.
Install Additional Clients
When using EPI, the SQL Sentry client security requirements remain the same. See the Client Security article for details.
To install only the SQL Sentry client on a machine:
- Double-click the SQL Sentry executable file.
- Wait for the process to complete and load the client shortcut onto the desktop.
- Double-click the shortcut to pull the client bits from the SQL Sentry database.
Success: The SQL Sentry client is now installed and ready to use.
Uninstall via EPI
Uninstall
To uninstall the local controller and monitoring service, run the following:
so uninstall -n <connectionName>If you want to remove the Enterprise Platform Installer entirely, you can run the executable that was used to install it and choose the uninstall option, or you can uninstall it from Add or remove programs in Windows. This will stop and remove the controller and monitoring services locally, in addition to removing the CLI. For more information about uninstalling SQL Sentry , see the Uninstalling SQL Sentry article.
Uninstall SentryOne Portal
If you installed SentryOne Portal using EPI, you can uninstall it from a machine via EPI by following the steps below.
- Open Command Prompt (use the Run as administrator option)
- Change to the SentryOne Framework directory (or custom directory used during installation)
cd C:\Program Files\SentryOne Framework
- Stop the SentryOne Portal service
so stopmp -n <connectionName> -s <portalServerFQDN>
- Uninstall the SentryOne Portal
so uninstallmp -n <connectionName> -s <portalServerFQDN>
Upgrade via EPI
See the Upgrade SQL Sentry via EPI article.
Downgrade (non-typical process)
See the Downgrade section of the EPI Upgrade article.
Available Commands
See the EPI Commands article for a table of available commands and flag examples.
Advanced
Topics
PowerShell
PowerShell may be used with EPI. The SQL Sentry installation package with EPI must exist on the machines where you plan to do an installation or run commands, and then PowerShell can be used to unpack it and execute the necessary commands. See the SQL Sentry PowerShell Module article for information on importing the SQL Sentry module to use with EPI.
Troubleshooting
Problem: Timeout message displayed
Certain commands such as the so install may display a timeout message in the command line interface. This timeout does not refer to the operation itself, but rather the display timeout. If the command has a default timeout of 30 seconds, but the operation takes 60 seconds to complete, then the timeout message will display while the operation continues to execute.
Use the so help command to view the default timeout value for applicable commands. For example, the so uninstallms has a default timeout of 30 seconds, while the so install has a default of 120 seconds.
In a high latency environment, you may want to increase the default timeout if you want to see the process complete in the command line interface.
In this example, the -t (--timeout) is set to 1 second to illustrate what the timeout looks like, using so installmp:
If you have or expect to receive timeout messages and would rather see Result = Success in the command line interface, use the -t (--timeout) flag to increase the default timeout as needed.
Error: Option 'IAcceptLicenseTerms' is unknown
If you receive this error when using the --IAcceptLicenseTerms switch, you need to run the installer (SentryOneSetup.exe) to update the SentryOne Framework folder with the new EPI commands.
Viewing Log Files
See the SQL Sentry Troubleshooting article for information about log files.