Implementar el cliente de Relay en Linux

Esta página cubre los detalles de configuración de producción específicos para Linux. Para conocer los requisitos previos multiplataforma y los requisitos de red, consulta Implementar el cliente de Relay.

Requisitos del sistema operativo

El cliente de Relay requiere systemd 229 o posterior. Para verificar: systemctl --version.

Distribución	Versión mínima
Ubuntu	20.04 LTS (focal)
Debian	10 (Buster)
Red Hat Enterprise Linux	8
Amazon Linux	2023
SUSE Linux Enterprise Server	15
Oracle Linux	8

Se espera que funcione cualquier distribución de Linux con systemd 229+. Para entornos sin systemd, el cliente de Relay puede ejecutarse en modo de primer plano (--detach=false), pero usted es responsable de la gestión de procesos, el inicio automático y la recuperación.

Privilegios necesarios: se necesita acceso sudo (raíz) para instalar los servicios de systemd (/etc/systemd/system/), crear directorios de datos y registros predeterminados y copiar el binario en /usr/local/bin/. Para instalaciones sin raíz, consulta Modo de usuario.

Comprobaciones previas a la instalación

System

• Distribución de Linux compatible con systemd 229+
• Acceso sudo (raíz) — o planea utilizar --user-mode
• 200 MB de espacio libre en disco como mínimo

Red

• Se permite el HTTPS saliente (puerto 443) a cloud.uipath.com
• Se permite TLS saliente (puerto 443) a <region>-relay.uipath.com
• Paso de TLS configurado para el punto final de Relay (sin inspección TLS)
• El nodo de Relay tiene acceso de red a todos los servicios locales que planea exponer

Seguridad

• Exclusiones de SELinux / AppArmor / fapolicyd configuradas (si corresponde): consulta Marcos de seguridad

Configuración

• Grupo de Relay creado y cadena de configuración del cliente lista: consulta Configurar un grupo de Relay

Comandos de validación

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

# Verify sudo access
sudo -v

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

Instalar

1. Descargar y extraer

Arquitectura	Archivar
x86_64	Relay-Linux-AMD64.zip
ARM64	Relay-Linux-Arm64.zip

unzip relay_linux_amd64.zip && chmod +x relay

2. Iniciar

Puedes proporcionar la cadena de configuración del cliente (desde Administración de UiPath; consulta Configurar un grupo de Relay) de dos maneras:

Opción A: en línea. Pasa la cadena de configuración directamente. No hay ningún archivo para crear o limpiar:

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

Opción B: Archivo. Guarda la configuración en un archivo y luego haz referencia a ella. Recomendado: mantiene el secreto fuera del historial del shell:

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

Los marcadores --config y --config-file son mutuamente excluyentes. Para ejecutarse en primer plano en lugar de como un servicio en segundo plano (útil para la depuración), pasa --detach=false.

El cliente de Relay valida la conectividad, se autentica con OAuth, se registra en Test Cloud, descarga la Configuración del proxy, cifra las credenciales e instala un servicio de systemd, todo con un solo comando.

Salida 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 el inicio, el cliente de Relay copia automáticamente el binario en /usr/local/bin/relay. Todos los grupos de Relay en la máquina comparten este único binario. Anula el directorio de instalación con --bin-dir.

3. Verificar

relay list

Un cliente en buen estado muestra ● running en la columna ESTADO. El valor ID que se muestra se utiliza en todos los comandos posteriores (relay stop <id>, relay logs <id>, etc.). También puedes encontrarlo en Administración de UiPath en la página de detalles del grupo de Relay.

Confirma que el túnel está establecido comprobando los registros de login to server success:

sudo relay logs <id> -f

Administrar

Lista

Muestra todos los grupos de Relay instalados en esta máquina con estado y versión. No requiere sudo

relay list
relay list --json

Detener

Detiene el servicio de Relay. La configuración y los registros se conservan: el Relay se puede reiniciar más tarde.

sudo relay stop <id>

Reiniciar y actualizar

Reinicia el servicio de Relay y obtiene la configuración más reciente del proxy de Test Cloud.

sudo relay restart <id>

Actualización binaria: descarga el nuevo binario relay y ejecuta sudo ./relay restart <id> desde él. El comando de reinicio compara el binario en ejecución con la copia instalada por hash SHA256 y actualiza el binario instalado automáticamente si difieren.

Escenario	Comando
Puntos finales añadidos o eliminados en Test Cloud	sudo relay restart <id>
Rotación de secretos de cliente: en línea	sudo relay restart --config "<new-config>"
Rotación de secreto de cliente: archivo	sudo relay restart --config-file /path/to/new-config.txt
Actualización binaria	Descargue el nuevo binario y luego sudo ./relay restart <id>

Cuando se proporciona --config o --config-file , el argumento <id> es opcional: se extrae de la configuración.

Eliminar

Detiene el servicio, anula el registro de Test Cloud y elimina todos los archivos de configuración y de registro locales.

sudo relay delete <id>

Para forzar la limpieza local sin cancelar el registro en la nube, por ejemplo, si se pierden las credenciales o el grupo de Relay en la nube ya se ha eliminado:

sudo relay delete <id> --force

Versión

relay version

No hay actualización automática. Para actualizar, descarga el nuevo binario y ejecuta sudo ./relay restart <id> para cada grupo.

Estructura del directorio

Todos los directorios se crean automáticamente en la primera ejecución.

/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

Permisos de archivo

Ruta	Mode	Razón
Directorios	755	Acceso de lectura/escritura de Relay
client_config	600	Contiene credenciales OAuth cifradas
.credentials.key	600	Clave de cifrado AES-256-GCM
metadata.json	644	Metadatos del servicio (estado, PID, marcas de tiempo de instalación)
relay.log	644	Legible para la solución de problemas
Binario	755	Ejecutable por systemd

Rutas personalizadas

Anula los directorios predeterminados en el momento de la instalación:

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

Marca	Predeterminado	Descripción
--bin-dir	/usr/local/bin	Directorio para el binario compartido
--data-dir	/var/lib	Raíz para datos de configuración
--logs-dir	/var/log	Raíz para archivos de registro

El cliente de Relay anexa uipath-relay/ en los datos personalizados y las raíces de registro:

--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 y --logs-dir solo son aceptados por el comando start . Otros comandos (stop, restart, delete, list) derivan rutas automáticamente de la configuración del servicio instalado.

Configuración de proxy

Si tu red enruta el tráfico saliente a través de un proxy, exporta las variables de entorno del proxy antes de ejecutar relay start. Usa sudo -E para preservar el entorno al 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>"

Sin -E, sudo restablece el entorno y se pierde la configuración del proxy.

El cliente de Relay escribe las variables de proxy capturadas como directivas Environment= en el archivo de unidad systemd, por lo que el servicio en segundo plano las utiliza, no en todo el sistema /etc/environment.

Para actualizar el proxy después de la instalación: exporta los nuevos valores y ejecuta sudo -E relay restart <id>.

Para eliminar el proxy: unset HTTPS_PROXY HTTP_PROXY NO_PROXY y luego sudo relay restart <id>.

Para verificar lo que utiliza el servicio: systemctl cat relay-<id> | grep -i environment.

Para ver los esquemas de proxy y la autenticación compatibles, consulta la sección de proxy en Implementar el cliente de Relay.

Marcos de seguridad

Si su entorno utiliza SELinux, AppArmor o fapolicyd, asegúrese de que el binario del cliente de Relay y sus directorios de datos estén permitidos.

SELinux

# 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

AppArmor

Asegúrate de que ningún perfil restrinja a /usr/local/bin/relay el acceso a la red o la escritura de archivos a /var/lib/uipath-relay/ y /var/log/uipath-relay/. Si utiliza rutas personalizadas, sustitúyalas en consecuencia.

fapolicyd

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

Rutas para permitir

Tipo	Ruta predeterminada
Binario	/usr/local/bin/relay
Datos	/var/lib/uipath-relay/
Registros	/var/log/uipath-relay/

Si utilizaste --bin-dir, --data-dir o --logs-dir, permite esas rutas personalizadas en su lugar.

Modo de usuario

El modo de usuario (--user-mode) instala el cliente de Relay como un servicio de usuario de systemd en lugar de un servicio del sistema, lo que le permite ejecutarse sin sudo. Esto es adecuado para máquinas compartidas y entornos restringidos donde el acceso a la raíz no está disponible.

Requisitos

Requisitos	Detalles
systemd 229+	Verificar: systemctl --version
Directorio de inicio	Debe existir y ser propiedad del usuario de destino
sesión de usuario de systemd	Verificar: systemctl --user is-system-running devuelve running o degraded
Inicio de sesión SSH	Obligatorio: su / sudo su no proporcionan la sesión de D-Bus que necesitan los servicios de usuario
loginctl linger	Obligatorio para que el servicio persista después de cerrar la sesión e iniciarse en el arranque

Habilitar persistencia (una vez, requiere administrador):

sudo loginctl enable-linger <username>

Sin linger, los servicios de usuario se detienen al cerrar la sesión y no se inician al arrancar.

Iniciar en modo de usuario

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

Diseño del directorio en modo de usuario

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

La ruta ~/.config/systemd/user/ no se puede anular. Las rutas binarias, de datos y de registro se pueden personalizar con --bin-dir, --data-dir y --logs-dir.

Comandos de gestión en modo de usuario

Todos los comandos funcionan sin sudo:

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

Cuándo utilizar el modo de usuario

Escenario	Recomendado
Servidor de producción con acceso raíz	Modo de sistema (predeterminado)
Máquina compartida, sin acceso a la raíz	Modo de usuario
Desarrollo o pruebas	Modo de usuario
Entornos sensibles a la seguridad	Modo de sistema (ruta binaria a prueba de manipulaciones)

Desinstalar

1. Elimine todos los clientes de Relay (use relay list para ver los grupos instalados):

   sudo relay delete <id>
   

2. Eliminar el binario compartido:

   sudo rm /usr/local/bin/relay
   

3. Eliminar los directorios de datos y registro restantes:

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

Para el modo de usuario, reemplaza los comandos por los equivalentes en modo de usuario (sin sudo) y elimina ~/.local/bin/relay y ~/.local/share/uipath-relay.

Solución de problemas

Síntoma	Causa	Resolución
El servicio no se inicia	Permisos insuficientes	Ejecutar con sudo
permission denied	No se pueden crear directorios	Verifique el acceso sudo o utilice rutas personalizadas a una ubicación de escritura
systemctl: command not found	systemd no instalado	Utilice el modo en primer plano (--detach=false) o instale systemd
El servicio se inicia y se detiene inmediatamente	Error de configuración o de red	Compruebe relay.log si hay errores de inicio
Servicio en ejecución pero túnel no establecido	Problema de red o autenticación	Compruebe relay.log para ver si hay login to server errores; verificar el paso de TLS
Ejecución de bloqueo de SELinux o AppArmor	Política de marco de seguridad	Consulta Marcos de seguridad
XDG_RUNTIME_DIR not found (modo de usuario)	No ha iniciado sesión a través de SSH	Inicie sesión a través de SSH o habilite la persistencia
D-Bus session bus unreachable (modo de usuario)	No ha iniciado sesión a través de SSH	Inicie sesión a través de SSH o habilite la persistencia
Proxy no utilizado por el servicio	Variable no capturada al inicio	Vuelva a ejecutar con sudo -E o verifique con systemctl cat relay-<id> | grep -i environment
CPU o memoria altas	Nivel de registro establecido en trace o debug	Establezca el nivel de registro en info o 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 errores de autenticación y conectividad compartidos entre plataformas, consulta Resolución de problemas.

Referencia rápida

Acción	Comando
Iniciar	sudo relay start --config-file config.txt
Detener	sudo relay stop <id>
Reiniciar/actualizar	sudo relay restart <id>
Eliminar	sudo relay delete <id>
Eliminar (forzar)	sudo relay delete <id> --force
Lista	relay list
Registros	relay logs <id> -f
Estado del servicio	systemctl status relay-<id>
Diario de Systemd	journalctl -u relay-<id> -f