【ITニュース解説】Stop Guessing systemd Service APIs: Practical varlinkctl on Linux

システムエンジニアがLinuxシステム上でサービスと対話する際、従来の方法には課題が多かった。例えば、特定の情報を取得するためにsystemctlコマンドのテキスト出力を解析したり、D-Busという複雑な仕組みを用いて専用のクライアントプログラムを作成したり、あるいは独自の通信プロトコルを定義してUnixソケット経由でやり取りしたりする方法が一般的であった。しかし、これらの方法は、出力形式が変更されると動かなくなる脆さや、手間がかかるという問題があった。

この状況を改善するため、現代のsystemdコンポーネントではVarlinkという新しいインターフェースが採用されつつある。Varlinkは、サービスとの対話をよりシンプルかつ堅牢にするための仕組みだ。そして、varlinkctlは、Varlinkサービスを操作するためのコマンドラインツールであり、システム運用者がこれらのサービスと効果的にやり取りできるように設計されている。

Varlinkとは具体的に何なのだろうか。Varlinkは、JSON形式のメソッド呼び出しをストリーム（主にUnixドメインソケット）経由で行うためのプロトコルである。これは、Web APIでよく使われるJSONを、ローカルシステム内のプロセス間通信（IPC）に持ち込んだようなものだと考えるとよい。Varlinkには、型付きインターフェース定義言語（IDL）があり、サービスが提供する機能や、それらの機能に渡すべき引数、返される値の構造を明確に定義できる。これにより、クライアントはサービスの利用方法を正確に把握し、誤った使い方を防ぐことができる。VarlinkはUAPI.20という仕様に基づいており、プロトコルと通信手段のバインディングを統合している。

D-BusもLinuxにおける主要なIPCの仕組みだが、VarlinkはD-Busの代替品ではない。D-Busは依然としてデスクトップ環境や多くのシステムAPIで広く利用されており、Varlinkは特に新しいsystemdコンポーネントで採用され、JSON形式での通信に特化している。VarlinkのメッセージはシンプルなJSONオブジェクトであり、ストリーム転送では各メッセージがヌル文字で区切られる。また、サービス自身が実行時に自分のインターフェース情報を公開するため、クライアントは別途スキーマファイルをインストールすることなく、利用可能なインターフェースやそのIDLを動的に取得できるという利点がある。

varlinkctlコマンドを利用するには、systemdのバージョンが255以降である必要がある。また、特定の操作、例えばシステムに関する特権的な情報にアクセスする際には、ルート権限が必要となる場合がある。

varlinkctlがサービスと接続する際のアドレス形式はいくつかある。例えば、/run/path.sockのようにUnixドメインソケットのパスを直接指定する方法が最も一般的だ。unix:/run/path.sockと明示的に指定することもできる。また、exec:/usr/lib/systemd/toolのように、Varlinkプロトコルをサポートする実行ファイルを直接起動して通信させることも可能だ。さらに、ssh-unix:host:/run/...やssh-exec:host:cmdlineのように、SSH経由でリモートホスト上のVarlinkサービスと安全に通信する機能も提供されている。これは、リモートマシンに特別なエージェントをインストールすることなく、システムの状態を検査する際に非常に便利である。ただし、この機能にはOpenSSHのバージョン9.4以上が必要となる。

実際にvarlinkctlを使ってVarlinkサービスを操作する方法を見ていこう。まず、サービスの情報を知るには、varlinkctl infoコマンドを使う。これにソケットパスを渡すことで、そのサービスがどのベンダーの、どの製品で、どのバージョンであるか、そしてどのようなインターフェースを提供しているかといったメタデータを取得できる。varlinkctl list-interfacesを使えば提供されているインターフェース名だけを、varlinkctl list-methodsを使えば各インターフェースが提供するメソッド名だけを一覧表示できる。さらに詳細な情報、例えばメソッドの引数や返り値の型定義を知りたい場合は、varlinkctl introspectコマンドでインターフェースの完全なIDL（インターフェース定義言語）を取得できる。これらのコマンドは、JSON形式で情報を出力することも可能であり、スクリプトでの自動処理に役立つ。

次に、Varlinkサービスのメソッドを呼び出す方法だ。varlinkctl callコマンドを使用する。このコマンドには、サービスのアドレス、呼び出したいメソッドの完全修飾名（例: io.systemd.Resolve.ResolveHostname）、そしてJSON形式の引数を渡す。引数がない場合は空のJSONオブジェクト{}を指定する。メソッドの実行結果もJSONオブジェクトとして標準出力に返されるため、jqなどのツールと組み合わせて必要な情報を抽出できる。例えば、ホスト名解決サービスsystemd-resolvedのResolveHostnameメソッドを呼び出し、systemd.ioというホスト名のIPv4アドレスを解決するといったことが可能だ。

Varlinkには、複数の応答を返すメソッドや、応答を期待しないメソッドを扱うためのオプションも用意されている。--moreフラグを使うと、複数のJSONメッセージが順次ストリームとして送られてくるようなメソッド（JSON-SEQ形式）を処理できる。サブスクリプションのように継続的に更新を受け取りたい場合は、-Eまたは--timeout=infinityを指定してタイムアウトなしで待機することも可能だ。また、--collectフラグを使えば、複数の応答を一つのJSON配列としてまとめて受け取ることができる。一方で、--onewayフラグは、サービス側からの応答を必要としない（fire-and-forget）メソッドを呼び出す際に使用する。これは、例えばログの記録など、結果を待つ必要がない処理に適している。

varlinkctlは、長期間稼働するデーモンだけでなく、単一のタスクを実行するために起動されるバイナリとVarlink通信を行うこともできる。例えば、systemd-pcrextendのようなツールは、実行時にVarlinkプロトコルを話すように設計されている。このようなツールは、exec:/path/to/toolというアドレス形式で指定することで、varlinkctlから直接操作できる。

さらに、varlinkctl serveコマンドは、標準入出力で特定のプロトコルを話す既存のコマンドを、Varlinkサービスとしてソケット経由で公開する機能を提供する。これは、systemdのソケットユニットとサービスユニットを組み合わせて利用することで、コマンドをサンドボックス環境で安全に実行し、クライアントからは安定したVarlinkメソッドとしてアクセスさせるような高度な連携が可能になる。例えば、xzコマンドを解凍サービスとしてVarlink経由で提供し、システムリソースを制限しながら利用者に提供できる。クライアントは--upgradeフラグを使用して、JSON形式のコントロールメッセージから生のデータストリームに切り替えることで、実際にデータを送受信できるようになる。

インターフェースを開発する際には、varlinkctl validate-idlコマンドが役立つ。これは、Varlinkのインターフェース定義ファイル（IDLファイル）の構文を検証し、命名規則や構造上の誤りを早期に発見できる。これは、サービスがイントロスペクションで返すIDLの形と、クライアントが期待するIDLの形が一致していることを確認するために重要である。

varlinkctlを扱う上で遭遇しやすい問題もいくつかある。ソケットパスの指定ミスやサービスが起動していないことによる「No such file or directory」エラー、パーミッション不足による「Connection refused / permission denied」エラーが一般的だ。また、メソッド名のタイプミスやsystemdパッケージのバージョンが古いことによる「Method not found」エラー、複数の応答を返すメソッドに対して--moreフラグを付け忘れたことによるタイムアウトなどが挙げられる。JSON引数のシェルクォーティングのミスもよくある問題だ。

busctlやD-Busは、デスクトップ環境や多くのシステムAPIで依然として重要な役割を担っている。varlinkctlはこれとは異なり、JSONネイティブな新しい通信経路であり、特に新しいsystemdコンポーネントで活用されている。resolvectlやhostnamectlといったコマンドは、varlinkctlが扱うVarlinkデーモンの上位に位置する、よりユーザーフレンドリーなコマンドである。varlinkctlは、これらの上位コマンドでは実現できない、低レベルな制御や自動化が必要な場合に「汎用的な道具」として利用できる。

このように、varlinkctlは、Linuxシステム上のサービスとの対話を、より堅牢でプログラムしやすいJSONベースのインターフェースに移行させる強力なツールである。コマンドのテキスト出力を解析するような脆い方法や、複雑なD-Busクライアントを実装する手間から解放され、簡単な名前解決からサンドボックス化されたヘルパーサービスの構築まで、幅広いシナリオで効率的なシステム連携を実現できるだろう。