Implantação do cliente de Relay no Linux

Esta página abrange detalhes da configuração de produção específicos do Linux. Para pré-requisitos multiplataforma, 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.

Lista de verificação de pré-instalação

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

Rede

• HTTPS de saída (porta 443) para cloud.uipath.com é permitido
• A saída TLS (porta 443) para <region>-relay.uipath.com é permitida
• Passagem TLS configurada para o endpoint do relay (sem inspeção TLS)
• O nó de relay tem acesso à rede para todos os serviços locais que você planeja expor

Segurança

• exclusões SELinux / AppArmo / fapolicyd configuradas (se aplicável) — consulte Estruturas de segurança

Configuração

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

Comandos de validação

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

# Verify sudo access
sudo -v

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

Instalar

1. Baixe e extraia

Arquitetura	Arquivar
x86_64	relay-linux-amd64.zip
ARM 64	relay-linux-ram64.zip

unzip relay-linux-amd64.zip && chmod +x relay

2. Iniciar

Você pode fornecer a string de configuração do cliente (da Administração do UiPath — consulte Configuração de um grupo de Relay) de duas maneiras:

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

sudo ./relay start --config "<your-config>"

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

sudo ./relay start --config-file /path/to/config.txt

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>

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

Gerenciar

List

Mostra todos os grupos de relay instalados nesta máquina com status e versão. Não requer sudo.

relay list
relay list --json

Parar

Interrompe o Serviço de Relay. A configuração e os logs são retidos — o relay pode ser reiniciado posteriormente.

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>

Atualização de binário: baixe o novo binário relay e execute sudo ./relay restart <id> a partir dele. O comando restart compara o binário em execução com a cópia instalada pelo hash SHA256 e atualiza o binário instalado automaticamente se eles forem diferentes.

Cenário	Command
Endpoints 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
Atualização binária	Baixe novo binário e, em seguida, sudo ./relay restart <id>

Quando ou --config é fornecido, <id> --config-file 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

Não há atualização automática. Para atualizar, baixe o novo binário e sudo ./relay restart <id> 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)

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

/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)
relay.log	644	Legível para solução de problemas
Binário	755	Executável por systemd

Caminhos personalizados

Substitua os diretórios padrão no momento da instalação:

sudo ./relay start --config-file /path/to/config.txt \
  --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 dos arquivos de log

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

--bin-dir, --data-dir e --logs-dir são aceitos apenas pelo comando start . Outros comandos (stop, restart, 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>"

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 systemd unit, para que o serviço de 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.

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

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.

fapolicyd

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

Caminhos para permitir

Tipo	Caminho padrão
Binário	/usr/local/bin/relay
Dados	/var/lib/uipath-relay/
Logs	/var/log/uipath-relay/

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	Necessário — su / sudo su não fornece a sessão D-Bus de que os serviços do usuário precisam
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

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)
  logs/<id>/
    relay.log
    relay.YYYYMMDD-HHMMSS.log

~/.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 senha do TLS
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 <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
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
Logs	relay logs <id> -f
Status do serviço	systemctl status relay-<id>
Diário do sistema	journalctl -u relay-<id> -f