Bereitstellen des Relay-Clients unter Linux

Diese Seite behandelt Details zur Produktionseinrichtung, die für Linux spezifisch sind. Informationen zu plattformübergreifenden Voraussetzungen und Netzwerkanforderungen finden Sie unter Bereitstellen des Relay-Clients.

Anforderungen des Betriebssystems

Der Relay-Client erfordert systemd 229 oder höher. Zu überprüfen: systemctl --version.

Verteilung	Mindestversion
Ubuntu	20.04 LTS (Fokal)
Deian	10 (Buser)
Red Hat Enterprise Linux	8
Amazon Linux	2023
SVerwenden Sie Linux Enterprise Server	15
Oracle Linux	8

Es wird erwartet, dass jede Linux-Distribution mit systemd 229+ funktioniert. Für Umgebungen ohne systemd kann der Relay-Client im Vordergrundmodus (--detach=false) ausgeführt werden, aber Sie sind für die Prozessverwaltung, den Autostart und die Wiederherstellung verantwortlich.

Erforderliche Berechtigungen: sudo -Stammzugriff ist erforderlich, um systemd-Dienste (/etc/systemd/system/) zu installieren, Standarddaten- und Protokollverzeichnisse zu erstellen und die Binärdatei nach /usr/local/bin/ zu kopieren. Informationen zu stammlosen Installationen finden Sie unter Benutzermodus.

Checkliste vor der Installation

System

• Unterstützte Linux-Distribution mit Systemd 229+
• sudo -Zugriff (Stamm) – oder Sie planen die Verwendung --user-mode
• Mindestens 200 MB freier Speicherplatz

Netzwerk

• Ausgehende HTTPS (Port 443) nach cloud.uipath.com ist zulässig
• Ausgehende TLS (Port 443) nach <region>-relay.uipath.com ist zulässig
• TLS-Password für den Relay-Endpunkt konfiguriert (keine TLS-Prüfung)
• Der Relay-Knoten hat Netzwerkzugriff auf alle lokalen Dienste, die Sie verfügbar machen möchten

Sicherheit

• konfigurierte SELinux-/AppARMor-/fapolicyd-Ausnahmen (falls zutreffend) – siehe Sicherheitsframeworks

Konfiguration

• Relay-Gruppe erstellt und Client-Konfigurationszeichenfolge bereit – siehe Konfigurieren einer Relay-Gruppe

Validierungsbefehle

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

# Verify sudo access
sudo -v

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

Installieren

1. Herunterladen und Extrahieren

Architektur	Archiv (Archive)
x86_64	Relay-linux-amd64.zip
ARM64	Relay-linux-arm64.zip

unzip relay_linux_amd64.zip && chmod +x relay

2. Starten

Sie können die Client-Konfigurationszeichenfolge (über die UiPath-Verwaltung – siehe Konfigurieren einer Relay-Gruppe) auf zwei Arten bereitstellen:

Option A – Inline. Übergeben Sie die Konfigurationszeichenfolge direkt. Keine Datei zum Erstellen oder Bereinigen:

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

Option B – Datei. Speichern Sie die Konfiguration in einer Datei und verweisen Sie dann darauf. Empfohlen – hält das Geheimnis aus dem Shell-Verlauf heraus:

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

Die Flags --config und --config-file schließen sich gegenseitig aus. Um im Vordergrund statt als Hintergrunddienst ausgeführt zu werden (nützlich für das Debuggen), übergeben Sie --detach=false.

Der Relay-Client validiert die Verbindung, authentifiziert sich bei OAuth, registriert sich bei der Test Cloud, lädt die Proxykonfiguration herunter, verschlüsselt Anmeldeinformationen und installiert einen systemd-Dienst – alles in einem einzigen Befehl.

Erwartete Ausgabe:

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>

Während des Starts kopiert der Relay-Client automatisch die Binärdatei nach /usr/local/bin/relay. Alle Relay-Gruppen auf der Maschine teilen sich diese einzelne Binärdatei. Überschreiben Sie das Installationsverzeichnis mit --bin-dir.

3. Überprüfen

relay list

Ein fehlerfreier Client zeigt ● running in der Spalte Status an. Der angezeigte ID -Wert wird in allen nachfolgenden Befehlen verwendet (relay stop <id>, relay logs <id> usw.). Sie finden sie auch in der UiPath-Verwaltung auf der Seite mit den Details zur Relay-Gruppe.

Bestätigen Sie, dass der Tunnel eingerichtet ist, indem Sie die Protokolle auf login to server success überprüfen:

sudo relay logs <id> -f

Verwalten

Liste

Zeigt alle installierten Relay-Gruppen auf dieser Maschine mit Status und Version an. Erfordert nicht sudo.

relay list
relay list --json

Stoppen

Stoppt den Relay-Dienst. Konfiguration und Protokolle werden beibehalten – der Relay-Dienst kann später neu gestartet werden.

sudo relay stop <id>

Neustart und Upgrade

Startet den Relay-Dienst neu und ruft die neueste Proxykonfiguration aus der Test Cloud ab.

sudo relay restart <id>

Binäres Upgrade: Laden Sie die neue relay -Binärdatei herunter und führen Sie sudo ./relay restart <id> damit aus. Der Befehl „Neustart“ vergleicht die laufende Binärdatei mit der installierten Kopie per SHA256-Hash und aktualisiert die installierte Binärdatei automatisch, wenn sie sich unterscheiden.

Szenario	Befehl
In der Test Cloud hinzugefügte oder entfernte Endpunkte	sudo relay restart <id>
Rotation des geheimen Clientschlüssels – inline	sudo relay restart --config "<new-config>"
Rotation des geheimen Clientschlüssels – Datei	sudo relay restart --config-file /path/to/new-config.txt
Binäres Upgrade	Dann neue Binärdatei herunterladen sudo ./relay restart <id>

Wenn --config oder --config-file angegeben ist, ist das <id> -Argument optional – es wird aus der Konfiguration extrahiert.

Löschen

Stoppt den Dienst, meldet sich von der Test Cloud ab und entfernt alle lokalen Konfigurations- und Protokolldateien.

sudo relay delete <id>

So erzwingen Sie die lokale Bereinigung ohne Cloud-Deregistrierung – z. B. wenn Anmeldeinformationen verloren gehen oder die cloudseitige Relay-Gruppe bereits gelöscht wurde:

sudo relay delete <id> --force

Version

relay version

Es gibt kein automatisches Upgrade. Zum Aktualisieren laden Sie die neue Binärdatei herunter und führen sudo ./relay restart <id> für jede Gruppe aus.

Verzeichnisstruktur

Alle Verzeichnisse werden bei der ersten Ausführung automatisch erstellt.

/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

Dateiberechtigungen

Pfad	Mode	Grund
Verzeichnisse	755	Relay-Lese-/Schreibzugriff
client_config	600	Enthält verschlüsselte OAuth-Anmeldeinformationen
.credentials.key	600	AES-256-GCM-Verschlüsselungsschlüssel
metadata.json	644	Dienstmetadaten (Status, PID, Installationszeitstempel)
relay.log	644	Für Fehlerbehebung lesbar
Binär	755	Ausführbar von systemd

Benutzerdefinierte Pfade

Überschreiben Sie die Standardverzeichnisse zum Zeitpunkt der Installation:

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

Markieren	Standard	Beschreibung
--bin-dir	/usr/local/bin	Verzeichnis für die freigegebene Binärdatei
--data-dir	/var/lib	Stamm für Konfigurationsdaten
--logs-dir	/var/log	Stamm für Protokolldateien

Der Relay-Client fügt uipath-relay/ unter den benutzerdefinierten Daten- und Protokollstammsätzen an:

--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 und --logs-dir werden nur vom Befehl start akzeptiert. Andere Befehle (stop, restart, delete, list) leiten Pfade automatisch von der Konfiguration des installierten Dienstes ab.

Proxykonfiguration

Wenn Ihr Netzwerk ausgehenden Datenverkehr über einen Proxy weiterleitet, exportieren Sie die Proxy-Umgebungsvariablen, bevor Sie relay start ausführen. Verwenden Sie sudo -E , um die Umgebung bei der Erhöhung zu erhalten:

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

Ohne -E setzt sudo die Umgebung zurück, und die Proxyeinstellungen gehen verloren.

Der Relay-Client schreibt die erfassten Proxy-Variablen als Environment= -Anweisungen in die Datei für die Systemeinheit, sodass der Hintergrunddienst sie verwendet – nicht systemübergreifend /etc/environment.

So aktualisieren Sie den Proxy nach der Installation: Exportieren Sie die neuen Werte und führen Sie sudo -E relay restart <id> aus.

So entfernen Sie den Proxy: unset HTTPS_PROXY HTTP_PROXY NO_PROXY und dann sudo relay restart <id>.

So überprüfen Sie, was der Dienst verwendet: systemctl cat relay-<id> | grep -i environment.

Unterstützte Proxyschemas und Authentifizierung finden Sie im Abschnitt Proxy unter Bereitstellen des Relay-Clients.

Sicherheitsframeworks

Wenn Ihre Umgebung SELinux, AppARMor oder fapolicyd verwendet, stellen Sie sicher, dass die Relay-Client-Binärdatei und ihre Datenverzeichnisse zulässig sind.

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

Stellen Sie sicher, dass kein Profil /usr/local/bin/relay beim Netzwerkzugriff einschränkt oder Dateischreibvorgänge in /var/lib/uipath-relay/ oder /var/log/uipath-relay/ schreibt. Wenn Sie benutzerdefinierte Pfade verwenden, ersetzen Sie sie entsprechend.

fapolicyd

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

Pfade, die zugelassen werden sollen

Typ	Standardpfad
Binär	/usr/local/bin/relay
Daten	/var/lib/uipath-relay/
Protokolle	/var/log/uipath-relay/

Wenn Sie --bin-dir, --data-dir oder --logs-dir verwendet haben, lassen Sie stattdessen diese benutzerdefinierten Pfade zu.

Benutzermodus

Der Benutzermodus (--user-mode) installiert den Relay-Client als systemd-Benutzerdienst anstelle eines Systemdiensts, sodass er ohne sudo ausgeführt werden kann. Dies ist für gemeinsam genutzte Maschinen und eingeschränkte Umgebungen geeignet, in denen kein Stammzugriff verfügbar ist.

Anforderungen

Anforderungen	Details
systemd 229+	Überprüfen Sie: systemctl --version
Basisverzeichnis	Muss vorhanden sein und dem Zielbenutzer gehören
systemd-Benutzersitzung	Überprüfen: systemctl --user is-system-running gibt running oder degradedzurück
SSH-Anmeldung	Erforderlich – su / sudo su stellen nicht die D-Business-Sitzung bereit, die die Benutzerdienste benötigen
loginctl linger	Erforderlich, damit der Dienst nach der Abmeldung bestehen bleibt und beim Booten gestartet wird

Aktivieren Sie die Linging-Aktivität (einmalig, erfordert Administrator):

sudo loginctl enable-linger <username>

Ohne Linger Benutzerdienste werden angehalten, wenn Sie sich abmelden, und werden beim Booten nicht gestartet.

Starten Sie im Benutzermodus

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

Verzeichnislayout im Benutzermodus

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

Der Pfad ~/.config/systemd/user/ kann nicht überschrieben werden. Binär-, Daten- und Protokollpfade können mit --bin-dir, --data-dir und --logs-dir angepasst werden.

Verwaltungsbefehle im Benutzermodus

Alle Befehle funktionieren ohne sudo:

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

Wann der Benutzermodus verwendet werden soll

Szenario	Empfohlen
Produktionsserver mit Stammzugriff	Systemmodus (Standard)
Freigegebene Maschine, kein Stammzugriff	Benutzermodus
Entwicklung oder Tests	Benutzermodus
Sicherheitssensible Umgebungen	Systemmodus ( Manipulationssicherer Binärpfad)

Deinstallieren

1. Alle Relay-Clients löschen ( relay list verwenden, um installierte Gruppen anzuzeigen):

   sudo relay delete <id>
   

2. Entfernen Sie die freigegebene Binärdatei:

   sudo rm /usr/local/bin/relay
   

3. Entfernen Sie verbleibende Daten- und Protokollverzeichnisse:

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

Ersetzen Sie für den Benutzermodus die Befehle durch die Benutzermodus-Äquivalente (kein sudo) und entfernen Sie ~/.local/bin/relay und ~/.local/share/uipath-relay.

Fehlersuche und ‑behebung

Symptome	Ursache	Resolution
Dienst kann nicht gestartet werden	Unzureichende Berechtigungen	Ausführen mit sudo
permission denied	Verzeichnisse können nicht erstellt werden	Überprüfen Sie den sudo -Zugriff oder verwenden Sie benutzerdefinierte Pfade zu einem beschreibbaren Speicherort
systemctl: command not found	systemd nicht installiert	Verwenden Sie den Vordergrundmodus (--detach=false) oder installieren Sie systemd
Der Dienst wird gestartet und dann sofort angehalten	Konfigurations- oder Netzwerkfehler	Prüfen Sie relay.log auf Startfehler
Dienst wird ausgeführt, aber Tunnel nicht eingerichtet	Netzwerk- oder Authentifizierungsproblem	Prüfen Sie relay.log auf login to server Fehler; Überprüfen Sie die TLS-Weitergabe
SELinux oder AppARMor blockiert die Ausführung	Sicherheitsframeworkrichtlinie	Siehe Sicherheitsframeworks
XDG_RUNTIME_DIR not found (Benutzermodus)	Nicht über SSH angemeldet	Melden Sie sich über SSH an, oder aktivieren Sie die Linger-Aktivität
D-Bus session bus unreachable (Benutzermodus)	Nicht über SSH angemeldet	Melden Sie sich über SSH an, oder aktivieren Sie die Linger-Aktivität
Proxy wird vom Dienst nicht verwendet	Variable beim Start nicht erfasst	Mit sudo -E erneut ausführen oder mit systemctl cat relay-<id> | grep -i environmentüberprüfen
Hohe CPU oder hohe Arbeitsspeicher	Protokollebene auf trace oder debugfestgelegt	Legen Sie die Protokollebene auf info oder höher fest

Diagnosebefehle

# 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

Informationen zu Authentifizierungs- und Verbindungsfehlern, die plattformübergreifend genutzt werden, finden Sie unter Fehlerbehebung.

Schnellreferenz

Aktion	Befehl
Starten	sudo relay start --config-file config.txt
Stoppen	sudo relay stop <id>
Neustart/Upgrade	sudo relay restart <id>
Löschen	sudo relay delete <id>
Löschen (erzwingen)	sudo relay delete <id> --force
Liste	relay list
Protokolle	relay logs <id> -f
Status des Dienstes	systemctl status relay-<id>
Systemd-Judge	journalctl -u relay-<id> -f