Implantação do cliente de Relay no Linux

Implante o Cliente do Relay como um serviço sistematizado no Linux para estabelecer um túnel de saída entre sua rede e o Test Cloud.

Esta página abrange detalhes da configuração de produção específicos do Linux. Para pré-requisitos multiplataforma e requisitos de rede, consulte Implantando o cliente de Relay.

Requisitos do sistema operacional

O cliente de Relay requer systemd 229 ou posterior. Para verificar: systemctl --version.

Distribuição	Versão mínima
Ubuntu	20.04 LTS (focal)
Debio	10 (Buster)
Red Hat Linux Enterprise	8
Amazon Linux	2023
Servidor Linux Enterprise Server	15
Oracle Linux	8

Espera-se que qualquer distribuição Linux com systemd 229+ funcione. Para ambientes sem systemd, o cliente de Relay pode ser executado no modo de --detach=false plano (), mas você é responsável pelo gerenciamento do processo, início automático e recuperação.

Privilégios necessários: o acesso sudo (root) é necessário para instalar os serviços do systemd (/etc/systemd/system/), criar diretórios de dados e log padrão e copiar o binário para /usr/local/bin/. Para instalações sem raiz, consulte Modo de usuário.

Pré-requisitos

System

• Distribuição Linux suportada com systemd 229+
• Acesso sudo (raiz) ou planeja usar --user-mode
• Espaço mínimo em disco de 200 MB
• Se você usar uma conexão baseada em TCP compatível que requer o executor no local:
  • Revise a capacidade recomendada de host e executor
  • Um JRE ou JDK Java 21 ou posterior, no PATH ou aprovado com --onprem-executor-java-home. Uma instalação existente funciona.

Rede

• Para o cliente de Relay 26.4.2 ou posterior, o HTTPS de saída (porta 443) para cloud.uipath.com é permitido, incluindo atualizações do WebSocket
• Para versões do cliente de Relay anteriores a 26.4.2, a saída TLS (porta 443) para <region>-relay.uipath.com é permitida e a passagem do TLS está configurada
• O host de relay pode resolver e conectar-se a todos os pontos de extremidade HTTP ou HTTPS registrados, e ao host e à porta de cada ponto de extremidade baseado em TCP compatível

Segurança

• Exclusões SELinux / AppArmo / fapolicyd configuradas (se aplicável) (consulte Estruturas de segurança)
• Se você usar o executor local: um diretório de dependências de propriedade do administrador e instalação Java que nenhuma conta sem privilégio pode escrever. O executor carrega código de ambos, com os privilégios da conta de serviço de Relay

Configuração

• Grupo de Relay criado e string de configuração do cliente pronta (consulte Configuração de um grupo de Relay)

Validar pré-requisitos

Execute os seguintes comandos:

# Check systemd version (must be 229+)
systemctl --version

# Verify sudo access
sudo -v

# Check available disk space
df -h /var/lib

# On-prem executor only: Java 21+ on PATH, or pass --onprem-executor-java-home
java -version

Instalar

1. Baixe e extraia

Baixe o arquivo do cliente Relay para sua arquitetura (x86_64 ou ARM64) no UiPath Customer Portal.

unzip relay_linux_amd64.zip && chmod +x relay

A partir do cliente de Relay 26.4.3, o arquivo também contém onprem-executor.jar. Deixe-o ao lado do binário relay no diretório extraído e execute os comandos de instalação ou atualização desse diretório.

2. Iniciar

Você pode fornecer a string de configuração do cliente (gerada na UiPath Administration, conforme descrito em Configuração de um grupo de Relay) de duas maneiras:

Opção A: embutida. Passe a string de configuração diretamente. Nenhum arquivo para criar ou limpar:

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

Opção B: arquivo. Salve a configuração em um arquivo e, depois, faça referência a ela. Essa é a opção recomendada porque mantém o segredo fora do histórico do shell:

sudo ./relay start --config-file /path/to/config.txt --accept-license-agreement

Para uma conexão baseada em TCP compatível que requer o executor no local, prepare as bibliotecas de conector primeiro, conforme descrito em Adicionar dependências do conector, depois inicie o cliente com um único comando.

Adicionar dependências do conector

Alguns conectores exigem bibliotecas de terceiros que não estão incluídas no cliente de Relay. Obtenha-os no fornecedor do conector e coloque-os todos em um diretório dedicado no host do Relay. O cliente de Relay armazena o caminho do diretório, mas não copia as bibliotecas.

Importante:

O executor local carrega e executa essas bibliotecas com as permissões da conta de serviço do Relay. Mantenha o diretório, seus pais e cada arquivo nele pertencente e gravável apenas por root, com acesso de leitura para a conta de serviço. Qualquer pessoa que possa modificar seu conteúdo pode executar código com essas permissões.

Para instalações sem acesso raiz, consulte Executor no local no modo de usuário.

Para SAP BAPI, obtenha as bibliotecas SAP JCo 3 do SAP e coloque esses arquivos no diretório de dependência:

Arquivo necessário	Finalidade
sapjco3.jar	Biblioteca Java SAP JCo
sapidoc3.jar	Biblioteca Java SAP IDoc
libsapjco3.so	Biblioteca nativa SAP JCo Linux correspondente à arquitetura de runtime Java

Para outro conector compatível, coloque as bibliotecas do fornecedor listadas na documentação desse conector no mesmo diretório.

Comece com o Executor no local

Crie o diretório de dependências, copie as bibliotecas para ele e inicie o cliente de Relay com o executor habilitado. --onprem-executor-java-home Aponte em um runtime Java 21 ou posterior, usando um caminho absoluto, para que o executor use o runtime que você pretende:

sudo ./relay start --config-file /path/to/config.txt \
  --accept-license-agreement \
  --enable-onprem-executor \
  --onprem-executor-java-home /usr/lib/jvm/java-21-openjdk \
  --onprem-executor-dep-dir /opt/uipath/relay/executor-deps

Observação:

Os sinalizadores --config e --config-file são mutuamente exclusivos. Para executar em primeiro plano em vez de como um serviço em segundo plano (útil para depuração), passe --detach=false.

O cliente de Relay valida a conectividade, autentica com o OAuth, registra-se no Test Cloud, baixa a configuração do proxy, criptografa credenciais e instala um serviço do systemd, tudo em um único comando.

Saída esperada:

Running prerequisite checks...
  ✓ Directory permissions: OK
  ✓ Cloud portal connectivity: OK
✓ All prerequisite checks passed
Waiting for service to start...
  ✓ Service is running

✓ Relay is now running in the background.
Check status: systemctl status relay-<id>

Observação:

Durante a inicialização, o cliente de Relay copia automaticamente o binário /usr/local/bin/relay. Todos os grupos de Relay na máquina compartilham esse binário único. Substitua o diretório de instalação por --bin-dir.

3. Verificar

relay list

Um cliente íntegro mostra ● running na coluna Status. O valor ID mostrado é usado em todos os comandos subsequentes (relay stop <id>, relay logs <id>, e assim por diante). Você também pode encontrá-lo na UiPath Administration na página de detalhes do grupo de Relay.

Confirme que o túnel foi estabelecido verificando os logs para login to server success:

sudo relay logs <id> -f

Se o executor no local estiver habilitado, confirme sua configuração:

sudo relay describe <id>

A seção Executor no local relata Enabled: true com a porta de escuta, versão de runtime, caminho de runtime, página inicial do Java e diretório de dependências que está usando. Verifique se o início do Java e o diretório de dependências são aqueles que você pretende.

Em seguida, confirme se o executor foi iniciado. Seu log contém uma entrada Started OnPremRuntimeApplication assim que estiver pronto:

sudo grep "Started OnPremRuntimeApplication" /var/log/uipath-relay/logs/<id>/onprem-executor.log
sudo tail -n 20 /var/log/uipath-relay/logs/<id>/onprem-executor.log

Se você configurou um diretório de log personalizado, use seu caminho onprem-executor.log em vez disso. Em seguida, execute uma chamada de teste do conector que usa esse ponto de extremidade para confirmar que o caminho completo funciona.

Gerenciar

List

Mostra todos os grupos de relay instalados nesta máquina com status, versão e nome do grupo, quando disponível. Não requer sudo.

relay list
relay list --json

Descrever

Observação:

Disponível com o cliente de Relay 26.4.2 e posterior. Execute relay version para verificar sua versão instalada.

Mostra informações detalhadas para um grupo de Relay, incluindo configurações de serviço, caminhos configurados, status, versão e nome do grupo quando disponível. Não requer sudo. Para um serviço do sistema com o executor local habilitado, execute-o com sudo para incluir a versão do executor, que é lida a partir do onprem-executor.jar de propriedade raiz.

relay describe <id>
relay describe <id> --json

Parar

Interrompe o Serviço de Relay. A configuração e os logs são retidos. O relay pode ser reiniciado mais tarde.

sudo relay stop <id>

Reiniciar e atualizar

Reinicia o serviço de Relay e busca a configuração de proxy mais recente do Test Cloud.

sudo relay restart <id>

Atualizar: extraia o novo arquivo do cliente de Relay. Mantenha o novo binário relay e a correspondência de onprem-executor.jar juntos e, em seguida, execute sudo ./relay restart <id> a partir do diretório extraído. O comando de reinício atualiza o binário instalado e, quando o Executor é habilitado, seu JAR.

Para habilitar o executor em um serviço que já está instalado, execute sudo ./relay restart <id> --enable-onprem-executor a partir do diretório do arquivo extraído, para que o onprem-executor.jar correspondente fique disponível.

Cenário	Command
Pontos de extremidade adicionados ou removidos no Test Cloud	sudo relay restart <id>
Rotação de segredo do cliente (em linha)	sudo relay restart --config "<new-config>"
Rotação de segredo do cliente (arquivo)	sudo relay restart --config-file /path/to/new-config.txt
Alteração do nível de registro	sudo relay restart <id> --log-level debug
Diretório de logs ou alteração de retenção	sudo relay restart <id> --logs-dir /opt/mycompany --log-retention-days 30
Habilitar o Executor no local	sudo ./relay restart <id> --enable-onprem-executor
Desabilitar o Executor no local	sudo relay restart <id> --disable-onprem-executor
Atualização do cliente de Relay	Extraia o novo arquivo e, em seguida, execute sudo ./relay restart <id>

Observação:

Quando --config ou --config-file é fornecido, o <id> argumento é opcional. Ele é extraído da configuração.

Excluir

Interrompe o serviço, cancela o registro do Test Cloud e remove todas as configurações locais e arquivos de log.

sudo relay delete <id>

Para forçar a limpeza local sem o cancelamento do registro da nuvem, por exemplo, se as credenciais forem perdidas ou o grupo de relay do lado da nuvem já tiver sido excluído:

sudo relay delete <id> --force

Versão

relay version

Observação:

Não há atualização automática. Extraia o novo arquivo e execute sudo ./relay restart <id> a partir de seu diretório para cada grupo.

Estrutura de diretório

Todos os diretórios são criados automaticamente na primeira execução.

/usr/local/bin/
  relay                                      # Shared binary (755)

/var/lib/uipath-relay/                       # Data root (755)
  groups/<id>/
    client_config                            # OAuth credentials (encrypted, 600)
    metadata.json                            # State, PID, install timestamps (644)
    .credentials.key                         # AES-256-GCM encryption key (600)
    onprem-executor.jar                      # Executor runtime when enabled (600)

/var/log/uipath-relay/                       # Logs root (755)
  logs/<id>/
    relay.log                                # Current log (644)
    relay.YYYYMMDD-HHMMSS.log                # Rotated logs (644)
    onprem-executor.log                      # Executor log when enabled

/etc/systemd/system/
  relay-<id>.service                         # Systemd unit file

Permissões de arquivo

Path	Mode	Motivo
Diretórios	755	Acesso de leitura/gravação do relay
client_config	600	Contém credenciais do OAuth criptografadas
.credentials.key	600	Chave de criptografia AES-256-GCM
metadata.json	644	Metadados de serviço (estado, PID, carimbos de data/hora de instalação)
onprem-executor.jar	600	Runtime do executor copiado no armazenamento de serviço protegido
relay.log	644	Legível para solução de problemas
Binário	755	Executável por systemd
Diretório de dependências (apenas o executor)	755, de propriedade de root	Você o cria; o executor carrega JARs e bibliotecas nativas como código
Arquivos no diretório de dependências	644, de propriedade de root	O acesso de gravação a qualquer um deles é a execução de código como a conta de serviço

O cliente de Relay cria e mantém cada caminho nessa tabela, exceto o diretório de dependências. Essa é sua para criar e manter: mantenha-a e tudo nela, de propriedade de root e gravável apenas de root.

Caminhos personalizados

Substitua os diretórios padrão ao instalar o cliente de Relay.

sudo ./relay start --config-file /path/to/config.txt \
  --accept-license-agreement \
  --bin-dir /opt/mycompany/bin \
  --data-dir /opt/mycompany \
  --logs-dir /opt/mycompany

Bandeira	Padrão	Description
--bin-dir	/usr/local/bin	Diretório para o binário compartilhado
--data-dir	/var/lib	Raiz dos dados de configuração
--logs-dir	/var/log	Raiz para arquivos de log; pode ser alterado com restart

O cliente de Relay anexa uipath-relay/ sob os dados personalizados e raiz de log:

--bin-dir  /opt/mycompany/bin  =>  /opt/mycompany/bin/relay
--data-dir /opt/mycompany      =>  /opt/mycompany/uipath-relay/groups/<id>/
--logs-dir /opt/mycompany      =>  /opt/mycompany/uipath-relay/logs/<id>/

Observação:

--bin-dir e --data-dir são aceitos apenas pelo comando start . --logs-dir é aceito por start e restart. Outros comandos (stop, delete, list) derivam caminhos automaticamente da configuração do serviço instalado.

Proxy Configuration

Se sua rede roteia o tráfego de saída por meio de um proxy, exporte as variáveis de ambiente do proxy antes de relay start. Use sudo -E para preservar o ambiente ao elevar:

export HTTPS_PROXY="http://proxy.corp.example.com:8080"
export NO_PROXY="localhost,127.0.0.1,.corp.example.com"
sudo -E ./relay start --config "<your-config>" --accept-license-agreement

Sem -E, sudo redefine o ambiente e as configurações de proxy são perdidas.

O cliente de Relay grava as variáveis de proxy capturadas como diretivas Environment= no arquivo de unidade do systemd, para que o serviço em segundo plano as use, não /etc/environment em todo o sistema.

Para atualizar o proxy após a instalação: exporte os novos valores e sudo -E relay restart <id>.

Para remover o proxy: unset HTTPS_PROXY HTTP_PROXY NO_PROXY, em seguida, sudo relay restart <id>.

Para verificar o que o serviço usa: systemctl cat relay-<id> | grep -i environment.

Para esquemas de proxy e autenticação compatíveis, consulte a seção proxy em Implantação do cliente de Relay.

Estruturas de segurança

Se seu ambiente usar SELinux, AppArmo ou fapolicyd, certifique-se de que o binário do cliente de Relay e seus diretórios de dados sejam permitidos.

Se você habilitar o executor local, o Serviço de Relay também executará o executável Java e carregará as bibliotecas nativas do diretório de dependências. Permita ambos, ou o executor falha ao iniciar ou não pode carregar suas bibliotecas de conector.

SEL Linux

# Check enforcement mode
getenforce

# Relabel the binary if a custom policy blocks it
sudo semanage fcontext -a -t bin_t '/usr/local/bin/relay'
sudo restorecon -v /usr/local/bin/relay

Quando o executor local está habilitado, o Serviço de Relay também executa o executável Java e carrega bibliotecas nativas do diretório de dependências. Rotule apenas os caminhos que geram recusas. Verifique se há recusas primeiro.

sudo ausearch -m AVC -ts recent | grep -i -e relay -e java

Se as recusas mostrarem que o processo Java recusou acesso de leitura ou mapeamento ao diretório de dependências, rotule as bibliotecas nativas como bibliotecas compartilhadas.

sudo semanage fcontext -a -t lib_t '/opt/uipath/relay/executor-deps(/.*\.so(\..*)?)?'
sudo restorecon -Rv /opt/uipath/relay/executor-deps

Para quaisquer recusas restantes, crie um módulo de política em vez de desabilitar a aplicação.

sudo ausearch -m AVC -ts recent | audit2allow -M uipath-relay-executor
sudo semodule -i uipath-relay-executor.pp

Robô do Aplicativo

Certifique-se de que nenhum perfil restrinja /usr/local/bin/relay do acesso à rede ou gravações de arquivos a /var/lib/uipath-relay/ e /var/log/uipath-relay/. Se você usar caminhos personalizados, substitua de acordo.

Se sua organização restringir os serviços locais com seus próprios perfis do AppArmo e o executor local estiver habilitado, o perfil que cobre o binário de Relay também deverá permitir que ela execute o runtime Java, e permitir que o processo Java leia e mapeie as bibliotecas de conector na diretório de dependências. Verifique se há recusas com sudo journalctl -k | grep -i apparmor.

fapolicyd

sudo fapolicyd-cli --file add /usr/local/bin/relay
sudo fapolicyd-cli --update

Quando o executor local está habilitado, o fapolicyd também deve confiar no executável Java, no JAR de runtime do executor e em cada biblioteca de conector. Um runtime Java instalado a partir de um arquivo, em vez de um pacote de distribuição, não está no banco de dados do pacote e não é confiável por padrão; um runtime empacotado, como java-21-openjdk não precisa de entrada.

Confie em cada arquivo individualmente.

sudo fapolicyd-cli --file add <java-home>/bin/java
sudo fapolicyd-cli --file add /var/lib/uipath-relay/groups/<id>/onprem-executor.jar
sudo fapolicyd-cli --file add /opt/uipath/relay/executor-deps/sapjco3.jar
sudo fapolicyd-cli --file add /opt/uipath/relay/executor-deps/sapidoc3.jar
sudo fapolicyd-cli --file add /opt/uipath/relay/executor-deps/libsapjco3.so
sudo fapolicyd-cli --update

Execute novamente fapolicyd-cli --file update <path> e fapolicyd-cli --update após qualquer atualização que substitua um arquivo confiável: uma atualização de cliente de Relay, que substitui onprem-executor.jar, uma atualização de Java ou uma nova versão da biblioteca de conector. As entradas de confiança registram o tamanho e o hash de cada arquivo e, portanto, param de corresponder quando o arquivo é alterado. Se o executor falhar ao iniciar em um host executando fapolicyd, verifique sudo journalctl -u fapolicyd -n 50.

Caminhos para permitir

Tipo	Caminho padrão
Binário	/usr/local/bin/relay
Dados	/var/lib/uipath-relay/
Logs	/var/log/uipath-relay/
Execuável Java (apenas executor no local)	O caminho java resolvido a partir de PATH ou <java-home>/bin/java
Bibliotecas de conector (apenas executor no local)	O diretório passado para --onprem-executor-dep-dir

Se você usou --bin-dir, --data-dir ou --logs-dir, permita esses caminhos personalizados.

Modo de Usuário

O modo de usuário --user-mode) instala o cliente de Relay como um serviço de usuário do systemd em vez de um serviço do sistema, permitindo que ele seja executado sem sudo. Isso é adequado para máquinas compartilhadas e ambientes restritos em que o acesso raiz não está disponível.

Requisitos

Requisito	Detalhes
systemd 229+	Verificar: systemctl --version
Diretório inicial	Deve existir e ser de propriedade do usuário de destino
sessão do usuário do systemd	Verificar: systemctl --user is-system-running retorna running ou degraded
Logon do SSH	Obrigatório. su / sudo su não fornecem a sessão D-Bus necessária para os serviços do usuário
loginctl linger	Necessário para que o serviço persista após o logout e seja iniciado na inicialização

Habilitar demora ( uma vez, requer administrador):

sudo loginctl enable-linger <username>

Sem demora, os serviços do usuário são interrompidos quando você faz logoff e não são iniciados na inicialização.

Iniciar no modo de usuário

./relay start --user-mode --config-file /path/to/config.txt --accept-license-agreement

Executor local no modo de usuário

No modo de usuário, o executor é executado como sua conta de usuário em vez root de, e os mesmos sinalizadores de executor se aplicam:

./relay start --user-mode --config-file /path/to/config.txt \
  --accept-license-agreement \
  --enable-onprem-executor \
  --onprem-executor-java-home <java-home> \
  --onprem-executor-dep-dir <dep-dir>

O diretório de dependências não deve ser gravável por grupo ou pelo mundo. Se um administrador estiver disponível, peça que ele o crie de propriedade de root com acesso de leitura para sua conta, para que nenhuma conta sem privilégios possa alterar o que o executor carrega. Caso contrário, crie você mesmo com chmod 0755 no diretório e 0644 nos arquivos.

Layout do diretório do modo de usuário

~/.local/bin/
  relay                                      # Shared binary (755)

~/.local/share/uipath-relay/
  groups/<id>/
    client_config                            # OAuth credentials (encrypted, 600)
    metadata.json                            # Service metadata (644)
    .credentials.key                         # Encryption key (600)
    onprem-executor.jar                      # Executor runtime when enabled (600)
  logs/<id>/
    relay.log
    relay.YYYYMMDD-HHMMSS.log
    onprem-executor.log                      # Executor log when enabled

~/.config/systemd/user/
  relay-<id>.service                         # Systemd user unit file

O caminho ~/.config/systemd/user/ não pode ser substituído. Binários, dados e caminhos de log podem ser personalizados com --bin-dir, --data-dir e --logs-dir.

Comandos de gerenciamento no modo de usuário

Todos os comandos funcionam sem sudo:

relay list
relay stop <id>
relay restart <id>
relay delete <id>
relay logs <id> -f

Quando usar o modo de usuário

Cenário	Recomendado
Servidor de produção com acesso raiz	Modo do sistema (padrão)
Máquina compartilhada, sem acesso raiz	Modo de Usuário
Desenvolvimento ou teste	Modo de Usuário
Ambientes confidenciais da segurança	Modo do sistema (caminho binário à vontade)

Desinstalar

1. Exclua todos os clientes do Relay (use relay list para ver os grupos instalados):

   sudo relay delete <id>
   

2. Remova o binário compartilhado:

   sudo rm /usr/local/bin/relay
   

3. Remova os diretórios de dados e logs restantes:

   sudo rm -rf /var/lib/uipath-relay /var/log/uipath-relay
   

Para o modo de usuário, substitua os comandos pelos equivalentes do modo de usuário (sem sudo) e remova ~/.local/bin/relay e ~/.local/share/uipath-relay.

Solução de problemas

Problema	Causa	Resolution
Falha ao iniciar o serviço	Permissões insuficientes	Executar com sudo
permission denied	Não é possível criar diretórios	Verifique o acesso sudo ou use caminhos personalizados para um local gravável
systemctl: command not found	systemd não instalado	Use o modo de primeiro plano (--detach=false) ou instale o systemd
O serviço é iniciado e interrompido imediatamente	Erro de configuração ou de rede	Verifique relay.log há erros de inicialização
Serviço em execução, mas túnel não estabelecido	Problema de rede ou autenticação	Verifique se login to server relay.log ; verificar a conectividade com cloud.uipath.com; para versões do cliente do Relay anteriores à 26.4.2, verifique a passagem do TLS para o nome do host do relay regional
SELinux ou AppArgu bloqueando a execução	Política de estrutura de segurança	Consulte Estruturas de segurança
XDG_RUNTIME_DIR not found (modo de usuário)	Não conectado via SSH	Faça login via SSH ou habilite o atualmente
D-Bus session bus unreachable (modo de usuário)	Não conectado via SSH	Faça login via SSH ou habilite o atualmente
Proxy não usado pelo serviço	Variável não capturada no início	Execute novamente com sudo -E ou verifique com systemctl cat relay-<id> | grep -i environment
CPU ou memória alta	Nível de log definido como trace ou debug	Definir nível de log como info ou superior

Comandos de diagnóstico

# Real-time logs
sudo relay logs <id> -f

# Systemd journal
journalctl -u relay-<id> -f

# Service status
systemctl status relay-<id>

# Connectivity test
nc -zv cloud.uipath.com 443

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

# Check if binary is blocked by SELinux
sudo ausearch -m AVC -ts recent

# Check AppArmor status
sudo aa-status

Para erros de autenticação e conectividade compartilhados entre plataformas, consulte Solução de problemas.

Referência rápida

Ação	Command
Iniciar	sudo relay start --config-file config.txt --accept-license-agreement
Parar	sudo relay stop <id>
Reiniciar/atualizar	sudo relay restart <id>
Excluir	sudo relay delete <id>
Excluir (forçar)	sudo relay delete <id> --force
List	relay list
Descrever	relay describe <id>
Logs	relay logs <id> -f
Status do serviço	systemctl status relay-<id>
Diário do sistema	journalctl -u relay-<id> -f