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>--no-legend</option></term>
  98
  99         <listitem>
 100           <para>Do not print the legend,
 101           i.e. the column headers and the
 102           footer.</para>
 103         </listitem>
 104       </varlistentry>
 105
 106       <varlistentry>
 107         <term><option>--system</option></term>
 108
 109         <listitem>
 110           <para>Talk to the systemd system manager (the
 111           default).</para>
 112         </listitem>
 113       </varlistentry>
 114
 115       <varlistentry>
 116         <term><option>--user</option></term>
 117
 118         <listitem>
 119           <para>Talk to the systemd manager of the calling
 120           user.</para>
 121         </listitem>
 122       </varlistentry>
 123
 124       <varlistentry>
 125         <term><option>-H</option></term>
 126         <term><option>--host</option></term>
 127
 128         <listitem>
 129           <para>Execute the operation remotely. Specify a hostname, or
 130           username and hostname separated by <literal>@</literal>, to
 131           connect to. This will use SSH to talk to the remote systemd
 132           instance.</para>
 133         </listitem>
 134       </varlistentry>
 135
 136       <varlistentry>
 137           <term><option>-M</option></term>
 138           <term><option>--machine=</option></term>
 139
 140           <listitem><para>Execute the operation on a local container.
 141           Specify a container name to connect to.</para></listitem>
 142       </varlistentry>
 143
 144       <varlistentry>
 145           <term><option>--address=<replaceable>ADDRESS</replaceable></option></term>
 146
 147           <listitem><para>Connect to the bus specified by
 148           <replaceable>ADDRESS</replaceable> instead of using suitable
 149           defaults for either the system or user bus (see
 150           <option>--system</option> and <option>--user</option>
 151           options).</para></listitem>
 152       </varlistentry>
 153
 154       <varlistentry>
 155           <term><option>--show-machine</option></term>
 156
 157           <listitem><para>When showing the list of endpoints, show a
 158           column containing the names of containers they belong to.
 159           See
 160           <citerefentry><refentrytitle>systemd-machined.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
 161           </para></listitem>
 162       </varlistentry>
 163
 164       <varlistentry>
 165           <term><option>--unique</option></term>
 166
 167           <listitem><para>When showing the list of endpoints, show
 168           only "unique" names (of the form
 169           <literal>:<replaceable>number</replaceable>.<replaceable>number</replaceable></literal>).
 170           </para></listitem>
 171       </varlistentry>
 172
 173       <varlistentry>
 174           <term><option>--acquired</option></term>
 175
 176           <listitem><para>The opposite of <option>--unique</option> —
 177           only "well-known" names will be shown.</para></listitem>
 178       </varlistentry>
 179
 180       <varlistentry>
 181           <term><option>--activatable</option></term>
 182
 183           <listitem><para>When showing the list of endpoints, show
 184           only endpoints which have actually not been activated yet,
 185           but may be started automatically if accessed.</para>
 186           </listitem>
 187       </varlistentry>
 188
 189       <varlistentry>
 190           <term><option>--match=<replaceable>MATCH</replaceable></option></term>
 191
 192           <listitem><para>When showing messages being exchanged, show only the
 193           subset matching <replaceable>MATCH</replaceable>.</para></listitem>
 194           <!-- TODO: link to sd_bus_add_match when it is written? -->
 195       </varlistentry>
 196     </variablelist>
 197   </refsect1>
 198
 199   <refsect1>
 200     <title>Commands</title>
 201
 202     <para>The following commands are understood:</para>
 203
 204     <variablelist>
 205       <varlistentry>
 206         <term><command>list</command></term>
 207
 208         <listitem><para>Show endpoints attached to the bus. This is
 209         the default if no command is specified.</para></listitem>
 210       </varlistentry>
 211
 212       <varlistentry>
 213         <term><command>monitor</command>  <arg choice="opt" rep="repeat"><replaceable>NAME</replaceable></arg></term>
 214
 215         <listitem><para>Dump messages being exchanged. If
 216         <replaceable>NAME</replaceable> is specified, show messages
 217         to or from this endpoint. Otherwise, show all messages on the
 218         bus.</para></listitem>
 219       </varlistentry>
 220
 221       <varlistentry>
 222         <term><command>status</command>  <arg choice="plain"><replaceable>NAME</replaceable></arg></term>
 223
 224         <listitem><para>Show process information and credentials of a
 225         bus endpoint.</para></listitem>
 226       </varlistentry>
 227
 228       <varlistentry>
 229         <term><command>help</command></term>
 230
 231         <listitem><para>Show command syntax help.</para></listitem>
 232       </varlistentry>
 233     </variablelist>
 234   </refsect1>
 235
 236   <refsect1>
 237     <title>See Also</title>
 238
 239     <para>
 240       <citerefentry><refentrytitle>dbus-daemon</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 241       <ulink url="http://freedesktop.org/wiki/Software/dbus">D-Bus</ulink>,
 242       <ulink url="https://code.google.com/p/d-bus/">kdbus</ulink>,
 243       <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 244       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 245       <citerefentry><refentrytitle>systemd-bus-proxyd</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 246       <citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 247     </para>
 248   </refsect1>
 249 </refentry>