Déploiement du client de relais sur Linux

Cette page couvre les détails de la configuration de production spécifiques à Linux. Pour les prérequis multiplate-formes, les exigences de mise en réseau, consultez le déploiement du client de relais.

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.

Liste de contrôles avant l’installation

Système

• Distribution Linux prise en charge avec systemd 229+
• Accès à sudo (root) — ou prévoir d'utiliser --user-mode
• 200 Mo d’espace disque libre minimum

Réseau

• Le protocole HTTPS sortant (port 443) vers cloud.uipath.com est autorisé
• Le TLS sortant (port 443) vers <region>-relay.uipath.com est autorisé
• Autorisation TLS configurée pour le point de terminaison du relais (aucune inspection TLS)
• Le nœud Relay dispose d’un accès réseau à tous les services locaux que vous prévoyez d’exposer

Sécurité

• Exclusions SELinux / AppArgor / fapolicy configurées (le cas échéant) — voir Infrastructures de sécurité

Configuration

• Groupe de relais créé et chaîne de configuration client prête — consultez Configuration d'un groupe de relais

Commandes de validation

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

# Verify sudo access
sudo -v

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

Démarrage rapide

1. Télécharger et extraire

Architecture	Archiver
x86_64	Relay-linux-amd64.zip
ARM64	Relay-linux-am64.zip

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

2. Démarrer

Vous pouvez fournir la chaîne de configuration client (à partir de l’administration UiPath — consultez Configuration d'un groupe de relais) de deux manières:

Option A — En ligne. Transmettez la chaîne de configuration directement. Aucun fichier à créer ou à nettoyer:

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

Option B — Fichier. Enregistrez la configuration dans un fichier, puis référencez-la. Recommandé — maintient le secret en dehors de l’historique du shell:

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

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.

Le client de relais valide la connectivité, s'authentifie avec OAuth, s'enregistre avec Automation Cloud, télécharge la configuration du proxy, chiffre les identifiants et installe un service systemd — le tout dans une seule commande.

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>

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

Gérer (Manage)

List

Affiche tous les groupes de Relay installés sur cette machine avec le statut et la version. Ne nécessite pas sudo.

relay list
relay list --json

Arrêter

Arrête le service de relais. La configuration et les journaux sont conservés — le relais peut être redémarré ultérieurement.

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>

Mise à niveau binaire: téléchargez le nouveau binaire relay et exécutez sudo ./relay restart <id> à partir de celui-ci. La commande de redémarrage compare le binaire en cours d'exécution à la copie installée par hachage SHA256 et met à jour automatiquement le binaire installé s'il diffère.

Scénario	Commande
Points de terminaison ajoutés ou supprimés dans Automation Cloud	sudo relay restart <id>
Rotation de la clé secrète du client — en ligne	sudo relay restart --config "<new-config>"
Rotation de la clé secrète du client — fichier	sudo relay restart --config-file /path/to/new-config.txt
Mise à niveau binaire	Télécharger le nouveau binaire, puis sudo ./relay restart <id>

Lorsque --config ou --config-file est fourni, l'argument <id> est facultatif — il est extrait de la 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>

Pour forcer le nettoyage local sans désenregistrement du cloud, par exemple si les informations d’identification sont perdues ou si le groupe de Relay côté cloud a déjà été supprimé:

sudo relay delete <id> --force

Version

relay version

Il n'y a pas de mise à niveau automatique. Pour mettre à jour, téléchargez le nouveau binaire et exécutez sudo ./relay restart <id> pour chaque groupe.

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)

/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

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)
relay.log	644	Libellé à des fins de résolution des problèmes
Binaire	755	Exécutable par systemd

Chemins d’accès personnalisés

Remplacer les répertoires par défaut au moment de l’installation:

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

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

--bin-dir, --data-dir, et --logs-dir ne sont acceptés que par la commande start . Les autres commandes (stop, restart, 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>"

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

Le client de relais écrit les variables de proxy capturées sous forme de Environment= instructions dans le fichier d'unité système, de sorte que le service en arrière-plan les utilise, et non l'échelle du système /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.

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

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.

Fapolicyd

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

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/

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	Requis: su / sudo su ne fournissent pas la session D-Bus dont les services utilisateur ont besoin
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

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

~/.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érifier la transmission TLS
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 <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
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
Journaux (Logs)	relay logs <id> -f
État du service	systemctl status relay-<id>
Journal système	journalctl -u relay-<id> -f