- Getting Started
- Requirements
- Best Practices
- Installation
- Updating
- Identity Server
- Troubleshooting startup errors
Platform Configuration Tool
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.
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.
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.
|
Software |
Compatible Version |
|---|---|
|
PowerShell |
5.1 |
|
WebAdministration Module |
N/A |
|
pki Module |
N/A |
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 |
|---|---|
|
|
Invoked using the
-Readiness command.
Checks the sanity and readiness of your environment before an upgrade and the certificate requirements after the installation. |
|
|
Invoked using the
UpdateUiPathUrl command.
Updates the public address of Orchestrator and checks if the new address is valid with the current certificate. |
|
|
Invoked using the
UpdateUiPathCertificate command.
Updates the Orchestrator SSL certificate or the Identity Server token-signing certificate. |
|
|
Invoked using the
AddHostAdmin command.
Adds a system administrator to the host tenant. |
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.
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.
UiPath.Orchestrator.dll.config.
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.
<system.webServer> element contains any locked sections. If such sections exist, you need to manually unlock them in IIS.
Checks if SQL Server Scaleout is used. You are informed that during the installation Redis Scaleout is enabled.
Checks that external credential store plugins target a supported framework.
Checks that NLog plugins target a supported framework.
Buckets.FileSystem.Allowlist app setting is present in Orchestrator versions starting with 2020.4. This covers both pre-installation checks (Orchestrator
2020.4) and post-installation checks (Orchestrator 2020.10+). Orchestrator versions prior to 2020.4 skip this check.
-
To perform the following checks, you need to decrypt the
connectionStringsandappSettingsconfig 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.Allowlistapp 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.Allowlistapp 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.Allowlistapp 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 toBuckets.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.
Checks that all certificate requirements are met by your Orchestrator instance after an upgrade.
SSL Certificate Checks
- the
hostnameof 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 (
2048bits or larger), - has a private key accessible by the AppPool user, and
- is not expired.
Check the docs on installation considerations for other areas impacted by an upgrade to 2020.10+ that you need to be aware of.
|
Command & Parameters |
Description |
|---|---|
|
|
Checks the sanity and readiness of your environment before an upgrade and the certificate requirements after the installation. Parameters:
|
|
|
Updates the public address of Orchestrator. Parameters:
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. Use this command with caution as it does not have a roll-back mechanism if a step errors out during execution.
|
|
|
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:
|
|
|
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:
|
|
Parameter |
Description |
|---|---|
|
|
Optional. The name of the Orchestrator website on the target machine. Defaults to
"UiPath Orchestrator". -InstallationDirectory and SiteName are mutually exclusive.
|
|
|
Optional. Displays information about the tool options or available commands, such as the commands' syntax or the checks it performs. |
|
|
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 (
\).
|
|
|
Mandatory. The new public address of Orchestrator. |
|
|
Optional. UiPath database connection string. If left empty, the value is read from the
appsettings.Production.json file.
|
|
|
Optional. The thumbprint of the new token signing certificate. |
|
|
Optional.The thumbprint of the new SSL certificate. |
|
|
Only mandatory when using the
-AddHostAdmin command. Username of the host admin user to create or restore.
|
|
|
Email of the host admin user to create or restore when using the
-AddHostAdmin command. Only mandatory if using these external identity providers:
|
|
|
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.
|
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"-verbose level.
.\Platform.Configuration.Tool.ps1 ` -Readiness ` -SiteName "UiPath Orchestrator".\Platform.Configuration.Tool.ps1 ` -Readiness ` -SiteName "UiPath Orchestrator"Pre-Installation checks successful output (for upgrades from 2020.4).
Validating 22.10 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.10 pre-installation checks are done. Platform readiness validations: 10 succeeded, 0 failed and 0 warning(s).Validating 22.10 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.10 pre-installation checks are done. Platform readiness validations: 10 succeeded, 0 failed and 0 warning(s).The following example enables you to update the Orchestrator SSL and the Identity Server token-signing certificates.
.\Platform.Configuration.Tool.ps1 ` -UpdateUiPathCertificate ` -KeepOldCertificate $false -SiteName "UiPath Orchestrator" ` -NewSSLThumbprint "a1b2c3d4" ` -NewTokenSigningThumbprint "z6y5x4v3".\Platform.Configuration.Tool.ps1 ` -UpdateUiPathCertificate ` -KeepOldCertificate $false -SiteName "UiPath Orchestrator" ` -NewSSLThumbprint "a1b2c3d4" ` -NewTokenSigningThumbprint "z6y5x4v3"- Any
appsettingsfiles should be decrypted prior to using the script. - Make sure the certificates have the appropriate permissions set to prevent an internal server error. Refer to Troubleshooting Certificates for more details.
If the private key has not been added to the certificate, you can add it manually by taking the following steps:
- To locate the private key, start Internet Information Service (IIS) Manager, and select Application Pool. You should find the private key for each service under the Identity column.
- Go to Manage Computer Certificates under Control Panel.
- Go to Personal/Certificates.
- Right-click New certificate, then go to All Tasks > Manage PrivateKey to add the private key.
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;"hostlogin URL documented in
Accessing Identity Management Portal
.
.\Platform.Configuration.Tool.ps1 ` -AddHostAdmin ` -SiteName "UiPath Orchestrator" ` -HostAdminUsername someuser ` -HostAdminPassword som3pwd! ` -HostAdminEmail testemail@company.com.\Platform.Configuration.Tool.ps1 ` -AddHostAdmin ` -SiteName "UiPath Orchestrator" ` -HostAdminUsername someuser ` -HostAdminPassword som3pwd! ` -HostAdminEmail testemail@company.com- Overview
- Prerequisites
- Script Cmdlets
- Pre-Installation Checks
- Asp.Net Core
- CyberArk AIM
- Web.config Encryption
- Web.config Locked Sections
- SQL Server Scaleout
- Credential Store Plugins
- NLog Plugins
- FileSystem Buckets
- Post-Installation Checks
- Certificate Requirements
- Other Considerations
- Running the Script
- Command Reference
- Script Parameters
- Examples
- Performing a Readiness Check
- Changing Certificates After Installation
- Changing Orchestrator URL
- Creating a New System Administrator
- Output
