SentryOne Enhanced Platform Installer

Overview

Introduction

EPI increases the speed and simplicity of installing and upgrading SentryOne implementations. It allows the automation of upgrades and deployments of the SentryOne 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.

SentryOne Enterprise Platform InstallerExample of the SentryOne Installer Command Line Interface.

To get started with EPI (available in v19.1.1), all installed SentryOne components (database, monitoring service, and client) must have the EPI version of SentryOne installed, and the EPI bootstrapper must exist on all machines where a monitoring service or client is installed. If you are installing SentryOne for the first time, or have removed all SentryOne components from your environment, follow the installation instructions on the Install tab. If you would like to upgrade an existing SentryOne installation to use EPI, follow the Option 2. First EPI Upgrade steps on the Upgrade tab.

Run as Administrator

Command Prompt must be "Run as administrator" for all commands.

Case-Sensitivity

The commands are case-sensitive.

This means that --connectionserver will not work for --connectionServer.

Parameters

The instructions include commands with placeholders for parameters specific to your SentryOne environment. This section describes all of the parameters 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
ParameterDescription
<connectionName>The friendly name for this connection which appears on the Repository Connection Management screen. This is labeled with a "1" in the image below, which has "VM-SENTRYONE-DB.Sentr..." displayed as its truncated value. The name itself is arbitrary, but once you pick one, you must stick with it for all EPI commands associated with this connection.
Example of where the parameters are used in the connection window
<serverName>The name of the server hosting the SentryOne database or where you will install the SentryOne database. This is labeled with a "2" in the image above, which has "VM-SENTRYONE-DB" as the value. You may use "localhost", if applicable.
<databaseName>The name of the SentryOne database that will be created or updated. This is labeled with a "3" in the image above which has "SentryOne19" as the value

Note:  In many cases, the value of this database name will simply be "SentryOne".
<SQLServerUserName>The SQL Server authentication user name.

Note:  This is only needed when using SQL Server authentication.
<SQLServerUserPassword>The SQL Server authentication password associated with the SQL Server user name.

Note:  This is only needed when using SQL Server authentication.
<SQLServerConnectionPort>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>The account used to run the SentryOne monitoring service.

The following command is equivalent to completing the Service Account Information screen as shown below.

so install -n <connectionName> -u <serviceAccount>
Service Account Information screen

See the Monitoring Service Security article for additional information on service account requirements.
<servicePassword>The password associated with the service account.

The servicePassword will be masked in the command line interface.
SentryOne Masked Password Option for Installer
Example of masked password.

If you want the password displayed, use the -p <servicePassword>  after the serviceAccount as shown below:

so install -n <connectionName> -u <serviceAccount> -p <servicePassword>
<packageVersion>
<packagePath>

SentryOne Client Impacts

How does using the SentryOne installer impact the SentryOne client during an upgrade?

If a SentryOne user has the SentryOne client open, they receive an alert informing them that the SentryOne client must be shut down due to an upgrade. It will ask them to exit the application and display a "shutdown countdown" starting at 120 seconds.

How does using the SentryOne installer impact the SentryOne client after an upgrade?

When the SentryOne client is launched after an upgrade, a message appears, indicating to the user that the client is checking for updates and asks them to wait while the client is updated.

SentryOne Client Checking for UpdatesUpdate message displayed to user in client

Install

Install SentryOne

Complete the following steps to install SentryOne for the first time. There should be no existing SentryOne components on the machines where you complete this install. This process walks you through creating the SentryOne 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 section on the Overview tab for more information about the <parameters> used in the following commands.

1. On the machine that will serve as the monitoring service, double-click SentryOneSetup.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 for the server that will host the SentryOne 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 listreg

5. Create a new SentryOne database using the registered connection:

so createdb -n <connectionName>

Note:  Packages are written to the tables during this step.

6. Install the SentryOne monitoring service (you will be prompted for the <serviceAccount> password): 

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

Note:  The SentryOne monitoring service is now installed and running. 

See the Monitoring Sevice Security article for more information about account requirements.

7. Launch the SentryOne client. You will see a loading dialog as files are downloaded from the SentryOne 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: SentryOne is installed and ready to use. Continue to the Onboarding article for additional assistance.

Install Additional Monitoring Services

In many cases, a SentryOne 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 SentryOneSetup.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 listreg

5. Install the SentryOne monitoring service (using the same <connectionName> used during the installation):

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

Success: The SentryOne monitoring service is now installed and running.

Install Additional Clients

To install only the SentryOne client on a machine:

  1. Double-click the SentryOne executable file.
  2. Wait for the process to complete and load the client shortcut onto the desktop.
  3. Double-click the shortcut to pull the client bits from the SentryOne database.

Success: The SentryOne client is now installed and ready to use.

Uninstall SentryOne

To uninstall the local controller and monitoring service, run the following:

so uninstall -n <connectionName>

Note:  The so uninstall command is a local command and is used to uninstall the local controller and monitoring service only. It does not affect controllers and monitoring services running in other environments.

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 servuces locally, in addition to removing the CLI. For more information about uninstalling SentryOne, see the Uninstalling SentryOne article.

Upgrade

Upgrade

Warning: There are two different upgrade paths. One path is used if your installation was performed using EPI, and the other is for an installation that did not use EPI. If you used EPI for the installation or previous upgrade, follow the first set of instructions for Existing EPI Upgrade. If your installation or previous upgrade did not use EPI, following the second set of instructions for First EPI Upgrade.

Option 1. Existing EPI Upgrade

Use this option if EPI was used for the initial installation or previous upgrade.

1. Run Command Prompt as Administrator and change the directory to SentryOne Framework:

cd c:\Program Files\SentryOne Framework 

2. Verify that you have the correct connection to the SentryOne database:

so listreg

3. Push the .s1package to the SentryOne database:

so push -n <connectionName> -f <packagePath>

Note:  You can omit the -f option if you installed the SentryOne Frameworks installer with the version you want to upgrade to

4. Validate available packages:  

so listpackage -n <connectionName>

5. Start the upgrade: 

so upgrade -n <connectionName> -t <packageVersion>

6. Wait for the upgrade to complete.

Note:  The upgrade command so upgrade is a global command that informs all controller services that a new desired state has been marked with a version increase to version <packageVersion>. Once this new state is detected, any monitoring service connected to the affected SentryOne database will be stopped, upgraded, and 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. There is no status indicator. 

7. Launch the SentryOne client. You will see a loading dialog as files are downloaded from the SentryOne database for the latest version of the client. It may take a few minutes for the files to download.

Note:  To verify the status of the upgrade without launching the client, validate the package:

so listpackage -n <connectionName>

Success: The SentryOne installation has been upgraded and is now ready for use.

Option 2. First EPI Upgrade

Use this option if EPI was not used for the initial installation or previous upgrade. The .NET Framework 4.7.2 is installed during this process, which may force a reboot.

1. Uninstall all current SentryOne monitoring services using Add/Remove Programs in Windows.

Note:  The EPI installer will uninstall the existing product when you execute it.

2. Ensure all SentryOne clients are closed (disconnected from the SentryOne database).

3. Double-click SentryOneSetup.exe

Note:  The files are unpacked to C:\Program Files\SentryOne Framework.  

4. Run Command Prompt as Administrator and change directory to SentryOne Framework: 

cd c:\Program Files\SentryOne Framework 

5. Add a new connection:

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>

6. Verify available connections are registered:

so listreg

7. Upgrade the SentryOne database to the latest version and push upgrade package:

Important:  If you are on version 18.3+ (in which case the SentryOne database already contains the setup schema), you must first push the package before running the so upgrade. To do so, run so push -n <connectionName> before proceeding with the step below.

so upgradedb -n <connectionName>

8. Install the SentryOne monitoring service (you will be prompted for the serviceAccount password): 

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

Note:  The SentryOne monitoring service is now installed and running. 

9. Launch the SentryOne client. You will see a loading dialog as files are downloaded from the SentryOne database for the latest version of the client. It may take a few minutes for the files to download. 

Note:  To verify the status of the upgrade without launching the client, validate the package:

so listpackage -n <connectionName>

Success: The SentryOne installation has been upgraded and is now ready for use. The next time you need to upgrade, use Option 1 for an Existing EPI Upgrade.

Available Commands

Command Line Interface Available Commands

CommandDescription
listpackageLists all packages in the SentryOne database.
pushPushes an upgrade package into the SentryOne database.
addregAdds a connection registration.
removeregRemoves a connection registration.
removeallregRemoves all connection registrations.
updateregUpdates a connection registration.
listregLists existing connection registrations.
installInstalls the SentryOne controller software.

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 in other environments.
uninstallUninstalls the SentryOne controller software.

Note:  The so uninstall -n <connectionName> command stops the SentryOne controller and monitoring service that are connected to <connectionName> and uninstalls them from the local environment.
startStarts the SentryOne controller.
stopStops the SentryOne controller.

Note:  If you want to stop the monitoring service, you must first use the stop command to stop the SentryOne controller service, otherwise it will attempt to restart the monitoring service after a manual stop.
uninstallmsUninstalls a SentryOne monitoring service.
startmsStarts a SentryOne monitoring service.
stopmsStops a SentryOne monitoring service.
createdbCreates a SentryOne database.
upgradedbUpgrades a SentryOne database.
upgradeMarks a SentryOne version to upgrade to.

Note:  so upgrade is a global command that informs all controller services that a new desired state has been marked with a version increase to version X. Once this new state is detected, any monitoring service connected to the affected SentryOne database will be stopped, upgraded, and 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.
helpDisplays more information on a specific command.
versionDisplays version information.
Advanced

Advanced

PowerShell

PowerShell may be used with EPI. The SentryOne 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.

Important:  PowerShell ISE is not recommended as it may cause issues. For example, use of PowerShell ISE will lead to problems with the so install command when used without the password (as you are instructed on the Install tab).

Telemetry

By default, telemetry is disabled after completing an initial installation using EPI. If you would like to enable it or learn more about telemetry in SentryOne, see the Telemetry article.

Troubleshooting

Problem: The upgrade process is being blocked.

If this is for the first option, where EPI already exists, it's possible that SentryOne components were installed before using the EPI. For example, there may be clients connected to the SentryOne database that were installed pre-EPI. In this scenario, there are no bootstrappers running to manage those client processes, which means that the so upgrade command cannot control those pre-EPI clients. The pre-EPI clients will continue sending a heartbeat to the SentryOne, and the upgrade will be blocked until the clients are shut down.

Viewing Log Files

If you need to view any of the log files, they are located as follows:

Service

C:\ProgramData\SentryOne\monitoringservice\bin\rolling-log.txt

Service Bootstrapper

C:\ProgramData\SentryOne\servicebootstrapper\logs\rolling-log.txt

Client Bootstrapper

C:\Users\username\AppData\Local\sentryone\clientbootstrapper-log.txt

Client

C:\Users\username\AppData\Local\SentryOne\console-log-file.txt