SentryOne Enhanced Platform Installer

Introduction

EPI increases the speed and simplicity of installing and upgrading SentryOne 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 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.

Example of SentryOne Installer Command Line Interface

Getting Started

Version Availability & Components

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 SentryOne controller service (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 in the Install section. If you would like to upgrade an existing SentryOne installation to use EPI, follow the Option 2. First EPI Upgrade steps in the Upgrade section.

Note: 

  • To use the original installation method, see the SentryOne Installation article. This original installation option is recommended for smaller environments (i.e. estates with a single monitoring service or client) and those who do not need a command line experience for streamlining the installation or upgrade processes.
  • EPI is not available for SentryOne Monitor (a web-based version of SentryOne).

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

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 SentryOne 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.
Example of where the parameters are used in the connection window
 
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 Table of Commands & Examples.
<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 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 SentryOne database is part of an availability group, it is recommended to use the availability group listener name instead o the SQL Server name.
<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 SentryOne as the value.
<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 --IAcceptLicenseTerms -n <connectionName> -u <serviceAccount>
Service Account Information screen

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>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.
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 --IAcceptLicenseTerms -n <connectionName> -u <serviceAccount> -p <servicePassword>
Note:  The -p flag is only recommended for use when scripting out commands.

Important:  See the Password section in the Available Commands section of this article for information on using non-alphanumeric (i.e. special) characters such as (~!@#$%^&*_-+=`|\(){}[]:;"'<>,.?/) 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>The SentryOne version to which you are upgrading (i.e. 19.2.2).
<packagePath>The file path where the SentryOne upgrade package is located.

Install via EPI

Requirements

Before installing SentryOne, review the following articles:

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

Important:  See the Password section of this article for information on using non-alphanumeric (i.e. special) characters such as (~!@#$%^&*_-+=`|\(){}[]:;"'<>,.?/) 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.

Install SentryOne

Go to my.sentryone.com to download the Enhanced Platform Installer version of SentryOne. This is the SentryOneSetup.exe file referenced in the instructions below.

Download SentryOneSetup.exe from my.sentryone.com before startingExample: Download the Enhanced Platform Installer product from my.sentryone.com to get SentryOneSetup.exe

1. On the machine that will serve as the monitoring service, double-click SentryOneSetup.exe.

Note:  The files are unpacked to C:\Program Files\SentryOne Framework by default and that directory is used in the examples below. If needed, change the Destination Folder during SentryOne Setup and use that directory to run commands.

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

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

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

Versions prior to 2020.8 use the following:

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

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

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

Important:  The EPI installation adds a SentryOne Client shortcut to the desktop, but does not install the client. Running the executable file that the shortcut points to opens the Client installer and then installs the Client on the machine. You can remove the SentryOne Client shortcut if you don't want to install the client. 

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 below to install the SentryOne Portal or to the Onboarding article for additional assistance.

Install SentryOne Portal

Review the System Requirements and Portal Configuration articles before installing SentryOne Portal.

After you have ensured that your machine meets the prerequisite requirements, you can begin installing SentryOne Portal. Install SentryOne Portal on your machine with EPI by completing the following steps:

1. You must have installed or upgraded SentryOne to version 20 or greater using EPI before proceeding.

2. SentryOne Portal requires the SentryOne controller service on the machine where it is installed. If the machine where you are installing SentryOne Portal needs the controller service, follow the Install Additional Monitoring Services instructions below.

Note:  If you are installing SentryOne Portal on a machine where you have installed a monitoring service, then it already has the required controller service, however, the recommended setup is a dedicated machine that does not have the full monitoring service.

3. Run the following command to complete SentryOne Portal installation:

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> -b ipAddress:port

Versions prior to 2020.8 use the following:

Note:  This example shows Windows Authentication being used, which will work prior to version 2020.8, but not in 2020.8. Support for Windows Authentication will be re-added in a later release. You can use SQL Server Authentication in any version by adding the parameters as shown above.

so installmp -n <connectionName> -s <portalServerFQDN> -u <serviceAccount> -b <ipAddress:port>

Note: 

  • The user <SQLServerUserName> must be a SQL Server account as installmp requires SQL Server Authentication for the SentryOne Portal service.
  • The --server (-s) switch is for the server that will host SentryOne 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 Available Commands section for additional information on using list.
so list -t services -n <connectionName> 
  • The switch -b <ipAddress:port> is optional, and can be omitted if you're using the default value of 0.0.0.0:9991.
  • See the Parameters & Examples section for more information on the <parameters> used such as <serverName> and <databaseName>. These are referring to the SentryOne database and the SQL Server that hosts it.

Success: SentryOne Portal is installed and ready to use. Continue to the Getting Started with SentryOne Portal 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). The first option is for the full monitoring service (typical installation), while the second option is for configuring a machine for SentryOne 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 -n <connectionName> -u <serviceAccount> 

Versions prior to 2020.8 use the following:

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

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

2. SentryOne Portal / controller service only install option:

Note:  If you are completing this step for a machine to install the SentryOne Portal, then the entire monitoring service is not needed. You should run the install with the following parameter to install only the necessary components (i.e. the SentryOne controller service) and not the monitoring service by using the --installmonitoringservice flag and parameter 0:

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

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

Versions prior to 2020.8 use the following:

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

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

Additional Information: Interested in installing the SentryOne monitoring service on a Windows Server Core machine? See this blog post for a demonstration.

Install Additional Clients

When using EPI, the SentryOne client security requirements remain the same. See the Client Security article for details.

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.

Upgrade via EPI

SentryOne Client Impacts

How does using EPI 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 EPI 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

Things to Know Before Upgrading

Important: 

  • Back up the SentryOne database before performing an upgrade.
  • A major version upgrade requires a license upgrade. See the Product Version Mismatch section of the License Management article for more information.
  • Review the System Requirements before upgrading. The latest version may require a newer version of Microsoft .NET, which could require restarts during the upgrade process.
  • All SentryOne components, including the SentryOne database, monitoring service(s), and client(s) must be on the same build to work.
  • See the Password section of this article for information on using non-alphanumeric characters such as (~!@#$%^&*_-+=`|\(){}[]:;"'<>,.?/) 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: 

  • 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.
  • If you are unsure about which version of SentryOne you have installed (EPI or non-EPI), you can determine this from the presence of: 
    • The SentryOne controller service, which only exists in the EPI version. 
      • See the list command in the Available Commands section to get a list of monitoring services that are running without the controller. 
    • The Setup.Bootstrapper table in the SentryOne database, which only exists in the EPI version. 
    • If you need additional help determining which version you have installed, please contact our support team at support.sentryone.com.

Files referenced in upgrade instructions

There are two files available from my.sentryone.com: The full installation (Enhanced Platform Installer / SentryOneSetup.exe) and the upgrade package (Enhanced Platform Upgrade Package / current.s1package).

Note:  Depending on your environment, the current.s1package may download as current.zip. You will need to change the file type to .s1package.

Download SentryOneSetup.exe from my.sentryone.com before startingExample: Download the Enhanced Platform Installer product from my.sentryone.com to get SentryOneSetup.exe

Download the current.s1package from my.sentryone.comExample: Download the Enhanced Platform Upgrade Package from my.sentryone.com to get current.s1package

Upgrade Paths

Warning:  

  • There are three different upgrade paths.
    • If you used EPI for the installation or previous upgrade, follow the first set of instructions under Option 1. Existing EPI Upgrade. Note that going from a pre v20 release to a v20.0+ release has some additional prerequisite steps (i.e. v19.2 to v20.0 or v20.0.1) that must be completed for Option 1.
    • If your installation or previous upgrade did not use EPI, follow the second set of instructions under Option 2. First EPI Upgrade.
    • If you used EPI for the installation or previous upgrade, and are now upgrading to Version 20.0, there is an alternate path available under Option 3. Version 20.0 Existing EPI Alternative which allows you to upgrade from a pre v20 release to a v20+ release without having to uninstall/install the controller service on all machines with a monitoring service at the time of the upgrade. This is not the typical or recommended path.

Option 1. Existing EPI to EPI upgrade

Warning:  For Version 20.0, customers currently on an EPI build of SentryOne must follow these steps before continuing to the steps listed in Option 1. Existing EPI Upgrade.

These steps are needed to go from any pre v20 release to a v20+ release (i.e. 19.2 to 20.0 or 20.0.1). If you are upgrading from a v20+ EPI release to another v20+ EPI release, skip the perquisite steps and continue to Option 1. Existing EPI Upgrade below.

Before starting, log in to my.sentryone.com and download the new EPI version of SentryOne.

Option 1. Prerequisite Steps for an Existing EPI Upgrade (pre v20 to v20+)

On each server with an existing SentryOne monitoring service, complete the following steps:

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

cd c:\Program Files\SentryOne Framework

2. Uninstall the SentryOne Monitoring service.

so uninstall -n <connectionName>

3. Open the Control Panel > Programs > Programs and Features. Select SentryOne, then select Uninstall.

4. Double-click SentryOneSetup.exe. The files are unpacked to C:\Program Files\SentryOne Framework.

5. Install the SentryOne 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 -n <connectionName> -u <serviceAccount> 

Versions prior to 2020.8 use the following:

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

Success: You can now proceed to Option 1. Existing EPI Upgrade to complete your SentryOne EPI Version 20.0 installation.

Option 1. Existing EPI Upgrade

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

Note:  For version 20.0 follow the prerequisite steps listed above before continuing. These steps are needed to go from any pre v20 release to a v20+ release (i.e. 19.2 to 20.0 or 20.0.1).

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.

Note:  If you do not enter a <packagePath>, then the default path and package will be used: C:\Program Files\SentryOne Framework\current.s1package

4. Validate available packages:  

so listpackage -n <connectionName>

5. Start the upgrade. Note:  See more about using the upgrade command in the Table of Commands & Examples.

If your currently installed version is below 2020.8 use the following:

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

If your currently installed version is 2020.8 or later, then the --IAcceptLicenseTerms is needed:

so upgrade --IAcceptLicenseTerms -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. 

Important:  The EPI installation adds a SentryOne Client shortcut to the desktop, but does not install the client. Running the executable file that the shortcut points to opens the Client installer and then installs the Client on the machine. You can remove the SentryOne Client shortcut if you don't want to install the client. 

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.

Note:  If you are using SentryOne Portal, see the upgrading section of this article to complete the upgrade steps for that service.

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.

Important:  For Version 20.0, you must perform the monitoring service uninstall before proceeding.

2. Ensure all SentryOne clients are closed (disconnected from the SentryOne database). For Version 20.0, it is required that you uninstall the SentryOne clients from the machines in your SentryOne environment before proceeding.

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.Push the upgrade package:

so push -n <connectionName>

Important:  If you are on a version older than 18.3, skip this step, and proceed straight to step 8 to continue.

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

so upgradedb -n <connectionName>

9. Install the SentryOne 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 -n <connectionName> -u <serviceAccount>

Versions prior to 2020.8 use the following:

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

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

Important:  The EPI installation adds a SentryOne Client shortcut to the desktop, but does not install the client. Running the executable file that the shortcut points to opens the Client installer and then installs the Client on the machine. You can remove the SentryOne Client shortcut if you don't want to install the client. 

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>

Note:  See the Install Additional Clients and Install Additional Monitoring Services sections of this article for instructions on installing the EPI compatible versions of the SentryOne client and monitoring service onto additional machines as needed.

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.

Option 3. An alternative option (non-typical path)

Option 3 allows you to upgrade from a pre v20 release to a v20+ release without having to uninstall/install the controller service on all machines with a monitoring service at the time of the upgrade. This is not the typical or recommended path. This options allows you to upgrade SentryOne controller services on your own schedule, if needed. It is not required to upgrade the controllers at the same time.

Warning:  Option 1 is the recommended upgrade path. The upgrade option below does not upgrade the controller services and future compatibility is not guaranteed with this alternative option.

Important:  The upgraded controller services are needed to install and use SentryOne Portal. This option does not meet those requirements.

For this option, you'll need to upgrade the SentryOne framework on one machine. The instructions vary depending on which (if any) SentryOne components are installed on the machine where you are running the EPI upgrade. Read below to determine if you should use Option A or Option B.

Option A: Machine without services

On a machine that does not have the SentryOne monitoring or controller services, follow these steps:

1. If there's an existing installation of the SentryOne framework, open the Control Panel > Programs > Programs and Features. Select SentryOne, then select Uninstall to remove it before continuing.

2. Install the v20.0 SentryOne Framework. Double-click SentryOneSetup.exe. The files are unpacked to C:\Program Files\SentryOne Framework.

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

cd c:\Program Files\SentryOne Framework 

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

so listreg

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

Note:  If you do not enter a <packagePath>, then the default path and package will be used: C:\Program Files\SentryOne Framework\current.s1package

6. Validate available packages:  

so listpackage -n <connectionName>

7. Start the upgrade. Note:  See more about using the upgrade command in the Table of Commands & Examples.

If your currently installed version is below 2020.8 use the following:

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

If your currently installed version is 2020.8 or later, then the --IAcceptLicenseTerms is needed:

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

8. Wait for the upgrade to complete before starting the SentryOne client.

Note:  If you are using SentryOne Portal, see the upgrading section of the SentryOne Portal Configuration article to complete the upgrade steps for that service.

Option B: Machine with services

On a machine that has the SentryOne monitoring or controller services, follow these steps:

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. Uninstall the service:

so uninstall -n <connectionName>

4. Uninstall the existing installation of the SentryOne framework by opening the Control Panel > Programs > Programs and Features. Select SentryOne, then select Uninstall to remove it before continuing.

5. Install the v20.0 SentryOne Framework. Double-click SentryOneSetup.exe. The files are unpacked to C:\Program Files\SentryOne Framework.

6. Install the SentryOne monitoring service (you'll be prompted for the password):

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

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

Versions prior to 2020.8 use the following:

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

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

Note:  If you do not enter a <packagePath>, then the default path and package will be used: C:\Program Files\SentryOne Framework\current.s1package

8. Validate available packages:  

so listpackage -n <connectionName>

9. Start the upgrade. Note:  See more about using the upgrade command in the Table of Commands & Examples.

If your currently installed version is below 2020.8 use the following:

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

If your currently installed version is 2020.8 or later, then the --IAcceptLicenseTerms is needed:

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

10. Wait for the upgrade to complete before starting the SentryOne client.

Note:  If you are using SentryOne Portal, see the upgrading section of the SentryOne Portal Configuration article to complete the upgrade steps for that service.

Upgrade SentryOne Portal

If you installed SentryOne Portal using EPI, you can upgrade via EPI by following the steps below. The upgrade process involves uninstalling, then reinstalling SentryOne Portal. You must upgrade the SentryOne version first via EPI, before you can upgrade the SentryOne Portal version.

Note:  The default SentryOne Framework directory is used in the instructions. If you used a non-default location, use that path instead.

  1. Open Command Prompt (use the Run as administrator option)
  2. Change to the SentryOne Framework directory
    cd C:\Program Files\SentryOne Framework
  3. Stop the SentryOne Portal service
    so stopmp -n <connectionName> -s <portalServerFQDN>
  4. Uninstall the SentryOne Portal
    so uninstallmp -n <connectionName> -s <portalServerFQDN>
  5. Install the SentryOne Portal (see the note in the Installation section for information about using the optional port number)

    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> -b ipAddress:port

    Versions prior to 2020.8 use the following:

    so installmp --connectionUseIntegrated false --server <portalServerFQDN> --connectionServer <serverName> --connectionDatabase <databaseName> --connectionUsername <SQLServerUserName> --connectionPassword <SQLServerUserPassword> -b ipAddress:port
  6. Start the SentryOne Portal service
    so startmp -n <connectionName> -s <portalServerFQDN>

Uninstall via EPI

Uninstall

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

  1. Open Command Prompt (use the Run as administrator option)
  2. Change to the SentryOne Framework directory (or custom directory used during installation)
    cd C:\Program Files\SentryOne Framework
  3. Stop the SentryOne Portal service
    so stopmp -n <connectionName> -s <portalServerFQDN>
  4. Uninstall the SentryOne Portal
    so uninstallmp -n <connectionName> -s <portalServerFQDN>

Downgrade (non-typical process)

In the event that a downgrade or rollback is required, the process will differ depending on whether the database schema changed between versions.

Verify the schema

Use the listpackage command to view the details of the old and new package:

so listpackage -n <connectionName>

Same Schema Version

If the schema version is the same between the old and new packages, then you can downgrade to the older version using the upgrade command and the older package:

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

There is no need to run any uninstall commands in this scenario.

Note:  See more about using the upgrade command in the Table of Commands & Examples.

Different Schema Version

If the schema version is different between the old and new packages, then you should:

  1. Restore the SentryOne database from backup
  2. Uninstall the current version using so uninstall (see the Uninstall section in this article for details) or through the control panel
  3. Reinstall the previous monitoring service and controller version using the so install command

Available Commands

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
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 (~!@#$%^&*_-+=`|\(){}[]:;"'<>,.?/) 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> -b ipAddress:port
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>.

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

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>
Important:  This is used to update the password only, not the service user account. You cannot change the user account with EPI at this time.
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.

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:

Important:  Using non-alphanumeric (i.e. special) characters such as (~!@#$%^&*_-+=`|\(){}[]:;"'<>,.?/) with the -p flag requires specific formatting around those characters.

If the password is p@ss"w0rd then it must be formatted as one of the following:

1. The entire password inside single quotes ( ' ) with the backslash ( \ ) escape character:

'p@ss\"w0rd'

or

2. With single quotes ( ' ) around the backslash ( \ ) escape character and non-alphanumeric character:

p@ss'\"'w0rd

Note:  If the password contains a single quote ( ' ) as the non-alphanumeric character, then it must be surrounded by double quotes ( " ), but not escaped. For example p@ss'w0rd would be formatted as:

p@ss"'"w0rd  

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

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

Timeout

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

Advanced

Topics

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. See the SentryOne PowerShell Module article for information on importing the SentryOne module to use with EPI.

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 in the Install section).

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.

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:

The Timeout was set to 1 second, process took longer than 1 second, Result = Timeout displayed, but process did complete and SentryOne Portal installed.

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.

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>\Documents\sentryone\client\<computername>\<sentryonedatabase>\bin\console-log-file.txt