Implementar el cliente de Relay en Linux

Implementa el cliente de Relay como servicio de systemd en Linux para establecer un túnel saliente entre tu red y Test Cloud.

This page covers production setup details specific to Linux. For cross-platform prerequisites and network requirements, see Deploying the Relay client.

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.

Requisitos previos

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
• If you use a supported TCP-based connection that requires the on-prem executor:
  • Review the recommended host and executor capacity
  • Install a Java 21 or later JRE or JDK and make it available to the Relay service account

Red

• Para el cliente de Relay 26.4.2 o posterior, se permite el HTTPS saliente (puerto 443) a cloud.uipath.com, incluidas las actualizaciones de WebSocket
• Para las versiones de cliente de Relay anteriores a 26.4.2, se permite el TLS saliente (puerto 443) a <region>-relay.uipath.com y se configura el paso de TLS
• Relay host can resolve and connect to every registered HTTP or HTTPS endpoint, and to the host and port of each supported TCP-based endpoint

Seguridad

• Exclusiones de SELinux / AppArmor / fapolicyd configuradas (si corresponde): consulta Marcos de seguridad
• If you use the on-prem executor: an administrator-owned dependencies directory and Java installation that no unprivileged account can write. The executor loads code from both, with the privileges of the Relay service account

Configuración

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

Validate prerequisites

Ejecuta los siguientes comandos:

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

# Verify sudo access
sudo -v

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

# Check Java version (must be 21+), only when using the on-prem executor
java -version

Instalar

1. Descargar y extraer

Descargue el archivo del cliente de Relay para su arquitectura (x86_64 o ARM64) desde el Customer Portal de UiPath.

unzip relay_linux_amd64.zip && chmod +x relay

Starting with Relay client 26.4.3, the archive also contains onprem-executor.jar. Leave it next to the relay binary in the extracted directory, and run installation or upgrade commands from that directory.

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>" --accept-license-agreement

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 --accept-license-agreement

For a supported TCP-based connection that requires the on-prem executor, stage the connector libraries first, as described in Add connector dependencies, then start the client with a single command.

Add connector dependencies

Some connectors require third-party libraries that are not included with the Relay client. Obtain them from the connector vendor and place them all in a dedicated directory on the Relay host. The Relay client stores the directory path but does not copy the libraries.

Importante:

The on-prem executor loads and executes these libraries with the permissions of the Relay service account. Keep the directory, its parents, and every file in it owned and writable only by root, with read access for the service account. Anyone who can modify its contents can run code with those permissions.

For installations without root access, see On-prem executor in user mode.

For SAP BAPI, obtain the SAP JCo 3 libraries from SAP and place these files in the dependency directory:

Required file	Propósito
sapjco3.jar	SAP JCo Java library
sapidoc3.jar	SAP IDoc Java library
libsapjco3.so	SAP JCo Linux native library matching the Java runtime architecture

For another supported connector, place the vendor libraries listed in that connector's documentation in the same directory.

Start with the on-prem executor

Create the dependency directory, copy the libraries into it, and start the Relay client with the executor enabled. Point --onprem-executor-java-home at a Java 21 or later runtime, using an absolute path, so the executor uses the runtime you intend:

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

Nota:

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>

Nota:

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

If the on-prem executor is enabled, confirm its configuration:

sudo relay describe <id>

The On-Prem Executor section reports Enabled: true with the listen port, runtime version, runtime path, Java home, and dependencies directory it is using. Check that the Java home and dependencies directory are the ones you intended.

Then confirm that the executor started. Its log contains a Started OnPremRuntimeApplication entry once it is ready:

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

If you configured a custom log directory, use its onprem-executor.log path instead. Then run a test call from the connector that uses this endpoint, to confirm the full path works.

Administrar

Lista

Muestra todos los grupos de Relay instalados en esta máquina con el estado, la versión y el nombre del grupo cuando esté disponible. No requiere sudo.

relay list
relay list --json

Describir

Nota:

Disponible con el cliente de Relay 26.4.2 y posterior. Ejecuta relay version para comprobar tu versión instalada.

Shows detailed information for one relay group, including service settings, configured paths, status, version, and group name when available. Does not require sudo. For a system service with the on-prem executor enabled, run it with sudo to include the executor version, which is read from the root-owned onprem-executor.jar.

relay describe <id>
relay describe <id> --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>

Upgrade: extract the new Relay client archive. Keep the new relay binary and matching onprem-executor.jar together, then run sudo ./relay restart <id> from the extracted directory. The restart command updates the installed binary and, when the executor is enabled, its JAR.

To enable the executor on a service that is already installed, run sudo ./relay restart <id> --enable-onprem-executor from the extracted archive directory, so the matching onprem-executor.jar is available.

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
Cambio de nivel de registro	sudo relay restart <id> --log-level debug
Cambio de directorio o retención de registros	sudo relay restart <id> --logs-dir /opt/mycompany --log-retention-days 30
Enable the on-prem executor	sudo ./relay restart <id> --enable-onprem-executor
Disable the on-prem executor	sudo relay restart <id> --disable-onprem-executor
Relay client upgrade	Extract the new archive, then run sudo ./relay restart <id>

Nota:

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

Nota:

There is no auto-upgrade. Extract the new archive and run sudo ./relay restart <id> from its directory for each group.

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

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)
onprem-executor.jar	600	Executor runtime copied into protected service storage
relay.log	644	Legible para la solución de problemas
Binario	755	Ejecutable por systemd
Dependencies directory (executor only)	755, owned by root	You create it; the executor loads JARs and native libraries from it as code
Files in the dependencies directory	644, owned by root	Write access to any of them is code execution as the service account

The Relay client creates and maintains every path in this table except the dependencies directory. That one is yours to create and maintain: keep it, and everything in it, owned by root and writable only by root.

Rutas personalizadas

Anule los directorios predeterminados al instalar el 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

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; se puede cambiar con restart

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

Nota:

--bin-dir y --data-dir solo son aceptados por el comando start. --logs-dir es aceptado por start y restart. Otros comandos (stop, 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>" --accept-license-agreement

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.

If you enable the on-prem executor, the Relay service also runs the Java executable and loads native libraries from the dependencies directory. Allow both, or the executor fails to start or cannot load its connector libraries.

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

When the on-prem executor is enabled, the Relay service also runs the Java executable and loads native libraries from the dependencies directory. Label only the paths that generate denials. Check for denials first.

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

If the denials show the Java process refused read or map access to the dependencies directory, label the native libraries as shared libraries.

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

For any remaining denials, build a policy module rather than disabling enforcement.

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

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.

If your organization confines local services with its own AppArmor profiles and the on-prem executor is enabled, the profile covering the Relay binary must also allow it to execute the Java runtime, and allow the Java process to read and map the connector libraries in the dependencies directory. Check for denials with sudo journalctl -k | grep -i apparmor.

fapolicyd

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

When the on-prem executor is enabled, fapolicyd must also trust the Java executable, the executor runtime JAR, and each connector library. A Java runtime installed from an archive rather than a distribution package is not in the package database and is untrusted by default; a packaged runtime such as java-21-openjdk needs no entry.

Trust each file individually.

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

Re-run fapolicyd-cli --file update <path> and fapolicyd-cli --update after any upgrade that replaces a trusted file: a Relay client upgrade, which replaces onprem-executor.jar, a Java upgrade, or a new connector library version. Trust entries record each file's size and hash, so they stop matching once a file changes. If the executor fails to start on a host running fapolicyd, check sudo journalctl -u fapolicyd -n 50.

Rutas para permitir

Tipo	Ruta predeterminada
Binario	/usr/local/bin/relay
Datos	/var/lib/uipath-relay/
Registros	/var/log/uipath-relay/
Java executable (on-prem executor only)	The java path resolved from PATH, or <java-home>/bin/java
Connector libraries (on-prem executor only)	The directory passed to --onprem-executor-dep-dir

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 --accept-license-agreement

On-prem executor in user mode

In user mode the executor runs as your user account instead of root, and the same executor flags apply:

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

The dependencies directory must not be group- or world-writable. If an administrator is available, have them create it owned by root with read access for your account, so no unprivileged account can change what the executor loads. Otherwise, create it yourself with chmod 0755 on the directory and 0644 on the files.

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

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 la conectividad a cloud.uipath.com; para versiones de cliente de Relay anteriores a 26.4.2, verifique el paso de TLS al nombre de host de Relay regional
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 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 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 --accept-license-agreement
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
Describir	relay describe <id>
Registros	relay logs <id> -f
Estado del servicio	systemctl status relay-<id>
Diario de Systemd	journalctl -u relay-<id> -f