Linux での Relay クライアントのデプロイ

このページでは、Linux に固有の運用設定の詳細について説明します。クロスプラットフォームの前提条件、ネットワーク要件については、「 リレークライアントのデプロイ」を参照してください。

オペレーティング システムの要件

Relay クライアントには systemd 229 以降が必要です。確認するには、以下の手順を実行します。 systemctl --version。

分布	最小バージョン
Ubuntu	20.04 LTS (フォーカル)
Debian	10(バスター)
Red Hat Enterprise Linux	8
Amazon Linux	2023 年
SUSE Linux Enterprise Server	15
Oracle Linux	8

systemd 229+ を搭載した Linux ディストリビューションであれば、すべて動作することが期待されます。systemd のない環境では、リレークライアントはフォアグラウンドモード (--detach=false) で実行できますが、プロセス管理、自動起動、およびリカバリはユーザーが担当します。

必要な権限: systemd サービス (/etc/systemd/system/) をインストールし、デフォルトのデータディレクトリとログディレクトリを作成し、バイナリを /usr/local/bin/にコピーするには、sudo (root) アクセスが必要です。ルートレス インストールの場合は、「 ユーザー モード」をご覧ください。

インストール前のチェックリスト

システム

• systemd 229+ でサポートされる Linux ディストリビューション
• sudo (root) アクセス — または使用する予定 --user-mode
• 最小 200 MB の空きディスク領域

ネットワーク

• cloud.uipath.com への送信 HTTPS (ポート 443) が許可されます
• <region>-relay.uipath.com への送信 TLS (ポート 443) が許可されます
• リレーエンドポイントに設定されたTLSパススルー(TLSインスペクションなし)
• リレー ノードは、公開する予定のすべてのオンプレミス サービスにネットワーク アクセスできます

セキュリティ

• SELinux / AppArmor / fapolicyd の除外が構成されている (該当する場合) — 「セキュリティ フレームワーク」をご覧ください

構成

• Relay グループが作成され、クライアント設定文字列が準備完了 — 「Relay グループを設定する」を参照してください。

検証コマンド

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

# Verify sudo access
sudo -v

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

インストール

1. ダウンロードして抽出する

アーキテクチャ	アーカイブ
x86_64	relay-linux-amd64.zip
ARM64	relay-linux-arm64.zip

unzip relay_linux_amd64.zip && chmod +x relay

2. 開始

クライアント設定文字列を (UiPath Administration から提供 — 「Relay グループを設定する」を参照) は、次の 2 つの方法で指定できます。

オプション A — インライン。構成文字列を直接渡します。作成またはクリーンアップするファイルがない :

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

オプション B — ファイル。設定をファイルに保存し、参照します。推奨 — シェルの履歴から秘密を隠します。

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

--config フラグと --config-file フラグは相互に排他的です。バックグラウンド サービスとしてではなくフォアグラウンドで実行する (デバッグに便利) には、 --detach=falseを渡します。

Relay クライアントは、接続の検証、OAuth による認証、Test Cloud への登録、プロキシ構成のダウンロード、資格情報の暗号化、systemd サービスのインストールのすべてを 1 つのコマンドで行います。

期待される出力:

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>

起動時に、Relayクライアントはバイナリを自動的に /usr/local/bin/relayにコピーします。マシン上のすべてのリレー グループは、この 1 つのバイナリを共有します。インストール ディレクトリを --bin-dirで上書きします。

3. 確認する

relay list

正常なクライアントでは、STATUS 列に ● running が表示されます。表示される ID 値は、後続のすべてのコマンド (relay stop <id>、 relay logs <id>など) で使用されます。また、UiPath Administration の [リレー グループの詳細] ページにもアクセスできます。

ログで次の login to server successを確認して、トンネルが確立されていることを確認します。

sudo relay logs <id> -f

管理

リスト (List)

このマシンにインストールされているすべてのリレー グループのステータスとバージョンが表示されます。sudoは必要ありません。

relay list
relay list --json

停止

リレー サービスを停止します。設定とログは保持され、リレーは後で再起動できます。

sudo relay stop <id>

再起動してアップグレードする

Relay サービスを再起動し、Test Cloud から最新のプロキシ構成を取得します。

sudo relay restart <id>

バイナリアップグレード: 新しい relay バイナリをダウンロードし、そこから sudo ./relay restart <id> を実行します。restart コマンドは、実行中のバイナリとインストールされたコピーを SHA256 ハッシュで比較し、異なる場合はインストールされたバイナリを自動的に更新します。

シナリオ	コマンド
Test Cloud でのエンドポイントの追加または削除	sudo relay restart <id>
クライアント シークレットのローテーション — インライン	sudo relay restart --config "<new-config>"
クライアント シークレットのローテーション — ファイル	sudo relay restart --config-file /path/to/new-config.txt
バイナリアップグレード	新しいバイナリをダウンロードし、 sudo ./relay restart <id>

--config または --config-file を指定した場合、<id> 引数は任意です。設定から抽出されます。

削除する

サービスを停止して Test Cloud から登録を解除し、ローカルの設定ファイルとログ ファイルをすべて削除します。

sudo relay delete <id>

クラウドの登録を解除せずにローカルクリーンアップを強制するには (たとえば、資格情報が失われた場合や、クラウド側のリレー グループがすでに削除されている場合)、次の手順を実行します。

sudo relay delete <id> --force

バージョン

relay version

自動アップグレードはありません。更新するには、新しいバイナリをダウンロードし、グループごとに sudo ./relay restart <id> を実行します。

ディレクトリ構造

すべてのディレクトリは、最初の実行時に自動的に作成されます。

/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

ファイルのアクセス許可

パス	モード	理由
ディレクトリ	755	読み取り/書き込みアクセスをリレーする
client_config	600	暗号化された OAuth 資格情報が含まれます
.credentials.key	600	AES-256-GCM 暗号化キー
metadata.json	644	サービス メタデータ (状態、PID、インストールのタイムスタンプ)
relay.log	644	トラブルシューティングが容易
バイナリ	755	systemdによる実行可能

カスタム パス

インストール時に既定のディレクトリを上書きする:

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

フラグ	既定 (Default)	説明
--bin-dir	/usr/local/bin	共有バイナリのディレクトリ
--data-dir	/var/lib	構成データのルート
--logs-dir	/var/log	ログ ファイルのルート

リレークライアントは、カスタムデータルートとログルートの下に uipath-relay/ を追加します。

--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、および --logs-dir は、 start コマンドでのみ受け付けられます。その他のコマンド ( [stop、 restart、 delete、 list) は、インストールされているサービス構成から自動的にパスを派生させます。

プロキシ構成

ネットワークで送信トラフィックがプロキシ経由でルーティングされる場合は、relay startを実行する前にプロキシ環境変数をエクスポートしてください。sudo -E を使用して、昇格時に環境を保護します。

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

-Eを使用しない場合、sudo は環境をリセットし、プロキシ設定は失われます。

リレークライアントは、キャプチャされたプロキシ変数を Environment= ディレクティブとしてsystemdユニットファイルに書き込むため、バックグラウンドサービスはシステム全体の /etc/environmentではなく、それらを使用します。

インストール後にプロキシを更新するには: 新しい値をエクスポートして [ sudo -E relay restart <id>] を実行します。

プロキシを削除するには、unset HTTPS_PROXY HTTP_PROXY NO_PROXY、次にsudo relay restart <id>します。

サービスが使用するものを確認するには、以下の手順を実行します。 systemctl cat relay-<id> | grep -i environment.

サポートされているプロキシスキームと認証については、 リレークライアントのデプロイのプロキシセクションを参照してください。

セキュリティ フレームワーク

環境で SELinux、AppArmor、または fapolicy d を使用している場合は、Relay クライアントバイナリとそのデータディレクトリが許可されていることを確認してください。

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

App Armor

/usr/local/bin/relayネットワークアクセスや /var/lib/uipath-relay/ や /var/log/uipath-relay/へのファイル書き込みを制限するプロファイルがないことを確認します。カスタム パスを使用する場合は、それに応じて置換します。

fapolicyd

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

許可するパス

入力	既定のパス
バイナリ	/usr/local/bin/relay
データ	/var/lib/uipath-relay/
ログ	/var/log/uipath-relay/

--bin-dir、--data-dir、または --logs-dirを使用した場合は、代わりにこれらのカスタム パスを許可します。

ユーザー モード

ユーザーモード (--user-mode) は、リレークライアントをシステムサービスではなく systemd ユーザーサービス としてインストールし、 sudoなしで実行できるようにします。これは、ルートアクセスが利用できない共有マシンや制限された環境に適しています。

要件

要件	詳細
systemd 229+	次のコマンドを確認します。 systemctl --version
ホーム ディレクトリ	ターゲット ユーザーが存在し、所有している必要があります
systemd ユーザー セッション	Verify: systemctl --user is-system-running は running または degraded を返します。
SSH ログイン	必須 — su / sudo su は、ユーザー サービスが必要とする D-Bus セッションを提供しません。
loginctl linger	ログアウト後もサービスを維持し、起動時に開始するために必要です

リンガーを有効にする (1 回限り、管理者が必要):

sudo loginctl enable-linger <username>

リンガーがない場合、ユーザー サービスはログアウト時に停止し、起動時に開始されません。

ユーザー モードで開始

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

ユーザー モードのディレクトリ レイアウト

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

~/.config/systemd/user/パスは上書きできません。バイナリ、データ、およびログのパスは、 --bin-dir、 --data-dir、および --logs-dirでカスタマイズできます。

ユーザー モードでの管理コマンド

すべてのコマンドは sudoなしで機能します。

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

ユーザー モードを使用する状況

シナリオ	推奨仕様
ルートアクセス権を持つ本番サーバー	システム モード (既定)
共有マシン、ルート アクセスなし	ユーザー モード
開発またはテスト	ユーザー モード
セキュリティが重視される環境	システムモード(改ざん防止バイナリパス)

アンインストール

1. すべてのRelayクライアントを削除します( relay list を使用して、インストールされているグループを表示します)。

   sudo relay delete <id>
   

2. 共有バイナリを削除します。

   sudo rm /usr/local/bin/relay
   

3. 残りのデータ ディレクトリとログ ディレクトリを削除します。

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

ユーザー モードの場合は、コマンドを同等のユーザー モード ( sudoなし) に置き換え、 ~/.local/bin/relay と ~/.local/share/uipath-relayを削除します。

トラブルシューティング

症状	原因	解決方法
サービスの開始に失敗する	権限が不十分である	次で実行 sudo
permission denied	ディレクトリを作成できない	sudoアクセスを確認するか、書き込み可能な場所へのカスタム パスを使用します
systemctl: command not found	systemd がインストールされていない	フォアグラウンドモード(--detach=false)を使用するか、systemdをインストールします
サービスが開始された後、すぐに停止します	構成またはネットワーク エラー	起動エラーがないか relay.log を確認する
サービスは実行されていますが、トンネルが確立されていません	ネットワークまたは認証の問題	relay.loglogin to serverエラーがないか確認します。TLS パススルーの確認
SELinux または AppArmor による実行のブロック	セキュリティ フレームワーク ポリシー	詳しくは、「セキュリティ フレームワーク」をご覧ください
XDG_RUNTIME_DIR not found (ユーザー モード)	SSH 経由でログインしていない	SSH 経由でログインするか、linger を有効にします
D-Bus session bus unreachable (ユーザー モード)	SSH 経由でログインしていない	SSH 経由でログインするか、linger を有効にします
プロキシがサービスで使用されていない	変数が開始時にキャプチャされない	sudo -Eで再実行するか、systemctl cat relay-<id> | grep -i environment で検証します
CPU またはメモリの使用率が高い	ログ レベルを trace または debug に設定	ログ レベルを info 以上に設定します

診断コマンド

# 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

プラットフォーム間で共有される認証エラーと接続エラーについては、「 トラブルシューティング」を参照してください。

クイック リファレンス

操作	コマンド
先頭	sudo relay start --config-file config.txt
停止	sudo relay stop <id>
再起動/アップグレード	sudo relay restart <id>
削除する	sudo relay delete <id>
削除 (強制)	sudo relay delete <id> --force
リスト (List)	relay list
ログ	relay logs <id> -f
サービスのステータス	systemctl status relay-<id>
Systemdジャーナル	journalctl -u relay-<id> -f