PAM Tunnel非対話モード
PAM Tunnel — 非対話モード
pam tunnel start の非対話モードでは、対話型ターミナルセッションなしに、スクリプト、CI/CDジョブ、ヘッドレスサーバー、systemdなどのプロセススーパーバイザーからPAMトンネルを実行できます。本機能はPR #1848 (初版、2026-03-06) で導入され、PR #1993 (#1848を置き換え、2026-04-24) で確定しました。
概要
対話型トンネルワークフローはTTY上のユーザー操作を前提とします。バッチジョブ、ログインシェルのないリモートサーバー、パイプライン、監督下サービスでは、トンネルが予測可能に起動し、準備完了を通知し、方針に応じて存続またはデタッチし、作業完了時に確実に終了する必要があります。
コマンダーは pam tunnel start にオプションのフラグを追加し、同一コマンドで以下が可能になります。
フォアグラウンドで停止または
--timeout(WebRTC待機) まで実行を継続親プロセスは即座に終了し、デタッチした子プロセスでバックグラウンド実行
単一のシェルコマンドをラップ: トンネルを起動し、コマンドを実行し、トンネルを終了し、ラップしたコマンドの終了コードで終了
ファイルベースのトンネルレジストリにより、プロセス間での可視化とシャットダウンが可能です。他のコマンダーインスタンスが別プロセスで起動したトンネルを一覧表示し、シグナルで停止できます。keeper shell (対話モード) 内では、セッション中にトンネルが既に存続するため、 --foreground と --background はスキップされます (エラーにならず無視)。
コマンダーは、これらの動作を適用する際に非対話環境 (TTYなし) を自動検出します。
主な利用者
対話型ターミナルがトンネルライフサイクルを所有しないヘッドレスサーバー
限定ステップのためにトンネルを確実に起動・終了する必要があるCI/CDパイプライン
メインPID、PIDファイル、シグナル駆動のシャットダウンを想定するsystemdサービス (および同様のスーパーバイザー)
トンネルポート経由のlocalhost上のサービスに対する運用コマンドをラップする自動化スクリプト
実装上の注記
PR #1993ではリリースブランチへクリーンにリベースし、変更セットを3ファイルに限定したうえで、以前のPR #1848実装を置き換えつつ、ここで説明するオペレーター向けの動作は維持されています。
新規フラグリファレンス (pam tunnel start)
pam tunnel start)構文 (概念)
本ページで説明する新規オプションのみを示します。既存の pam tunnel start 引数 (例: --port) は従来どおりです。
--foreground
-fg
Boolean
false
トンネルを現在のプロセスで実行。Ctrl+Cまたは --timeout (WebRTC待機) まで存続。
--background
-bg
Boolean
false
デタッチした子プロセスを起動し、親は即座に終了。準備完了はファイルベースのトンネルレジストリのポーリングで判定。
--run
-R
String
(なし)
トンネル起動後に指定シェルコマンドをexecし、終了時にトンネルを終了し、ラップしたコマンドの終了コードで終了。
--timeout
—
Integer (seconds)
30
トンネル起動時のWebRTC接続待機の最大時間。
--pid-file
—
Path string
(なし)
接続成功後にプロセスPIDを書き込む。トンネル停止時にファイルは削除される。
新規フラグはすべて任意です。 --foreground 、 --background 、 --run は相互排他です (「相互排他ルール」をご参照ください)。
--foreground (-fg)
--foreground (-fg)動作
トンネルは keeper 呼び出しと同一プロセスで実行されます。SIGINT (例: Ctrl+C) を受信するか、WebRTC接続待機が --timeout を超えるまでアクティブです。
実務上の要点
トンネルは
keeperプロセスと同一プロセスで動作する。WebRTCセッションをデタッチした子プロセスに引き渡す構成にはならない。対話型割り込み (Ctrl+C) は通常のターミナル駆動の方法 (SIGINT) でプロセスを終了させる。
--timeout内にトンネルが準備完了にならない場合、他モードと同じタイムアウト意味論で起動は失敗する。
利用シーン
スーパーバイザーまたは対話オペレーターがトンネルライフサイクルを所有する場合。ターミナル、単一メインプロセスのコンテナ、systemd が MAINPID を追跡するユニットなど。
例 — 終了まで存続
例 — PIDファイル付きフォアグラウンド
接続後にPIDを書き込み、外部ツールがプロセスへシグナルを送れるようにする例。
--background(-bg)
--background(-bg)動作
コマンダーはトンネルを所有するデタッチした子プロセスを起動します。起動が進むと親は即座に終了します。準備完了はファイルベースのトンネルレジストリ (<tmp>/keeper-tunnel-sessions/ 配下のJSONセッションファイル) のポーリングで確認します。
実務上の要点
親子の分離: 子がトンネルを継続し、親は起動開始後すぐにシェルまたはCIランナーへ制御を返す。
準備完了: 対話的にブロックせず、レジストリファイルでトンネル登録がライブセッションを反映しているかを確認する。
シャットダウン:
--pid-fileに記録したPIDへシグナルを送るか、pam tunnel stopで停止できる (下記のプロセス間連携をご参照ください)。
利用シーン
スクリプトが直ちに制御を返す必要がある場合。トンネル起動後に同一スクリプトでクライアントコマンドを実行し、PIDファイルまたは pam tunnel stop で停止する、など。
例 — デーモン化、クライアント実行、PIDで停止
--run (-R)
--run (-R)動作
コマンダーはトンネルを起動し、続けて指定したシェルコマンドを実行します。コマンド終了時にトンネルを停止し、プロセス全体の終了コードはラップしたコマンドと同じになります。
ライフサイクルの概要
起動
トンネルを確立し、WebRTCの準備完了まで最大 --timeout 待機 (デフォルト30秒)。
実行
トンネルが利用可能になったあと、通常のシェル意味論で "<command>" を実行。
停止
ラップしたコマンド終了時にトンネルを自動終了 (成功・失敗を問わない)。
終了コード
ラップしたコマンドの終了コードを呼び出し元 (CI、スクリプト、systemd) へ伝播。
利用シーン
ワンショット自動化: データベースダンプ、マイグレーション、ヘルスチェックなど、トンネル経由のlocalhostアクセスが必要で起動・停止を手動管理したくないCLI。
例 — トンネルライフサイクル付き単一コマンド
例 — コマンド実行前のWebRTC待機時間を延長
--timeout と --pid-file
--timeout と --pid-file--timeout <seconds>
--timeout <seconds>トンネル起動時のWebRTC接続待機時間を制御します。デフォルト: 30 秒。遅延や高レイテンシのネットワークでは --run などで値を増やしてください。
タイムアウトは接続確立に適用され、その後トンネルが存続する時間には適用されません。長時間トンネルには --foreground または **--background**を使い、外部 (シグナル、 pam tunnel stop 、スーパーバイザー) でライフサイクルを管理してください。
--pid-file <path>
--pid-file <path>トンネル接続後、プロセスPIDを指定パスへ書き込みます。トンネル停止時にファイルは削除されます。 --foreground (メインプロセスへシグナル) や --background (デタッチした所有者へシグナル) と相性が良いです。
運用上の注記
PIDファイルは
kill -SIGTERM $(cat /path/to/pid)形式のオーケストレーション (PRの例) の安定した連携点です。systemdでは
PIDFile=を--pid-fileと揃え、$MAINPIDとExecStopが同一プロセスを指すようにします (systemdサービス例をご参照ください)。
例
プロセス間トンネルレジストリ
モジュール keepercommander/commands/tunnel_registry.py は、トンネルをプロセス間で可視化するファイルベースのレジストリを実装しています。
セッションメタデータは以下の配下へアトミックなJSON書き込みで保存されます。
セッションディレクトリはPOSIXで
0o700権限です。古いエントリは自動クリーンアップされます。
重複バインド検出により競合するトンネルエンドポイントを回避しやすくなります。
ファイル名とレイアウト
各JSONファイルは <pid>.json でキーされ、pid はそのレジストリエントリを所有するトンネルプロセスを識別します。親ディレクトリ keeper-tunnel-sessions はプラットフォームの一時ディレクトリ (<tmp>) 配下にあり、OSの慣例に従って解決されます。
目的
プロセス間のビューがなければ、起動したコマンダープロセスだけがアクティブなトンネルを把握できます。レジストリによりバックグラウンド起動の観測が可能になり、トンネルが起動シェルを超えて存続してもlist / stopが一貫します。スクリプト、サービス、リモート自動化で重要です。
このレジストリにより、他のコマンダープロセスで起動したトンネルとも pam tunnel list および pam tunnel stop が連携します。
pam tunnel list と pam tunnel stop (プロセス間)
pam tunnel list と pam tunnel stop (プロセス間)pam tunnel list
pam tunnel listlistコマンドでは、現在のセッションが所有するトンネルだけでなく、ファイルレジストリを読み取り他プロセスのトンネルも表示します。古いレジストリエントリは自動クリーンアップされます。
pam tunnel stop
pam tunnel stopstopはファイルレジストリにフォールバックし、プロセス間のトンネルをPOSIXではSIGTERM、WindowsではTerminateProcessで終了します。--all オプションもレジストリ経由で発見したプロセス間トンネルを停止します。
オペレーター向け早見表
例のPIDファイルパターンで停止
--pid-fileを読みSIGTERMを送信 (例: kill -SIGTERM $(cat /tmp/tunnel.pid))。
コマンダー経由でプロセス間トンネルを停止
pam tunnel stop を実行 — ファイルレジストリにフォールバックし、リモート所有者へシグナル (SIGTERM / TerminateProcess)。
すべて停止
pam tunnel stop --allもレジストリで見つかったプロセス間トンネルを停止。
他プロセスのトンネルを確認
pam tunnel list を実行 — レジストリ上のセッションが表示され、古いエントリは自動クリーンアップ。
systemdサービス例
PR #1993には [Service] 配線のコメント付き例が含まれています。以下は /etc/systemd/system/ に配置できる完全なユニット例です (パスと keeper の位置は環境に合わせて調整してください)。
以下のユニットはsystemd監督下でトンネルをフォアグラウンド実行し、接続後にPIDファイルを書き、SIGTERM でクリーンに停止します。
ExecStart のパス、<UID>、--port、PIDFile は環境に合わせて調整してください。
相互排他ルール
以下のモードは併用できません。
フォアグラウンド
--foreground/-fg
バックグラウンド
--background/-bg
実行ラッパー
--run/-R
1回の呼び出しでは、上記3つのうち1つを選択してください。
追加の動作
コマンダーは TTY がない場合に非対話利用を自動検出します。
対話型の
keeper shellセッション内では、--foregroundと--backgroundはスキップされます (そのコンテキストではトンネルが既に存続)。
相互作用の概要
コンテキスト
--foreground/--background
コマンダーが非対話モード (TTYなし) を自動検出した場合
各セクションで説明どおり動作する。
対話型**keeper shell**
--foreground と --background はスキップ — そのセッションではトンネルが既に存続。
後方互換性
新規フラグのデフォルトは、リファレンス表のとおり false、None、30 (--timeout) です。省略した場合、これらの変更前と pam tunnel start の動作は同じです。既存のスクリプトや操作手順は修正なしで有効です。
最終更新