Manpages

NAME

busctl - 內 省 與 監 視 D-Bus 總 線

SYNOPSIS

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

描 述

busctl 可 用 於 內 省 與 監 視 D-Bus 總 線

選 項

能 夠 識 別 的 命 令 行 選 項 如 下 ：

--address=ADDRESS 連 接 到 ADDRESS 指 定 的 總 線 ， 而 不 是 默 認 的 總 線 (無 論 是 --system 系 統 總 線 還 是 --user 用 戶 總 線 )。

--show-machine 在 使 用 list 命 令 顯 示 總 線 上 的 所 有 peer 列 表 時 ， 額 外 顯 示 一 個 "MACHINE"列 ， 指 明 其 所 屬 容 器 的 名 稱 。 參 見 systemd-machined.service(8) 手 冊 。

--unique 在 使 用 list 命 令 顯 示 總 線 上 的 所 有 peer 列 表 時 ， 僅 顯 示 ":number.number" 格 式 的 "唯 一 名 "(UniqueName)。

--acquired 在 使 用 list 命 令 顯 示 總 線 上 的 所 有 peer 列 表 時 ， 與 --unique 選 項 正 好 相 反 ， 僅 顯 示 "易 讀 名 "(well-known name)。

--activatable 在 使 用 list 命 令 顯 示 總 線 上 的 所 有 peer 列 表 時 ， 僅 顯 示 當 前 未 被 激 活 並 且 可 以 在 被 訪 問 時 自 動 激 活 的 peer 。

--match=MATCH 在 使 用 monitor 命 令 監 視 已 交 換 的 消 息 時 ， 僅 顯 示 與 MATCH 匹 配 的 消 息 。 參 見 sd_bus_add_match(3)

--size= 在 使 用 capture 命 令 捕 獲 已 交 換 的 消 息 時 ， 指 定 允 許 捕 獲 的 最 大 消 息 尺 寸 ("snaplen")， 默 認 值 是 4096 字 節 。

--list 在 使 用 tree 命 令 顯 示 對 象 路 徑 時 ， 不 以 樹 形 縮 進 顯 示 ， 而 是 以 平 鋪 列 表 的 格 式 顯 示 。

--quiet 與 call 命 令 連 用 ， 禁 止 顯 示 應 答 消 息 。 注 意 ： 錯 誤 消 息 依 然 會 被 顯 示 出 來 ， 並 且 依 然 可 以 用 返 回 值 判 斷 成 敗 。

--verbose 與 call 或 get-property 命 令 連 用 ， 表 示 以 詳 細 模 式 顯 示 輸 出 。

--expect-reply=BOOL 與 call 命 令 連 用 ， 設 置 是 否 等 待 被 調 用 的 方 法 執 行 完 成 。 "yes" 表 示 等 待 方 法 執 行 完 成 並 且 返 回 應 答 數 據 ， 然 後 busctl 將 返 回 一 個 可 用 於 判 斷 方 法 執 行 成 敗 的 返 回 碼 。 "no" 表 示 調 用 方 法 之 後 不 等 待 其 執 行 完 成 也 不 顯 示 應 答 數 據 ， 而 是 直 接 退 出 ， 並 且 不 返 回 有 意 義 的 返 回 碼 。 如 果 只 是 想 屏 蔽 應 答 數 據 ， 應 該 使 用 --quiet 選 項 。 默 認 值 爲 "yes"

--auto-start=BOOL 與 call 命 令 連 用 ， 設 置 是 否 應 該 隱 含 的 啓 動 當 前 尚 未 運 行 、 但 是 被 配 置 爲 自 動 啓 動 的 服 務 。 默 認 是 "yes"

--allow-interactive-authorization=BOOL 與 call 命 令 連 用 ， 設 置 服 務 在 執 行 操 作 時 ， 是 否 應 該 強 制 進 行 交 互 式 授 權 (在 安 全 策 略 已 配 置 的 時 候 )。 默 認 是 "yes"

--timeout=SECS 與 call 命 令 連 用 ， 設 置 等 候 方 法 完 成 的 最 大 秒 數 。 注 意 ， 此 處 的 超 時 設 置 對 --expect-reply=no 無 效 。 可 使 用 明 確 的 時 間 單 位 後 綴 ： us, ms, s, min, h, d, w, month, y 。 默 認 值 是 "25s" (注 意 ， 設 爲 "0"也 等 價 於 "25s")。

--augment-creds=BOOL 設 置 list/status 命 令 報 告 的 憑 據 數 據 是 否 應 該 被 擴 展 爲 包 含 來 自 /proc 的 數 據 。 若 設 爲 "yes"(默 認 值 )， 那 麼 顯 示 的 數 據 可 能 會 不 一 致 ， 因 爲 /proc 中 的 數 據 可 能 會 更 新 。

--user 與 當 前 調 用 用 戶 的 用 戶 服 務 管 理 器 (systemd 用 戶 實 例 )通 信 ， 而 不 是 默 認 的 系 統 服 務 管 理 器 (systemd 系 統 實 例 )。

--system 與 系 統 服 務 管 理 器 (systemd 系 統 實 例 )通 信 ， 這 是 默 認 值 。

-H, --host= 操 作 指 定 的 遠 程 主 機 。 可 以 僅 指 定 一 個 主 機 名 (hostname)， 也 可 以 使 用 "username@hostname" 格 式 。 hostname 後 面 還 可 以 加 上 容 器 名 (以 冒 號 分 隔 )， 也 就 是 形 如 "hostname:container" 的 格 式 ， 以 表 示 直 接 連 接 到 指 定 主 機 的 指 定 容 器 內 。 操 作 將 通 過 SSH協 議 進 行 ， 以 確 保 安 全 。 可 以 通 過 machinectl -H HOST 命 令 列 出 遠 程 主 機 上 的 所 有 容 器 名 稱 。

-M, --machine= 在 本 地 容 器 內 執 行 操 作 。 必 須 明 確 指 定 容 器 的 名 稱 。

--no-pager 不 將 程 序 的 輸 出 內 容 管 道 (pipe)給 分 頁 程 序 。

--no-legend 不 輸 出 列 標 題 ， 也 就 是 不 在 輸 出 列 表 的 頭 部 和 尾 部 顯 示 字 段 的 名 稱 。

-h, --help 顯 示 簡 短 的 幫 助 信 息 並 退 出 。

--version 顯 示 簡 短 的 版 本 信 息 並 退 出 。

命 令

能 夠 識 別 的 命 令 如 下 ：

list 顯 示 總 線 上 的 所 有 peer(依 據 服 務 名 稱 )， 這 是 默 認 命 令 。 默 認 同 時 顯 示 "唯 一 名 "(UniqueName)與 "易 讀 名 "(well-known name)， 但 是 可 以 使 用 --unique 與 --acquired 選 項 進 行 修 改 。

status [SERVICE] 如 果 SERVICE 是 一 個 總 線 服 務 的 "唯 一 名 "或 "易 讀 名 "， 那 麼 顯 示 該 服 務 的 進 程 信 息 及 憑 證 信 息 。 如 果 SERVICE 是 一 個 進 程 的 PID， 那 麼 顯 示 該 進 程 的 進 程 信 息 及 憑 證 信 息 。 如 果 未 指 定 SERVICE 參 數 ， 那 麼 顯 示 總 線 所 有 者 的 進 程 信 息 及 憑 證 信 息 。

monitor [SERVICE...] 監 視 已 交 換 的 消 息 ， 可 使 用 Ctrl-C 中 斷 監 視 。 如 果 未 指 定 SERVICE 參 數 ， 那 麼 顯 示 總 線 上 的 所 有 消 息 。 如 果 指 定 了 SERVICE 參 數 ("唯 一 名 "或 "易 讀 名 ")， 那 麼 僅 顯 示 到 達 此 peer或 者 從 此 peer發 出 的 消 息 。

capture [SERVICE...] 與 monitor 命 令 類 似 ， 不 同 之 處 在 於 以 pcap 格 式 輸 出 (詳 見 Libpcap File Format [1] )。 強 烈 推 薦 將 STDOUT 重 定 向 到 一 個 文 件 中 ， 然 後 使 用 wireshark(1) 工 具 查 看 與 分 析 。

tree [SERVICE...] 顯 示 服 務 的 對 象 樹 。 如 果 給 出 了 SERVICE 參 數 ， 那 麼 僅 顯 示 指 定 服 務 的 對 象 樹 ， 否 則 顯 示 總 線 上 所 有 具 有 "易 讀 名 "服 務 的 對 象 樹 。

introspect SERVICE OBJECT [INTERFACE] 顯 示 SERVICE服 務 上 OBJECT對 象 (以 路 徑 表 示 )的 interface, method, property, signal 值 。 如 果 指 定 了 INTERFACE 參 數 ， 那 麼 僅 輸 出 指 定 接 口 上 的 成 員 。

call SERVICE OBJECT INTERFACE METHOD [SIGNATURE [ARGUMENT...]] 調 用 一 個 方 法 並 顯 示 應 答 。 必 須 指 定 服 務 名 稱 (SERVICE)、 對 象 路 徑 (OBJECT)、 接 口 名 稱 (INTERFACE)、 方 法 名 稱 (METHOD)。 如 果 要 給 方 法 傳 遞 參 數 ， 那 麼 必 須 使 用 類 型 標 記 (SIGNATURE)後 跟 一 個 參 數 字 符 串 (ARGUMENT)。 格 式 細 節 參 見 下 面 的 "參 數 格 式 "小 節 。 可 以 使 用 --quiet 選 項 抑 制 輸 出 。

get-property SERVICE OBJECT INTERFACE PROPERTY... 顯 示 對 象 屬 性 的 當 前 值 。 必 須 指 定 服 務 名 稱 (SERVICE)、 對 象 路 徑 (OBJECT)、 接 口 名 稱 (INTERFACE)、 屬 性 名 稱 (PROPERTY)。 如 果 同 時 指 定 了 多 個 屬 性 名 稱 ， 那 麼 將 按 照 每 行 一 個 ， 依 次 顯 示 每 個 屬 性 的 當 前 值 。 默 認 以 精 簡 格 式 輸 出 ， 但 是 可 以 使 用 --verbose 選 項 以 詳 細 格 式 輸 出 。

set-property SERVICE OBJECT INTERFACE PROPERTY SIGNATURE ARGUMENT... 設 置 對 象 屬 性 的 當 前 值 。 必 須 指 定 下 列 參 數 ： 服 務 名 稱 (SERVICE)、 對 象 路 徑 (OBJECT)、 接 口 名 稱 (INTERFACE)、 屬 性 名 稱 (PROPERTY)、 類 型 標 記 (SIGNATURE)、 參 數 字 符 串 (ARGUMENT)。

help 顯 示 語 法 幫 助

參 數 格 式

call 與 set-property 命 令 都 接 收 一 個 類 型 標 記 (SIGNATURE)與 多 個 參 數 字 符 串 (ARGUMENT)。 有 關 "類 型 標 記 "的 詳 細 說 明 ， 參 見 Type system chapter of the D-Bus specification [2] 文 檔 的 "Type System"小 節 。 對 於 簡 單 類 型 (Basic types)， 類 型 標 記 (SIGNATURE)後 面 的 每 個 參 數 (ARGUMENT)都 必 須 是 參 數 值 的 字 符 串 表 示 。 布 爾 類 型 真 值 可 以 表 示 爲 "true", "yes", "on", "1" ； 布 爾 類 型 假 值 可 以 表 示 爲 "false", "no", "off", "0" 。 對 於 數 組 ， 先 是 一 個 表 示 數 組 項 數 的 數 字 ， 然 後 跟 着 數 組 中 的 每 一 項 。 對 於 變 量 ， 先 是 一 個 表 示 變 量 類 型 的 字 符 ， 然 後 跟 着 變 量 的 值 。 對 於 字 典 與 結 構 ， 直 接 指 定 其 內 容 即 可 。 例 如 ，

s jawoll 是 一 個 簡 單 的 字 符 串 "jawoll" ， "s"是 類 型 標 記 ， "jawoll"是 參 數 字 符 串 。

as 3 hello world foobar 是 一 個 字 符 串 數 組 ， 包 含 3個 成 員 ， 分 別 是 "hello", "world", "foobar"

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 命 令 提 供 了 --verbose 選 項 用 於 輸 出 詳 細 的 、 易 於 理 解 的 多 行 輸 出 格 式 。

例 子

Example 1. 讀 寫 屬 性 下 面 的 兩 個 命 令 ， 首 先 寫 入 一 個 屬 性 ， 然 後 再 讀 取 它 。 該 屬 性 位 於 "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"

Example 2. 精 簡 輸 出 與 詳 細 輸 出 下 面 的 兩 個 命 令 ， 兩 次 讀 取 同 一 個 屬 性 (字 符 串 數 組 類 型 )， 第 一 次 以 精 簡 格 式 顯 示 ， 第 二 次 以 詳 細 格 式 顯 示 ：

$ busctl get-property org.freedesktop.systemd1 /org/freedesktop/systemd1 org.freedesktop.systemd1.Manager Environment
as 2 "LANG=en_US.utf8" "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.utf8";
STRING "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin"; };

Example 3. 調 用 方 法 下 面 的 命 令 ， 在 "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"

參 見

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

NOTES

1.

Libpcap File Format

http://wiki.wireshark.org/Development/LibpcapFileFormat

2.

Type system chapter of the D-Bus specification

http://dbus.freedesktop.org/doc/dbus-specification.html#type-system

3.

D-Bus

http://freedesktop.org/wiki/Software/dbus

跋

本 頁 面 中 文 版 由 中 文 man 手 冊 頁 計 劃 提 供 。 翻 譯 人 員 ： 金 步 國 金 步 國 作 品 集 ： http://www.jinbuguo.com 中 文 man 手 冊 頁 計 劃 ： https://github.com/man-pages-zh/manpages-zh