busctl - リファレンスマニュアル、オプション、コマンド例

名前

busctl - D-Bus バスのイントロスペクトと監視

概要

busctl [OPTIONS...] [COMMAND] [NAME...]

説明

busctl は、D-Bus バスのイントロスペクトと監視に使用できます。

コマンド

次のコマンドが理解されます。

list

バス上のすべてのピアをサービス名別に表示します。デフォルトでは、一意の名前と既知の名前の両方が表示されますが、これは --unique スイッチと --acquired スイッチを使用して変更できます。これは、コマンドが指定されていない場合のデフォルトの動作です。

status [SERVICE]

バス サービス (一意の名前または既知の名前で指定されている場合)、プロセス (数値 PID で指定されている場合)、またはバスの所有者 (パラメーターが指定されていない場合) のプロセス情報と認証情報を表示します。 。

monitor [SERVICE...]

交換中のメッセージをダンプします。 SERVICE が指定されている場合は、既知の名前または一意の名前で識別される、このピアとの間のメッセージを表示します。それ以外の場合は、バス上のすべてのメッセージを表示します。 Ctrl+C を使用してダンプを終了します。

capture [SERVICE...]

モニターと似ていますが、出力を pcapng 形式で書き込みます (詳細については、PCAP Next Generation (pcapng) キャプチャ ファイル形式[1]を参照してください)。標準出力を必ずファイルまたはパイプにリダイレクトしてください。 wireshark(1) などのツールを使用して、結果のファイルを分析して表示できます。

tree [SERVICE...]

1 つ以上のサービスのオブジェクト ツリーを表示します。 SERVICE を指定した場合は、指定したサービスのオブジェクト ツリーのみを表示します。それ以外の場合は、少なくとも 1 つの既知の名前を取得したバス上のすべてのサービスのすべてのオブジェクト ツリーを表示します。

introspect SERVICE OBJECT [INTERFACE]

指定されたサービス上の指定されたオブジェクト (パスで識別される) のインターフェイス、メソッド、プロパティ、およびシグナルを表示します。インターフェイス引数が渡された場合、出力は指定されたインターフェイスのメンバーに限定されます。

call SERVICE OBJECT INTERFACE METHOD [SIGNATURE [ARGUMENT...]]

メソッドを呼び出して応答を表示します。サービス名、オブジェクト パス、インターフェイス名、およびメソッド名を受け取ります。パラメータをメソッド呼び出しに渡す場合は、署名文字列が必要で、その後に個別に文字列としてフォーマットされた引数が続きます。使用されるフォーマットの詳細については、以下を参照してください。返されたデータの出力を抑制するには、--quiet オプションを使用します。

emit OBJECT INTERFACE SIGNAL [SIGNATURE [ARGUMENT...]]

信号を発します。オブジェクトのパス、インターフェイス名、メソッド名を受け取ります。パラメータを渡す場合は、署名文字列が必要で、その後に個別に文字列としてフォーマットされた引数が続きます。使用されるフォーマットの詳細については、以下を参照してください。信号の宛先を指定するには、--destination= オプションを使用します。

get-property SERVICE OBJECT INTERFACE PROPERTY...

1 つ以上のオブジェクト プロパティの現在の値を取得します。サービス名、オブジェクト パス、インターフェイス名、プロパティ名を受け取ります。複数のプロパティを一度に指定できます。その場合、それらの値は改行で区切られて次々に表示されます。デフォルトでは、出力は簡潔な形式になります。より複雑な出力形式には、--verbose を使用します。

set-property SERVICE OBJECT INTERFACE PROPERTY SIGNATURE ARGUMENT...

オブジェクトのプロパティの現在の値を設定します。サービス名、オブジェクト パス、インターフェイス名、プロパティ名、プロパティ署名を受け取り、その後に文字列としてフォーマットされたパラメータのリストが続きます。

help

コマンド構文のヘルプを表示します。

オプション

次のオプションが理解されます。

--address=ADDRESS

システムまたはユーザー バスのいずれかに適切なデフォルトを使用するのではなく、アドレスで指定されたバスに接続します (--system および --user オプションを参照) ）。

--show-machine

ピアのリストを表示する場合、ピアが属するコンテナーの名前を含む列を表示します。 systemd-machined.service(8) を参照してください。

--unique

ピアのリストを表示するときは、「一意の」名前 (「:number.number」の形式) のみを表示します。

--acquired

-- ユニーク の逆で、「よく知られた」名前のみが表示されます。

--activatable

ピアのリストを表示する場合、実際にはまだ起動されていないが、アクセスされると自動的に起動される可能性があるピアのみを表示します。

--match=MATCH

交換中のメッセージを表示する場合は、MATCH に一致するサブセットのみを表示します。 sd_bus_add_match(3) を参照してください。

--size=

capture コマンドと一緒に使用する場合、キャプチャするバス メッセージの最大サイズを指定します (「snaplen」)。デフォルトは 4096 バイトです。

--list

tree コマンドと一緒に使用すると、ツリーの代わりにオブジェクト パスのフラット リストが表示されます。

-q, --quiet

call コマンドと一緒に使用すると、応答メッセージ ペイロードの表示が抑制されます。このオプションが指定されている場合でも、返されたエラーは出力され、ツールはプロセスの終了コードで成功または失敗を示すことに注意してください。

--verbose

call または get-property コマンドと一緒に使用すると、より詳細な形式で出力が表示されます。

--xml-interface

introspect 呼び出しで使用すると、通常の出力の代わりに、D-Bus の org.freedesktop.DBus.Introspectable.Introspect 呼び出しから受信した XML 記述をダンプします。

--json=MODE

call または get-property コマンドと一緒に使用すると、JSON 形式の出力が表示されます。 「short」(余分な空白や改行を含まない可能な限り短い出力) または「pretty」(インデントと改行を備えた同じバージョンのきれいなバージョン) のいずれかを期待します。 D-Bus マーシャリングから JSON への変換は損失のない方法で行われることに注意してください。これは、型情報が JSON オブジェクト ツリーに埋め込まれることを意味します。

-j

端末から対話的に呼び出す場合は --json=pretty と同等です。それ以外の場合、特に出力が他のプログラムにパイプされる場合は、--json=short と同等です。

--expect-reply=BOOL

call コマンドと一緒に使用する場合、busctl がメソッド呼び出しの完了を待機し、返されたメソッド応答データを出力し、プロセス終了コードを介して成功または失敗を返すかどうかを指定します。 。これが「no」に設定されている場合、メソッド呼び出しは発行されますが、応答は期待されず、ツールはすぐに終了するため、応答は表示されず、終了コードによって成功または失敗は返されません。応答メッセージ ペイロードの出力のみを抑制するには、上記の --quiet を使用します。デフォルトは「はい」です。

--auto-start=BOOL

call または emit コマンドと一緒に使用すると、呼び出されたサービスがまだ実行されていないが自動開始されるように構成されている場合に、メソッド呼び出しで呼び出されたサービスを暗黙的にアクティブ化するかどうかを指定します。デフォルトは「はい」です。

--allow-interactive-authorization=BOOL

call コマンドと一緒に使用すると、セキュリティ ポリシーが設定されている場合、操作の実行中にサービスが対話型認証を強制できるかどうかを指定します。デフォルトは「はい」です。

--timeout=SECS

call コマンドと一緒に使用する場合、メソッド呼び出しの完了を待機する最大時間を指定します。時間単位が指定されていない場合は、秒とみなされます。通常の他の単位 (ms、us、s、min、h、d、w、month、y) も理解できます。 --expect-reply=no が使用されている場合、ツールは応答メッセージを待機しないため、このタイムアウトは適用されないことに注意してください。指定しない場合、または 0 に設定した場合は、デフォルトの「25 秒」が想定されます。

--augment-creds=BOOL

リストまたはステータスによって報告される資格情報データを /proc/ からのデータで拡張するかどうかを制御します。これをオンにすると、/proc/ から読み取られたデータが残りの資格情報よりも新しい可能性があるため、表示されるデータが不整合になる可能性があります。デフォルトは「はい」です。

--watch-bind=BOOL

指定したAF_UNIX バス ソケットがファイル システムに表示されるまで接続する前に待機するかどうかを制御します。デフォルトはオフです。有効にすると、ツールはソケットが作成されるまでファイル システムを監視し、ソケットに接続します。

--destination=SERVICE

サービス名を取得します。 emit コマンドと一緒に使用すると、指定されたサービスにシグナルが送信されます。

--user

システムのサービス マネージャーではなく、発信ユーザーのサービス マネージャーに相談してください。

--system

システムのサービスマネージャーに相談してください。これは暗黙のデフォルトです。

-H, --host=

操作をリモートで実行します。接続先のホスト名、またはユーザー名とホスト名を「@」で区切って指定します。ホスト名には、オプションで ssh がリッスンしているポートを「:」で区切って接尾辞として付け、その後に「/」で区切ってコンテナ名を付けることができます。これは、指定したホスト上の特定のコンテナに直接接続します。これにより、SSH を使用してリモート マシン マネージャー インスタンスと通信します。コンテナ名は machinectl -H HOST で列挙できます。 IPv6 アドレスを括弧内に入力します。

-M, --machine=

ローカルコンテナ上で操作を実行します。接続するコンテナ名を指定します。必要に応じて、接続するユーザー名と区切り文字「@」を接頭辞として付けます。コンテナ名の代わりに特別な文字列「.host」を使用すると、ローカル システムへの接続が確立されます (これは、特定のユーザーのユーザー バスに接続するのに便利です: "--user --machine=lennart@.host" ")。 「@」構文が使用されない場合、接続は root ユーザーとして行われます。 「@」構文を使用する場合は、左側または右側のいずれかを省略できます (両方は省略できません)。その場合、ローカル ユーザー名と「.host」が暗黙的に示されます。

-l, --full

list コマンドの出力を省略しないでください。

--no-pager

出力をポケットベルにパイプしないでください。

--no-legend

凡例、つまりヒントを含む列ヘッダーとフッターを印刷しないでください。

-h, --help

短いヘルプ テキストを印刷して終了します。

--version

短いバージョンの文字列を出力して終了します。

パラメータのフォーマット

call および set-property コマンドは、署名文字列の後に文字列としてフォーマットされたパラメータのリストを受け取ります (D-Bus 署名文字列の詳細については、Type を参照してください) D-Bus 仕様のシステムの章[2])。単純な型の場合、シグネチャに続く各パラメータは、単に文字列としてフォーマットされたパラメータ値である必要があります。正のブール値は、「true」、「yes」、「on」、または「1」としてフォーマットできます。負のブール値は、「false」、「no」、「off」、または「0」として指定できます。配列の場合、エントリ数の数値引数に続いてエントリを指定する必要があります。バリアントの場合、コンテンツの署名が指定され、その後にコンテンツが続きます。辞書や構造体については、その内容を直接指定する必要があります。

例えば、

s jawoll

単一の文字列「jawoll」の書式設定です。

as 3 hello world foobar

これは、「hello」、「world」、「foobar」という 3 つのエントリを含む文字列配列のフォーマットです。

a{sv} 3 One s Eins Two u 2 Yes b true

文字列をバリアントにマップする辞書配列の書式設定であり、3 つのエントリで構成されます。文字列「One」には文字列「Eins」が割り当てられます。文字列「Two」には 32 ビットの符号なし整数 2 が割り当てられます。文字列「Yes」には正のブール値が割り当てられます。

call、get-property、introspect コマンドも、返されたデータに対してこの形式で出力を生成することに注意してください。この形式は簡潔すぎて簡単に理解できない場合があるため、call コマンドと get-property コマンドに - が渡されると、より詳細な複数行の出力が生成される場合があります。 - 冗長オプション。

例

例 1. プロパティの書き込みと読み取り

次の 2 つのコマンドは、まずプロパティを書き込み、次にそれを読み取ります。このプロパティは、「org.freedesktop.systemd1」サービスの「/org/freedesktop/systemd1」オブジェクトにあります。プロパティの名前は、「org.freedesktop.systemd1.Manager」インターフェイスの「LogLevel」です。プロパティには単一の文字列が含まれます。

busctl set-property org.freedesktop.systemd1 /org/freedesktop/systemd1 org.freedesktop.systemd1.Manager LogLevel s debug
busctl get-property org.freedesktop.systemd1 /org/freedesktop/systemd1 org.freedesktop.systemd1.Manager LogLevel s "debug"

例 2. 簡潔で冗長な出力

次の 2 つのコマンドは、文字列の配列を含むプロパティを読み取り、まず簡潔な形式で表示し、次に詳細な形式で表示します。

busctl get-property org.freedesktop.systemd1 /org/freedesktop/systemd1 org.freedesktop.systemd1.Manager Environment
as 2 "LANG=en_US.UTF-8" "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin"
busctl get-property --verbose org.freedesktop.systemd1 /org/freedesktop/systemd1 org.freedesktop.systemd1.Manager Environment
ARRAY "s" {
        STRING "LANG=en_US.UTF-8";
        STRING "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin";
};

例 3. メソッドの呼び出し

次のコマンドは、「org.freedesktop.systemd1」サービスの「/org/freedesktop/systemd1」オブジェクトの「org.freedesktop.systemd1.Manager」インターフェースの「StartUnit」メソッドを呼び出し、それに 2 つの文字列「cups」を渡します。 .service」と「replace」。メソッド呼び出しの結果として、単一のオブジェクト パス パラメーターが受信され、表示されます。

busctl call org.freedesktop.systemd1 /org/freedesktop/systemd1 org.freedesktop.systemd1.Manager StartUnit ss "cups.service" "replace" o "/org/freedesktop/systemd1/job/42684"

関連項目

dbus-daemon(1), D-Bus[3], sd-bus(3), systemd(1), machinectl(1), wireshark(1)

ノート

  1. PCAP 次世代 (pcapng) キャプチャ ファイル形式: https://github.com/pcapng/pcapng/

  2. D-Bus 仕様のタイプ システムの章: https://dbus.freedesktop.org/doc/dbus-specation.html#type-system

  3. D-Bus: https://www.freedesktop.org/wiki/Software/dbus