プラットフォーム構成ツール

重要: プラットフォーム構成ツールは、過去 3 年間にリリースされたバージョンから現在のメジャー バージョンにアップグレードする場合に使用できます。Orchestrator のインストール後は、インストール後の確認と操作が可能です。

概要

UiPath プラットフォーム構成ツールは、Orchestrator の適切なインストール/アップグレードを支援する PowerShell スクリプトです。アップグレード前に実際の環境の健全性と準備状況を確認し、インストール後に実行するいくつかの操作を支援します。

ツールは下記のリンクからダウンロードでき、UiPathOrchestrator.msi インストーラーもバンドルされています。バンドルされているスクリプトは、Orchestrator のインストール ディレクトリ (既定では C:\Program Files (x86)\UiPath\Orchestrator\) の Tools フォルダーにあります。このスクリプトは Orchestrator のマシンをチェックします。マルチノード インストールの場合、このツールはいずれか 1 つのノードで実行すれば十分です。

プラットフォーム構成ツールは UiPathOrchestrator.msi インストーラーとは異なるバージョン管理方式に従っており、製品リリース サイクルに関係なく更新できます。常にツールの最新バージョンを、下記のリンクから入手することを推奨します。

ツールをダウンロードする

前提条件

ソフトウェア	対応バージョン
PowerShell	5.1
WebAdministration モジュール	N/A
pki モジュール	N/A

スクリプト コマンドレット

このスクリプトは、特定の機能の実行を目的とした 3 つのコマンドレットから構成されています。コマンドレットで起動するコマンドと関連パラメーターを、コマンド ラインから入力して即座に実行することができます。

コマンドレット	説明
Test-PlatformReadiness	-Readiness コマンドを使用して起動されます。 アップグレード前に実際の環境の健全性と準備状況を、インストール後に証明書の要件を確認します。
Update-UiPathUrl	UpdateUiPathUrl コマンドを使用して起動されます。 Orchestrator のパブリック アドレスを更新し、新しいアドレスが現在の証明書で有効かどうかを確認します。
Update-UiPathCertificate	UpdateUiPathCertificate コマンドを使用して起動されます。 Orchestrator の SSL 証明書または Identity Server のトークン署名証明書を更新します。
AddHostAdmin	AddHostAdmin コマンドを使用して起動されます。 ホスト テナントにシステム管理者を追加します。

インストール前の確認

Asp.Net Core

ASP.NET Core の IIS モジュール v3.1.x 以降がインストールされ、機能していることを確認します。インストールされて適切に機能していない場合は、ASP.Net Core ホスティング バンドルのアンインストールと再インストールを促すプロンプトが表示されます。

CyberArk AIM

CyberArk AIM エージェントが C:\Program Files (x86)\CyberArk フォルダーにインストールされていることを確認します。インストールされていない場合は、インストール後に Plugins.SecureStores.CyberArk.CLIPasswordSDKExePath キーを使用して UiPath.Orchestrator.dll.config ファイルに CLIPasswordSdk.exe を追加するよう促すプロンプトが表示されます。

 この確認は、CyberArk が UiPath.Orchestrator.dll.config に定義されていない場合、実行されません。

web.config の暗号化

web.config ファイルが復号されているかどうかを確認します。暗号化されている場合は、アップグレード前に手動で復号する必要があります。アップグレード後、Orchestrator の設定のほとんどは、UiPath.Orchestrator.dll.config に移されます。

UiPath.Orchestrator.dll.config ファイルを暗号化する方法については、こちらをご覧ください。

web.config のロックされたセクション

<system.webServer> 要素にロックされたセクションが含まれているかどうかを確認します。ロックされたセクションが存在する場合は、IIS で手動でロック解除する必要があります。

SQL Server のスケールアウト

SQL Server のスケールアウトが使用されているかどうかを確認します。結果はインストール中に通知され、Redis スケールアウトが有効化されます。

資格情報ストア プラグイン

外部資格情報ストア プラグインのターゲットが、サポート対象のフレームワークであることを確認します。

NLog プラグイン

NLog プラグインのターゲットが、サポート対象のフレームワークであることを確認します。

FileSystem バケット

この確認では、アプリ設定パラメーター Buckets.FileSystem.Allowlist が v2020.4 以降のバージョンの Orchestrator に存在するかどうかが検証されます。インストール前の確認 (Orchestrator v2020.4) とインストール後の確認 (Orchestrator v2020.10) の両方が実行されます。v2020.4 より前のバージョンの Orchestrator では、この確認がスキップされます。

• 次の確認を実行するには、構成セクションの connectionStrings と appSettings を復号する必要があります。これらの構成セクションのどれか 1 つでも暗号化されている場合は、ターミナルで警告が表示され、バケットの検証の残りの手順はスキップされます。

  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. Could not connect to the UiPath Database.

• この検証は、Orchestrator データベースのバケット テーブルから取得したバケットの、ルート パスに対して実行されます。非修飾のパスがある場合は、ターミナルで警告が表示されます。被修飾のパスについての同様の確認が、構成ファイルのアプリ設定パラメーター Buckets.FileSystem.Allowlist のパスに対しても行われます。
• 2 つのソース内のパスのいずれかが有効でない場合、または非修飾である場合は、以下に示す検証の残りの部分に対してはそのパスは考慮されません。
• アプリ設定パラメーター Buckets.FileSystem.Allowlist が構成ファイルで設定されていない場合、ターミナルでエラーが表示され、構成ファイルに許可リストを追加するよう求められます。エラー内で提案されるパスは、ファイル システム プロバイダーを使用するバケットのルート パスです。

  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\" />

• アプリ設定パラメーター Buckets.FileSystem.Allowlist が構成ファイルで設定されている場合、FileSystem プロバイダーを使用するバケットのルート パスに対して検証が実行されます。バケットのルート パスが許可リストで定義したパスのサブパスではない場合、ターミナルで警告が表示され、バケットのルート パスを 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\

• 上記の条件に当てはまらず、バケットのすべてのルート パスが許可リストのいずれかのパスのサブパスである場合は、ターミナルに成功メッセージが表示されます。

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

インストール後の確認

証明書の要件

アップグレード後の Orchestrator インスタンスで証明書の要件がすべて満たされていることを確認します。

SSL 証明書の確認

• Orchestrator サイトの hostname が証明書のサブジェクトまたはサブジェクトの代替名 (ワイルドカードを含む) と一致している
• 信頼チェーンが有効である
• 有効期限が切れていない

Identity Server のトークン署名証明書の確認

• 証明書のキーのサイズが適切である (2048 ビット以上)
• AppPool ユーザーがアクセスできる秘密キーがある
• 有効期限が切れていない

その他の考慮事項

v2020.10 以降へのアップグレードによる影響を受ける、その他の注意すべき領域については、「インストールに関する考慮事項」をご覧ください。

スクリプトを実行する

コマンド リファレンス

コマンドとパラメーター	説明
-Readiness	アップグレード前に実際の環境の健全性と準備状況を、インストール後に証明書の要件を確認します。 パラメーター: -SiteName -help -InstallationDirectory
-UpdateUiPathUrl	Orchestrator のパブリック アドレスを更新します。 パラメーター: -SiteName -orchestratorUrl -SqlConnectionString 重要: このコマンドを使用するには、SQL Server の PowerShell モジュールが必要です。このモジュールは、既定で SQL Server とともにインストールされます。このモジュールがインストールされていないマシンで作業する場合は、こちらのインストール方法をご覧ください。実行中にエラーが発生した場合のロールバック機能がないため、このコマンドは慎重に使用してください。
-UpdateUiPathCertificate	Orchestrator の SSL 証明書または Identity Server のトークン署名証明書を更新します。-readiness コマンドと組み合わせて使用して、新しい証明書の有効性を確認します。 パラメーター: -SiteName -NewTokenSigningThumbprint -NewSSLThumbprint -KeepOldCertificate
-AddHostAdmin	ホスト組織へのアクセス権が失われた場合 (たとえばシステム管理者のパスワードを紛失したり、システム管理者アカウントを持つ唯一のユーザーが退職したりしたときなど)、このコマンドを使用してシステム管理者を追加または復元できます。 パラメーター: -SiteName -HostAdminUsername -HostAdminPassword -HostAdminEmail

スクリプトのパラメーター

パラメーター	説明
-SiteName	任意です。ターゲットとなるマシン上の Orchestrator Web サイトの名前。既定値は "UiPath Orchestrator" です。-InstallationDirectory と SiteName は相互に排他的です。
-Help	任意。コマンドの構文やそのコマンドが機能するかどうかの確認など、ツールのオプションや使用可能なコマンドに関する情報を表示します。
-InstallationDirectory	任意です。Orchestrator のインストール ディレクトリのパス。通常は、C:\Program Files (x86)\UiPath\Orchestrator\ です。-InstallationDirectory と SiteName は相互に排他的です。 注: インストール ディレクトリ パスはバックスラッシュ (\) で終わるようにしてください。
-OrchestratorUrl	必須。Orchestrator の新しいパブリック アドレス
-SqlConnectionString	任意。UiPath データベースの接続文字列。空のままにすると、appsettings.Production.json ファイルから値が読み出されます。
-NewTokenSigningThumbprint	任意です。Orchestrator Identity Server で使用される新しいトークン署名証明書の拇印。
-NewSSLThumbprint	任意です。Orchestrator Web アプリで使用される新しい SSL 証明書の拇印。
-HostAdminUsername	-AddHostAdmin コマンドを使用する場合のみ、必須。作成または復元するホスト管理者ユーザーのユーザー名。
-HostAdminPassword	-AddHostAdmin コマンドを使用するときに、作成または復元するホスト管理者ユーザーのメール アドレス。以下の外部 ID プロバイダーを使用する場合のみ 必須。 Google Azure Active Directory メール ユーザーのマッピング方法を利用した SAML
-HostAdminEmail	-AddHostAdmin コマンドを使用するときに作成するホスト管理者ユーザーのパスワード。パスワードは、ユーザーが基本認証ユーザーの場合にのみ必須です。最初のログイン時にパスワードを変更する必要があります。

例

プラットフォーム構成ツール スクリプトで作業を行うには、管理者として PowerShell スクリプトを開きます。

プラットフォーム構成ツールのアーカイブを解凍したディレクトリを確認し、現在のディレクトリをその場所に変更します。

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

準備状況の確認

Orchestrator のインストール前の要件は、以下の例に従って検証できます。この手順は、各ステップと追加の出力情報を -verbose レベルでログに記録します。

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

インストール前のチェックが正常に完了した場合の出力 (v2020.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).

インストール後に証明書を変更する

Orchestrator の SSL 証明書および Identity Server のトークン署名証明書は、以下の例に従って更新できます。

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

注:

• appsettings ファイルは、スクリプトを使用する前に復号しておく必要があります。
• 内部サーバー エラーを防ぐには、証明書に適切な権限一式が設定されている必要があります。詳細については、「証明書のトラブルシューティング」をご覧ください。
• KeepOldCertificate パラメーターは、現在の証明書で署名されたトークンの検証キーとして、現在の証明書を引き続き使用するかどうかを指定します。

秘密キーが証明書に追加されていない場合は、次の手順を実行して手動で追加できます。

1. 秘密キーを見つけるには、インターネット インフォメーション サービス (IIS) マネージャーを起動し、[アプリケーション プール] を選択します。[ID] 列に、各サービスの秘密キーが表示されています。
2. [コントロール パネル] の [コンピューター証明書の管理] に進みます。
3. [個人] > [証明書] に移動します。
4. [新しい証明書] を右クリックして、[すべてのタスク] > [秘密キーの管理] に移動して秘密キーを追加します。

注: 複数の Orchestrator ノードがある場合は、すべてのサーバー ノードで証明書を更新してください。

Orchestrator URL の変更

Orchestrator の URL は、以下の例に従って更新できます。

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

注: Orchestrator の URL には小文字を使用することをお勧めしますが、大文字の文字列はツールによって自動的に小文字に変換されます。

新しいシステム管理者を作成する

次の例では、基本認証を使用して、ホスト テナントに新しいシステム管理者を作成します。外部 ID プロバイダーが排他的に設定されている場合、基本認証には、ID 管理ポータルへのアクセスに記載されている hostlogin URL からしかアクセスできません。

.\Platform.Configuration.Tool.ps1 ` 
-AddHostAdmin ` 
-SiteName "UiPath Orchestrator" ` 
-HostAdminUsername someuser ` 
-HostAdminPassword som3pwd! ` 
-HostAdminEmail [e-mail]

出力

出力は、色分けされます。

色	説明
赤	インストールの阻害要因が存在します。 必要な要素が不足しているか、設定されていないためにインストールを実行できません。
黄	Warning Orchestrator のインストールは可能ですが、一部の機能を使用できません。
緑	Messages 環境はインストールの準備が整っています。