summaryrefslogtreecommitdiffstats
path: root/man/org.freedesktop.LogControl1.xml
blob: 5738a3dda678b50ea94cb3ddaf4f5589712c007e (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
<?xml version='1.0'?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
  "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" >
<!-- SPDX-License-Identifier: LGPL-2.1-or-later -->

<refentry id="org.freedesktop.LogControl1"
    xmlns:xi="http://www.w3.org/2001/XInclude">
  <refentryinfo>
    <title>org.freedesktop.LogControl1</title>
    <productname>systemd</productname>
  </refentryinfo>

  <refmeta>
    <refentrytitle>org.freedesktop.LogControl1</refentrytitle>
    <manvolnum>5</manvolnum>
  </refmeta>

  <refnamediv>
    <refname>org.freedesktop.LogControl1</refname>
    <refpurpose>D-Bus interface to query and set logging configuration</refpurpose>
  </refnamediv>

  <refsect1>
    <title>Introduction</title>

    <para><interfacename>org.freedesktop.LogControl1</interfacename> is a generic interface that is intended
    to be used by any daemon which allows the log level and target to be set over D-Bus. It is implemented by
    various daemons that are part of the
    <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry> suite.</para>

    <para>It is assumed that those settings are global for the whole program, so a fixed object path is
    used. The interface should always be available under the path
    <filename>/org/freedesktop/LogControl1</filename>.</para>
  </refsect1>

  <refsect1>
    <title>Description</title>

    <para>The following interface is exposed:</para>

    <programlisting executable="systemd" node="/org/freedesktop/LogControl1" interface="org.freedesktop.LogControl1">
node /org/freedesktop/LogControl1 {
  interface org.freedesktop.LogControl1 {
    properties:
      @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
      @org.freedesktop.systemd1.Privileged("true")
      readwrite s LogLevel = '...';
      @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
      @org.freedesktop.systemd1.Privileged("true")
      readwrite s LogTarget = '...';
      @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
      readonly s SyslogIdentifier = '...';
  };
  interface org.freedesktop.DBus.Peer { ... };
  interface org.freedesktop.DBus.Introspectable { ... };
  interface org.freedesktop.DBus.Properties { ... };
};
    </programlisting>

    <!--Autogenerated cross-references for systemd.directives, do not edit-->

    <variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.LogControl1"/>

    <variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.LogControl1"/>

    <variablelist class="dbus-property" generated="True" extra-ref="LogLevel"/>

    <variablelist class="dbus-property" generated="True" extra-ref="LogTarget"/>

    <variablelist class="dbus-property" generated="True" extra-ref="SyslogIdentifier"/>

    <!--End of Autogenerated section-->

    <refsect2>
      <title>Properties</title>

      <para><varname>LogLevel</varname> describes the
      <citerefentry project="man-pages"><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry>-style
      log-level, and should be one of <literal>emerg</literal>, <literal>alert</literal>,
      <literal>crit</literal>, <literal>err</literal>, <literal>warning</literal>, <literal>notice</literal>,
      <literal>info</literal>, <literal>debug</literal>, in order of increasing verbosity.</para>

      <para><varname>LogTarget</varname> describes the log target (mechanism). It should be one of
      <literal>console</literal> (log to the console or standard output),
      <literal>kmsg</literal> (log to the kernel ring buffer),
      <literal>journal</literal> (log to the journal natively, see
      <citerefentry><refentrytitle>systemd-journald.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>),
      <literal>syslog</literal> (log using the
      <citerefentry project="man-pages"><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry> call).
      </para>

      <para>Those two properties are writable, so they may be set by sufficiently privileged users.</para>

      <para><varname>SyslogIdentifier</varname> is a read-only property that shows the "syslog identifier".
      It is a short string that identifies the program that is the source of log messages that is passed to
      the <citerefentry project="man-pages"><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry> call.
      </para>
    </refsect2>
  </refsect1>

  <refsect1>
    <title>Tools</title>

    <para><command>journalctl</command> option <option>-p</option>/<option>--priority=</option> may be used
    to filter log messages by log level, option <option>-t</option>/<option>--identifier=</option> may be
    used to by the syslog identifier, and filters like <literal>_TRANSPORT=syslog</literal>,
    <literal>_TRANSPORT=journal</literal>, and <literal>_TRANSPORT=kernel</literal> may be used to filter
    messages by the mechanism through which they reached <command>systemd-journald</command>.</para>

    <para><command>systemctl log-level</command> and <command>systemctl log-target</command> verbs may be
    used to query and set the <varname>LogLevel</varname> and <varname>LogTarget</varname> properties of the
    service manager. <command>systemctl service-log-level</command> and <command>systemctl
    service-log-target</command> may similarly be used for individual services. (Services must have the
    <varname>BusName=</varname> property set and must implement the interface described here. See
    <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>
    for details about <varname>BusName=</varname>.)</para>
  </refsect1>

  <refsect1>
    <title>Example</title>

    <example>
      <title>Create a simple listener on the bus that implements LogControl1</title>

      <programlisting><xi:include href="logcontrol-example.c" parse="text"/></programlisting>

      <para>This creates a simple server on the bus. It implements the LogControl1 interface by providing
      the required properties and allowing to set the writable ones. It logs at the configured log level using
      <citerefentry><refentrytitle>sd_journal_print</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>
    </example>
  </refsect1>

  <refsect1>
    <title>See Also</title>
    <para><simplelist type="inline">
      <member><citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
      <member><citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
      <member><citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
      <member><citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry></member>
      <member><citerefentry project="man-pages"><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry></member>
    </simplelist></para>
  </refsect1>
</refentry>