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