Déploiement du client de relais sur Linux

Déployez le client de relais en tant que service système sur Linux pour les environnements de production, y compris les exigences de version et les étapes de configuration spécifiques à Linux.

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

Configuration système requise pour le système d’exploitation

Le client de relais nécessite systemd 229 ou une version ultérieure. À vérifier: systemctl --version.

Distribution	Version minimale
Ubuntu	20.04 assistance longue durée
Déban	10
Red Hat Enterprise Linux	8
Amazon Linux	2023
Serveur d'entreprise SUtiliser Linux	15
Oracle Linux	8

Toute distribution Linux avec systemd 229+ est censée fonctionner. Pour les environnements sans système, le client de relais peut s'exécuter en mode de premier plan (--detach=false), mais vous êtes responsable de la gestion des processus, du démarrage automatique et de la récupération.

Privilèges requis: l'accès sudo (root) est nécessaire pour installer les services système (/etc/systemd/system/), créer des répertoires de données et de journaux par défaut, et copier le binaire dans /usr/local/bin/. Pour les installations sans racine, voir Mode utilisateur.

Prérequis

Système

• Distribution Linux prise en charge avec systemd 229+
• sudo (root) access, or plan to use --user-mode
• 200 Mo d’espace disque libre minimum
• If you use a supported TCP-based connection that requires the on-prem executor:
  • Review the recommended host and executor capacity
  • A Java 21 or later JRE or JDK, either on the PATH or passed with --onprem-executor-java-home. An existing installation works.

Réseau

• Pour le client de relais 26.4.2 ou version ultérieure, le HTTPS sortant vers cloud.uipath.com est autorisé, y compris les mises à niveau WebSocket
• Pour les versions de client de relais antérieures à 26.4.2, le TLS sortant (port 443) vers <region>-relay.uipath.com est autorisé et l’interception TLS est configurée
• 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

Sécurité

• SELinux / AppArmor / fapolicyd exclusions configured (if applicable) (see Security frameworks)
• 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

Configuration

• Relay Group created and client configuration string ready (see Configuring a Relay group)

Validate prerequisites

Exécutez les commandes suivantes :

# 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

Installer

1. Télécharger et extraire

Téléchargez l'archive du client de relais correspondant à votre architecture (x86_64 ou ARM64) à partir du Customer Portal 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. Démarrer

You can provide the client configuration string (generated in UiPath Administration, as described in Configuring a Relay group) in two ways:

Option A: Inline. Pass the configuration string directly. No file to create or clean up:

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

Option B: File. Save the configuration to a file, then reference it. This is the recommended option because it keeps the secret out of shell history:

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.

Important :

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

Remarque :

Les indicateurs --config et --config-file sont mutuellement exclusifs. Pour exécuter au premier plan plutôt qu'en tant que service d'arrière-plan (utile pour le débogage), saisissez --detach=false.

The Relay client validates connectivity, authenticates with OAuth, registers with Automation Cloud, downloads proxy configuration, encrypts credentials, and installs a systemd service, all in a single command.

Sortie attendue :

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>

Remarque :

Lors du démarrage, le client de relais copie automatiquement le binaire dans /usr/local/bin/relay. Tous les groupes de Relay sur la machine partagent ce fichier binaire unique. Remplacez le répertoire d'installation par --bin-dir.

3. Vérifier

relay list

Un client sain affiche ● running dans la colonne STATUT. La valeur ID affichée est utilisée dans toutes les commandes suivantes (relay stop <id>, relay logs <id>, etc.). Il est également disponible dans l’administration d’UiPath sous la page des détails du groupe de Relay.

Confirmez que le tunnel est établi en vérifiant les journaux pour 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.

Gérer (Manage)

List

Affiche tous les groupes de Relay installés sur cette machine avec le statut, la version et le nom de groupe lorsqu'il est disponible. Ne nécessite pas sudo.

relay list
relay list --json

Décrire

Remarque :

Disponible avec le client de relais 26.4.2 et versions ultérieures. Exécutez relay version pour vérifier votre version installée.

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

Arrêter

Stops the relay service. Configuration and logs are retained. The relay can be restarted later.

sudo relay stop <id>

Redémarrer et mettre à niveau

Redémarre le service de relais et récupère la dernière configuration du proxy à partir d’Automation 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.

Scénario	Commande
Points de terminaison ajoutés ou supprimés dans Automation Cloud	sudo relay restart <id>
Client secret rotation (inline)	sudo relay restart --config "<new-config>"
Client secret rotation (file)	sudo relay restart --config-file /path/to/new-config.txt
Modification du niveau de journalisation	sudo relay restart <id> --log-level debug
Consigner le répertoire ou la modification de la rétention	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>

Remarque :

When --config or --config-file is provided, the <id> argument is optional. It is extracted from the configuration.

Supprimer (Delete)

Arrête le service, annule l'inscription d'Automation Cloud et supprime tous les fichiers de configuration et journaux locaux.

sudo relay delete <id>

To force local cleanup without cloud deregistration, for example if credentials are lost or the cloud-side relay group has already been deleted:

sudo relay delete <id> --force

Version

relay version

Remarque :

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

Structure du répertoire

Tous les répertoires sont créés automatiquement lors de la première exécution.

/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

Autorisations de fichier

Chemin d'accès	Mode	Raison
Répertoires	755	Accès en lecture/écriture au relais
client_config	600	Contient des informations d’identification OAuth chiffrées
.credentials.key	600	Clé de chiffrement AES-256-GCM
metadata.json	644	Métadonnées de service (état, PID, horodatage d'installation)
onprem-executor.jar	600	Executor runtime copied into protected service storage
relay.log	644	Libellé à des fins de résolution des problèmes
Binaire	755	Exécutable par 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.

Chemins d’accès personnalisés

Remplacez les répertoires par défaut lors de l’installation du client de relais.

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

Drapeau	Default	Description
--bin-dir	/usr/local/bin	Répertoire pour le fichier binaire partagé
--data-dir	/var/lib	Racine pour les données de configuration
--logs-dir	/var/log	Racine pour les fichiers journaux; peut être modifié avec restart

Le client de relais ajoute uipath-relay/ sous les données personnalisées et les racines du journal:

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

Remarque :

--bin-dir et --data-dir ne sont acceptés que par la commande start . --logs-dir est accepté par start et restart. Les autres commandes (stop, delete, list) dérivent automatiquement des chemins à partir de la configuration du service installé.

Configuration du proxy

Si votre réseau achemine le trafic sortant via un proxy, exportez les variables d’environnement du proxy avant d’exécuter relay start. Utilisez sudo -E pour préserver l'environnement lors de l'élévation:

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

Sans -E, sudo réinitialise l'environnement et les paramètres du proxy sont perdus.

The Relay client writes the captured proxy variables as Environment= directives in the systemd unit file, so the background service uses them, not system-wide /etc/environment.

Pour mettre à jour le proxy après l'installation: exportez les nouvelles valeurs et exécutez sudo -E relay restart <id>.

Pour supprimer le proxy: unset HTTPS_PROXY HTTP_PROXY NO_PROXY, puis sudo relay restart <id>.

Pour vérifier ce que le service utilise: systemctl cat relay-<id> | grep -i environment.

Pour les schémas de proxy et l’authentification pris en charge, consultez la section du proxy dans le déploiement du client de relais.

Infrastructures de sécurité

Si votre environnement utilise SELinux, AppArgor ou fapolicy, assurez-vous que le fichier binaire du client de relais et ses répertoires de données sont autorisés.

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.

Sé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

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

Protection de l'application

Assurez-vous qu'aucun profil ne restreint /usr/local/bin/relay de l'accès au réseau ou des écritures de fichiers à /var/lib/uipath-relay/ et /var/log/uipath-relay/. Si vous utilisez des chemins personnalisés, remplacez-les en conséquence.

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.

Chemins à autoriser

Saisie de texte	Chemin par défaut
Binaire	/usr/local/bin/relay
Données	/var/lib/uipath-relay/
Journaux (Logs)	/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 vous avez utilisé --bin-dir, --data-dir ou --logs-dir, autorisez plutôt ces chemins personnalisés.

Mode utilisateur

Le mode utilisateur (--user-mode) installe le client de relais en tant que service utilisateur système au lieu d'un service système, ce qui lui permet de s'exécuter sans sudo. Il est adapté aux machines partagées et aux environnements restreints où l’accès root n’est pas disponible.

Prérequis

Prérequis	Détails (Details)
système 229+	Vérifier : systemctl --version
Répertoire d’accueil	Doit exister et appartenir à l’utilisateur cible
session utilisateur système	Vérification: systemctl --user is-system-running renvoie running ou degraded
Connexion SSH	Required. su / sudo su do not provide the D-Bus session that user services need
loginctl linger	Requis pour que le service persiste après la déconnexion et démarre au démarrage

Activer le linger (Unique, nécessite l'administrateur):

sudo loginctl enable-linger <username>

Sans délai, les services utilisateur s'arrêtent lorsque vous vous déconnectez et ne démarrent pas au démarrage.

Démarrer en mode utilisateur

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

Disposition du répertoire en mode utilisateur

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

Le chemin d'accès ~/.config/systemd/user/ ne peut pas être remplacé. Les chemins d'accès aux fichiers binaires, aux données et aux journaux peuvent être personnalisés avec --bin-dir, --data-dir et --logs-dir.

Commandes de gestion en mode utilisateur

Toutes les commandes fonctionnent sans sudo:

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

Quand utiliser le mode utilisateur

Scénario	Recommandé (Recommended)
Serveur de production avec accès root	Mode système (par défaut)
Machine partagée, aucun accès root	Mode utilisateur
Développement ou test	Mode utilisateur
Environnements sensibles à la sécurité	Mode système (chemin binaire inscriptible)

Désinstaller

1. Supprimez tous les clients de relais (utilisez relay list pour voir les groupes installés):

   sudo relay delete <id>
   

2. Supprimez le fichier binaire partagé:

   sudo rm /usr/local/bin/relay
   

3. Supprimez les données et les répertoires de journaux restants:

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

Pour le mode utilisateur, remplacez les commandes par les équivalents en mode utilisateur (pas sudo) et supprimez ~/.local/bin/relay et ~/.local/share/uipath-relay.

Résolution des problèmes

Symptôme	Origine	Résolution
Le service ne démarre pas	Autorisations insuffisantes	Exécuter avec sudo
permission denied	Impossible de créer des répertoires	Vérifiez l’accès sudo ou utilisez des chemins personnalisés vers un emplacement inscriptible
systemctl: command not found	non installé	Utiliser le mode premier plan (--detach=false) ou installer systemd
Le service démarre puis s’arrête immédiatement	Erreur de configuration ou de réseau	Consultez relay.log pour obtenir les erreurs de démarrage
Service en cours d’exécution, mais tunnel non établi	Problème de réseau ou d'authentification	Consultez relay.log pour obtenir les erreurs login to server ; vérifiez la connectivité à cloud.uipath.com; pour les versions de client de relais antérieures à 26.4.2, vérifiez la transmission TLS au nom d’hôte du relais régional
Blocage de l'exécution par SELinux ou AppArgor	Politique d’infrastructure de sécurité	Voir Infrastructures de sécurité
XDG_RUNTIME_DIR not found (mode utilisateur)	Non connecté via SSH	Connectez-vous via SSH ou activez le persistant
D-Bus session bus unreachable (mode utilisateur)	Non connecté via SSH	Connectez-vous via SSH ou activez le persistant
Proxy non utilisé par le service	Variable non capturée au début	Réexécuter avec sudo -E ou vérifier avec systemctl cat relay-<id> | grep -i environment
Processeur ou mémoire élevé	Niveau de journal défini sur trace ou debug	Définir le niveau de journalisation sur info ou plus

Commandes de diagnostic

# 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

Pour les erreurs d'authentification et de connectivité partagées entre les plates-formes, voir Résolution des problèmes.

Référence rapide

Action	Commande
Démarrer (Start)	sudo relay start --config-file config.txt --accept-license-agreement
Arrêter	sudo relay stop <id>
Redémarrer/Mettre à niveau	sudo relay restart <id>
Supprimer (Delete)	sudo relay delete <id>
Supprimer (forcer)	sudo relay delete <id> --force
List	relay list
Décrire	relay describe <id>
Journaux (Logs)	relay logs <id> -f
État du service	systemctl status relay-<id>
Journal système	journalctl -u relay-<id> -f