busctl
busctl — 内省与监视 D-Bus 总线
busctl
[OPTIONS…] [COMMAND] [NAME
…]
命令
能够识别的命令如下:
-
list
显示总线上的所有peer(依据服务名称), 这是默认命令。 默认同时显示"唯一名"(UniqueName)与"易读名"(well-known name), 但是可以使用
--unique
与--acquired
选项进行修改。 -
status [
SERVICE
]如果 SERVICE 是一个总线服务的"唯一名"或"易读名", 那么显示该服务的进程信息及凭证信息。 如果 SERVICE 是一个进程的PID,那么显示该进程的进程信息及凭证信息。 如果未指定 SERVICE 参数, 那么显示总线所有者的进程信息及凭证信息。
-
monitor [
SERVICE
…]监视已交换的消息。 如果未指定
SERVICE
参数,那么显示总线上的所有消息。 如果指定了SERVICE
参数(“唯一名"或"易读名”), 那么仅显示到达此peer或者从此peer发出的消息。 可使用 Ctrl+C 中断监视。 -
capture [
SERVICE
…]与 monitor 命令类似, 不同之处在于以 pcap 格式输出(详见 Libpcap File Format)。 强烈推荐将标准输出(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
显示语法帮助
选项
能够识别的命令行选项如下:
-
--address=*
ADDRESS*
连接到
ADDRESS
指定的总线, 而不是默认的总线(无论是--system
系统总线还是--user
用户总线)。 -
--show-machine
在使用 list 命令 显示总线上的所有 peer 列表时, 额外显示一个"MACHINE"列,指明其所属容器的名称。参见 systemd-machined.service(8) 手册。
-
--unique
在使用 list 命令 显示总线上的所有 peer 列表时,仅显示 “
:*
number*.*
number*
” 格式的"唯一名"(UniqueName)。root@obmc:~# busctl list --unique | grep power :1.21 225 power-control root :1.21 xyz.openbmc_project.Chassis.Control.Power.service - - root@obmc:~# busctl list | grep power :1.21 225 power-control root :1.21 xyz.openbmc_project.Chassis.Control.Power.service - - xyz.openbmc_project.Chassis.Buttons 225 power-control root :1.21 xyz.openbmc_project.Chassis.Control.Power.service - - xyz.openbmc_project.Control.Host.NMI 225 power-control root :1.21 xyz.openbmc_project.Chassis.Control.Power.service - - xyz.openbmc_project.Control.Host.RestartCause 225 power-control root :1.21 xyz.openbmc_project.Chassis.Control.Power.service - - xyz.openbmc_project.State.Chassis 225 power-control root :1.21 xyz.openbmc_project.Chassis.Control.Power.service - - xyz.openbmc_project.State.Host 225 power-control root :1.21 xyz.openbmc_project.Chassis.Control.Power.service - - xyz.openbmc_project.State.OperatingSystem 225 power-control root :1.21 xyz.openbmc_project.Chassis.Control.Power.service - -
-
--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 命令显示对象路径时, 不以树形缩进显示,而是以平铺列表的格式显示。
-
-q
,--quiet
与 call 命令连用, 禁止显示应答消息。 注意: 错误消息依然会被显示出来, 并且依然可以用返回值判断成败。
-
--verbose
与 call 或 get-property 命令连用, 表示以详细模式显示输出。
-
--json=
MODE
与 call 或 get-property 命令连用,表示以 JSON 格式显示输出内容。
MODE
可以是 “short
”(以最短方式输出,不带任何多余的空白或换行符) 或 “pretty
”(以易读方式输出,带有空白与换行符)。 注意,从 D-Bus 信号编集(marshalling)到 JSON 的转换是无损的, 也就是说类型信息也被嵌入了 JSON 对象树中。 -
-j
当从终端交互式调用时等价于
--json=pretty
, 否则等价于--json=short
(特别是将输出内容通过管道传递给另一个程序时)。 -
--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
中的数据可能会更新。 -
--watch-bind=
BOOL
在连接到特定的
AF_UNIX
套接字之前,是否等待它出现在文件系统中。 设为 yes 表示一直监视文件系统,直到所需的套接字被创建之后,才会去连接。 默认值是 off 。 -
--user
与当前调用用户的用户服务管理器(systemd 用户实例)通信, 而不是默认的系统服务管理器(systemd 系统实例)。
-
--system
与系统服务管理器(systemd 系统实例)通信, 这是默认值。
-
-H
,--host=
操作指定的远程主机。可以仅指定一个主机名(hostname), 也可以使用 “
username@hostname
” 格式。 hostname 后面还可以加上 SSH监听端口(以冒号":
“分隔)与容器名(以正斜线”/
"分隔), 也就是形如 “hostname:port/container
” 的格式, 以表示直接连接到指定主机的指定容器内。 操作将通过SSH协议进行,以确保安全。 可以通过 machinectl -H *HOST
* 命令列出远程主机上的所有容器名称。IPv6地址必须放在方括号([])内。 -
-M
,--machine=
在本地容器内执行操作。 必须明确指定容器的名称。
-
--no-pager
不将程序的输出内容管道(pipe)给分页程序。
-
--no-legend
不输出列标题, 也就是不在输出列表的头部和尾部显示字段的名称。
-
-h
,--help
显示简短的帮助信息并退出。
-
--version
显示简短的版本信息并退出。
参数格式
call 与 set-property 命令都接收一个类型标记(SIGNATURE)与多个参数字符串(ARGUMENT)。 有关"类型标记"的详细说明, 参见 Type system chapter of the D-Bus specification 文档的"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
选项用于输出详细的、易于理解的多行输出格式。
例子
例 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"
例 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";
};
例 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"
org.freedesktop.DBus
在dbus总线上,每个service下的object path下都会有org.freedesktop.DBus的interface。
其中org.freedesktop.DBus.Introspectable 下的Introspect 对应 busctl 的Introspect。
org.freedesktop.DBus.Properties下的set/get 对应 busctl的set/get-property,设置/获取某一个属性的值。可以在代码中调用。
org.freedesktop.DBus.Properties下的GetAll 获取某一个interface下的所有property的值。可以在代码中调用。
org.freedesktop.DBus.Properties下的 PropertiesChanged 是信号,代码中可以订阅当有property变化时会发出信号。