orchestrator

2021.10

false

OUT OF SUPPORT

Orchestrator Installation Guide

DELIVERY:

Automation Cloud Automation Cloud Public Sector Automation Suite Standalone

Last updated Oct 31, 2024

Platform Configuration Tool

Important: The Platform Configuration Tool works for upgrades from a version released in the past three years relative to the current major version. Post-installation checks and operations work after installing Orchestrator.

Overview

The UiPath Platform Configuration Tool is a PowerShell script used to assist you in the successful installation/upgrade of Orchestrator. It helps you check the sanity and readiness of your environment before an upgrade, and assists you in performing several operations post-installation.

The tool is available for download below and is also bundled with the UiPathOrchestrator.msi installer. The bundled script can be found in the Tools folder of the Orchestrator installation directory, C:\Program Files (x86)\UiPath\Orchestrator\ by default. The script checks the Orchestrator machine. In the case of a multi-node installation, it is enough to run the tool on one node.

The Platform Configuration Tool does not follow the same versioning scheme as the UiPathOrchestrator.msi installer and can be updated outside of the product release cycle. We recommend that you always download and use the latest version of the tool which is available below.

Download the tool

Prerequisites

Software	Compatible Version
PowerShell	5.1
WebAdministration Module	N/A

Script Cmdlets

The script consists of three cmdlets intended to perform specific functions. A cmdlet-invoking command and its relevant parameters can be entered in the command line for immediate execution.

Cmdlet	Description
`Test-PlatformReadiness`	Invoked using the `-Readiness` command. Checks the sanity and readiness of your environment before an upgrade and the certificate requirements after the installation.
`Update-UiPathUrl`	Invoked using the `UpdateUiPathUrl` command. Updates the public address of Orchestrator.
`Update-UiPathCertificate`	Invoked using the `UpdateUiPathCertificate` command. Updates the Orchestrator SSL certificate or the Identity Server token-signing certificate.
`AddHostAdmin`	Invoked using the `AddHostAdmin` command. Adds a system administrator to the host tenant.

Pre-Installation Checks

Asp.Net Core

Checks if ASP.NET Core IIS module v3.1.x+ is installed and functional. If it's not, you are prompted to uninstall and reinstall the ASP.Net Core Hosting Bundle.

CyberArk AIM

Checks if the CyberArk AIM agent is installed under the C:\Program Files (x86)\CyberArk folder. If it's not, the user is prompted to add CLIPasswordSdk.exe in the UiPath.Orchestrator.dll.config file using Plugins.SecureStores.CyberArk.CLIPasswordSDKExePath key after the installation.

This check is not performed if CyberArk is not found in UiPath.Orchestrator.dll.config.

Web.config Encryption

Checks if the web.config file is decrypted. If encrypted, you need to manually decrypt it before upgrading. After the upgrade, most of Orchestrator's configuration settings are moved to UiPath.Orchestrator.dll.config.

Learn how to encrypt the UiPath.Orchestrator.dll.config file.

Web.config Locked Sections

Checks if the <system.webServer> element contains any locked sections. If such sections exist, you need to manually unlock them in IIS.

SQL Server Scaleout

Checks if SQL Server Scaleout is used. You are informed that during the installation Redis Scaleout is enabled.

Credential Store Plugins

Checks that external credential store plugins target a supported framework.

NLog Plugins

Checks that NLog plugins target a supported framework.

FileSystem Buckets

This check validates that the Buckets.FileSystem.Allowlist app setting is present in Orchestrator versions starting with v2020.4. This covers both pre-installation checks (Orchestrator v2022.4) and post-installation checks (Orchestrator v2022.4). Orchestrator versions prior to v2020.4 skip this check.

To perform the following checks, you need to decrypt the connectionStrings and appSettings config sections. If any of these configuration sections is encrypted, then a warning prompts you in the terminal, and the rest of the buckets validations are skipped.
```
Could not determine if any buckets with file system provider are in use. Config section 'connectionString' is encrypted, could not find the sql connection string to the UiPath database.Could not determine if any buckets with file system provider are in use. Config section 'connectionString' is encrypted, could not find the sql connection string to the UiPath database.
```

If, for any reason, the buckets could not be retrieved from the database, a warning prompts you in the terminal, and the rest of the validations are skipped as well.

Could not determine if any buckets with file system provider are in use. Could not connect to the UiPath Database.Could not determine if any buckets with file system provider are in use. Could not connect to the UiPath Database.

This validation is performed on the retrieved buckets root paths from the Orchestrator database buckets table. If there are any unqualified paths, then a warning prompts you in the terminal. A similar check for the unqualified paths is done for the paths in the Buckets.FileSystem.Allowlist app setting in the config file.
If any of the paths in the two sources is not valid or is unqualified, then it is not be taken into considerations for the rest of the validations described below.

If the Buckets.FileSystem.Allowlist app setting is not set in the config file, then the terminal prompts you with an error asking you to add the allowlist to the config file. The suggested paths are the root path of the buckets that use the file system provider.

All storage buckets using the file system provider are not on the allowed list. Add the following setting in the configuration file to allow all exiting buckets root paths: <add key="Buckets.FileSystem.Allowlist" value="C:\work\stuff\Bucket\|C:\work\stuff\Bucket1\" />All storage buckets using the file system provider are not on the allowed list. Add the following setting in the configuration file to allow all exiting buckets root paths: <add key="Buckets.FileSystem.Allowlist" value="C:\work\stuff\Bucket\|C:\work\stuff\Bucket1\" />

If the Buckets.FileSystem.Allowlist app setting is set in the config file, then a validation is performed on the buckets root path that use the FileSystem provider. If a bucket root path is not a subpath of any of the paths defined in the allowlist, then a warning prompts you in the terminal asking you to add the bucket root path to Buckets.FileSystem.Allowlist .

There are some storage buckets using the file system provider that are not on the allowed list. The buckets feature will not work for buckets with root paths that are not on the allowed list. Check if any of the following paths are required to be on the allowed list and add them to the 'Buckets.FileSystem.Allowlist' key in configuration file: |C:\work\stuff\Buckets\|C:\work\stuff\Bucket1\There are some storage buckets using the file system provider that are not on the allowed list. The buckets feature will not work for buckets with root paths that are not on the allowed list. Check if any of the following paths are required to be on the allowed list and add them to the 'Buckets.FileSystem.Allowlist' key in configuration file: |C:\work\stuff\Buckets\|C:\work\stuff\Bucket1\

Otherwise, if every bucket root path is a subpath of any path in the allowed list, then the terminal displays a success message.

All storage buckets using file system provider have the root path on the allow list in the configuration file.All storage buckets using file system provider have the root path on the allow list in the configuration file.

Post-Installation Checks

Certificate Requirements

Checks that all certificate requirements are met by your Orchestrator instance after an upgrade.

SSL Certificate Checks

the hostname of the Orchestrator site matches the Subject or a Subject Alternate Name (including wildcards) on the certificate,
has a valid trust chain, and
is not expired.

Identity Server Token-Signing Certificate Checks

The certificate has the appropriate key size (2048 bits or larger),
has a private key accessible by the AppPool user, and
is not expired.

Other Considerations

Check the docs on installation considerations for other areas impacted by an upgrade to v2022.4 that you need to be aware of.

Running the Script

Command Reference

Command & Parameters	Description
`-Readiness`	Checks the sanity and readiness of your environment before an upgrade and the certificate requirements after the installation. Parameters: `-SiteName` `-Help` `-InstallationDirectory`
`-UpdateUiPathUrl`	Updates the public address of Orchestrator. Parameters: `-SiteName` `-OrchestratorUrl` `-SqlConnectionString` Important: The SQL Server PowerShell module is required to use this command. The module is installed by default with SQL Server. If you’re working on a machine that doesn’t have the module installed, see here how to install it. Important: Use this command with caution as it does not have a roll-back mechanism if a step errors out during execution.
`-UpdateUiPathCertificate`	Updates the Orchestrator SSL certificate or the Identity Server token-signing certificate. Use it in conjunction with the `-readiness` command to check the validity of the new certificates. Parameters: `-SiteName` `-NewTokenSigningThumbprint` `-NewSSLThumbprint`
`-AddHostAdmin`	If access to the host organization is lost (for example, if the password for the system administrator is lost or the only users with system administrator accounts leave the company), you can use this command to add or restore a system administrator. Parameters: `-SiteName` `-HostAdminUsername` `-HostAdminPassword` `-HostAdminEmail`

Script Parameters

Parameter	Description
`-SiteName`	Optional. The name of the Orchestrator website on the target machine. Defaults to `"UiPath Orchestrator"`. `-InstallationDirectory` and `SiteName` are mutually exclusive.
`-Help`	Optional. Displays information about the tool options or available commands, such as the commands' syntax or the checks it performs.
`-InstallationDirectory`	Optional. The path of Orchestrator's installation directory. Usually `C:\Program Files (x86)\UiPath\Orchestrator\`. `-InstallationDirectory` and `SiteName` are mutually exclusive. Note: Make sure the installation directory path ends with a trailing backslash (`\`).
`-OrchestratorUrl`	Mandatory. The new public address of Orchestrator.
`-SqlConnectionString`	Optional. UiPath database connection string. If left empty, the value is read from the `appsettings.Production.json` file.
`-NewTokenSigningThumbprint`	Optional. The thumbprint of the new token signing certificate used by the Orchestrator Identity Server.
`-NewSSLThumbprint`	Optional.The thumbprint of the new SSL certificate used by the Orchestrator Web App.
`-HostAdminUsername`	Only mandatory when using the `-AddHostAdmin` command. Username of the host admin user to create or restore.
`-HostAdminPassword`	Email of the host admin user to create or restore when using the `-AddHostAdmin` command. Only mandatory if using these external identity providers: Google Azure Active Directory SAML with email user mapping strategy
`-HostAdminEmail`	Password of the host admin user to create when using the `-AddHostAdmin` command. Password is only mandatory if the user is a basic authentication user. The password will need to be changed on first login.

Examples

To work with the Platform Configuration Tool script, open an Administrator PowerShell script.

Locate the directory where you unzipped the Platform Configuration Tool archive and change the directory to that location:

cd "C:\Program Files (x86)\UiPath\Orchestrator\Tools\PlatformConfiguration"cd "C:\Program Files (x86)\UiPath\Orchestrator\Tools\PlatformConfiguration"

Performing a Readiness Check

The following example enables you to perform a validation of the pre-installation requirements of Orchestrator. The procedure logs its steps and output extra information at the -verbose level.

.\Platform.Configuration.Tool.ps1 ` 
-Readiness ` 
-SiteName "UiPath Orchestrator".\Platform.Configuration.Tool.ps1 ` 
-Readiness ` 
-SiteName "UiPath Orchestrator"

Pre-Installation checks successful output.

Validating 22.4 pre-installation requirements... Checking AspNetCore hosting module... AspNetCore hosting module is installed. Checking CyberArk CLIPasswordSDK.exe path... CyberArk CLIPasswordSDK.exe was found at the default installation path 'C:\Program Files (x86)\CyberArk\ApplicationPasswordSdk\CLIPasswordSDK.exe'. Checking Web.config sections encryption... Web.config sections are not encrypted. Checking IIS configuration locked sections... Configuration sections are not locked. Checking Orchestrator ssl certificate subject alternative names... Orchestrator host name is valid for the ssl certificate subject alternative names. Checking sql server scaleout use... Sql server scaleout is not used. Checking external credential store plugins target framework... Credential stores plugins validation is finished. Checking external NLog plugins target framework... NLog plugins validation is finished. Checking buckets with file system storage provider... All storage buckets using file system provider have the root path on the allowed list in the configuration file. Checking platform certificates... Platform certificates validation is finished. All 22.4 pre-installation checks are done. Platform readiness validations: 10 succeeded, 0 failed and 0 warning(s).Validating 22.4 pre-installation requirements... Checking AspNetCore hosting module... AspNetCore hosting module is installed. Checking CyberArk CLIPasswordSDK.exe path... CyberArk CLIPasswordSDK.exe was found at the default installation path 'C:\Program Files (x86)\CyberArk\ApplicationPasswordSdk\CLIPasswordSDK.exe'. Checking Web.config sections encryption... Web.config sections are not encrypted. Checking IIS configuration locked sections... Configuration sections are not locked. Checking Orchestrator ssl certificate subject alternative names... Orchestrator host name is valid for the ssl certificate subject alternative names. Checking sql server scaleout use... Sql server scaleout is not used. Checking external credential store plugins target framework... Credential stores plugins validation is finished. Checking external NLog plugins target framework... NLog plugins validation is finished. Checking buckets with file system storage provider... All storage buckets using file system provider have the root path on the allowed list in the configuration file. Checking platform certificates... Platform certificates validation is finished. All 22.4 pre-installation checks are done. Platform readiness validations: 10 succeeded, 0 failed and 0 warning(s).

Changing Certificates After Installation

The following example enables you to update the Orchestrator SSL and the Identity Server token-signing certificates.

.\Platform.Configuration.Tool.ps1 ` 
-UpdateUiPathCertificate ` 
-SiteName "UiPath Orchestrator" ` 
-NewSSLThumbprint "a1b2c3d4" ` 
-NewTokenSigningThumbprint "z6y5x4v3".\Platform.Configuration.Tool.ps1 ` 
-UpdateUiPathCertificate ` 
-SiteName "UiPath Orchestrator" ` 
-NewSSLThumbprint "a1b2c3d4" ` 
-NewTokenSigningThumbprint "z6y5x4v3"

Note:

Any appsettings files should be decrypted prior to using the script.
If you have multiple Orchestrator nodes, please make sure to update the certificate on all server nodes.
Make sure the certificates have the appropriate permissions set to prevent an internal server error. Refer to Troubleshooting Certificates for more details.

Changing Orchestrator URL

The following example enables you to update the Orchestrator URL.

.\Platform.Configuration.Tool.ps1 `
  -UpdateUiPathUrl `
  -OrchestratorUrl "https://mydomainname" `
  -SiteName "UiPath Orchestrator" `
  -SqlConnectionString "Server=myServerName\myInstanceName;Database=myDataBase;User Id=myUsername;Password=myPassword;".\Platform.Configuration.Tool.ps1 `
  -UpdateUiPathUrl `
  -OrchestratorUrl "https://mydomainname" `
  -SiteName "UiPath Orchestrator" `
  -SqlConnectionString "Server=myServerName\myInstanceName;Database=myDataBase;User Id=myUsername;Password=myPassword;"

Creating a New System Administrator

The following example creates a new system administrator on the host tenant using basic authentication. Note that if an external identity provider is set as exclusive, basic authentication is only accessible through the hostlogin URL.

.\Platform.Configuration.Tool.ps1 <code> `
  -AddHostAdmin </code> `
  -SiteName "UiPath Orchestrator" <code> `
  -HostAdminUsername someuser </code> `
  -HostAdminPassword som3pwd! `
  -HostAdminEmail testemail@company.com.\Platform.Configuration.Tool.ps1 <code> `
  -AddHostAdmin </code> `
  -SiteName "UiPath Orchestrator" <code> `
  -HostAdminUsername someuser </code> `
  -HostAdminPassword som3pwd! `
  -HostAdminEmail testemail@company.com

Output

The output is color-coded.

Color	Description
Red	Blockers Elements are missing or are not configured and will prevent the installation.
Yellow	Warnings You can install Orchestrator, but additional benefits will be absent.
Green	Messages The environment is ready for installation.

Was this page helpful?

PREVIOUSAWS Deployment

NEXTUiPath.Orchestrator.dll.config

Support and Services

Get The Help You Need

UiPath Academy

Learning RPA - Automation Courses

UiPath Forum

UiPath Community Forum

Trust and Security

Cookies Policy