Implantação do cliente de Relay

Pré-requisitos do cliente de relay, requisitos mínimos e etapas de configuração entre plataformas para conectar sua rede local ao Test Cloud.

Instale e inicie o cliente de Relay em uma máquina dentro de sua rede para estabelecer o túnel de saída para o Test Cloud. Antes de começar, configure um grupo de Relay e tenha a string de configuração do cliente pronta.

Pré-requisitos

Requisitos de Hardware

Perfil	vCPU	BATER	Grupos de Relay	Endpoints por grupo	Use case
Padrão	1	2 GiB	Até 10	Até 50	A maioria das implantações
Grande	2	4 GiB	10+	Até 50	Ambientes de alta taxa de transferência ou grande escala

These are minimum requirements for the Relay client when the on-prem executor is not enabled. If the host also runs other workloads, add capacity for them on top of these figures. For deployments that enable the executor, use the figures in Resource planning for supported TCP-based connections instead.

Resource planning for supported TCP-based connections

Each Relay Group you install runs as its own Relay client service. With the on-prem executor enabled, that service starts and supervises one Java process. The figures below are for a single Relay Group with the executor enabled.

Workload	Host CPU	Total host memory	Memory reserved for executor
Typical production traffic	2 vCPU	4 GiB	1 GiB
Large payloads or sustained concurrency	4 vCPU or more	4 GiB or more	1 GiB or more

Total host memory includes the executor reservation, the operating system, and the Java runtime. Add capacity for monitoring and any other workloads on the host. After go-live, if the executor's memory use approaches its reservation, raise the reservation and the total host memory together.

For production, register all your TCP-based endpoints under a single Relay Group. That group's Relay client service runs one on-prem executor, which serves every TCP-based endpoint in the group. Consolidating this way keeps the memory reservation, host capacity, and executor logs to a single process.

If your network segmentation or availability requirements call for more than one Relay Group with the executor on the same host:

• Assign each group's executor a unique --onprem-executor-listen-port value.
• Reserve another 1 GiB for each additional executor process.
• Size CPU for the total traffic across all groups, rather than multiplying the per-group CPU figure by the number of groups.
• Allow disk for a separate executor JAR and log file per group.

Requisitos do disco

Perfil	Mínimo de disco livre
Padrão (1 a 10 grupos)	200 MB
Grande (mais de 10 grupos)	1 GB

The minimums above cover the Relay client alone. If you enable the on-prem executor, allow additional space for the Java runtime, onprem-executor.jar, the connector libraries you supply, and retained executor logs. Log growth depends on your traffic volume, log level, and the configured retention period.

Sistemas operacionais compatíveis

Arquitetura	Linux	Windows
x86_64 (amd64)	Suportado	Suportado
ARM64 (aarch64)	Suportado	Suportado

Requisitos de rede

O cliente de Relay requer conectividade apenas de saída. Nenhuma regra de firewall de entrada é necessária.

Every Relay client version reaches cloud.uipath.com to authenticate and register. Starting with Relay client 26.4.2, new configurations also carry the persistent tunnel over that same URL, so they no longer need a region-specific relay hostname allowlisted.

Configuração do cliente de Relay	Protocol	Porta	Destino	Passagem TLS necessária	Finalidade
All Relay client versions	Https	443	cloud.uipath.com	Não é necessário	Autenticação e registro de relay
Cliente de Relay 26.4.2 ou posterior	HTTPS/WSS	443	cloud.uipath.com	Não é necessário	Túnel persistente
Relay versões do cliente anteriores à 26.4.2	TLS	443	<region>-relay.uipath.com	Required	Túnel persistente

As versões do cliente de Relay anteriores a 26.4.2 continuam a funcionar com nomes de host de Relay regionais. Mantenha esses nomes de host na lista de permissões até que você mude para o cliente de Relay 26.4.2 ou posterior e conecte-se por meio de cloud.uipath.com.

For Relay client versions earlier than 26.4.2, replace <region> with the region of your Test Cloud tenant. For the full list of regions, see Global cloud regions.

Região	Nome do host do servidor de relay
NÓS	us-relay.uipath.com
UE	eu-relay.uipath.com
Canadá	ca-relay.uipath.com
Suíça	ch-relay.uipath.com
Austrália	au-relay.uipath.com
Singapura	sg-relay.uipath.com
Japão	jp-relay.uipath.com
Coreia do Sul	kr-relay.uipath.com
Emirados Árabes Unidos	ae-relay.uipath.com
Reino Unido	uk-relay.uipath.com
União Europeia (região com atraso)	gxp-eu-relay.uipath.com
Estados Unidos (região com atraso)	gxp-us-relay.uipath.com

Observação:

Entre em contato com o suporte da UiPath para confirmar o nome do host do servidor de relay se a região do seu tenant não estiver listada acima.

Escolha a região que corresponde à sua região de tenant do UiPath Cloud, não a localização física do nó de relay. Por exemplo, se seu tenant for provisionado na região dos EUA, use us-relay.uipath.com que o próprio relay seja executado em uma geografia diferente. As configurações do cliente de Relay 26.4.2 que se conectam por meio de cloud.uipath.com não usam esse nome de host regional.

Considerações sobre latência: como o tráfego atravessa o UiPath Cloud → Servidor de Relay → nó de Relay → serviço no local, colocar o nó de relay geograficamente próximo da região do seu tenant minimiza o tempo de ida e volta e melhora a taxa de transferência geral.

For Relay client 26.4.2 configurations that connect through cloud.uipath.com, configure firewalls and proxies to allow HTTPS traffic and WebSocket upgrades to cloud.uipath.com:443. If a proxy inspects TLS for cloud.uipath.com, install the proxy's signing CA in the OS trust store used by the Relay client, and make sure the proxy allows WebSocket upgrades.

Para versões de cliente de Relay anteriores a 26.4.2, configure seu firewall e qualquer proxy ou dispositivo DLP de inspeção de TLS para permitir a passagem de TLS para <region>-relay.uipath.com:443; a inspeção de TLS no nome do host de Relay regional interrompe o túnel de Relay.

The Relay host must resolve and connect to every registered HTTP or HTTPS endpoint, and to the host and port of each supported TCP-based endpoint.

The routing path is flexible. A direct network route, a corporate egress proxy, or a jump host are all acceptable, as long as the connection succeeds from the Relay host. Plan placement so that every destination in the group stays reachable.

largura de banda

The control channel (heartbeats and authentication) uses approximately 1–2 KB/minute when idle. Data traffic scales with the volume of requests your cloud services send to on-premises endpoints. For HTTP and HTTPS endpoints, the relay acts as a transparent tunnel, with no additional overhead beyond TLS and the lightweight WebSocket framing used for cloud.uipath.com connections.

For supported TCP-based connections, the on-prem executor translates each request into the connector's protocol. Traffic between the executor and the target system therefore reflects that protocol rather than the size of the original request. Traffic between the Relay client and the executor stays on the loopback interface and does not leave the host.

Verificar conectividade

Antes de instalar o cliente de Relay, confirme se o tráfego de saída na porta 443 é permitido para os destinos necessários para sua configuração.

Linux

nc -zv cloud.uipath.com 443

# Required only for Relay client versions earlier than 26.4.2
nc -zv <region>-relay.uipath.com 443

Windows (PowerShell)

Test-NetConnection -ComputerName cloud.uipath.com -Port 443

# Required only for Relay client versions earlier than 26.4.2
Test-NetConnection -ComputerName <region>-relay.uipath.com -Port 443

Um resultado bem-sucedido mostra TcpTestSucceeded : True no Windows e succeeded no Linux. Se uma verificação necessária falhar, revise suas regras de firewall. Para configurações do cliente de Relay 26.4.2 que se conectam por meio de cloud.uipath.com, confirme se as atualizações do WebSocket são permitidas; para versões do cliente de Relay anteriores à 26.4.2, confirme se a senha TLS está configurada para o nome do host do servidor de Relay.

On-prem executor for supported TCP-based connections

For supported TCP-based connections, such as SAP BAPI, the Relay client starts and supervises a local Java process, the on-prem executor, that speaks the connector's protocol and forwards the call to the target system.

Importante:

On-prem executor support requires Relay client 26.4.3 or later.

The Relay client starts one executor process for each Relay client service, in Linux and Windows service deployments. The executor listens on localhost only, on port 18080 by default, and is not reachable from outside the host. Like any loopback service it is reachable by other processes on the same host, so treat local access to the Relay host as sensitive.

Before you enable it:

• Install Java 21 or later. A JRE or JDK is sufficient. Run java -version from the installation account to verify it.
• Extract the Relay binary, relay on Linux or relay.exe on Windows, and the bundled onprem-executor.jar from the same archive. Leave the two files together in the extracted directory, and run installation or upgrade commands from that directory.
• Make sure the Relay host can reach the target system hostname and port.
• If a connector requires libraries that UiPath does not ship, put them all in one durable directory that the Relay service account can read, then point --onprem-executor-dep-dir at it. The Relay client stores the path but does not copy the files.
• For SAP BAPI, that directory holds the SAP JCo 3 files sapjco3.jar and sapidoc3.jar, plus the native library matching the host operating system and Java runtime architecture. Use the SAP JCo release that SAP supports for your SAP system and Java runtime.
• The dependencies directory is a code-load path for the executor, which runs with the Relay service account's privileges. It must be administrator-owned and must not be writable by unprivileged users.
• On Linux, use 0755 for the directory and 0644 for the files. On Windows, place it under C:\Program Files, which grants administrators write access and other accounts read and execute by default.

For copyable installation and verification commands, see Linux or Windows. After installing, relay describe <id> reports whether the executor is enabled and which Java home and dependencies directory it uses.

Importante:

TCP-based connections are not supported when you run the Relay client as a container, because the on-prem executor is not available there. Use a Linux or Windows service deployment for these connections.

Configure um proxy (se aplicável)

If your network routes outbound traffic through a proxy, set the following environment variables before running relay start. The Relay client uses these settings for proxy-aware outbound traffic.

Variável	Finalidade
HTTPS_PROXY / https_proxy	URL do proxy (verificado primeiro)
HTTP_PROXY / http_proxy	URL do proxy (retorno)
NO_PROXY / no_proxy	Hosts ou domínios separados por vírgulas que ignoram o proxy

O URL do proxy deve usar um desses esquemas: http://, https://, socks5:// ou ntlm://. Formato: scheme://[user:password@]host:port.

Para proxies https:// : o cliente de Relay valida o certificado TLS do proxy contra o armazenamento de confiança do SO. Se seu proxy usar uma CA corporativa ou autoassinada, adicione essa CA ao armazenamento de confiança da máquina cliente de Relay antes de iniciar o relay; caso contrário, o handshake do TLS falhará com um erro de verificação de certificado.

Para configurações de clientes de Relay 26.4.2 que se conectam por meio de cloud.uipath.com, configure seu proxy para permitir conexões HTTPS de longa duração e atualizações de WebSocket para cloud.uipath.com:443. Se o proxy inspecionar o TLS para cloud.uipath.com, instale a CA de assinatura do proxy no armazenamento de confiança do sistema operacional usado pelo cliente de Relay.

Para versões do cliente do Relay anteriores a 26.4.2, configure seu proxy para ignorar a inspeção do TLS para <region>-relay.uipath.com:443. Arquivos PAC, descoberta automática de WPAD e encadeamento de proxy não são compatíveis — defina a URL de proxy explicitamente. Quando um proxy é detectado, as verificações de pré-requisitos mostram via proxy na saída.

Importante:

The Relay client redacts proxy passwords in logs. However, credentials set in environment variables may be visible in process listings and systemd unit files. Use dedicated service credentials and restrict access to the relay node accordingly.

Configurar IPs confiáveis (se aplicável)

Se sua organização restringir o acesso por endereço IP, adicione o IP NAT da máquina que executa o cliente de Relay à lista de IPs Confiáveis na UiPath Administration. O tráfego de saída do cliente de Relay chega ao Test Cloud a partir desse endereço IP, portanto, você deve permiti-lo explicitamente.

Para obter instruções, consulte Adicionar intervalos de IP confiáveis.

Aceite o contrato de licença

Antes de iniciar o cliente de Relay, você deve aceitar o contrato de licença. Escolha um dos seguintes métodos:

Opção 1 (variável de ambiente) — Defina a variável de ambiente LICENSE_AGREEMENT para aceitar:

Linux

export LICENSE_AGREEMENT=accept

Windows

$env:LICENSE_AGREEMENT=accept

Opção 2 (parâmetro incorporado) — Acrescentar --accept-license-agreement ao comando relay start :

./relay start --config "<your-config>" --accept-license-agreement

Guias de configuração

Para implantações de produção, consulte o guia da plataforma para seu sistema operacional — ele abrange comandos de início rápido, estrutura de diretórios, gerenciamento de serviços, configuração da estrutura de segurança e procedimentos de desinstalação:

Plataforma	Guia
Linux	Implantação do cliente de Relay no Linux
Windows	Implantando o cliente de Relay no Windows
Contêiner	Implantação do cliente de Relay como um contêiner

Operações

Resiliência da conexão

O cliente de Relay mantém o túnel automaticamente:

• Pulsações a cada 30 segundos por padrão (configurável via --heartbeat-interval, mínimo 10 segundos). O tempo limite do túnel é 3 × o intervalo de pulsação. Reduza o intervalo se seu firewall, proxy ou NAT descartar conexões TCP ociosas antes de 30 segundos:

  relay start --config "<config>" --heartbeat-interval 10 --accept-license-agreement
  relay restart <id> --heartbeat-interval 10
  

• Reconexão automática ao desconectar, usando o dimensionamento de espera exponencial para intervalos de 20 segundos.
• Reinicialização automática do serviço se o processo falhar, gerenciada pelo systemd no Linux e pelo Gerenciador de Controle de Serviços do Windows no Windows.
• Início automático do serviço na reinicialização do sistema.

Reconexão proativa

Algumas redes — por trás de um proxy corporativo, balanceador de carga ou firewall com um tempo limite de conexão ociosa — encerram silenciosamente conexões TLS de longa duração. A reconexão proativa restaura a conexão de controle em um cronograma fixo para evitar isso.

Habilite-o com o sinalizador --reconnect-interval :

relay start --config "<config>" --reconnect-interval 1800 --accept-license-agreement

O mínimo efetivo é de 1800 segundos (30 minutos). Defina o intervalo para aproximadamente metade do tempo limite ocioso de seu dispositivo de rede — por exemplo, 1800 segundos para um tempo limite de firewall de 60 minutos. Deixe desabilitado em redes estáveis sem um tempo limite de conexão ociosa.

• Descarga suave. Quando o intervalo transcorre, o cliente de Relay para de aceitar novo trabalho e aguarda as conexões em andamento serem concluídas — até um tempo limite de drenagem de 300 segundos — antes de fechar a conexão antiga e abrir uma nova. As solicitações ainda em andamento quando o tempo limite de drenagem é atingido são encerradas.

• Alta disponibilidade. Quando vários clientes do Relay são implantados no mesmo grupo, eles se coordenam para que apenas um cliente seja drenado de cada vez. O grupo continua atendendo o tráfego ao longo de cada ciclo de reconexão.

• Indica que a reconexão proativa é necessária: os logs mostram erros unexpected EOF ou desconexões silenciosas apesar de uma rede subjacente estável — normalmente causados por um tempo limite ocioso de 30 a 60 minutos em um firewall, proxy ou balanceador de carga.

Recarregar configuração

relay reload <id>

Busca novamente a configuração de proxy do Test Cloud e a aplica sem reiniciar. Alterações no lado da nuvem — novos pontos de extremidade, caminhos de verificação de integridade atualizados — chegam automaticamente a um cliente Relay em execução e normalmente não exigem recarregamento.Use esse comando como fallback apenas se um ponto de extremidade recém-adicionado retornar 404.

Geração de logs

Configuração	Valor
Nível padrão	info
Rotação	Daily
Retenção	7 dias
arquivo de log	relay.log (atual), relay.YYYYMMDD-HHMMSS.log (rotacionado)

Substitua o nível de log padrão por --log-level trace/debug/info/warn/error. No cliente de Relay 26.4.2 ou posterior, substitua a retenção de log rotacionado por --log-retention-days <days> em relay start ou relay restart; a retenção mínima é de 7 dias.

Referência de comando

Início do relay

Provisione um novo cliente de Relay e inicie-o como um serviço em segundo plano.

Contrato de licença (um necessário)

• --accept-license-agreement — accept the end-user license agreement inline.
• LICENSE_AGREEMENT=accept — environment-variable equivalent to the flag. relay start prints the EULA and exits if neither is set.

Configuração (uma necessária)

• -c, --config <string> — string de configuração codificada base64 embutida.
• --config-file <path> — caminho para um arquivo que contém a string de configuração. Recomendado — mantém o segredo fora do histórico do shell.

Ajuste (opcional)

• --heartbeat-interval <sec> intervalo de pulsação do túnel. Padrão 30. Mínimo de 10. O tempo limite do túnel é 3 × esse valor. Menor se seu firewall, NAT ou proxy eliminar o TCP ocioso antes de 30 segundos.
• --reconnect-interval <sec> — intervalo de reconexão proativo. Padrão 0 (desabilitado); mínimo efetivo 1800 (30 minutos) quando definido.
• --log-level <level> — trace, debug, info, warn ou error. Padrão info.
• --log-retention-days <days> — número de dias para reter arquivos de log rotacionados. Padrão 7. Mínimo de 7. Requer o cliente de Relay 26.4.2 ou posterior.
• -d, --detach=false — executado em primeiro plano em vez de como um serviço em segundo plano. Útil para depurar problemas de inicialização.

On-prem executor (optional)

• --enable-onprem-executor — in Linux and Windows service deployments, start the bundled on-prem executor Java process for this Relay client service.
• --onprem-executor-listen-port <port> — local TCP port where the on-prem executor listens. Default 18080.
• --onprem-executor-java-home <path> — JAVA_HOME used to run the on-prem executor. If omitted, java is resolved from PATH.
• --onprem-executor-dep-dir <path> — single directory holding every connector dependency, both the JARs and the matching native OS libraries. For SAP BAPI, that is sapjco3.jar, sapidoc3.jar, and the SAP JCo native library for the host.

The executor address is fixed to localhost. Relay log level and retention settings also apply to onprem-executor.log.

Caminhos de instalação não padrão (opcional)

• --data-dir <path> — diretório de configuração.
• --logs-dir <path> — diretório do arquivo de log.
• --bin-dir <path> — diretório de instalação binário.

Apenas Linux

• --user-mode — instale como um serviço de usuário do sistema (sem sudo necessário, usa caminhos XDG).

Windows apenas

• --service-account <DOMAIN\user> execute o serviço do Windows em uma conta específica. O padrão é LocalSystem.
• --service-account-password <password> — senha para --service-account.

Reinicialização do relay

Interrompa e reinicie o serviço do cliente de Relay. Detecta binários atualizados e aplica alterações na definição do serviço. Os seguintes sinalizadores podem ser substituídos no momento da reinicialização (todos por padrão permanecem inalterados, a menos que seja indicado):

• --config / --config-file — substitua a configuração do cliente.
• --accept-license-agreement aceite o contrato de licença durante a reinicialização, útil ao atualizar um serviço instalado mais antigo que não persistiu a aceitação da licença.
• --log-level altere o nível de log.
• --logs-dir <path> — realoque o diretório de logs do serviço instalado. Requer o cliente de Relay 26.4.2 ou posterior.
• --log-retention-days <days> alterar a retenção de log rotacionado. Mínimo de 7; passe -1 para deixar inalterado. Requer o cliente de Relay 26.4.2 ou posterior.
• --heartbeat-interval altere o intervalo de pulsação. Mínimo de 10; passe 0 para deixar inalterado.
• --reconnect-interval altere o intervalo de reconexão proativo. Mínimo de 1800 (30 minutos) quando definido. Passe 0 para desabilitar ou -1 para deixar inalterado.
• --enable-onprem-executor — enable or update the on-prem executor settings on an installed service.
• --disable-onprem-executor — remove persisted on-prem executor settings and restart without the executor process.
• --onprem-executor-listen-port, --onprem-executor-java-home, --onprem-executor-dep-dir — update specific on-prem executor settings. Passing any of these flags implies an executor update.

If the installed service already has the on-prem executor enabled, relay restart <id> preserves its settings. To upgrade Relay and the executor together, extract both files from the new archive and run relay restart <id> using the new Relay binary. Java and executor checks run before the service is stopped.

Logs de relay

Mostre a saída de log para um cliente de Relay.

• -f, --follow — transmita novas linhas de log continuamente.
• -n, --lines <N> — número de linhas do final. Padrão 50.

Lista de relays

Mostra todos os clientes de Relay nesta máquina com status, versão, carimbos de data/hora de criação e atualização e nome do grupo quando disponível. Os nomes de grupos longos são truncados na saída da tabela.

• --json emita saída JSON para automação e script, incluindo nomes completos de grupos.

Descrição do relay (Cliente de Relay 26.4.2 ou posterior)

Mostre informações detalhadas para um cliente de Relay, incluindo ID e nome do grupo, ID do segredo, status, versão, modo de serviço e caminho executável, pulsação configurada e intervalos de reconexão, nível de log, caminhos locais e carimbos de data/hora.

An On-Prem Executor section reports whether the executor is enabled and, when it is, the listen port, runtime version, runtime path, Java home, and dependencies directory.

• --json emita a saída JSON para automação e script.

Recarregar relay

Busque novamente a configuração de proxy do Test Cloud e aplique-a sem reiniciar. Use como fallback se um ponto de extremidade recém-adicionado retornar 404.

Parada do relay

Interrompa o serviço ao cliente do Relay. A configuração e as credenciais são preservadas — o cliente de Relay pode ser reiniciado mais tarde.

Exclusão do relay

Interrompa o serviço, cancele o registro do Test Cloud e remova todas as configurações e credenciais locais.

• -f, --force — remover localmente sem cancelamento de registro na nuvem. Use quando as credenciais forem ilegíveis ou os recursos do lado da nuvem já tiverem sido excluídos.

Pacote de suporte do relay [id]

Colete um arquivo editado de configuração, logs e metadados do sistema para um ticket de suporte da UiPath. [id] para agrupar todos os clientes do Relay na máquina. As credenciais e as chaves de criptografia nunca são incluídas. Consulte Coletar um pacote de suporte para obter detalhes completos.

Versão do relay

Visualize a versão do cliente de Relay, a data de compilação e o hash de confirmação do git.

Segurança de antivírus e ponto de extremidade

Se sua organização executar um software de proteção de ponto de extremidade, adicione exclusões para o binário de relay e seu diretório de dados para evitar que o cliente de Relay seja bloqueado ou colocado em quarentena. Para configurações do cliente de Relay 26.4.2 que se conectam por meio de cloud.uipath.com, permita cloud.uipath.com:443. Para versões do cliente de Relay anteriores à 26.4.2, configure proxies de inspeção TLS, dispositivos DLP e sistemas IDS/IPS para ignorar a inspeção para <region>-relay.uipath.com:443.

If you enable the on-prem executor, extend those exclusions to the Java executable, the dependencies directory, and onprem-executor.log. The Relay service starts a Java child process that loads third-party connector libraries, which some endpoint protection products block by default. Scope the exclusions to those paths rather than the whole directory tree.

Destino	Porta	Protocol	Ação
cloud.uipath.com	443	Https	Permitir
<region>-relay.uipath.com	443	TLS	Permitir + ignorar inspeção TLS para versões do cliente de Relay anteriores a 26.4.2