<?xml version='1.0'?> <!--*-nxml-*-->

<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"

"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">

<refentry id="busctl"

xmlns:xi="http://www.w3.org/2001/XInclude">

<refentryinfo>

<title>busctl</title>

<productname>systemd</productname>

<authorgroup>

<author>

<contrib>A monkey with a typewriter</contrib>

<firstname>Zbigniew</firstname>

<surname>Jędrzejewski-Szmek</surname>

<email>zbyszek@in.waw.pl</email>

</author>

</authorgroup>

</refentryinfo>

<refmeta>

<refentrytitle>busctl</refentrytitle>

<manvolnum>1</manvolnum>

</refmeta>

<refnamediv>

<refname>busctl</refname>

<refpurpose>Introspect the bus</refpurpose>

</refnamediv>

<refsynopsisdiv>

<cmdsynopsis>

<command>busctl</command>

<arg choice="opt" rep="repeat">OPTIONS</arg>

<arg choice="opt">COMMAND</arg>

<arg choice="opt" rep="repeat"><replaceable>NAME</replaceable></arg>

</cmdsynopsis>

</refsynopsisdiv>

<refsect1>

<title>Description</title>

<para><command>busctl</command> may be used to

introspect and monitor the D-Bus bus.</para>

</refsect1>

<refsect1>

<title>Options</title>

<para>The following options are understood:</para>

<variablelist>

<varlistentry>

<term><option>--address=<replaceable>ADDRESS</replaceable></option></term>

<listitem><para>Connect to the bus specified by

<replaceable>ADDRESS</replaceable> instead of using suitable

defaults for either the system or user bus (see

<option>--system</option> and <option>--user</option>

options).</para></listitem>

</varlistentry>

<varlistentry>

<term><option>--show-machine</option></term>

<listitem><para>When showing the list of endpoints, show a

column containing the names of containers they belong to.

See

<citerefentry><refentrytitle>systemd-machined.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.

</para></listitem>

</varlistentry>

<varlistentry>

<term><option>--unique</option></term>

<listitem><para>When showing the list of endpoints, show

only "unique" names (of the form

<literal>:<replaceable>number</replaceable>.<replaceable>number</replaceable></literal>).

</para></listitem>

</varlistentry>

<varlistentry>

<term><option>--acquired</option></term>

<listitem><para>The opposite of <option>--unique</option> —

only "well-known" names will be shown.</para></listitem>

</varlistentry>

<varlistentry>

<term><option>--activatable</option></term>

<listitem><para>When showing the list of endpoints, show

only endpoints which have actually not been activated yet,

but may be started automatically if accessed.</para>

</listitem>

</varlistentry>

<varlistentry>

<term><option>--match=<replaceable>MATCH</replaceable></option></term>

<listitem><para>When showing messages being exchanged, show only the

subset matching <replaceable>MATCH</replaceable>.</para></listitem>

<!-- TODO: link to sd_bus_add_match when it is written? -->

</varlistentry>

<varlistentry>

<term><option>--no-legend</option></term>

<listitem>

<para>Do not print the legend,

i.e. the column headers and the

footer.</para>

</listitem>

</varlistentry>

<varlistentry>

<term><option>--size=</option></term>

<listitem>

<para>When used with the <command>capture</command> command

specifies the maximum bus message size to capture

("snaplen"). Defaults to 4096 bytes.</para>

</listitem>

</varlistentry>

<varlistentry>

<term><option>--list</option></term>

<listitem>

<para>When used with the <command>tree</command> shows a

flat list of object paths instead of a tree.</para>

</listitem>

</varlistentry>

<varlistentry>

<term><option>--quiet</option></term>

<listitem>

<para>When used with the <command>call</command> command suppresses

display of the response message.</para>

</listitem>

</varlistentry>

<xi:include href="user-system-options.xml" xpointer="user" />

<xi:include href="user-system-options.xml" xpointer="system" />

<xi:include href="user-system-options.xml" xpointer="host" />

<xi:include href="user-system-options.xml" xpointer="machine" />

<xi:include href="standard-options.xml" xpointer="help" />

<xi:include href="standard-options.xml" xpointer="version" />

<xi:include href="standard-options.xml" xpointer="no-pager" />

</variablelist>

</refsect1>

<refsect1>

<title>Commands</title>

<para>The following commands are understood:</para>

<variablelist>

<varlistentry>

<term><command>list</command></term>

<listitem><para>Show service names on the bus. This is the

default if no command is specified.</para></listitem>

</varlistentry>

<varlistentry>

<term><command>tree</command> <arg choice="opt" rep="repeat"><replaceable>NAME</replaceable></arg></term>

<listitem><para>Shows an object tree of one or more

services. If <replaceable>NAME</replaceable> is specified,

show object tree of the specified services only. Otherwise,

show all object trees of all services on the bus that acquired

at least one well-known name.</para></listitem>

</varlistentry>

<varlistentry>

<term><command>monitor</command> <arg choice="opt" rep="repeat"><replaceable>NAME</replaceable></arg></term>

<listitem><para>Dump messages being exchanged. If

<replaceable>NAME</replaceable> is specified, show messages

to or from this endpoint. Otherwise, show all messages on the

bus.</para></listitem>

</varlistentry>

<varlistentry>

<term><command>capture</command> <arg choice="opt" rep="repeat"><replaceable>NAME</replaceable></arg></term>

<listitem><para>Similar to <command>monitor</command> but

writes the output in pcap format (for details see the <ulink

url="http://wiki.wireshark.org/Development/LibpcapFileFormat">Libpcap

File Format</ulink> description. Make sure to redirect the

output to STDOUT to a file. Tools like

<citerefentry><refentrytitle>wireshark</refentrytitle><manvolnum>1</manvolnum></citerefentry>

may be used to dissect and view the generated

files.</para></listitem>

</varlistentry>

<varlistentry>

<term><command>status</command> <arg choice="plain"><replaceable>NAME</replaceable></arg></term>

<listitem><para>Show process information and credentials of a

bus service.</para></listitem>

</varlistentry>

<varlistentry>

<term><command>call</command> <arg choice="plain"><replaceable>SERVICE</replaceable></arg> <arg choice="plain"><replaceable>OBJECT</replaceable></arg> <arg choice="plain"><replaceable>INTERFACE</replaceable></arg> <arg choice="plain"><replaceable>METHOD</replaceable></arg> <arg choice="opt"><replaceable>SIGNATURE</replaceable> <arg choice="opt" rep="repeat"><replaceable>PARAMETERS</replaceable></arg></arg></term>

<listitem><para>Invoke a method and show the response.</para></listitem>

</varlistentry>

<varlistentry>

<term><command>help</command></term>

<listitem><para>Show command syntax help.</para></listitem>

</varlistentry>

</variablelist>

</refsect1>

<refsect1>

<title>See Also</title>

<para>

<citerefentry><refentrytitle>dbus-daemon</refentrytitle><manvolnum>1</manvolnum></citerefentry>,

<ulink url="http://freedesktop.org/wiki/Software/dbus">D-Bus</ulink>,

<ulink url="https://code.google.com/p/d-bus/">kdbus</ulink>,

<citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>,

<citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,

<citerefentry><refentrytitle>systemd-bus-proxyd</refentrytitle><manvolnum>8</manvolnum></citerefentry>,

<citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,

<citerefentry><refentrytitle>wireshark</refentrytitle><manvolnum>1</manvolnum></citerefentry>

</para>

</refsect1>

</refentry>