man/org.freedesktop.LogControl1.xml

   1 <?xml version='1.0'?>
   2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
   3   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" >
   4 <!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
   5
   6 <refentry id="org.freedesktop.LogControl1"
   7     xmlns:xi="http://www.w3.org/2001/XInclude">
   8   <refentryinfo>
   9     <title>org.freedesktop.LogControl1</title>
  10     <productname>systemd</productname>
  11   </refentryinfo>
  12
  13   <refmeta>
  14     <refentrytitle>org.freedesktop.LogControl1</refentrytitle>
  15     <manvolnum>5</manvolnum>
  16   </refmeta>
  17
  18   <refnamediv>
  19     <refname>org.freedesktop.LogControl1</refname>
  20     <refpurpose>D-Bus interface to query and set logging configuration</refpurpose>
  21   </refnamediv>
  22
  23   <refsect1>
  24     <title>Introduction</title>
  25
  26     <para><interfacename>org.freedesktop.LogControl1</interfacename> is a generic interface that is intended
  27     to be used by any daemon which allows the log level and target to be set over D-Bus. It is implemented by
  28     various daemons that are part of the
  29     <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry> suite.</para>
  30
  31     <para>It is assumed that those settings are global for the whole program, so a fixed object path is
  32     used. The interface should always be available under the path
  33     <filename>/org/freedesktop/LogControl1</filename>.</para>
  34   </refsect1>
  35
  36   <refsect1>
  37     <title>Description</title>
  38
  39     <para>The following interface is exposed:</para>
  40
  41     <programlisting executable="systemd" node="/org/freedesktop/LogControl1" interface="org.freedesktop.LogControl1">
  42 node /org/freedesktop/LogControl1 {
  43   interface org.freedesktop.LogControl1 {
  44     properties:
  45       @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
  46       @org.freedesktop.systemd1.Privileged("true")
  47       readwrite s LogLevel = '...';
  48       @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
  49       @org.freedesktop.systemd1.Privileged("true")
  50       readwrite s LogTarget = '...';
  51       @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
  52       readonly s SyslogIdentifier = '...';
  53   };
  54   interface org.freedesktop.DBus.Peer { ... };
  55   interface org.freedesktop.DBus.Introspectable { ... };
  56   interface org.freedesktop.DBus.Properties { ... };
  57 };
  58     </programlisting>
  59
  60     <!--Autogenerated cross-references for systemd.directives, do not edit-->
  61
  62     <variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.LogControl1"/>
  63
  64     <variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.LogControl1"/>
  65
  66     <variablelist class="dbus-property" generated="True" extra-ref="LogLevel"/>
  67
  68     <variablelist class="dbus-property" generated="True" extra-ref="LogTarget"/>
  69
  70     <variablelist class="dbus-property" generated="True" extra-ref="SyslogIdentifier"/>
  71
  72     <!--End of Autogenerated section-->
  73
  74     <refsect2>
  75       <title>Properties</title>
  76
  77       <para><varname>LogLevel</varname> describes the
  78       <citerefentry project="man-pages"><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry>-style
  79       log-level, and should be one of <literal>emerg</literal>, <literal>alert</literal>,
  80       <literal>crit</literal>, <literal>err</literal>, <literal>warning</literal>, <literal>notice</literal>,
  81       <literal>info</literal>, <literal>debug</literal>, in order of increasing verbosity.</para>
  82
  83       <para><varname>LogTarget</varname> describes the log target (mechanism). It should be one of
  84       <literal>console</literal> (log to the console or standard output),
  85       <literal>kmsg</literal> (log to the kernel ring buffer),
  86       <literal>journal</literal> (log to the journal natively, see
  87       <citerefentry><refentrytitle>systemd-journald.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>),
  88       <literal>syslog</literal> (log using the
  89       <citerefentry project="man-pages"><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry> call).
  90       </para>
  91
  92       <para>Those two properties are writable, so they may be set by sufficiently privileged users.</para>
  93
  94       <para><varname>SyslogIdentifier</varname> is a read-only property that shows the "syslog identifier".
  95       It is a short string that identifies the program that is the source of log messages that is passed to
  96       the <citerefentry project="man-pages"><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry> call.
  97       </para>
  98     </refsect2>
  99   </refsect1>
 100
 101   <refsect1>
 102     <title>Tools</title>
 103
 104     <para><command>journalctl</command> option <option>-p</option>/<option>--priority=</option> may be used
 105     to filter log messages by log level, option <option>-t</option>/<option>--identifier=</option> may be
 106     used to by the syslog identifier, and filters like <literal>_TRANSPORT=syslog</literal>,
 107     <literal>_TRANSPORT=journal</literal>, and <literal>_TRANSPORT=kernel</literal> may be used to filter
 108     messages by the mechanism through which they reached <command>systemd-journald</command>.</para>
 109
 110     <para><command>systemctl log-level</command> and <command>systemctl log-target</command> verbs may be
 111     used to query and set the <varname>LogLevel</varname> and <varname>LogTarget</varname> properties of the
 112     service manager. <command>systemctl service-log-level</command> and <command>systemctl
 113     service-log-target</command> may similarly be used for individual services. (Services must have the
 114     <varname>BusName=</varname> property set and must implement the interface described here. See
 115     <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 116     for details about <varname>BusName=</varname>.)</para>
 117   </refsect1>
 118
 119   <refsect1>
 120     <title>Example</title>
 121
 122     <example>
 123       <title>Create a simple listener on the bus that implements LogControl1</title>
 124
 125       <programlisting><xi:include href="logcontrol-example.c" parse="text"/></programlisting>
 126
 127       <para>This creates a simple server on the bus. It implements the LogControl1 interface by providing
 128       the required properties and allowing to set the writable ones. It logs at the configured log level using
 129       <citerefentry><refentrytitle>sd_journal_print</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>
 130     </example>
 131   </refsect1>
 132
 133   <refsect1>
 134     <title>See Also</title>
 135     <para>
 136       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 137       <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 138       <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 139       <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 140       <citerefentry project="man-pages"><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 141     </para>
 142   </refsect1>
 143 </refentry>