proxmox-mirrors/systemd
1
0
Fork 0
mirror of https://git.proxmox.com/git/systemd synced 2025-07-27 08:48:50 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity
e735f4d4ea
systemd/man/busctl.html
Martin Pitt e735f4d4ea Imported Upstream version 219
2015-02-17 11:22:16 +01:00

202 lines
25 KiB
HTML
Raw Blame History

This file contains invisible Unicode characters

This file contains invisible Unicode characters that are indistinguishable to humans but may be processed differently by a computer. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<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>
a.headerlink {
color: #c60f0f;
font-size: 0.8em;
padding: 0 4px 0 4px;
text-decoration: none;
visibility: hidden;
}
a.headerlink:hover {
background-color: #c60f0f;
color: white;
}
h1:hover > a.headerlink, h2:hover > a.headerlink, h3:hover > a.headerlink, dt:hover > a.headerlink {
visibility: visible;
}
</style><a href="index.html">Index </a>·
<a href="systemd.directives.html">Directives </a>·
<a href="../python-systemd/index.html">Python </a>·
<a href="../libudev/index.html">libudev </a>·
<a href="../libudev/index.html">gudev </a><span style="float:right">systemd 219</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="idm140613074880256"></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
introspect and monitor the D-Bus bus.</p></div><div class="refsect1"><a name="idm140613074878512"></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
<em class="replaceable"><code>ADDRESS</code></em> instead of using suitable
defaults for either the system or user bus (see
<code class="option">--system</code> and <code class="option">--user</code>
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
column containing the names of containers they belong to.
See
<a href="systemd-machined.service.html"><span class="citerefentry"><span class="refentrytitle">systemd-machined.service</span>(8)</span></a>.
</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
only "unique" names (of the form
"<code class="literal">:<em class="replaceable"><code>number</code></em>.<em class="replaceable"><code>number</code></em></code>").
</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> —
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
only endpoints which have actually not been activated yet,
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
subset matching <em class="replaceable"><code>MATCH</code></em>.</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
specifies the maximum bus message size to capture
("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
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
suppresses display of the response message payload. Note that even
if this option is specified errors returned will still be
printed and the tool will indicate success or failure with
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
<span class="command"><strong>get-property</strong></span> command shows output in a
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
specifies whether <span class="command"><strong>busctl</strong></span> shall wait for
completion of the method call, output the returned method
response data, and return success or failure via the process
exit code. If this is set to "<code class="literal">no</code>" the
method call will be issued but no response is expected, the
tool terminates immediately, and thus no response can be
shown, and no success or failure is returned via the exit
code. To only suppress output of the reply message payload
use <code class="option">--quiet</code> above. Defaults to
"<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
whether the method call should implicitly activate the
called service should it not be running yet but is
configured to be auto-started. Defaults to
"<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
specifies whether the services may enforce interactive
authorization while executing the operation, if the security
policy is configured for this. Defaults to
"<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
specifies the maximum time to wait for method call
completion. If no time unit is specified assumes
seconds. The usual other units are understood, too (ms, us,
s, min, h, d, w, month, y). Note that this timeout does not
apply if <code class="option">--expect-reply=no</code> is used as the
tool does not wait for any reply message then. When not
specified or when set to 0 the default of
"<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
<span class="command"><strong>list</strong></span> or <span class="command"><strong>status</strong></span> shall
be augmented with data from
<code class="filename">/proc</code>. When this is turned on the data
shown is possibly inconsistent, as the data read from
<code class="filename">/proc</code> might be more recent than rest of
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,
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
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
username and hostname separated by "<code class="literal">@</code>", to
connect to. The hostname may optionally be suffixed by a
container name, separated by "<code class="literal">:</code>", which
connects directly to a specific container on the specified
host. This will use SSH to talk to the remote machine manager
instance. Container names may be enumerated with
<span class="command"><strong>machinectl -H
<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
container name to connect to.</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><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, i.e. column headers and the
footer with hints.</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.
</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></dl></div></div><div class="refsect1"><a name="idm140613073806304"></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
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
bus service (if one is specified by its unique or well-known
name), a process (if one is specified by its numeric PID), or
the owner of the bus (if no parameter is
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
<em class="replaceable"><code>SERVICE</code></em> is specified, show messages
to or from this endpoint. Otherwise, show all messages on the
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
writes the output in pcap format (for details see the <a class="ulink" href="http://wiki.wireshark.org/Development/LibpcapFileFormat" target="_top">Libpcap
File Format</a> description. Make sure to redirect the
output to STDOUT to a file. Tools like
<a href="wireshark.html"><span class="citerefentry"><span class="refentrytitle">wireshark</span>(1)</span></a>
may be used to dissect and view the generated
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
services. If <em class="replaceable"><code>SERVICE</code></em> 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.</p></dd><dt id="introspect SERVICE OBJECT INTERFACE"><span class="term"><span class="command"><strong>introspect</strong></span> <em class="replaceable"><code>SERVICE</code></em> <em class="replaceable"><code>OBJECT</code></em> [<em class="replaceable"><code>INTERFACE</code></em>]</span><a class="headerlink" title="Permalink to this term" href="#introspect%20SERVICE%20OBJECT%20INTERFACE"></a></dt><dd><p>Show interfaces, methods, properties and
signals of the specified object (identified by its path) on
the specified service. If the interface argument is passed the
output is limited to members of the specified
interface.</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
service name, object path, interface name and method name. If
parameters shall be passed to the method call a signature
string is required, followed by the arguments, individually
formatted as strings. For details on the formatting used, see
below. To suppress output of the returned data use the
<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
object properties. Takes a service name, object path,
interface name and property name. Multiple properties may be
specified at once in which case their values will be shown one
after the other, separated by newlines. The output is by
default in terse format. Use <code class="option">--verbose</code> for a
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
property. Takes a service name, object path, interface name,
property name, property signature, followed by a list of
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="idm140613073759888"></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
<span class="command"><strong>set-property</strong></span> commands take a signature string
followed by a list of parameters formatted as string (for details
on D-Bus signature strings see the <a class="ulink" href="http://dbus.freedesktop.org/doc/dbus-specification.html#type-system" target="_top">Type
system chapter of the D-Bus specification</a>). For simple
types each parameter following the signature should simply be the
parameter's value formatted as string. Positive boolean values may
be formatted as "<code class="literal">true</code>", "<code class="literal">yes</code>",
"<code class="literal">on</code>", "<code class="literal">1</code>"; negative boolean
values may be specified as "<code class="literal">false</code>",
"<code class="literal">no</code>", "<code class="literal">off</code>",
"<code class="literal">0</code>". For arrays, a numeric argument for the
number of entries followed by the entries shall be specified. For
variants the signature of the contents shall be specified,
followed by the contents. For dictionaries and structs the
contents of them shall be directly specified.</p><p>For example,
</p><pre class="programlisting">s jawoll</pre><p> is the formatting
of a single string "<code class="literal">jawoll</code>".</p><p>
</p><pre class="programlisting">as 3 hello world foobar</pre><p>
is the formatting of a string array with three entries,
"<code class="literal">hello</code>", "<code class="literal">world</code>" and
"<code class="literal">foobar</code>".</p><p>
</p><pre class="programlisting">a{sv} 3 One s Eins Two u 2 Yes b true</pre><p>
is the formatting of a dictionary
array that maps strings to variants, consisting of three
entries. The string "<code class="literal">One</code>" is assigned the
string "<code class="literal">Eins</code>". The string
"<code class="literal">Two</code>" is assigned the 32bit unsigned
integer 2. The string "<code class="literal">Yes</code>" is assigned a
positive boolean.</p><p>Note that the <span class="command"><strong>call</strong></span>,
<span class="command"><strong>get-property</strong></span>, <span class="command"><strong>introspect</strong></span>
commands will also generate output in this format for the returned
data. Since this format is sometimes too terse to be easily
understood, the <span class="command"><strong>call</strong></span> and
<span class="command"><strong>get-property</strong></span> commands may generate a more
verbose, multi-line output when passed the
<code class="option">--verbose</code> option.</p></div><div class="refsect1"><a name="idm140613073738704"></a><h2 id="Examples">Examples<a class="headerlink" title="Permalink to this headline" href="#Examples"></a></h2><div class="example"><a name="idm140613073738064"></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
read it back. The property is found on the
"<code class="literal">/org/freedesktop/systemd1</code>" object of the
"<code class="literal">org.freedesktop.systemd1</code>" service. The name of
the property is "<code class="literal">LogLevel</code>" on the
"<code class="literal">org.freedesktop.systemd1.Manager</code>"
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
# busctl get-property org.freedesktop.systemd1 /org/freedesktop/systemd1 org.freedesktop.systemd1.Manager LogLevel
s "debug"</pre></div></div><br class="example-break"><div class="example"><a name="idm140613073733408"></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
an array of strings, and first show it in terse format, followed
by verbose format:</p><pre class="programlisting">$ busctl get-property org.freedesktop.systemd1 /org/freedesktop/systemd1 org.freedesktop.systemd1.Manager Environment
as 2 "LANG=en_US.UTF-8" "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.UTF-8";
STRING "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin";
};</pre></div></div><br class="example-break"><div class="example"><a name="idm140613073730992"></a><p class="title"><b>Example 3. Invoking a Method</b></p><div class="example-contents"><p>The following command invokes a the
"<code class="literal">StartUnit</code>" method on the
"<code class="literal">org.freedesktop.systemd1.Manager</code>"
interface of the
"<code class="literal">/org/freedesktop/systemd1</code>" object
of the "<code class="literal">org.freedesktop.systemd1</code>"
service, and passes it two strings
"<code class="literal">cups.service</code>" and
"<code class="literal">replace</code>". As result of the method
call a single object path parameter is received and
shown:</p><pre class="programlisting"># busctl call org.freedesktop.systemd1 /org/freedesktop/systemd1 org.freedesktop.systemd1.Manager StartUnit ss "cups.service" "replace"
o "/org/freedesktop/systemd1/job/42684"</pre></div></div><br class="example-break"></div><div class="refsect1"><a name="idm140613073725040"></a><h2 id="See Also">See Also<a class="headerlink" title="Permalink to this headline" href="#See%20Also"></a></h2><p>
<a href="dbus-daemon.html"><span class="citerefentry"><span class="refentrytitle">dbus-daemon</span>(1)</span></a>,
<a class="ulink" href="http://freedesktop.org/wiki/Software/dbus" target="_top">D-Bus</a>,
<a class="ulink" href="https://code.google.com/p/d-bus/" target="_top">kdbus</a>,
<a href="sd-bus.html"><span class="citerefentry"><span class="refentrytitle">sd-bus</span>(3)</span></a>,
<a href="systemd.html"><span class="citerefentry"><span class="refentrytitle">systemd</span>(1)</span></a>,
<a href="systemd-bus-proxyd.html"><span class="citerefentry"><span class="refentrytitle">systemd-bus-proxyd</span>(8)</span></a>,
<a href="machinectl.html"><span class="citerefentry"><span class="refentrytitle">machinectl</span>(1)</span></a>,
<a href="wireshark.html"><span class="citerefentry"><span class="refentrytitle">wireshark</span>(1)</span></a>
</p></div></div></body></html>
Reference in New Issue View Git Blame Copy Permalink