Debian Codegraph @

upstream/debian-unstable/man5/org.freedesktop.LogControl1.5

raw
1 '\" t
2 .TH "ORG\&.FREEDESKTOP\&.LOGCONTROL1" "5" "" "systemd 261~rc3" "org.freedesktop.LogControl1"
3 .\" -----------------------------------------------------------------
4 .\" * Define some portability stuff
5 .\" -----------------------------------------------------------------
6 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
7 .\" http://bugs.debian.org/507673
8 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
9 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
10 .ie \n(.g .ds Aq \(aq
11 .el .ds Aq '
12 .\" -----------------------------------------------------------------
13 .\" * set default formatting
14 .\" -----------------------------------------------------------------
15 .\" disable hyphenation
16 .nh
17 .\" disable justification (adjust text to left margin only)
18 .ad l
19 .\" -----------------------------------------------------------------
20 .\" * MAIN CONTENT STARTS HERE *
21 .\" -----------------------------------------------------------------
22 .SH "NAME"
23 org.freedesktop.LogControl1 \- D\-Bus interface to query and set logging configuration
24 .SH "INTRODUCTION"
25 .PP
26 org\&.freedesktop\&.LogControl1
27 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
28 \fBsystemd\fR(1)
29 suite\&.
30 .PP
31 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
32 /org/freedesktop/LogControl1\&.
33 .SH "DESCRIPTION"
34 .PP
35 The following interface is exposed:
36 .sp
37 .if n \{\
38 .RS 4
39 .\}
40 .nf
41 node /org/freedesktop/LogControl1 {
42 interface org\&.freedesktop\&.LogControl1 {
43 properties:
44 @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false")
45 @org\&.freedesktop\&.systemd1\&.Privileged("true")
46 readwrite s LogLevel = \*(Aq\&.\&.\&.\*(Aq;
47 @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false")
48 @org\&.freedesktop\&.systemd1\&.Privileged("true")
49 readwrite s LogTarget = \*(Aq\&.\&.\&.\*(Aq;
50 @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false")
51 readonly s SyslogIdentifier = \*(Aq\&.\&.\&.\*(Aq;
52 };
53 interface org\&.freedesktop\&.DBus\&.Peer { \&.\&.\&. };
54 interface org\&.freedesktop\&.DBus\&.Introspectable { \&.\&.\&. };
55 interface org\&.freedesktop\&.DBus\&.Properties { \&.\&.\&. };
56 };
57 .fi
58 .if n \{\
59 .RE
60 .\}
61
62
63
64
65 .SS "Properties"
66 .PP
67 \fILogLevel\fR
68 describes the
69 \fBsyslog\fR(3)\-style log\-level, and should be one of
70 "emerg",
71 "alert",
72 "crit",
73 "err",
74 "warning",
75 "notice",
76 "info",
77 "debug", in order of increasing verbosity\&.
78 .PP
79 \fILogTarget\fR
80 describes the log target (mechanism)\&. It should be one of
81 "console"
82 (log to the console or standard output),
83 "kmsg"
84 (log to the kernel ring buffer),
85 "journal"
86 (log to the journal natively, see
87 \fBsystemd-journald.service\fR(8)),
88 "syslog"
89 (log using the
90 \fBsyslog\fR(3)
91 call)\&.
92 .if n \{\
93 .sp
94 .\}
95 .RS 4
96 .it 1 an-trap
97 .nr an-no-space-flag 1
98 .nr an-break-flag 1
99 .br
100 .ps +1
101 \fBWrite Access\fR
102 .ps -1
103 .br
104 .PP
105 The
106 \fILogLevel\fR
107 and
108 \fILogTarget\fR
109 properties are supposed to be writable\&. Care should be taken to ensure that only appropriately privileged clients can modify them\&.
110 .sp .5v
111 .RE
112 .PP
113 \fISyslogIdentifier\fR
114 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
115 \fBsyslog\fR(3)
116 call\&.
117 .SH "TOOLS"
118 .PP
119 \fBjournalctl\fR
120 option
121 \fB\-p\fR/\fB\-\-priority=\fR
122 may be used to filter log messages by log level, option
123 \fB\-t\fR/\fB\-\-identifier=\fR
124 may be used to by the syslog identifier, and filters like
125 "_TRANSPORT=syslog",
126 "_TRANSPORT=journal", and
127 "_TRANSPORT=kernel"
128 may be used to filter messages by the mechanism through which they reached
129 \fBsystemd\-journald\fR\&.
130 .PP
131 \fBsystemctl log\-level\fR
132 and
133 \fBsystemctl log\-target\fR
134 verbs may be used to query and set the
135 \fILogLevel\fR
136 and
137 \fILogTarget\fR
138 properties of the service manager\&.
139 \fBsystemctl service\-log\-level\fR
140 and
141 \fBsystemctl service\-log\-target\fR
142 may similarly be used for individual services\&. (Services must have the
143 \fIBusName=\fR
144 property set and must implement the interface described here\&. See
145 \fBsystemd.service\fR(5)
146 for details about
147 \fIBusName=\fR\&.)
148 .SH "EXAMPLE"
149 .PP
150 \fBExample\ \&1.\ \&Create a simple listener on the bus that implements LogControl1\fR
151 .sp
152 .if n \{\
153 .RS 4
154 .\}
155 .nf
156 /* SPDX\-License\-Identifier: MIT\-0 */
157
158 /* Implements the LogControl1 interface as per specification:
159 * https://www\&.freedesktop\&.org/software/systemd/man/org\&.freedesktop\&.LogControl1\&.html
160 *
161 * Compile with \*(Aqcc logcontrol\-example\&.c $(pkg\-config \-\-libs \-\-cflags libsystemd)\*(Aq
162 *
163 * To get and set properties via busctl:
164 *
165 * $ busctl \-\-user get\-property org\&.freedesktop\&.Example \e
166 * /org/freedesktop/LogControl1 \e
167 * org\&.freedesktop\&.LogControl1 \e
168 * SyslogIdentifier
169 * s "example"
170 * $ busctl \-\-user get\-property org\&.freedesktop\&.Example \e
171 * /org/freedesktop/LogControl1 \e
172 * org\&.freedesktop\&.LogControl1 \e
173 * LogTarget
174 * s "journal"
175 * $ busctl \-\-user get\-property org\&.freedesktop\&.Example \e
176 * /org/freedesktop/LogControl1 \e
177 * org\&.freedesktop\&.LogControl1 \e
178 * LogLevel
179 * s "info"
180 * $ busctl \-\-user set\-property org\&.freedesktop\&.Example \e
181 * /org/freedesktop/LogControl1 \e
182 * org\&.freedesktop\&.LogControl1 \e
183 * LogLevel \e
184 * "s" debug
185 * $ busctl \-\-user get\-property org\&.freedesktop\&.Example \e
186 * /org/freedesktop/LogControl1 \e
187 * org\&.freedesktop\&.LogControl1 \e
188 * LogLevel
189 * s "debug"
190 */
191
192 #include <errno\&.h>
193 #include <stdlib\&.h>
194 #include <stdio\&.h>
195 #include <syslog\&.h>
196 #include <systemd/sd\-bus\&.h>
197 #include <systemd/sd\-journal\&.h>
198
199 #define _cleanup_(f) __attribute__((cleanup(f)))
200
201 static int log_error(int log_level, int error, const char *str) {
202 sd_journal_print(log_level, "%s failed: %s", str, strerror(\-error));
203 return error;
204 }
205
206 typedef enum LogTarget {
207 LOG_TARGET_JOURNAL,
208 LOG_TARGET_KMSG,
209 LOG_TARGET_SYSLOG,
210 LOG_TARGET_CONSOLE,
211 _LOG_TARGET_MAX,
212 } LogTarget;
213
214 static const char* const log_target_table[_LOG_TARGET_MAX] = {
215 [LOG_TARGET_JOURNAL] = "journal",
216 [LOG_TARGET_KMSG] = "kmsg",
217 [LOG_TARGET_SYSLOG] = "syslog",
218 [LOG_TARGET_CONSOLE] = "console",
219 };
220
221 static const char* const log_level_table[LOG_DEBUG + 1] = {
222 [LOG_EMERG] = "emerg",
223 [LOG_ALERT] = "alert",
224 [LOG_CRIT] = "crit",
225 [LOG_ERR] = "err",
226 [LOG_WARNING] = "warning",
227 [LOG_NOTICE] = "notice",
228 [LOG_INFO] = "info",
229 [LOG_DEBUG] = "debug",
230 };
231
232 typedef struct object {
233 const char *syslog_identifier;
234 LogTarget log_target;
235 int log_level;
236 } object;
237
238 static int property_get(
239 sd_bus *bus,
240 const char *path,
241 const char *interface,
242 const char *property,
243 sd_bus_message *reply,
244 void *userdata,
245 sd_bus_error *error) {
246
247 object *o = userdata;
248
249 if (strcmp(property, "LogLevel") == 0)
250 return sd_bus_message_append(reply, "s", log_level_table[o\->log_level]);
251
252 if (strcmp(property, "LogTarget") == 0)
253 return sd_bus_message_append(reply, "s", log_target_table[o\->log_target]);
254
255 if (strcmp(property, "SyslogIdentifier") == 0)
256 return sd_bus_message_append(reply, "s", o\->syslog_identifier);
257
258 return sd_bus_error_setf(error,
259 SD_BUS_ERROR_UNKNOWN_PROPERTY,
260 "Unknown property \*(Aq%s\*(Aq",
261 property);
262 }
263
264 static int property_set(
265 sd_bus *bus,
266 const char *path,
267 const char *interface,
268 const char *property,
269 sd_bus_message *message,
270 void *userdata,
271 sd_bus_error *error) {
272
273 object *o = userdata;
274 const char *value;
275 int r;
276
277 r = sd_bus_message_read(message, "s", &value);
278 if (r < 0)
279 return r;
280
281 if (strcmp(property, "LogLevel") == 0) {
282 int i;
283 for (i = 0; i < LOG_DEBUG + 1; i++)
284 if (strcmp(value, log_level_table[i]) == 0) {
285 o\->log_level = i;
286 setlogmask(LOG_UPTO(i));
287 return 0;
288 }
289
290 return sd_bus_error_setf(error,
291 SD_BUS_ERROR_INVALID_ARGS,
292 "Invalid value for LogLevel: \*(Aq%s\*(Aq",
293 value);
294 }
295
296 if (strcmp(property, "LogTarget") == 0) {
297 LogTarget i;
298 for (i = 0; i < _LOG_TARGET_MAX; i++)
299 if (strcmp(value, log_target_table[i]) == 0) {
300 o\->log_target = i;
301 return 0;
302 }
303
304 return sd_bus_error_setf(error,
305 SD_BUS_ERROR_INVALID_ARGS,
306 "Invalid value for LogTarget: \*(Aq%s\*(Aq",
307 value);
308 }
309
310 return sd_bus_error_setf(error,
311 SD_BUS_ERROR_UNKNOWN_PROPERTY,
312 "Unknown property \*(Aq%s\*(Aq",
313 property);
314 }
315
316 /* https://www\&.freedesktop\&.org/software/systemd/man/sd_bus_add_object\&.html
317 */
318 static const sd_bus_vtable vtable[] = {
319 SD_BUS_VTABLE_START(0),
320 SD_BUS_WRITABLE_PROPERTY(
321 "LogLevel", "s",
322 property_get, property_set,
323 0,
324 0),
325 SD_BUS_WRITABLE_PROPERTY(
326 "LogTarget", "s",
327 property_get, property_set,
328 0,
329 0),
330 SD_BUS_PROPERTY(
331 "SyslogIdentifier", "s",
332 property_get,
333 0,
334 SD_BUS_VTABLE_PROPERTY_CONST),
335 SD_BUS_VTABLE_END
336 };
337
338 int main(int argc, char **argv) {
339 /* The bus should be relinquished before the program terminates\&. The cleanup
340 * attribute allows us to do it nicely and cleanly whenever we exit the
341 * block\&.
342 */
343 _cleanup_(sd_bus_flush_close_unrefp) sd_bus *bus = NULL;
344
345 object o = {
346 \&.log_level = LOG_INFO,
347 \&.log_target = LOG_TARGET_JOURNAL,
348 \&.syslog_identifier = "example",
349 };
350 int r;
351
352 /* https://man7\&.org/linux/man\-pages/man3/setlogmask\&.3\&.html
353 * Programs using syslog() instead of sd_journal can use this API to cut logs
354 * emission at the source\&.
355 */
356 setlogmask(LOG_UPTO(o\&.log_level));
357
358 /* Acquire a connection to the bus, letting the library work out the details\&.
359 * https://www\&.freedesktop\&.org/software/systemd/man/sd_bus_default\&.html
360 */
361 r = sd_bus_default(&bus);
362 if (r < 0)
363 return log_error(o\&.log_level, r, "sd_bus_default()");
364
365 /* Publish an interface on the bus, specifying our well\-known object access
366 * path and public interface name\&.
367 * https://www\&.freedesktop\&.org/software/systemd/man/sd_bus_add_object\&.html
368 * https://dbus\&.freedesktop\&.org/doc/dbus\-tutorial\&.html
369 */
370 r = sd_bus_add_object_vtable(bus, NULL,
371 "/org/freedesktop/LogControl1",
372 "org\&.freedesktop\&.LogControl1",
373 vtable,
374 &o);
375 if (r < 0)
376 return log_error(o\&.log_level, r, "sd_bus_add_object_vtable()");
377
378 /* By default, the service is assigned an ephemeral name\&. Also add a fixed
379 * one, so that clients know whom to call\&.
380 * https://www\&.freedesktop\&.org/software/systemd/man/sd_bus_request_name\&.html
381 */
382 r = sd_bus_request_name(bus, "org\&.freedesktop\&.Example", 0);
383 if (r < 0)
384 return log_error(o\&.log_level, r, "sd_bus_request_name()");
385
386 for (;;) {
387 /* https://www\&.freedesktop\&.org/software/systemd/man/sd_bus_wait\&.html
388 */
389 r = sd_bus_wait(bus, UINT64_MAX);
390 if (r < 0)
391 return log_error(o\&.log_level, r, "sd_bus_wait()");
392 /* https://www\&.freedesktop\&.org/software/systemd/man/sd_bus_process\&.html
393 */
394 r = sd_bus_process(bus, NULL);
395 if (r < 0)
396 return log_error(o\&.log_level, r, "sd_bus_process()");
397 }
398
399 /* https://www\&.freedesktop\&.org/software/systemd/man/sd_bus_release_name\&.html
400 */
401 r = sd_bus_release_name(bus, "org\&.freedesktop\&.Example");
402 if (r < 0)
403 return log_error(o\&.log_level, r, "sd_bus_release_name()");
404
405 return 0;
406 }
407 .fi
408 .if n \{\
409 .RE
410 .\}
411 .PP
412 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
413 \fBsd_journal_print\fR(3)\&.
414 .PP
415 Note that when porting this example to other D\-Bus libraries it might be necessary to add manual client privilege checks, as they typically do not default to the restrictive defaults of sd\-bus, where unprivileged access to properties is controlled via the
416 \fBSD_BUS_VTABLE_UNPRIVILEGED\fR
417 flag that is opt\-in rather than opt\-out\&.
418 .SH "SEE ALSO"
419 .PP
420 \fBsystemd\fR(1), \fBjournalctl\fR(1), \fBsystemctl\fR(1), \fBsystemd.service\fR(5), \fBsyslog\fR(3)