man/busctl.html

   1 <html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>busctl</title><meta name="generator" content="DocBook XSL Stylesheets V1.78.1"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><style>
   2     a.headerlink {
   3       color: #c60f0f;
   4       font-size: 0.8em;
   5       padding: 0 4px 0 4px;
   6       text-decoration: none;
   7       visibility: hidden;
   8     }
   9
  10     a.headerlink:hover {
  11       background-color: #c60f0f;
  12       color: white;
  13     }
  14
  15     h1:hover > a.headerlink, h2:hover > a.headerlink, h3:hover > a.headerlink, dt:hover > a.headerlink {
  16       visibility: visible;
  17     }
  18   </style><a href="index.html">Index </a>·
  19   <a href="systemd.directives.html">Directives </a>·
  20   <a href="../python-systemd/index.html">Python </a>·
  21   <a href="../libudev/index.html">libudev </a>·
  22   <a href="../libudev/index.html">gudev </a><span style="float:right">systemd 218</span><hr><div class="refentry"><a name="busctl"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>busctl — Introspect the bus</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><div class="cmdsynopsis"><p><code class="command">busctl</code>  [OPTIONS...] [COMMAND] [<em class="replaceable"><code>NAME</code></em>...]</p></div></div><div class="refsect1"><a name="idm140615102621232"></a><h2 id="Description">Description<a class="headerlink" title="Permalink to this headline" href="#Description">¶</a></h2><p><span class="command"><strong>busctl</strong></span> may be used to
  23     introspect and monitor the D-Bus bus.</p></div><div class="refsect1"><a name="idm140615102619488"></a><h2 id="Options">Options<a class="headerlink" title="Permalink to this headline" href="#Options">¶</a></h2><p>The following options are understood:</p><div class="variablelist"><dl class="variablelist"><dt id="--address=ADDRESS"><span class="term"><code class="option">--address=<em class="replaceable"><code>ADDRESS</code></em></code></span><a class="headerlink" title="Permalink to this term" href="#--address=ADDRESS">¶</a></dt><dd><p>Connect to the bus specified by
  24           <em class="replaceable"><code>ADDRESS</code></em> instead of using suitable
  25           defaults for either the system or user bus (see
  26           <code class="option">--system</code> and <code class="option">--user</code>
  27           options).</p></dd><dt id="--show-machine"><span class="term"><code class="option">--show-machine</code></span><a class="headerlink" title="Permalink to this term" href="#--show-machine">¶</a></dt><dd><p>When showing the list of endpoints, show a
  28           column containing the names of containers they belong to.
  29           See
  30           <a href="systemd-machined.service.html"><span class="citerefentry"><span class="refentrytitle">systemd-machined.service</span>(8)</span></a>.
  31           </p></dd><dt id="--unique"><span class="term"><code class="option">--unique</code></span><a class="headerlink" title="Permalink to this term" href="#--unique">¶</a></dt><dd><p>When showing the list of endpoints, show
  32           only "unique" names (of the form
  33           "<code class="literal">:<em class="replaceable"><code>number</code></em>.<em class="replaceable"><code>number</code></em></code>").
  34           </p></dd><dt id="--acquired"><span class="term"><code class="option">--acquired</code></span><a class="headerlink" title="Permalink to this term" href="#--acquired">¶</a></dt><dd><p>The opposite of <code class="option">--unique</code> —
  35           only "well-known" names will be shown.</p></dd><dt id="--activatable"><span class="term"><code class="option">--activatable</code></span><a class="headerlink" title="Permalink to this term" href="#--activatable">¶</a></dt><dd><p>When showing the list of endpoints, show
  36           only endpoints which have actually not been activated yet,
  37           but may be started automatically if accessed.</p></dd><dt id="--match=MATCH"><span class="term"><code class="option">--match=<em class="replaceable"><code>MATCH</code></em></code></span><a class="headerlink" title="Permalink to this term" href="#--match=MATCH">¶</a></dt><dd><p>When showing messages being exchanged, show only the
  38           subset matching <em class="replaceable"><code>MATCH</code></em>.</p></dd><dt id="--no-legend"><span class="term"><code class="option">--no-legend</code></span><a class="headerlink" title="Permalink to this term" href="#--no-legend">¶</a></dt><dd><p>Do not print the legend,
  39           i.e. the column headers and the
  40           footer.</p></dd><dt id="--size="><span class="term"><code class="option">--size=</code></span><a class="headerlink" title="Permalink to this term" href="#--size=">¶</a></dt><dd><p>When used with the <span class="command"><strong>capture</strong></span> command
  41           specifies the maximum bus message size to capture
  42           ("snaplen"). Defaults to 4096 bytes.</p></dd><dt id="--list"><span class="term"><code class="option">--list</code></span><a class="headerlink" title="Permalink to this term" href="#--list">¶</a></dt><dd><p>When used with the <span class="command"><strong>tree</strong></span> command shows a
  43           flat list of object paths instead of a tree.</p></dd><dt id="--quiet"><span class="term"><code class="option">--quiet</code></span><a class="headerlink" title="Permalink to this term" href="#--quiet">¶</a></dt><dd><p>When used with the <span class="command"><strong>call</strong></span> command
  44           suppresses display of the response message payload. Note that even
  45           if this option is specified errors returned will still be
  46           printed and the tool will indicate success or failure with
  47           the process exit code.</p></dd><dt id="--verbose"><span class="term"><code class="option">--verbose</code></span><a class="headerlink" title="Permalink to this term" href="#--verbose">¶</a></dt><dd><p>When used with the <span class="command"><strong>call</strong></span> or
  48           <span class="command"><strong>get-property</strong></span> command shows output in a
  49           more verbose format.</p></dd><dt id="--expect-reply=BOOL"><span class="term"><code class="option">--expect-reply=</code><em class="replaceable"><code>BOOL</code></em></span><a class="headerlink" title="Permalink to this term" href="#--expect-reply=BOOL">¶</a></dt><dd><p>When used with the <span class="command"><strong>call</strong></span> command
  50           specifies whether <span class="command"><strong>busctl</strong></span> shall wait for
  51           completion of the method call, output the returned method
  52           response data, and return success or failure via the process
  53           exit code. If this is set to "<code class="literal">no</code>" the
  54           method call will be issued but no response is expected, the
  55           tool terminates immediately, and thus no response can be
  56           shown, and no success or failure is returned via the exit
  57           code. To only suppress output of the reply message payload
  58           use <code class="option">--quiet</code> above. Defaults to
  59           "<code class="literal">yes</code>".</p></dd><dt id="--auto-start=BOOL"><span class="term"><code class="option">--auto-start=</code><em class="replaceable"><code>BOOL</code></em></span><a class="headerlink" title="Permalink to this term" href="#--auto-start=BOOL">¶</a></dt><dd><p>When used with the <span class="command"><strong>call</strong></span> command specifies
  60           whether the method call should implicitly activate the
  61           called service should it not be running yet but is
  62           configured to be auto-started. Defaults to
  63           "<code class="literal">yes</code>".</p></dd><dt id="--allow-interactive-authorization=BOOL"><span class="term"><code class="option">--allow-interactive-authorization=</code><em class="replaceable"><code>BOOL</code></em></span><a class="headerlink" title="Permalink to this term" href="#--allow-interactive-authorization=BOOL">¶</a></dt><dd><p>When used with the <span class="command"><strong>call</strong></span> command
  64           specifies whether the services may enforce interactive
  65           authorization while executing the operation, if the security
  66           policy is configured for this. Defaults to
  67           "<code class="literal">yes</code>".</p></dd><dt id="--timeout=SECS"><span class="term"><code class="option">--timeout=</code><em class="replaceable"><code>SECS</code></em></span><a class="headerlink" title="Permalink to this term" href="#--timeout=SECS">¶</a></dt><dd><p>When used with the <span class="command"><strong>call</strong></span> command
  68           specifies the maximum time to wait for method call
  69           completion. If no time unit is specified assumes
  70           seconds. The usual other units are understood, too (ms, us,
  71           s, min, h, d, w, month, y). Note that this timeout does not
  72           apply if <code class="option">--expect-reply=no</code> is used as the
  73           tool does not wait for any reply message then. When not
  74           specified or when set to 0 the default of
  75           "<code class="literal">25s</code>" is assumed.</p></dd><dt id="--augment-creds=BOOL"><span class="term"><code class="option">--augment-creds=</code><em class="replaceable"><code>BOOL</code></em></span><a class="headerlink" title="Permalink to this term" href="#--augment-creds=BOOL">¶</a></dt><dd><p>Controls whether credential data reported by
  76           <span class="command"><strong>list</strong></span> or <span class="command"><strong>status</strong></span> shall
  77           be augmented with data from
  78           <code class="filename">/proc</code>. When this is turned on the data
  79           shown is possibly inconsistent, as the data read from
  80           <code class="filename">/proc</code> might be more recent than rest of
  81           the credential information. Defaults to "<code class="literal">yes</code>".</p></dd><dt id="--user"><span class="term"><code class="option">--user</code></span><a class="headerlink" title="Permalink to this term" href="#--user">¶</a></dt><dd><p><a name="user-text"></a>Talk to the service manager of the calling user,
  82       rather than the service manager of the system.</p></dd><dt id="--system"><span class="term"><code class="option">--system</code></span><a class="headerlink" title="Permalink to this term" href="#--system">¶</a></dt><dd><p><a name="system-text"></a>Talk to the service manager of the system. This is the
  83       implied default.</p></dd><dt id="-H"><span class="term"><code class="option">-H</code>, </span><span class="term"><code class="option">--host=</code></span><a class="headerlink" title="Permalink to this term" href="#-H">¶</a></dt><dd><p><a name="host-text"></a>Execute the operation remotely. Specify a hostname, or a
  84       username and hostname separated by "<code class="literal">@</code>", to
  85       connect to. The hostname may optionally be suffixed by a
  86       container name, separated by "<code class="literal">:</code>", which
  87       connects directly to a specific container on the specified
  88       host. This will use SSH to talk to the remote machine manager
  89       instance. Container names may be enumerated with
  90       <span class="command"><strong>machinectl -H
  91       <em class="replaceable"><code>HOST</code></em></strong></span>.</p></dd><dt id="-M"><span class="term"><code class="option">-M</code>, </span><span class="term"><code class="option">--machine=</code></span><a class="headerlink" title="Permalink to this term" href="#-M">¶</a></dt><dd><p><a name="machine-text"></a>Execute operation on a local container. Specify a
  92       container name to connect to.</p></dd><dt id="-h"><span class="term"><code class="option">-h</code>, </span><span class="term"><code class="option">--help</code></span><a class="headerlink" title="Permalink to this term" href="#-h">¶</a></dt><dd><p><a name="help-text"></a>Print a short help text and exit.
  93     </p></dd><dt id="--version"><span class="term"><code class="option">--version</code></span><a class="headerlink" title="Permalink to this term" href="#--version">¶</a></dt><dd><p><a name="version-text"></a>Print a short version string and exit.</p></dd><dt id="--no-pager"><span class="term"><code class="option">--no-pager</code></span><a class="headerlink" title="Permalink to this term" href="#--no-pager">¶</a></dt><dd><p>Do not pipe output into a pager.</p></dd></dl></div></div><div class="refsect1"><a name="idm140615101541984"></a><h2 id="Commands">Commands<a class="headerlink" title="Permalink to this headline" href="#Commands">¶</a></h2><p>The following commands are understood:</p><div class="variablelist"><dl class="variablelist"><dt id="list"><span class="term"><span class="command"><strong>list</strong></span></span><a class="headerlink" title="Permalink to this term" href="#list">¶</a></dt><dd><p>Show service names on the bus. This is the
  94         default if no command is specified.</p></dd><dt id="status SERVICE"><span class="term"><span class="command"><strong>status</strong></span>  [<em class="replaceable"><code>SERVICE</code></em>]</span><a class="headerlink" title="Permalink to this term" href="#status%20SERVICE">¶</a></dt><dd><p>Show process information and credentials of a
  95         bus service (if one is specified by its unique or well-known
  96         name), a process (if one is specified by its numeric PID), or
  97         the owner of the bus (if no parameter is
  98         specified).</p></dd><dt id="monitor SERVICE"><span class="term"><span class="command"><strong>monitor</strong></span>  [<em class="replaceable"><code>SERVICE</code></em>...]</span><a class="headerlink" title="Permalink to this term" href="#monitor%20SERVICE">¶</a></dt><dd><p>Dump messages being exchanged. If
  99         <em class="replaceable"><code>SERVICE</code></em> is specified, show messages
 100         to or from this endpoint. Otherwise, show all messages on the
 101         bus. Use Ctrl-C to terminate dump.</p></dd><dt id="capture SERVICE"><span class="term"><span class="command"><strong>capture</strong></span>  [<em class="replaceable"><code>SERVICE</code></em>...]</span><a class="headerlink" title="Permalink to this term" href="#capture%20SERVICE">¶</a></dt><dd><p>Similar to <span class="command"><strong>monitor</strong></span> but
 102         writes the output in pcap format (for details see the <a class="ulink" href="http://wiki.wireshark.org/Development/LibpcapFileFormat" target="_top">Libpcap
 103         File Format</a> description. Make sure to redirect the
 104         output to STDOUT to a file. Tools like
 105         <a href="wireshark.html"><span class="citerefentry"><span class="refentrytitle">wireshark</span>(1)</span></a>
 106         may be used to dissect and view the generated
 107         files.</p></dd><dt id="tree SERVICE"><span class="term"><span class="command"><strong>tree</strong></span>  [<em class="replaceable"><code>SERVICE</code></em>...]</span><a class="headerlink" title="Permalink to this term" href="#tree%20SERVICE">¶</a></dt><dd><p>Shows an object tree of one or more
 108         services. If <em class="replaceable"><code>SERVICE</code></em> is specified,
 109         show object tree of the specified services only. Otherwise,
 110         show all object trees of all services on the bus that acquired
 111         at least one well-known name.</p></dd><dt id="introspect SERVICE OBJECT"><span class="term"><span class="command"><strong>introspect</strong></span>   <em class="replaceable"><code>SERVICE</code></em>    <em class="replaceable"><code>OBJECT</code></em> </span><a class="headerlink" title="Permalink to this term" href="#introspect%20SERVICE%20OBJECT">¶</a></dt><dd><p>Show interfaces, methods, properties and
 112         signals of the specified object (identified by its path) on
 113         the specified service.</p></dd><dt id="call SERVICE OBJECT INTERFACE METHOD SIGNATURE ARGUMENT"><span class="term"><span class="command"><strong>call</strong></span>   <em class="replaceable"><code>SERVICE</code></em>    <em class="replaceable"><code>OBJECT</code></em>    <em class="replaceable"><code>INTERFACE</code></em>    <em class="replaceable"><code>METHOD</code></em>   [<em class="replaceable"><code>SIGNATURE</code></em>  [<em class="replaceable"><code>ARGUMENT</code></em>...]]</span><a class="headerlink" title="Permalink to this term" href="#call%20SERVICE%20OBJECT%20INTERFACE%20METHOD%20SIGNATURE%20ARGUMENT">¶</a></dt><dd><p>Invoke a method and show the response. Takes a
 114         service name, object path, interface name and method name. If
 115         parameters shall be passed to the method call a signature
 116         string is required, followed by the arguments, individually
 117         formatted as strings. For details on the formatting used, see
 118         below. To suppress output of the returned data use the
 119         <code class="option">--quiet</code> option.</p></dd><dt id="get-property SERVICE OBJECT INTERFACE PROPERTY"><span class="term"><span class="command"><strong>get-property</strong></span>   <em class="replaceable"><code>SERVICE</code></em>    <em class="replaceable"><code>OBJECT</code></em>    <em class="replaceable"><code>INTERFACE</code></em>    <em class="replaceable"><code>PROPERTY</code></em>... </span><a class="headerlink" title="Permalink to this term" href="#get-property%20SERVICE%20OBJECT%20INTERFACE%20PROPERTY">¶</a></dt><dd><p>Retrieve the current value of one or more
 120         object properties. Takes a service name, object path,
 121         interface name and property name. Multiple properties may be
 122         specified at once in which case their values will be shown one
 123         after the other, separated by newlines. The output is by
 124         default in terse format. Use <code class="option">--verbose</code> for a
 125         more elaborate output format.</p></dd><dt id="set-property SERVICE OBJECT INTERFACE PROPERTY SIGNATURE ARGUMENT"><span class="term"><span class="command"><strong>set-property</strong></span>   <em class="replaceable"><code>SERVICE</code></em>    <em class="replaceable"><code>OBJECT</code></em>    <em class="replaceable"><code>INTERFACE</code></em>    <em class="replaceable"><code>PROPERTY</code></em>    <em class="replaceable"><code>SIGNATURE</code></em>    <em class="replaceable"><code>ARGUMENT</code></em>... </span><a class="headerlink" title="Permalink to this term" href="#set-property%20SERVICE%20OBJECT%20INTERFACE%20PROPERTY%20SIGNATURE%20ARGUMENT">¶</a></dt><dd><p>Set the current value an object
 126         property. Takes a service name, object path, interface name,
 127         property name, property signature, followed by a list of
 128         parameters formatted as strings.</p></dd><dt id="help"><span class="term"><span class="command"><strong>help</strong></span></span><a class="headerlink" title="Permalink to this term" href="#help">¶</a></dt><dd><p>Show command syntax help.</p></dd></dl></div></div><div class="refsect1"><a name="idm140615101496672"></a><h2 id="Parameter Formatting">Parameter Formatting<a class="headerlink" title="Permalink to this headline" href="#Parameter%20Formatting">¶</a></h2><p>The <span class="command"><strong>call</strong></span> and
 129     <span class="command"><strong>set-property</strong></span> commands take a signature string
 130     followed by a list of parameters formatted as string (for details
 131     on D-Bus signature strings see the <a class="ulink" href="http://dbus.freedesktop.org/doc/dbus-specification.html#type-system" target="_top">Type
 132     system chapter of the D-Bus specification</a>). For simple
 133     types each parameter following the signature should simply be the
 134     parameter's value formatted as string. Positive boolean values may
 135     be formatted as "<code class="literal">true</code>", "<code class="literal">yes</code>",
 136     "<code class="literal">on</code>", "<code class="literal">1</code>"; negative boolean
 137     values may be specified as "<code class="literal">false</code>",
 138     "<code class="literal">no</code>", "<code class="literal">off</code>",
 139     "<code class="literal">0</code>". For arrays, a numeric argument for the
 140     number of entries followed by the entries shall be specified. For
 141     variants the signature of the contents shall be specified,
 142     followed by the contents. For dictionaries and structs the
 143     contents of them shall be directly specified.</p><p>For example,
 144     </p><pre class="programlisting">s jawoll</pre><p> is the formatting
 145     of a single string "<code class="literal">jawoll</code>".</p><p>
 146     </p><pre class="programlisting">as 3 hello world foobar</pre><p>
 147     is the formatting of a string array with three entries,
 148     "<code class="literal">hello</code>", "<code class="literal">world</code>" and
 149     "<code class="literal">foobar</code>".</p><p>
 150     </p><pre class="programlisting">a{sv} 3 One s Eins Two u 2 Yes b true</pre><p>
 151     is the formatting of a dictionary
 152     array that maps strings to variants, consisting of three
 153     entries. The string "<code class="literal">One</code>" is assigned the
 154     string "<code class="literal">Eins</code>". The string
 155     "<code class="literal">Two</code>" is assigned the 32bit unsigned
 156     integer 2. The string "<code class="literal">Yes</code>" is assigned a
 157     positive boolean.</p><p>Note that the <span class="command"><strong>call</strong></span>,
 158     <span class="command"><strong>get-property</strong></span>, <span class="command"><strong>introspect</strong></span>
 159     commands will also generate output in this format for the returned
 160     data. Since this format is sometimes too terse to be easily
 161     understood, the <span class="command"><strong>call</strong></span> and
 162     <span class="command"><strong>get-property</strong></span> commands may generate a more
 163     verbose, multi-line output when passed the
 164     <code class="option">--verbose</code> option.</p></div><div class="refsect1"><a name="idm140615101475488"></a><h2 id="Examples">Examples<a class="headerlink" title="Permalink to this headline" href="#Examples">¶</a></h2><div class="example"><a name="idm140615101474848"></a><p class="title"><b>Example 1. Write and Read a Property</b></p><div class="example-contents"><p>The following two commands first write a property and then
 165       read it back. The property is found on the
 166       "<code class="literal">/org/freedesktop/systemd1</code>" object of the
 167       "<code class="literal">org.freedesktop.systemd1</code>" service. The name of
 168       the property is "<code class="literal">LogLevel</code>" on the
 169       "<code class="literal">org.freedesktop.systemd1.Manager</code>"
 170       interface. The property contains a single string:</p><pre class="programlisting"># busctl set-property org.freedesktop.systemd1 /org/freedesktop/systemd1 org.freedesktop.systemd1.Manager LogLevel s debug
 171 # busctl get-property org.freedesktop.systemd1 /org/freedesktop/systemd1 org.freedesktop.systemd1.Manager LogLevel
 172 s "debug"</pre></div></div><br class="example-break"><div class="example"><a name="idm140615101470192"></a><p class="title"><b>Example 2. Terse and Verbose Output</b></p><div class="example-contents"><p>The following two commands read a property that contains
 173       an array of strings, and first show it in terse format, followed
 174       by verbose format:</p><pre class="programlisting">$ busctl get-property org.freedesktop.systemd1 /org/freedesktop/systemd1 org.freedesktop.systemd1.Manager Environment
 175 as 2 "LANG=en_US.UTF-8" "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin"
 176 $ busctl get-property --verbose org.freedesktop.systemd1 /org/freedesktop/systemd1 org.freedesktop.systemd1.Manager Environment
 177 ARRAY "s" {
 178         STRING "LANG=en_US.UTF-8";
 179         STRING "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin";
 180 };</pre></div></div><br class="example-break"><div class="example"><a name="idm140615101467776"></a><p class="title"><b>Example 3. Invoking a Method</b></p><div class="example-contents"><p>The following command invokes a the
 181       "<code class="literal">StartUnit</code>" method on the
 182       "<code class="literal">org.freedesktop.systemd1.Manager</code>"
 183       interface of the
 184       "<code class="literal">/org/freedesktop/systemd1</code>" object
 185       of the "<code class="literal">org.freedesktop.systemd1</code>"
 186       service, and passes it two strings
 187       "<code class="literal">cups.service</code>" and
 188       "<code class="literal">replace</code>". As result of the method
 189       call a single object path parameter is received and
 190       shown:</p><pre class="programlisting"># busctl call org.freedesktop.systemd1 /org/freedesktop/systemd1 org.freedesktop.systemd1.Manager StartUnit ss "cups.service" "replace"
 191 o "/org/freedesktop/systemd1/job/42684"</pre></div></div><br class="example-break"></div><div class="refsect1"><a name="idm140615101461824"></a><h2 id="See Also">See Also<a class="headerlink" title="Permalink to this headline" href="#See%20Also">¶</a></h2><p>
 192       <a href="dbus-daemon.html"><span class="citerefentry"><span class="refentrytitle">dbus-daemon</span>(1)</span></a>,
 193       <a class="ulink" href="http://freedesktop.org/wiki/Software/dbus" target="_top">D-Bus</a>,
 194       <a class="ulink" href="https://code.google.com/p/d-bus/" target="_top">kdbus</a>,
 195       <a href="sd-bus.html"><span class="citerefentry"><span class="refentrytitle">sd-bus</span>(3)</span></a>,
 196       <a href="systemd.html"><span class="citerefentry"><span class="refentrytitle">systemd</span>(1)</span></a>,
 197       <a href="systemd-bus-proxyd.html"><span class="citerefentry"><span class="refentrytitle">systemd-bus-proxyd</span>(8)</span></a>,
 198       <a href="machinectl.html"><span class="citerefentry"><span class="refentrytitle">machinectl</span>(1)</span></a>,
 199       <a href="wireshark.html"><span class="citerefentry"><span class="refentrytitle">wireshark</span>(1)</span></a>
 200     </p></div></div></body></html>