Ferramenta de configuração da plataforma

Importante: a Ferramenta de Configuração da Plataforma funciona para atualizações a partir de uma versão lançada nos últimos três anos em relação à versão principal atual. Verificações e operações de pós-instalação funcionam após a instalação do Orchestrator.

Visão geral

A Ferramenta de Configuração da UiPath Platform é um script do PowerShell usado para ajudar você na instalação/atualização bem-sucedida do Orchestrator. Ela ajuda você a verificar a integridade e a preparação do seu ambiente antes de uma atualização e auxilia você na execução de várias operações após a instalação.

A ferramenta está disponível para download abaixo e também é fornecida junto com o instalador UiPathOrchestrator.msi. O script incluído pode ser encontrado na pasta Tools do diretório de instalação do Orchestrator, C:\Program Files (x86)\UiPath\Orchestrator\ por padrão. O script verifica a máquina do Orchestrator. Caso seja uma instalação de vários nós, executar a ferramenta em um nó já é suficiente.

A Ferramenta de Configuração da Plataforma não segue o mesmo esquema de versão do instalador UiPathOrchestrator.msi e pode ser atualizada fora do ciclo de versão do produto. Recomendamos que você sempre baixe e use a versão mais recente da ferramenta que está disponível abaixo.

Baixe a ferramenta

Pré-requisitos

Software	Versão compatível
PowerShell	5.1
Módulo do WebAdministration	N/A
Módulo pki	N/A

Script Cmdlets

O script consiste em três cmdlets destinados a executar funções específicas. Um comando cmdlet-invoking e seus parâmetros relevantes podem ser inseridos na linha de comando para execução imediata.

Cmdlet	Description
Test-PlatformReadiness	Invocados usando o comando -Readiness. Verifica a integridade e a preparação do seu ambiente antes de uma atualização e os requisitos de certificado após a instalação.
Update-UiPathUrl	Invocados usando o comando UpdateUiPathUrl. Atualiza o endereço público do Orchestrator e verifica se o endereço novo é válido com o certificado atual.
Update-UiPathCertificate	Invocados usando o comando UpdateUiPathCertificate. Atualiza o certificado SSL do Orchestrator ou o certificado de assinatura de token do Identity Server.
AddHostAdmin	Invocados usando o comando AddHostAdmin. Adiciona um administrador do sistema ao tenant do host.

Verificações pré-instalação

Asp.Net Core

Verifica se o módulo ASP.NET Core IIS v3.1.x+ está instalado e funcional. Se não estiver, você receberá uma solicitação para desinstalar e reinstalar o Pacote de Hospedagem do ASP.Net Core.

CyberArk AIM

Verifica se o agente do CyberArk AIM está instalado na pasta C:\Program Files (x86)\CyberArk. Se não estiver, o usuário é solicitado a adicionar CLIPasswordSdk.exe no arquivo UiPath.Orchestrator.dll.config usando a chave Plugins.SecureStores.CyberArk.CLIPasswordSDKExePath após a instalação.

Essa verificação não é executada se o CyberArk não for encontrado em UiPath.Orchestrator.dll.config.

Criptografia do web.config

Verifica se o arquivo web.config está descriptografado. Se estiver criptografado, você precisa descriptografá-lo manualmente antes de atualizar. Após a atualização, a maioria das definições de configuração do Orchestrator é movida para UiPath.Orchestrator.dll.config.

Aprenda como criptografar o arquivo UiPath.Orchestrator.dll.config.

Seções bloqueadas do web.config

Verifica se o elemento <system.webServer> contém qualquer seção bloqueada. Se essas seções existem, você precisa desbloqueá-las manualmente no IIS.

Dimensionamento do SQL Server

Verifica se o dimensionamento do SQL Server é usado. Você é informado de que durante a instalação o dimensionamento do Redis está habilitado.

Plugins do Armazenamento de credenciais

Verifica se os plug-ins do armazenamento de credenciais externas visam uma estrutura compatível.

Plugins do NLog

Verifica se os plug-ins do NLog visam uma estrutura compatível.

Buckets do FileSystem

Esta verificação valida se a configuração do aplicativo Buckets.FileSystem.Allowlist está presente nas versões do Orchestrator a partir da v2020.4. Isso abrange as verificações de pré-instalação (Orchestrator v2020.4) e de pós-instalação (Orchestrator v2020.10). Versões do Orchestrator antes da v2020.4 podem ignorar essa verificação.

• Para executar as verificações a seguir, você precisa descriptografar as seções de configuração connectionStrings e appSettings. Se qualquer uma dessas seções de configuração estiver criptografada, um alerta avisará você no terminal e as demais validações dos buckets serão ignoradas.

  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.

• Se, por qualquer motivo, os buckets não puderem ser recuperados do banco de dados, você receberá um aviso no terminal, e as outras validações também serão ignoradas.

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

• Essa validação é executada nos caminhos-raiz dos buckets recuperados da tabela de buckets do banco de dados do Orchestrator. Se houver algum caminho não qualificado, você receberá um aviso no terminal. Uma verificação semelhante para os caminhos não qualificados é feita para os caminhos na configuração do aplicativo Buckets.FileSystem.Allowlist no arquivo de configuração.
• Se qualquer um dos caminhos nas duas origens não for válido ou for não qualificado, ele não será levada em consideração para as outras validações descritas abaixo.
• Se a configuração do aplicativo Buckets.FileSystem.Allowlist não estiver definida no arquivo de configuração, você receberá um aviso no terminal com um erro ao adicionar a lista de permissões ao arquivo de configuração. Os caminhos sugeridos são o caminho-raiz dos buckets que usam o provedor do sistema de arquivos.

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

• Se a configuração do aplicativo Buckets.FileSystem.Allowlist estiver definida no arquivo de configuração, a validação será executada no caminho-raiz dos buckets que usam o provedor FileSystem. Se um caminho-raiz do bucket não for um subcaminho de nenhum dos caminhos definidos na lista de permissões, você receberá um aviso no terminal solicitando a adição do caminho-raiz do bucket a 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\

• Caso contrário, se todos os caminhos-raiz do bucket forem um subcaminho de qualquer caminho na lista permitida, o terminal exibirá uma mensagem de sucesso.

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

Verificações pós-instalação

Requisitos de certificado

Verifica se todos os requisitos de certificado são atendidos pela sua instância do Orchestrator após uma atualização.

Verificações de certificado SSL

• o hostname do site do Orchestrator corresponde ao Assunto ou a um Nome Alternativo de Assunto (incluindo curingas) no certificado,
• tem uma cadeia de confiança válida e
• não está expirado.

Verificações de certificado de assinatura de token do Identity Server

• O certificado tem o tamanho de chave adequado (2048 bits ou maior),
• tem uma chave privada acessível pelo usuário do AppPool e
• não está expirado.

Outras considerações

Verifique os documentos sobre considerações de instalação para outras áreas afetadas por uma atualização para a versão 2020.10+ que você precisa conhecer.

Execução do script

Referência de comando

Comando e Parâmetros	Description
-Readiness	Verifica a integridade e a preparação do seu ambiente antes de uma atualização e os requisitos de certificado após a instalação. Parâmetros: -SiteName -Ajuda -InstallationDirectory
-UpdateUiPathUrl	Atualiza o endereço público do Orchestrator. Parâmetros: -SiteName -UrlDoOrchestrator -SqlConnectionString Importante: o módulo do PowerShell do SQL Server é necessário para usar esse comando. O módulo é instalado por padrão com o SQL Server. Se você estiver trabalhando em uma máquina que não tenha o módulo instalado, consulte aqui como instalar. Use esse comando com cuidado, porque ele não tem um mecanismo de reversão se uma etapa falhar durante a execução.
-UpdateUiPathCertificate	Atualiza o certificado SSL do Orchestrator ou o certificado de assinatura de token do Identity Server. Use-o em conjunto com o comando -readiness para verificar a validade dos novos certificados. Parâmetros: -SiteName -NewTokenSigningThumbprint -NewSSLThumbprint -KeepOldCertificate
-AddHostAdmin	Se o acesso à organização do host for perdido (por exemplo, se a senha para o administrador do sistema for perdida ou se os únicos usuários com contas de administrador do sistema deixarem a empresa), você pode usar esse comando para adicionar ou restaurar um administrador do sistema. Parâmetros: -SiteName -HostAdminUsername -HostAdminPassword -HostAdminEmail

Parâmetros do script

Parâmetro	Description
-SiteName	Opcional. O nome do site do Orchestrator na máquina de destino. O padrão é "UiPath Orchestrator". -InstallationDirectory e SiteName são mutuamente exclusivos.
-Help	Opcional. Exibe informações sobre as opções de ferramentas ou comandos disponíveis, como a sintaxe do comando ou as verificações que ele executa.
-InstallationDirectory	Opcional. O caminho do diretório de instalação do Orchestrator. Geralmente C:\Program Files (x86)\UiPath\Orchestrator\. -InstallationDirectory e SiteName são mutuamente exclusivos. Observação: certifique-se de que o caminho do diretório de instalação termine com uma barra invertida (\).
-OrchestratorUrl	Obrigatório. O novo endereço público do Orchestrator.
-SqlConnectionString	Opcional. String de conexão do banco de dados da UiPath. Se deixado em branco, o valor será lido a partir do arquivo appsettings.Production.json.
-NewTokenSigningThumbprint	Opcional. A impressão digital do novo certificado de assinatura de token usado pelo Orchestrator Identity Server.
-NewSSLThumbprint	Opcional. A impressão digital do novo certificado SSL usado pelo Orchestrator Web App.
-HostAdminUsername	Obrigatório apenas ao usar o comando -AddHostAdmin. Nome de usuário do usuário administrador do host a ser criado ou restaurado.
-HostAdminPassword	E-mail do usuário administrador do host para criar ou restaurar ao usar o comando -AddHostAdmin. Obrigatório apenas se estiver usando estes provedores de identidade externos: Google Azure Active Directory SAML com estratégia de mapeamento de usuário de e-mail
-HostAdminEmail	Senha do usuário administrador do host a ser criado ao usar o comando -AddHostAdmin. A senha é obrigatória apenas se o usuário for um usuário de autenticação básica. A senha precisará ser alterada no primeiro logon.

Exemplos

Para trabalhar com o script da Ferramenta de Configuração da Plataforma, abra um script do Administrador do Powershell.

Localize o diretório onde você descompactou o arquivo da Ferramenta de Configuração da Plataforma e altere o diretório para aquele local:

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

Executando uma Verificação de Preparação

O seguinte exemplo permite que você execute uma validação dos requisitos de pré-instalação do Orchestrator. O procedimento registra suas etapas e informações extras de saída no nível -verbose.

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

A pré-instalação verifica saída bem-sucedida (para atualizações a partir de 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).

Alterando Certificados após a instalação

O seguinte exemplo permite que você atualize o SSL do Orchestrator e os certificados de assinatura de token do Identity Server.

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

Observação:

• Quaisquer arquivos appsettings devem ser descriptografados antes de usar o script.
• Certifique-se de que os certificados tenham as permissões apropriadas definidas para evitar um erro interno do servidor. Consulte Resolução de Problemas com Certificados para mais detalhes.
• O parâmetro KeepOldCertificate indica se o certificado atual deve continuar a ser usado como uma chave de validação para tokens que foram assinados com ele.

Se chave privada não tiver sido adicionada ao certificado, você pode adicioná-la manualmente seguindo os seguintes passos:

1. Para localizar a chave privada, inicie o Gerenciador do Internet Information Service (IIS) e selecione Pool de aplicativos. Você deve encontrar a chave privada para cada serviço na coluna Identity.
2. Vá para Gerenciar Certificados de Computador no Painel de controle.
3. Vá para Pessoal/Certificados.
4. Clique com o botão direito em Novo certificado e vá para Todas as Tarefas > Gerenciar PrivateKey para adicionar a chave privada.

Observação: se você tiver vários nós do Orchestrator, certifique-se de atualizar o certificado em todos os nós do servidor.

Alterando o URL do Orchestrator

O seguinte exemplo permite que você atualize o URL do Orchestrator.

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

Observação: embora recomendemos usar letras minúsculas para o URL do Orchestrator, a ferramenta converte automaticamente quaisquer letras maiúsculas para minúsculas.

Como criar um novo administrador do sistema

O exemplo a seguir cria um novo administrador do sistema no tenant do host usando autenticação básica. Observe que, se um provedor de identidades externo for definido como exclusivo, a autenticação básica só será acessível por meio da hostlogin URL documentada no Acesso ao Portal de Gerenciamento de Identidades .

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

Saída

A saída é codificada em cores.

Cor	Description
Vermelho	Bloqueadores Alguns elementos estão ausentes ou não foram configurados e isso impedirá a instalação.
Amarelo	Avisos Você pode instalar o Orchestrator, mas os benefícios adicionais estarão ausentes.
Verde	Mensagens O ambiente está pronto para a instalação.