systemd 260.1
busctl — バスの内部調査(introspect)を行う
busctl [OPTIONS...] [COMMAND] [NAME...]
以下のコマンドを使用することができる：
バス上のすべてのピア(peer)を表示する。その際にはピアのサービス名を使用する。デフォルトではユニーク名と周知の名前(well-known names)の両方を表示するが、この設定は「--unique」や「--acquired」というスイッチ(switch)を使用して変更することができる。このコマンドは、何もコマンドが指定されなかった場合のデフォルトの動作である。
SERVICE]あるバス・サービスのユニーク名もしくは周知の名前が(SERVICE に)指定された場合、同バス・サービスのプロセス情報と属性情報(credentials)を表示し、あるプロセスの PID の数値が指定された場合、同プロセスのプロセス情報と属性情報を表示し、何ら引数が指定されなかった場合、バスの所有者のプロセス情報と属性情報を表示する。(訳註：バス・サービスやプロセスは１つしか指定できない。)
SERVICE...]交信されているメッセージをダンプする(表示する)。SERVICE を指定した場合、そのピア(peer)へ向かうメッセージとそのピアから出てくるメッセージを表示する。「SERVICE」の部分では、周知の名前もしくはユニーク名を用いてピアを指定する。SERVICE を指定しなかった場合、バス上のすべてのメッセージを表示する。「Ctrl+C」を用いてダンプ処理を終わらせるか、もしくはオプション「--limit-messages=」によってダンプ処理の数を制限する。
SERVICE...]monitor によく似ているが、pcapng 形式で出力を書き出す点が異なる(詳しくは PCAP Next Generation (pcapng) Capture File Format を参照)。標準出力をファイルかパイプ(pipe)へリダイレクトしなければならない。wireshark(1) のようなツールを使用することで、生成されたファイルを解析したり表示したりすることができる。
SERVICE...]１つ以上のサービスのオブジェクト・ツリーを表示する。SERVICE を指定した場合、指定したサービス群のオブジェクト・ツリーだけを表示する。SERVICE を指定しなかった場合、バス上のサービスの中、少なくとも１つ周知の名前を取得しているもの全てのオブジェクト・ツリーを全て表示する(訳註：all object trees of all services)。
SERVICE OBJECT [INTERFACE]指定されたサービスの指定されたオブジェクト(オブジェクト経路で指定)が持つインターフェイス、メソッド、プロパティ及びシグナルを表示する。引数のインターフェイス(INTERFACE)を指定した場合、出力範囲は指定したインターフェイスのメンバに限定される。
SERVICE OBJECT INTERFACE METHOD [SIGNATURE [ARGUMENT...]]メソッドを呼び出し、その応答を表示する。サービス名、オブジェクト経路、インターフェイス名及びメソッド名を指定する。メソッド・コールに引数を渡す場合、まずシグネチャ文字列を指定する必要があり、このシグネチャ文字列の後ろに引数群を置く(各引数はそれぞれ別個の文字列で表す)。引数の書式については、後ほど詳しく述べる。返ってきたデータの出力を抑制するにはオプション「--quiet」を使用する。
OBJECT INTERFACE SIGNAL [SIGNATURE [ARGUMENT...]]シグナルを発する。オブジェクト経路、インターフェイス名及びメソッド名(訳註：？)を指定する。引数を渡す場合、まずシグネチャ文字列を指定する必要があり、このシグネチャ文字列の後ろに引数群を置く(各引数はそれぞれ別個の文字列で表す)。引数の書式については、後ほど詳しく述べる。シグナルの宛先を指定するにはオプション「--destination=」を使用する。
SERVICE] OBJECT INTERFACE SIGNAL シグナルを待ち受ける。オブジェクト経路、インターフェイス名及びシグナル名を指定する。シグナルを１つだけ待ち受けてすぐ終了するのでない場合、オプション「--limit-messages=」を使用する。返ってきたデータの出力を抑制するにはオプション「--quiet」を使用する。サービス名は省略することができる。その場合、busctl は任意の sender (送信者)からのシグナルにマッチする。
SERVICE OBJECT INTERFACE PROPERTY... オブジェクト・プロパティ(１個以上)の現在の値を取り出す。サービス名、オブジェクト経路、インターフェイス名及びプロパティ名を指定する。１度に複数のプロパティを指定することができる。その場合、プロパティの値は改行で区切られて順々に表示される。出力は、デフォルトでは簡潔な形式で表示される。詳細な出力形式で表示するには「--verbose」を使用する。
SERVICE OBJECT INTERFACE PROPERTY SIGNATURE ARGUMENT... オブジェクト・プロパティの現在の値を設定する。サービス名、オブジェクト経路、インターフェイス名、プロパティ名、プロパティのシグネチャを指定し、それに続けて文字列で表した引数のリストを指定する。
コマンドの構文が載っているヘルプを表示する。
以下のオプションを利用することができる：
--address=ADDRESSシステム・バスもしくはユーザ・バスを指すデフォルトのアドレス(オプションの「--system」と「--user」を見よ)は使用せず、ADDRESS で指定したバスに接続する。
--show-machineピア(peer)の一覧を表示する際、ピアが所属するコンテナの名前を載せた列を表示する。systemd-machined.service(8) を見よ。
--uniqueピアの一覧を表示する際、(「:」の形を持つ)ユニーク名のみを表示する。number.number
--acquired「--unique」の逆であり、周知の名前(well-known name)のみを表示する。
--activatableピアの一覧を表示する際、まだ実際にアクティベートされていないピアであって、且つアクセスされたならば自動的に起動できるもののみを表示する。
--match=MATCH交信されているメッセージを表示する際、MATCH にマッチする部分集合(メッセージの部分集合)のみを表示する。sd_bus_add_match(3) を見よ。
--size=コマンド capture と組み合わせて使用した場合、記録するバス・メッセージの最大サイズ("snaplen"：訳註：snapshot length)を指定する。デフォルト値は 4096 バイトである。
--listコマンド tree と組み合わせて使用した場合、オブジェクト経路の一覧を木構造ではなく同列に並べた形で表示する。
-q, --quietコマンド call と組み合わせて使用した場合、応答メッセージのペイロードの表示を抑制する。(訳註：表示しなくなる。) このオプションを指定した場合であっても、返ってきたエラーは依然として表示され、本ツールはプロセスの終了コード(exit code)で成功もしくは失敗を知らせることに注意。
--verboseコマンド call あるいは get-property と組み合わせて使用した場合、出力を詳細な形式で表示する。
--xml-interfaceintrospect の呼び出しと組み合わせて使用した場合、通常の出力の代わりに、D-Bus の org.freedesktop.DBus.Introspectable.Introspect の呼び出しから受け取ったXML 表現(XML description：XML 記述)を書き出す。
--expect-reply=BOOLコマンド call と組み合わせて使用した場合、次の動作を行うか否かを指定する。即ち、busctl がメソッド・コールの完了を待ち受け、返ってきたメソッドの応答データを出力し、プロセスの終了コードによって成功もしくは失敗を知らせるか否かを指定する。これが「no」に設定されている場合、メソッド・コールは発行されるが、応答は期待されず、本ツールは即座に終了し、したがって応答は一切表示されず、終了コードによる成功や失敗の報告が返ることもない。単に返答メッセージのペイロードの出力を抑制するだけであれば、上述の --quiet を使用する。デフォルト値は「yes」である。
--auto-start=BOOLコマンド call もしくは emit と組み合わせて使用した場合、次の動作を行うか否かを指定する。即ち、呼び出されたサービスはまだ実行されていないものの、同サービスを自動起動するように設定が為されている場合に、メソッド・コールが同サービスを暗黙のうちにアクティベートするか否かを指定する。デフォルト値は「yes」である。
コマンド call と組み合わせて使用した場合、次の動作の可否を指定する。即ち、セキュリティ・ポリシーにて対話的な認証(interactive authorization)を認めている場合に、サービスが処理の実行中に対話的な認証を強制できるか否かを指定する。デフォルト値は「yes」である。
--timeout=SECSコマンド call と組み合わせて使用した場合、メソッド・コールの完了を待ち受ける時間の最大値を指定する。コマンド monitor と組み合わせて使用した場合、v257 版以降では、monitor を自動的に終了する前にどれだけの時間メッセージを待ち受けるのかについて、その最大値を指定する。時間の単位を指定しなかった場合、単位は「秒」であると見做す。その他の一般的な単位も使用できる(ms、us、s、min、h、d、w、month、y)。call と組み合わせて使用するとき、--expect-reply=no も使用する場合には、この制限時間は意味を持たないことに注意。なぜかというと、この場合には本ツールは返答メッセージの待ち受けを行わないからである。このオプションを指定しなかった場合、あるいは 0 に設定した場合、call コマンドではデフォルト値である「25s」を指定したものと見做し、monitor コマンドでは時間制限そのものが無効になる。
--limit-messages=NUMBER, -N NUMBERコマンド monitor と組み合わせて使用した場合、busctl は、指定された数のメッセージを受信して表示し終えた時に終了するようになる。このオプションは --match= と組み合わせて使うと便利であり、特定の D-Bus メッセージが指定した回数発生するのを待ち受けることができる。一方、このオプションを指定しなかった場合、あるいはこのオプションに特別な値である「infinity」を設定した場合、無制限に監視を続けるのがデフォルトの動作である。
コマンド wait と組み合わせて使用した場合、busctl は、指定された数の DBus シグナルを受信して表示し終えた時に終了するようになる。この場合、このオプションに特別な値である「infinity」を設定すると、busctl は無制限に且つ途切れること無くシグナルを受信して表示し続けるようになる。何も指定しなかった場合、最初のシグナルを受信して表示したら直ちに終了するのがデフォルトの動作である。
--augment-creds=BOOLlist や status で表示される属性情報データ(credential data)に /proc/ からのデータを加えるか否かを指定する。このオプションを有効にした場合、表示するデータに整合性がなくなるかもしれない。なぜかというと、/proc/ から読み込まれる属性情報データは他の属性情報(credential information)よりも新しい可能性があるからである。デフォルト値は「yes」である。(訳註：「--augment-creds=no」を指定すると「PROCESS」「UNIT」「SESSION」などの欄が空になったり「n/a」になったりする。)
--watch-bind=BOOL指定した AF_UNIX バス・ソケットに接続する前にそのソケットがファイル・システムに現れるのを待ち受けるか否かを指定する。デフォルトでは無効である。有効にした場合、本ツールは、ソケットが作成されるまでファイル・システムを監視し、それから同ソケットに接続する。
--destination=SERVICEサービス名を指定する。コマンド emit と組み合わせて使用した場合、シグナルは指定したサービスへ向けて発信される。
--userシステムのサービス・マネージャではなく、本ツールを使用しているユーザ(calling user)のサービス・マネージャと通信する。
--systemシステムのサービス・マネージャと通信する。これは何も指定しなかった場合のデフォルトの動作である。
-H, --host=遠隔で操作を実行する。接続したいホスト名を指定するか、もしくはユーザ名とホスト名を「@」で繋げたもの(接続先)を指定する。ホスト名には、ssh が待ち受けているポート番号を「:」で区切って末尾に加えることができ、その後ろにコンテナ名を「/」で区切って加えることができる。その場合、指定したホストの指定したコンテナに直接接続を行う。この操作では、遠隔マシンのマネージャ・インスタンスと通信するのに SSH を使用する。コンテナ名は、「machinectl -H HOST」で列挙することができる。IPv6 のアドレスは角括弧で囲う。
-M, --machine=ローカルのコンテナで操作を実行する。接続したいコンテナの名前を指定する。この時、接続に使用するユーザ名と区切り文字の「@」をコンテナ名の前に加えることができる(任意)。コンテナ名の代わりに特別な文字列「.host」を使用した場合、ローカル・システムに接続する(これは特定のユーザのユーザ・バスに接続する時に役に立つ：「--user --machine=lennart@.host」)。「@」構文を使わなかった場合、ルート・ユーザとして接続する。「@」構文を使用した場合、@ の左側か右側のどちらかを省略することができる(両方省略することはできない)。この場合、それぞれローカル・ユーザのユーザ名と「.host」を指定したことになる。
-C, --capsule=カプセルで操作を実行する。接続したいカプセルの名前を指定する。カプセルの詳細については capsule@.service(5) を参照。
-l, --fulllist コマンドの出力で省略を行わない。
(訳註：「--no-pager」と組み合わせて使用すると効果がわかりやすい。)
--json=MODEJSON 形式の出力を表示する。次のいづれかの値を取る。「short」(余分な空白や改行を含まない、可能な限り短い出力)、「pretty」(同じ出力にインデントと改行を加えた、読みやすい形態(pretty version))、「off」(デフォルトの動作であり、JSON 形式で出力しない)。
-j端末で実行している場合、「--json=pretty」に等しい。そうでない場合、「--json=short」に等しい。
--no-pager出力をパイプでページャに渡さない。
--no-legend説明的装飾(legend)、即ち列の見出し(header)とヒントを載せたフッター(footer)とを表示しない。
(訳註：debian の busctl(1) では「Do not print the legend, i.e. the column headers and the footer.」)
-h, --help簡潔なヘルプの文章を表示して終了する。
--versionバージョンを表す簡潔な文を表示して終了する。
コマンドの call と set-property は、引数としてシグネチャ文字列を取り、それに続けて文字列で表した引数のリストを指定する(D-Bus のシグネチャ文字列については D-Bus 仕様の型システムの章を参照)。単純な型の場合、シグネチャの後ろに続く各引数は、単純に引数の値を文字列で表したものとなる。正のブール値は文字列「true」「yes」「on」「1」で表すことができる。負のブール値は文字列「false」「no」「off」「0」で指定することができる。配列の場合、まず要素(entry)の数を表す数字の引数を指定し、それに続けて要素群を指定する。ヴァリアント型(variant)の場合、中身の型を表すシグネチャを指定し、それに続けて中身を指定する。辞書項目型と構造体型の場合、それらの中身を直接指定する。
例えば、
s jawoll
これは単一の文字列「jawoll」の書式である。
as 3 hello world foobar
これは３つの要素「hello」「world」「foobar」を持つ配列(文字列配列)の書式である。
a{sv} 3 One s Eins Two u 2 Yes b true
これは、文字列をヴァリアントに対応させる辞書項目３つから成る配列の書式である。文字列「One」に対応するのは文字列「Eins」である。文字列「Two」に対応するのは符号無し整数 2 である。文字列「Yes」に対応するのは正のブール値である。
コマンド call、get-property、introspect も返ってきたデータをこの書式で出力することに注意。この書式は簡潔すぎて簡単に理解できないことがある。そのため、call コマンドと get-property コマンドは、オプションの「--verbose」を指定することによって複数行にわたる詳細な出力を生成できるようになっている。
例１、プロパティの書き込みと読み込み
次の２つのコマンドは、まずプロパティに書き込みを行い、次いで同プロパティから読み込みを行う。このプロパティはサービス「org.freedesktop.systemd1」のオブジェクト「/org/freedesktop/systemd1」にある。このプロパティの名前は「LogLevel」であり、インターフェイス「org.freedesktop.systemd1.Manager」にある。同プロパティには文字列が１つだけ入る：
# 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"
例２、簡潔な出力と詳細な出力
次の２つのコマンドは、文字列の配列が入っているプロパティを読み込むものである。最初のものは同プロパティを簡潔な形式で表示し、２番目のものは詳細な形式で表示する：
$ 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";
};
例３、メソッドを呼び出す
次のコマンドは、サービス「org.freedesktop.systemd1」のオブジェクト「/org/freedesktop/systemd1」のインターフェイス「org.freedesktop.systemd1.Manager」のメソッド「StartUnit」を呼び出すものであり、「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"