man/busctl.xml

   1 <?xml version='1.0'?> <!--*-nxml-*-->
   2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
   3 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
   4
   5 <!--
   6 This file is part of systemd.
   7
   8 Copyright 2014 Zbigniew Jędrzejewski-Szmek
   9
  10 systemd is free software; you can redistribute it and/or modify it
  11 under the terms of the GNU Lesser General Public License as published by
  12 the Free Software Foundation; either version 2.1 of the License, or
  13 (at your option) any later version.
  14
  15 systemd is distributed in the hope that it will be useful, but
  16 WITHOUT ANY WARRANTY; without even the implied warranty of
  17 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  18 Lesser General Public License for more details.
  19
  20 You should have received a copy of the GNU Lesser General Public License
  21 along with systemd; If not, see <http://www.gnu.org/licenses/>.
  22 -->
  23
  24 <refentry id="busctl">
  25
  26   <refentryinfo>
  27     <title>busctl</title>
  28     <productname>systemd</productname>
  29
  30     <authorgroup>
  31       <author>
  32         <contrib>A monkey with a typewriter</contrib>
  33         <firstname>Zbigniew</firstname>
  34         <surname>Jędrzejewski-Szmek</surname>
  35         <email>zbyszek@in.waw.pl</email>
  36       </author>
  37     </authorgroup>
  38   </refentryinfo>
  39
  40   <refmeta>
  41     <refentrytitle>busctl</refentrytitle>
  42     <manvolnum>1</manvolnum>
  43   </refmeta>
  44
  45   <refnamediv>
  46     <refname>busctl</refname>
  47     <refpurpose>Introspect the bus</refpurpose>
  48   </refnamediv>
  49
  50   <refsynopsisdiv>
  51     <cmdsynopsis>
  52       <command>busctl</command>
  53       <arg choice="opt" rep="repeat">OPTIONS</arg>
  54       <arg choice="opt">COMMAND</arg>
  55       <arg choice="opt" rep="repeat"><replaceable>NAME</replaceable></arg>
  56     </cmdsynopsis>
  57   </refsynopsisdiv>
  58
  59   <refsect1>
  60     <title>Description</title>
  61
  62     <para><command>busctl</command> may be used to
  63     introspect and monitor the D-Bus bus.</para>
  64   </refsect1>
  65
  66   <refsect1>
  67     <title>Options</title>
  68
  69     <para>The following options are understood:</para>
  70
  71     <variablelist>
  72       <varlistentry>
  73         <term><option>-h</option></term>
  74         <term><option>--help</option></term>
  75
  76         <listitem><para>Print a short help text and exit.
  77         </para></listitem>
  78       </varlistentry>
  79
  80       <varlistentry>
  81         <term><option>--version</option></term>
  82
  83         <listitem>
  84           <para>Print a short version string and exit.</para>
  85         </listitem>
  86       </varlistentry>
  87
  88       <varlistentry>
  89         <term><option>--no-pager</option></term>
  90
  91         <listitem>
  92           <para>Do not pipe output into a pager.</para>
  93         </listitem>
  94       </varlistentry>
  95
  96       <varlistentry>
  97         <term><option>--system</option></term>
  98
  99         <listitem>
 100           <para>Talk to the systemd system manager (the
 101           default).</para>
 102         </listitem>
 103       </varlistentry>
 104
 105       <varlistentry>
 106         <term><option>--user</option></term>
 107
 108         <listitem>
 109           <para>Talk to the systemd manager of the calling
 110           user.</para>
 111         </listitem>
 112       </varlistentry>
 113
 114       <varlistentry>
 115         <term><option>-H</option></term>
 116         <term><option>--host</option></term>
 117
 118         <listitem>
 119           <para>Execute the operation remotely. Specify a hostname, or
 120           username and hostname separated by <literal>@</literal>, to
 121           connect to. This will use SSH to talk to the remote systemd
 122           instance.</para>
 123         </listitem>
 124       </varlistentry>
 125
 126       <varlistentry>
 127           <term><option>-M</option></term>
 128           <term><option>--machine=</option></term>
 129
 130           <listitem><para>Execute the operation on a local container.
 131           Specify a container name to connect to.</para></listitem>
 132       </varlistentry>
 133
 134       <varlistentry>
 135           <term><option>--address=<replaceable>ADDRESS</replaceable></option></term>
 136
 137           <listitem><para>Connect to the bus specified by
 138           <replaceable>ADDRESS</replaceable> instead of using suitable
 139           defaults for either the system or user bus (see
 140           <option>--system</option> and <option>--user</option>
 141           options).</para></listitem>
 142       </varlistentry>
 143
 144       <varlistentry>
 145           <term><option>--show-machine</option></term>
 146
 147           <listitem><para>When showing the list of endpoints, show a
 148           column containing the names of containers they belong to.
 149           See
 150           <citerefentry><refentrytitle>systemd-machined.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
 151           </para></listitem>
 152       </varlistentry>
 153
 154       <varlistentry>
 155           <term><option>--unique</option></term>
 156
 157           <listitem><para>When showing the list of endpoints, show
 158           only "unique" names (of the form
 159           <literal>:<replaceable>number</replaceable>.<replaceable>number</replaceable></literal>).
 160           </para></listitem>
 161       </varlistentry>
 162
 163       <varlistentry>
 164           <term><option>--acquired</option></term>
 165
 166           <listitem><para>The opposite of <option>--unique</option> —
 167           only "well-known" names will be shown.</para></listitem>
 168       </varlistentry>
 169
 170       <varlistentry>
 171           <term><option>--activatable</option></term>
 172
 173           <listitem><para>When showing the list of endpoints, show
 174           only endpoints which have actually not been activated yet,
 175           but may be started automatically if accessed.</para>
 176           </listitem>
 177       </varlistentry>
 178
 179       <varlistentry>
 180           <term><option>--match=<replaceable>MATCH</replaceable></option></term>
 181
 182           <listitem><para>When showing messages being exchanged, show only the
 183           subset matching <replaceable>MATCH</replaceable>.</para></listitem>
 184           <!-- TODO: link to sd_bus_add_match when it is written? -->
 185       </varlistentry>
 186     </variablelist>
 187   </refsect1>
 188
 189   <refsect1>
 190     <title>Commands</title>
 191
 192     <para>The following commands are understood:</para>
 193
 194     <variablelist>
 195       <varlistentry>
 196         <term><command>list</command></term>
 197
 198         <listitem><para>Show endpoints attached to the bus. This is
 199         the default if no command is specified.</para></listitem>
 200       </varlistentry>
 201
 202       <varlistentry>
 203         <term><command>monitor</command>  <arg choice="opt" rep="repeat"><replaceable>NAME</replaceable></arg></term>
 204
 205         <listitem><para>Dump messages being exchanged. If
 206         <replaceable>NAME</replaceable> is specified, show messages
 207         to or from this endpoint. Otherwsise, show all messages on the
 208         bus.</para></listitem>
 209       </varlistentry>
 210
 211       <varlistentry>
 212         <term><command>status</command>  <arg choice="plain"><replaceable>NAME</replaceable></arg></term>
 213
 214         <listitem><para>Show process information and credentials of a
 215         bus endpoint.</para></listitem>
 216       </varlistentry>
 217
 218       <varlistentry>
 219         <term><command>help</command></term>
 220
 221         <listitem><para>Show command syntax help.</para></listitem>
 222       </varlistentry>
 223     </variablelist>
 224   </refsect1>
 225
 226   <refsect1>
 227     <title>See Also</title>
 228
 229     <para>
 230       <citerefentry><refentrytitle>dbus-daemon</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 231       <ulink url="http://freedesktop.org/wiki/Software/dbus">D-Bus</ulink>,
 232       <ulink url="https://code.google.com/p/d-bus/">kdbus</ulink>,
 233       <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 234       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 235       <citerefentry><refentrytitle>systemd-bus-proxyd</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 236       <citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 237     </para>
 238   </refsect1>
 239 </refentry>