Déploiement du client de relais sous Windows

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

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

Le client de relais utilise Windows Service Control Manager pour installer et gérer son service en arrière-plan. SCM est intégré à toutes les versions Windows prises en charge; aucun logiciel supplémentaire n’est requis.

Édition	Version minimale
Windows Server	2019
Bureau Windows	10 Entreprise

Exigences supplémentaires

• PowerShell 5.1+ — inclus par défaut; utilisé pour la gestion du service (Get-Service, Test-NetConnection). Vérification: $PSVersionTable.PSVersion.
• Privilèges d'administrateur — requis pour interagir avec SCM dans le cadre de l'installation, du démarrage, de l'arrêt et de la suppression du service; écrire dans C:\ProgramData\UiPathRelay\; copiez le binaire dans C:\Program Files\UiPathRelay\.

Par défaut, le service s'exécute en tant que LocalSystem. Pour vous exécuter sous un compte spécifique, utilisez --service-account au moment du début — voir Compte de service et autorisations.

Liste de contrôles avant l’installation

Système

• Windows Server 2019+ ou Windows 10 Enterprise+
• PowerShell 5.1 ou version ultérieure
• Accès de l’administrateur à la machine cible
• 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é

• Compte de service créé (si vous n'utilisez pas LocalSystem) — voir Compte de service et autorisations
• Exclusions Windows Plus et antivirus planifiées — voir Protection antivirus et protection des points de terminaison

Configuration

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

Commandes de validation (exécutées dans PowerShell):

# Check PowerShell version (must be 5.1+)
$PSVersionTable.PSVersion

# Verify Administrator access
([Security.Principal.WindowsPrincipal][Security.Principal.WindowsIdentity]::GetCurrent()).IsInRole([Security.Principal.WindowsBuiltInRole]::Administrator)

# Check available disk space
Get-PSDrive C | Select-Object Used, Free

Installer

1. Télécharger et extraire

Architecture	Archiver
x86_64	Relay-windows-amd64.zip
ARM64	Relay-windows-ARM64.zip

Extrayez l'archive zip. Il contient un seul binaire relay.exe prêt à être exécuté.

2. Démarrer

Ouvrez PowerShell en tant qu'administrateur avant d'exécuter une commande de démarrage.

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:

.\relay.exe 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:

Set-Content -Path "config.txt" -Value "<your-config>"
.\relay.exe start --config-file C:\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 Relay valide la connectivité, s'authentifie avec OAuth, s'enregistre avec Test Cloud, télécharge la configuration du proxy et installe un service Windows — 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:
  PowerShell: Get-Service "Relay-<id>"
  Services:   services.msc (look for "Relay - <id>")

Lors du démarrage, le client de relais copie automatiquement le binaire dans C:\Program Files\UiPathRelay\relay.exe. Tous les groupes de Relay sur la machine partagent ce fichier binaire unique. Remplacez le répertoire d'installation par --bin-dir.

Pour démarrer sous un compte de service personnalisé au lieu de LocalSystem:

.\relay.exe start --config-file C:\path\to\config.txt `
  --service-account "DOMAIN\svc-relay" `
  --service-account-password "password"

3. Vérifier

.\relay.exe list

Un client sain affiche ● running dans la colonne STATUT. La valeur ID affichée est utilisée dans toutes les commandes suivantes (.\relay.exe stop <id>, .\relay.exe 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:

.\relay.exe logs <id> -f

Gérer (Manage)

Toutes les commandes de gestion nécessitent Administrator PowerShell, à l'exception de list et version.

List

Affiche tous les groupes de Relay installés sur cette machine avec le statut et la version. Ne nécessite pas de privilèges d’administrateur.

.\relay.exe list
.\relay.exe 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.

.\relay.exe stop <id>

Redémarrer et mettre à niveau

Redémarre le service de relais et récupère la dernière configuration du proxy dans Test Cloud.

.\relay.exe restart <id>

Mise à niveau binaire: téléchargez le nouveau relay.exe et exécutez .\relay.exe 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 Test Cloud	.\relay.exe restart <id>
Rotation de la clé secrète du client — en ligne	.\relay.exe restart --config "<new-config>"
Rotation de la clé secrète du client — fichier	.\relay.exe restart --config-file new-config.txt
Mise à niveau binaire	Télécharger le nouveau binaire, puis .\relay.exe 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'enregistrement de Test Cloud et supprime tous les fichiers de configuration et journaux locaux.

.\relay.exe 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é:

.\relay.exe delete <id> --force

Version

.\relay.exe version

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

Structure du répertoire

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

C:\Program Files\UiPathRelay\
  relay.exe                                  # Shared binary

C:\ProgramData\UiPathRelay\
  groups\<id>\
    client_config                            # OAuth credentials (encrypted via DPAPI)
    metadata.json                            # State, PID, install timestamps
    .credentials.key                         # Encryption key
  logs\<id>\
    relay.log                                # Current log
    relay.YYYYMMDD-HHMMSS.log                # Rotated logs

Le nom du service Windows est Relay-<id> et le nom complet (affiché dans services.msc) est Relay - <id>. Le type de démarrage est Automatique; le compte par défaut est LocalSystem.

Chemins d’accès personnalisés

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

.\relay.exe start --config-file C:\path\to\config.txt `
  --bin-dir "D:\MyCompany\bin" `
  --data-dir "D:\MyCompany" `
  --logs-dir "D:\MyCompany"

Drapeau	Default	Description
--bin-dir	C:\Program Files\UiPathRelay	Répertoire pour le fichier binaire partagé
--data-dir	C:\ProgramData	Racine pour les données de configuration
--logs-dir	C:\ProgramData	Racine pour les fichiers journaux

Le client de relais ajoute UiPathRelay\ sous les données personnalisées et les racines du journal:

--bin-dir  D:\MyCompany\bin  =>  D:\MyCompany\bin\relay.exe
--data-dir D:\MyCompany      =>  D:\MyCompany\UiPathRelay\groups\<id>\
--logs-dir D:\MyCompany      =>  D:\MyCompany\UiPathRelay\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écouvrez automatiquement des chemins à partir de la configuration du service installé.

Compte de service et autorisations

Cette section s’applique uniquement lors de l’exécution du service sous un compte personnalisé au lieu du compte par défaut LocalSystem.

Droits d’utilisateur requis

Droite	Description	Comment configurer
SeServiceLogonRight	Ouvrir une session en tant que service	Stratégie de sécurité locale > Attribution des droits d’utilisateur > Se connecter en tant que service

Pour les environnements de domaine, configurez ce droit via la stratégie de groupe pour garantir la cohérence entre les serveurs.

Autorisations NTFS

Chemin d'accès	Autorisations requises
C:\Program Files\UiPathRelay\	Read & Execute
C:\ProgramData\UiPathRelay\	Lire, Écrire, Modifier
C:\ProgramData\UiPathRelay\logs\	Lire, Écrire, Modifier, Supprimer

Via PowerShell

$account = "DOMAIN\svc-relay"

$acl = Get-Acl "C:\Program Files\UiPathRelay"
$rule = New-Object System.Security.AccessControl.FileSystemAccessRule($account, "ReadAndExecute", "ContainerInherit,ObjectInherit", "None", "Allow")
$acl.SetAccessRule($rule)
Set-Acl "C:\Program Files\UiPathRelay" $acl

$acl = Get-Acl "C:\ProgramData\UiPathRelay"
$rule = New-Object System.Security.AccessControl.FileSystemAccessRule($account, "Modify", "ContainerInherit,ObjectInherit", "None", "Allow")
$acl.SetAccessRule($rule)
Set-Acl "C:\ProgramData\UiPathRelay" $acl

À partir d'un compte de service personnalisé

.\relay.exe start --config-file C:\path\to\config.txt `
  --service-account "DOMAIN\svc-relay" `
  --service-account-password "password"

--service-account-password est requis pour le domaine ou les comptes d'utilisateurs locaux. Les comptes de service gérés ne nécessitent pas de mot de passe.

Comptes de service gérés de groupe

# Install the gMSA on the server (run once per server)
Install-ADServiceAccount -Identity "gMSA-Relay$"

# Start the Relay client with gMSA (no password required)
.\relay.exe start --config-file config.txt --service-account "DOMAIN\gMSA-Relay$"

Les gMSA font automatiquement pivoter les mots de passe et éliminent les frais généraux liés à la gestion des informations d’identification.

Détails du service Windows

Affichage du statut du service

Via la console de services

1. Ouvrez Exécuter (Win + R) et saisissez services.msc.
2. Localisez le service avec le nom complet Relay - <id>.
3. Cliquez avec le bouton droit pour démarrer, arrêter, redémarrer ou afficher les propriétés.

Via PowerShell

# All Relay services
Get-Service "Relay-*"

# Detailed information
Get-Service "Relay-<id>" | Format-List *

# Service configuration (account, start mode)
Get-CimInstance Win32_Service -Filter "Name LIKE 'Relay-%'" | Select-Object Name, StartMode, State, StartName

Récupération du service

Lorsque le client de relais s'installe en tant que service, il configure la récupération automatique:

• Premier échec: redémarrer après 10 secondes
• Deuxième échec: redémarrer après 30 secondes
• Échecs suivants: redémarrer avec des délais d'escalade

Pour examiner ou ajuster les paramètres de récupération: ouvrez services.msc > cliquez droit sur le service > Propriétés > onglet Récupération .

Visionneuse d'événements

Utilisez l’Observateur d’événements (eventvwr.msc) pour diagnostiquer les problèmes de service.

Journal (Log)	Chemin d'accès	Events
Système	Journaux Windows > Système	Démarrage, arrêt, panne et récupération du service (série 7 000)
Application	Journaux Windows > Application	Erreurs d’application

Interroger les événements de Relay via PowerShell

Get-WinEvent -FilterHashtable @{LogName='System'; ID=7000,7009,7031,7034,7036,7045} -MaxEvents 100 |
  Where-Object { $_.Message -like '*Relay*' } |
  Format-Table TimeCreated, Id, Message -Wrap

ID d'événement	Signification
7000	Le service n’a pas pu démarrer — vérifiez les autorisations du compte
7009	Délai en attente de service — vérifiez la connectivité du réseau
7031	Le service a planté et action de récupération entreprise - vérifier relay.log
7034	Service terminé de manière inattendue — vérifiez l'épuisement des ressources
7045	Nouveau service installé — confirme l'installation réussie

Configuration du proxy

Les services Windows héritent des variables d’environnement du système. Définissez les variables de proxy au niveau de la machine avant de démarrer le client de relais:

[Environment]::SetEnvironmentVariable("HTTPS_PROXY", "http://proxy.corp.example.com:8080", "Machine")
[Environment]::SetEnvironmentVariable("NO_PROXY", "localhost,127.0.0.1,.corp.example.com", "Machine")
.\relay.exe start --config "<your-config>"

Définir des variables de proxy au niveau de l'utilisateur n'est pas suffisant — les services système ignorent les variables d'environnement au niveau de l'utilisateur.

Pour mettre à jour le proxy: modifiez la variable au niveau du système et exécutez .\relay.exe restart <id>.

Pour supprimer le proxy: [Environment]::SetEnvironmentVariable("HTTPS_PROXY", $null, "Machine"), puis .\relay.exe restart <id>.

À vérifier: [Environment]::GetEnvironmentVariable("HTTPS_PROXY", "Machine").

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.

Pare-feu Windows

Si le trafic sortant est restreint par le pare-feu Windows, ajoutez une règle sortante pour le fichier binaire du client de relais.

Paramètre	Valeur (Value)
Direction	Sortant
Programme	C:\Program Files\UiPathRelay\relay.exe
Protocole/Port	TCP/443
Profils	Domaine, privé

Via PowerShell

New-NetFirewallRule -DisplayName "UiPath Relay - Outbound HTTPS" `
  -Direction Outbound `
  -Program "C:\Program Files\UiPathRelay\relay.exe" `
  -Protocol TCP `
  -RemotePort 443 `
  -Action Allow `
  -Profile Domain,Private

# Verify rule
Get-NetFirewallRule -DisplayName "UiPath Relay*" | Format-Table Name, Enabled, Direction, Action

Via GUI (pare-feu Windows Pare-feu avec sécurité avancée):

1. Ouvrez wf.msc.
2. Sélectionnez Règles sortantes > Nouvelle règle.
3. Choisissez Program et spécifiez: C:\Program Files\UiPathRelay\relay.exe.
4. Sélectionnez Autoriser la connexion.
5. Appliquer aux profils de domaine et privés .
6. Nommez la règle: UiPath Relay - Outbound HTTPS.

Si votre organisation gère les règles de pare-feu via une stratégie de groupe ou un pare-feu tiers, adressez-vous à votre administrateur Windows afin d'ajouter une règle équivalente.

Protection antivirus et des points de terminaison

Ajoutez des exceptions pour le fichier binaire du client de relais et ses répertoires de données afin d’éviter toute interférence.

Saisie de texte	Chemin d'accès
Binaire	C:\Program Files\UiPathRelay\relay.exe
Données et journaux	C:\ProgramData\UiPathRelay\

Si vous avez utilisé des chemins personnalisés via --bin-dir, --data-dir ou --logs-dir, excluez plutôt ces chemins.

Windows Protection — via PowerShell

Add-MpPreference -ExclusionPath "C:\Program Files\UiPathRelay"
Add-MpPreference -ExclusionPath "C:\ProgramData\UiPathRelay"
Add-MpPreference -ExclusionProcess "relay.exe"

Windows Protection — par l'interface graphique

1. Ouvrez Sécurité Windows > Protection contre les virus et les menaces > Gérer les paramètres.
2. Sous Exclusions, sélectionnez Ajouter ou supprimer des exclues.
3. Ajoutez des exceptions de dossier: C:\Program Files\UiPathRelay\ et C:\ProgramData\UiPathRelay\
4. Ajoutez l’exclusion de processus: relay.exe

Pour la protection des points de terminaison gérée de manière centralisée, travaillez avec votre administrateur de sécurité pour ajouter les extractions ci-dessus.

Désinstaller

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

   .\relay.exe delete <id>
   

2. Supprimez le fichier binaire partagé:

   Remove-Item "C:\Program Files\UiPathRelay" -Recurse
   

3. Supprimer les répertoires de données restants:

   Remove-Item "C:\ProgramData\UiPathRelay" -Recurse
   

4. Supprimez les exclues Windows Définir:

   Remove-MpPreference -ExclusionPath "C:\Program Files\UiPathRelay"
   Remove-MpPreference -ExclusionPath "C:\ProgramData\UiPathRelay"
   Remove-MpPreference -ExclusionProcess "relay.exe"
   

5. Supprimez la règle Pare-feu Windows:

   Remove-NetFirewallRule -DisplayName "UiPath Relay - Outbound HTTPS"
   

Pour les règles ajoutées via la stratégie de groupe ou un pare-feu tiers, adressez-vous à votre administrateur Windows pour les supprimer.

Résolution des problèmes

Symptôme	Origine	Résolution
Le service ne démarre pas	Autorisations insuffisantes	Ouvrez PowerShell en tant qu'administrateur.
permission denied	Impossible d’écrire dans Fichiers de programme ou DonnéesProgramme	Vérifiez l’accès de l’administrateur ou utilisez --bin-dir / --data-dir pour les chemins inscriptibles
does not have the 'Log on as a service' right	Compte personnalisé manquant SeServiceLogonRight	Accorder via la stratégie de sécurité locale > Attribution des droits d’utilisateur ou utiliser la stratégie de groupe
not a valid Windows account	Format incorrect pour --service-account	Utilisez .\username pour les comptes locaux ou DOMAIN\username pour les comptes de domaine
marked for deletion /service - suppression en attente	services.msc a un handle ouvert	Fermez services.msc et réessayez; redémarrer si le problème persiste
service is disabled	Désactivé via services.msc ou la stratégie de groupe	Réactiver: Set-Service -Name "Relay-<id>" -StartupType Automatic
file is locked by another process	Binaire utilisé lors de la mise à jour	Arrêtez d’abord le service du client de relais, puis réessayez
path exceeds Windows path length limit	Le chemin des données/journaux dépasse la limite de 260 caractères	Utilisez des chemins plus courts pour --data-dir et --logs-dir
Blocage des antivirus relay.exe	Fichier binaire mis en quarantaine par la protection des points de terminaison	Ajoutez des exceptions (voir Protection antivirus et protection des points de terminaison); vérifier la mise en quarantaine et restaurer
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
DPAPI decrypt failed	L'identité de la machine a été modifiée après le clonage ou le réimage de la machine virtuelle	Réenregistrer le relais avec une nouvelle configuration à partir de l'administration UiPath
Proxy non utilisé par le service	Proxy défini au niveau de l’utilisateur, et non au niveau du système	Définissez HTTPS_PROXY au niveau de la machine (voir Configuration du proxy); redémarrer le service

Commandes de diagnostic

# Real-time logs
.\relay.exe logs <id> -f

# Service details
Get-Service "Relay-<id>" | Format-List *

# Connectivity test
Test-NetConnection -ComputerName <region>-relay.uipath.com -Port 443

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)	.\relay.exe start --config-file config.txt
Arrêter	.\relay.exe stop <id>
Redémarrer/Mettre à niveau	.\relay.exe restart <id>
Supprimer (Delete)	.\relay.exe delete <id>
Supprimer (forcer)	.\relay.exe delete <id> --force
List	.\relay.exe list
Journaux (Logs)	.\relay.exe logs <id> -f
État du service	Get-Service "Relay-<id>"
Console des services	services.msc