source: general/sysutils/dbus.xml@ cf4e047

elogind
Last change on this file since cf4e047 was cf4e047, checked in by DJ Lucas <dj@…>, 3 years ago

Added elogind support to Pulseaudio.
Text cleanups to elogind additions.

git-svn-id: svn://svn.linuxfromscratch.org/BLFS/branches/BOOK-elogind@20856 af4574ff-66df-0310-9fd7-8a98e5e911e0

  • Property mode set to 100644
File size: 24.2 KB
Line 
1<?xml version="1.0" encoding="ISO-8859-1"?>
2<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
3 "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
4 <!ENTITY % general-entities SYSTEM "../../general.ent">
5 %general-entities;
6
7 <!ENTITY dbus-download-http "https://dbus.freedesktop.org/releases/dbus/dbus-&dbus-version;.tar.gz">
8 <!ENTITY dbus-download-ftp " ">
9 <!ENTITY dbus-md5sum "ea11069521beeee4e47f0086596a43c8">
10 <!ENTITY dbus-size "2.0 MB">
11 <!ENTITY dbus-buildsize "21 MB (add 8 MB for the tests)">
12 <!ENTITY dbus-time "0.3 SBU (add 0.8 SBU for the tests)">
13]>
14
15<sect1 id="dbus" xreflabel="dbus-&dbus-version;">
16 <?dbhtml filename="dbus.html"?>
17
18 <sect1info>
19 <othername>$LastChangedBy$</othername>
20 <date>$Date$</date>
21 </sect1info>
22
23 <title>dbus-&dbus-version;</title>
24
25 <indexterm zone="dbus">
26 <primary sortas="a-D-Bus">D-Bus</primary>
27 </indexterm>
28
29 <sect2 role="package">
30 <title>Introduction to D-Bus</title>
31
32 <para revision="sysv">
33 <application>D-Bus</application> is a message bus system, a simple way
34 for applications to talk to one another.
35 <application>D-Bus</application> supplies both a system daemon (for
36 events such as <quote>new hardware device added</quote> or <quote>printer
37 queue changed</quote>) and a per-user-login-session daemon (for general
38 IPC needs among user applications). Also, the message bus is built on top
39 of a general one-to-one message passing framework, which can be used by
40 any two applications to communicate directly (without going through the
41 message bus daemon).
42 </para>
43
44 <para revision="systemd">
45 Even though <application>D-Bus</application> was built in LFS, there are
46 some features provided by the package that other BLFS packages need, but
47 their dependencies didn't fit into LFS.
48 </para>
49
50 &lfs83_checked;
51
52 <bridgehead renderas="sect3">Package Information</bridgehead>
53 <itemizedlist spacing="compact">
54 <listitem>
55 <para>
56 Download (HTTP): <ulink url="&dbus-download-http;"/>
57 </para>
58 </listitem>
59 <listitem>
60 <para>
61 Download (FTP): <ulink url="&dbus-download-ftp;"/>
62 </para>
63 </listitem>
64 <listitem>
65 <para>
66 Download MD5 sum: &dbus-md5sum;
67 </para>
68 </listitem>
69 <listitem>
70 <para>
71 Download size: &dbus-size;
72 </para>
73 </listitem>
74 <listitem>
75 <para>
76 Estimated disk space required: &dbus-buildsize;
77 </para>
78 </listitem>
79 <listitem>
80 <para>
81 Estimated build time: &dbus-time;
82 </para>
83 </listitem>
84 </itemizedlist>
85
86 <bridgehead renderas="sect3" revision="sysv">Additional Downloads</bridgehead>
87 <itemizedlist spacing="compact" revision="sysv">
88 <listitem>
89 <para>
90 Recommended patch:
91 <ulink url="&patch-root;/dbus-&dbus-version;-elogind-2.patch"/>
92 </para>
93 </listitem>
94 </itemizedlist>
95
96 <bridgehead renderas="sect3">D-Bus Dependencies</bridgehead>
97
98 <bridgehead renderas="sect4" revision="systemd">Required</bridgehead>
99 <para role="required" revision="systemd">
100 <xref linkend="systemd"/>
101 </para>
102
103
104 <bridgehead renderas="sect4">Recommended</bridgehead>
105 <para role="recommended">
106 <xref linkend="xorg7-lib"/> (for <command>dbus-launch</command> program)
107 <phrase revision="sysv"><xref linkend="elogind"/> (first build
108 without, and then again after elogind is installed) and
109 <xref linkend="autoconf-archive"/></phrase>
110 </para>
111
112 <bridgehead renderas="sect4">Optional</bridgehead>
113 <para role="optional">
114 For the tests:
115 <xref linkend="dbus-glib"/>,
116 <xref linkend="dbus-python"/>,
117 <xref linkend="pygobject3"/>,
118 and <xref linkend="valgrind"/>;
119
120 for documentation:
121 <xref linkend="doxygen"/>,
122 <xref linkend="xmlto"/>,
123 <ulink url="https://pypi.python.org/pypi/mallard-ducktype">Ducktype</ulink>,
124 and
125 <ulink url="http://ftp.gnome.org/pub/gnome/sources/yelp-tools/">Yelp Tools</ulink>
126 </para>
127
128 <para condition="html" role="usernotes">User Notes:
129 <ulink url="&blfs-wiki;/dbus"/>
130 </para>
131 </sect2>
132
133 <sect2 role="installation">
134 <title>Installation of D-Bus</title>
135
136 <para revision="sysv">
137 If they do not already exist,
138 as the <systemitem class="username">root</systemitem> user, create a
139 system user and group to handle the system message bus activity:
140 </para>
141
142<screen role="root" revision="sysv"><userinput>groupadd -g 18 messagebus &amp;&amp;
143useradd -c "D-Bus Message Daemon User" -d /var/run/dbus \
144 -u 18 -g messagebus -s /bin/false messagebus</userinput></screen>
145
146 <para revision="sysv">
147 Apply a patch to fix detection of <application>elogind</application>:
148 </para>
149
150<screen revision="sysv"><userinput>patch -Np1 -i ../dbus-&dbus-version;-elogind-2.patch &amp;&amp;
151autoreconf -fi</userinput></screen>
152
153 <para>
154 Install <application>D-Bus</application> by running the following
155 commands (you may wish to review the output from <command>./configure
156 --help</command> first and add any desired parameters to the
157 <command>configure</command> command shown below):
158 </para>
159
160<screen><userinput>./configure --prefix=/usr \
161 --sysconfdir=/etc \
162 --localstatedir=/var \
163 --enable-user-session \
164 --disable-doxygen-docs \
165 --disable-xml-docs \
166 --disable-static \
167 --docdir=/usr/share/doc/dbus-&dbus-version; \
168 --with-console-auth-dir=/run/console \
169 --with-system-pid-file=/run/dbus/pid \
170 --with-system-socket=/run/dbus/system_bus_socket &amp;&amp;
171make</userinput></screen>
172
173 <para>
174 See below for test instructions.
175 </para>
176
177 <warning revision="systemd">
178 <para>
179 Installing the package will override all files installed by
180 <application>D-Bus</application> in LFS. It is critical that
181 nothing uses <application>D-Bus</application> libraries or
182 programs during the installation. The best way to ensure that these
183 libraries are not being used is to run the installation in rescue mode.
184 To switch to rescue mode, run the following command as the
185 <systemitem class="username">root</systemitem> user (from a TTY):
186 </para>
187
188<screen role="root"><userinput>systemctl start rescue.target</userinput></screen>
189
190 </warning>
191
192 <para>
193 Now, as the <systemitem class="username">root</systemitem> user:
194 </para>
195
196<screen role="root"><userinput>make install</userinput></screen>
197
198 <para>
199 The shared library needs to be moved to
200 <filename class="directory">/lib</filename>, and as a result the
201 <filename class="extension">.so</filename> file in
202 <filename class="directory">/usr/lib</filename> will need to be
203 recreated. Run the following command as the
204 <systemitem class="username">root</systemitem> user:
205 </para>
206
207<screen role="root"><userinput>mv -v /usr/lib/libdbus-1.so.* /lib &amp;&amp;
208ln -sfv ../../lib/$(readlink /usr/lib/libdbus-1.so) /usr/lib/libdbus-1.so</userinput></screen>
209
210 <para>
211 If you are using a DESTDIR install,
212 <command>dbus-daemon-launch-helper</command> needs to be fixed
213 afterwards. Issue, as <systemitem class="username">root</systemitem>
214 user:
215 </para>
216
217<screen role="root"><userinput>chown -v root:messagebus /usr/libexec/dbus-daemon-launch-helper &amp;&amp;
218chmod -v 4750 /usr/libexec/dbus-daemon-launch-helper</userinput></screen>
219
220 <para revision="sysv">
221 If you are still building your system in chroot or you did not start the
222 daemon yet, but you want to compile some packages that require
223 <application>D-Bus</application>, generate
224 <application>D-Bus</application> UUID to avoid warnings when compiling
225 some packages with the following command as the
226 <systemitem class="username">root</systemitem> user:
227 </para>
228
229<screen role="root" revision="sysv"><userinput>dbus-uuidgen --ensure</userinput></screen>
230
231 <para revision="systemd">
232 If not in chroot, at this point, you should reload the systemd daemon,
233 and reenter multi-user mode with the following commands (as the
234 <systemitem class="username">root</systemitem> user):
235 </para>
236
237<screen role="root" revision="systemd"><userinput>systemctl daemon-reload
238systemctl start multi-user.target</userinput></screen>
239
240 <para>
241 The dbus tests cannot be run until after <xref linkend="dbus-glib"/> has
242 been installed. They must be run as an unprivileged user from a local
243 session with bus address. To run the standard tests issue
244 <command>make check</command>.
245 </para>
246
247 <para>
248 If you want to run the unit regression tests, configure requires
249 additional parameters which expose additional functionality in the
250 binaries that are not intended to be used in a production build of
251 <application>D-Bus</application>. If you would like to run the tests,
252 issue the following commands (for the tests, you don't need to build the
253 docs):
254 </para>
255
256<screen><userinput>make distclean &amp;&amp;
257./configure --enable-tests \
258 --enable-asserts \
259 --disable-doxygen-docs \
260 --disable-xml-docs &amp;&amp;
261make &amp;&amp;
262make check</userinput></screen>
263
264 <para>
265 The test <command>test-bus.sh</command> is known to fail. There has also
266 been reports that the tests may fail if running inside a Midnight
267 Commander shell. You may get out-of-memory error messages when running
268 the tests. These are normal and can be safely ignored.
269 </para>
270
271 </sect2>
272
273 <sect2 role="commands">
274 <title>Command Explanations</title>
275
276 <para>
277 <parameter>--disable-doxygen-docs</parameter>: This switch disables
278 doxygen documentation build and install, if you have
279 <application>doxygen</application> installed. If
280 <application>doxygen</application> is installed, and you wish to build
281 them, remove this parameter.
282 </para>
283
284 <para>
285 <parameter>--disable-xml-docs</parameter>: This switch disables html
286 documentation build and install, if you have
287 <application>xmlto</application> installed. If
288 <application>xmlto</application> is installed, and you wish to build
289 them, remove this parameter.
290 </para>
291
292 <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
293 href="../../xincludes/static-libraries.xml"/>
294
295 <para>
296 <parameter>--enable-user-session</parameter>: This parameter enables
297 per-user DBus sessions with
298 <phrase revision="sysv"><application>elogind</application>.</phrase>
299 <phrase revision="systemd"><application>systemd</application>.</phrase>
300 </para>
301
302 <para>
303 <parameter>--with-console-auth-dir=/run/console/</parameter>: This
304 parameter specifies the location of the
305 <application>ConsoleKit</application> auth dir.
306 </para>
307
308 <para>
309 <parameter>--with-system-pid-file=/run/dbus/pid</parameter>: This
310 parameter specifies the location of the PID file.
311 </para>
312
313 <para>
314 <parameter>--with-system-socket=/run/dbus/system_bus_socket</parameter>:
315 This parameter specifies the location of the system bus socket.
316 </para>
317
318 <para>
319 <parameter>--enable-tests</parameter>: Build extra parts of the code to
320 support all tests. Do not use on a production build.
321 </para>
322
323 <para>
324 <option>--enable-embedded-tests</option>: Build extra parts of the
325 code to support only unit tests. Do not use on a production build.
326 </para>
327
328 <para>
329 <parameter>--enable-asserts</parameter>: Enable debugging code to run
330 assertions for statements normally assumed to be true. This prevents a
331 warning that '<parameter>--enable-tests</parameter>' on its own is only
332 useful for profiling and might not give true results for all tests, but
333 adds its own NOTE that this should not be used in a production build.
334 </para>
335
336 </sect2>
337
338 <sect2 role="configuration">
339 <title>Configuring D-Bus</title>
340
341 <sect3 id="dbus-config">
342 <title>Config Files</title>
343
344 <para>
345 <filename>/etc/dbus-1/session.conf</filename>,
346 <filename>/etc/dbus-1/system.conf</filename> and
347 <filename>/etc/dbus-1/system.d/*</filename>
348 </para>
349
350 <indexterm zone="dbus dbus-config">
351 <primary sortas="e-etc-dbus-1-session.conf">/etc/dbus-1/session.conf</primary>
352 </indexterm>
353
354 <indexterm zone="dbus dbus-config">
355 <primary sortas="e-etc-dbus-1/system.conf">/etc/dbus-1/system.conf</primary>
356 </indexterm>
357
358 <indexterm zone="dbus dbus-config">
359 <primary sortas="e-etc-dbus-1-system.d-star">/etc/dbus-1/system.d/*</primary>
360 </indexterm>
361
362 </sect3>
363
364 <sect3 id="dbus-session-config" xreflabel="D-Bus custom services directory">
365 <title>Configuration Information</title>
366
367 <para>
368 The configuration files listed above should probably not be
369 modified. If changes are required, you should create
370 <filename>/etc/dbus-1/session-local.conf</filename> and/or
371 <filename>/etc/dbus-1/system-local.conf</filename> and make any
372 desired changes to these files.
373 </para>
374
375 <para>
376 If any packages install a
377 <application>D-Bus</application> <filename>.service</filename>
378 file outside of the standard <filename
379 class="directory">/usr/share/dbus-1/services</filename> directory,
380 that directory should be added to the local session configuration.
381 For instance, <filename
382 class="directory">/usr/local/share/dbus-1/services</filename> can
383 be added by performing the following commands as the
384 <systemitem class="username">root</systemitem> user:
385 </para>
386
387<screen role="root"><userinput>cat &gt; /etc/dbus-1/session-local.conf &lt;&lt; "EOF"
388<literal>&lt;!DOCTYPE busconfig PUBLIC
389 "-//freedesktop//DTD D-BUS Bus Configuration 1.0//EN"
390 "http://www.freedesktop.org/standards/dbus/1.0/busconfig.dtd"&gt;
391&lt;busconfig&gt;
392
393 &lt;!-- Search for .service files in /usr/local --&gt;
394 &lt;servicedir&gt;/usr/local/share/dbus-1/services&lt;/servicedir&gt;
395
396&lt;/busconfig&gt;</literal>
397EOF</userinput></screen>
398
399 </sect3>
400
401 <sect3 id="dbus-session">
402 <title>D-Bus Session Daemon</title>
403
404 <para revision="sysv">
405 To automatically start <command>dbus-daemon</command> when the
406 system is rebooted, install the
407 <filename>/etc/rc.d/init.d/dbus</filename> bootscript from the
408 <xref linkend="bootscripts"/> package.
409 </para>
410
411 <indexterm zone="dbus dbus-session" revision="sysv">
412 <primary sortas="f-dbus">dbus</primary>
413 </indexterm>
414
415<screen role="root" revision="sysv"><userinput>make install-dbus</userinput></screen>
416
417 <para revision="sysv">
418 Note that this boot script only starts the system-wide
419 <application>D-Bus</application> daemon. Each user requiring access to
420 <application>D-Bus</application> services will also need to run a
421 session daemon as well. There are many methods you can use to start a
422 session daemon using the <command>dbus-launch</command> command. Review
423 the <command>dbus-launch</command> man page for details about the
424 available parameters and options. Here are some suggestions and
425 examples:
426 </para>
427
428 <para revision="systemd">
429 There are many methods you can use to start a session daemon
430 using the <command>dbus-launch</command> command. Review the
431 <command>dbus-launch</command> man page for details about the
432 available parameters and options. Here are some suggestions and
433 examples:
434 </para>
435
436
437 <itemizedlist spacing="compact">
438 <listitem>
439 <para>
440 Add <command>dbus-launch</command> to the line in the
441 <filename>~/.xinitrc</filename> file that starts your graphical
442 desktop environment.
443 </para>
444 </listitem>
445 <listitem>
446 <para>
447 If you use <command>xdm</command> or some other display manager
448 that calls the <filename>~/.xsession</filename> file, you can add
449 <command>dbus-launch</command> to the line in your
450 <filename>~/.xsession</filename> file that starts your graphical
451 desktop environment. The syntax would be similar to the example in
452 the <filename>~/.xinitrc</filename> file.
453 </para>
454 </listitem>
455 <listitem>
456 <para>
457 The examples shown previously use
458 <command>dbus-launch</command> to specify a program to be run. This
459 has the benefit (when also using the
460 <parameter>--exit-with-session</parameter> parameter) of stopping the
461 session daemon when the specified program is stopped. You can also
462 start the session daemon in your system or personal startup scripts
463 by adding the following lines:
464 </para>
465
466<screen role="nodump"><userinput><literal># Start the D-Bus session daemon
467eval `dbus-launch`
468export DBUS_SESSION_BUS_ADDRESS</literal></userinput></screen>
469
470 <para>
471 This method will not stop the session daemon when you exit
472 your shell, therefore you should add the following line to your
473 <filename>~/.bash_logout</filename> file:
474 </para>
475
476<screen role="nodump"><userinput><literal># Kill the D-Bus session daemon
477kill $DBUS_SESSION_BUS_PID</literal></userinput></screen>
478 </listitem>
479
480 <listitem>
481 <para>
482 A hint has been written that provides ways to start scripts
483 using the KDM session manager of KDE. The concepts in this hint could
484 possibly be used with other session managers as well. The hint is
485 located at <ulink
486 url="&hints-root;/downloads/files/execute-session-scripts-using-kdm.txt"/>.
487 </para>
488 </listitem>
489
490 </itemizedlist>
491
492 </sect3>
493
494 </sect2>
495
496 <sect2 role="content" revision="sysv">
497 <title>Contents</title>
498
499 <segmentedlist>
500 <segtitle>Installed Programs</segtitle>
501 <segtitle>Installed Library</segtitle>
502 <segtitle>Installed Directories</segtitle>
503
504 <seglistitem>
505 <seg>
506 dbus-cleanup-sockets, dbus-daemon, dbus-launch, dbus-monitor,
507 dbus-run-session, dbus-send, dbus-test-tool,
508 dbus-update-activation-environment, and dbus-uuidgen
509 </seg>
510 <seg>
511 libdbus-1.so
512 </seg>
513 <seg>
514 /etc/dbus-1,
515 /usr/{include,lib}/dbus-1.0,
516 /usr/share/dbus-1,
517 /usr/share/doc/dbus-&dbus-version;, and
518 /var/{lib,run}/dbus
519 </seg>
520 </seglistitem>
521 </segmentedlist>
522
523 <variablelist>
524 <bridgehead renderas="sect3">Short Descriptions</bridgehead>
525 <?dbfo list-presentation="list"?>
526 <?dbhtml list-presentation="table"?>
527
528 <varlistentry id="dbus-cleanup-sockets">
529 <term><command>dbus-cleanup-sockets</command></term>
530 <listitem>
531 <para>
532 is used to clean up leftover sockets in a directory.
533 </para>
534 <indexterm zone="dbus dbus-cleanup-sockets">
535 <primary sortas="b-dbus-cleanup-sockets">dbus-cleanup-sockets</primary>
536 </indexterm>
537 </listitem>
538 </varlistentry>
539
540 <varlistentry id="dbus-daemon">
541 <term><command>dbus-daemon</command></term>
542 <listitem>
543 <para>
544 is the <application>D-Bus</application> message bus daemon.
545 </para>
546 <indexterm zone="dbus dbus-daemon">
547 <primary sortas="b-dbus-daemon">dbus-daemon</primary>
548 </indexterm>
549 </listitem>
550 </varlistentry>
551
552 <varlistentry id="dbus-launch">
553 <term><command>dbus-launch</command></term>
554 <listitem>
555 <para>
556 is used to start <command>dbus-daemon</command> from a shell
557 script. It would normally be called from a user's login
558 scripts.
559 </para>
560 <indexterm zone="dbus dbus-launch">
561 <primary sortas="b-dbus-launch">dbus-launch</primary>
562 </indexterm>
563 </listitem>
564 </varlistentry>
565
566 <varlistentry id="dbus-monitor">
567 <term><command>dbus-monitor</command></term>
568 <listitem>
569 <para>
570 is used to monitor messages going through a
571 <application>D-Bus</application> message bus.
572 </para>
573 <indexterm zone="dbus dbus-monitor">
574 <primary sortas="b-dbus-monitor">dbus-monitor</primary>
575 </indexterm>
576 </listitem>
577 </varlistentry>
578
579 <varlistentry id="dbus-run-session">
580 <term><command>dbus-run-session</command></term>
581 <listitem>
582 <para>
583 start a process as a new <application>D-Bus</application> session.
584 </para>
585 <indexterm zone="dbus dbus-run-session">
586 <primary sortas="b-dbus-run-session">dbus-run-session</primary>
587 </indexterm>
588 </listitem>
589 </varlistentry>
590
591 <varlistentry id="dbus-send">
592 <term><command>dbus-send</command></term>
593 <listitem>
594 <para>
595 is used to send a message to a <application>D-Bus</application>
596 message bus.
597 </para>
598 <indexterm zone="dbus dbus-send">
599 <primary sortas="b-dbus-send">dbus-send</primary>
600 </indexterm>
601 </listitem>
602 </varlistentry>
603
604 <varlistentry id="dbus-test-tool">
605 <term><command>dbus-test-tool</command></term>
606 <listitem>
607 <para>
608 is a <application>D-Bus</application> traffic generator and test
609 tool; it is a multi-purpose tool for debugging and profiling
610 <application>D-Bus</application>.
611 </para>
612 <indexterm zone="dbus dbus-test-tool">
613 <primary sortas="b-dbus-test-tool">dbus-test-tool</primary>
614 </indexterm>
615 </listitem>
616 </varlistentry>
617
618 <varlistentry id="dbus-update-activation-environment">
619 <term><command>dbus-update-activation-environment</command></term>
620 <listitem>
621 <para>
622 is used to update the environment used for
623 <application>D-Bus</application> session services;
624 it updates the list of environment variables used by
625 <command>dbus-daemon --session</command> when it activates session
626 services without using systemd.
627 </para>
628 <indexterm zone="dbus dbus-update-activation-environment">
629 <primary sortas="b-dbus-update-activation-environment">
630 dbus-update-activation-environment</primary>
631 </indexterm>
632 </listitem>
633 </varlistentry>
634
635 <varlistentry id="dbus-uuidgen">
636 <term><command>dbus-uuidgen</command></term>
637 <listitem>
638 <para>
639 is used to generate a universally unique ID.
640 </para>
641 <indexterm zone="dbus dbus-uuidgen">
642 <primary sortas="b-dbus-uuidgen">dbus-uuidgen</primary>
643 </indexterm>
644 </listitem>
645 </varlistentry>
646
647 <varlistentry id="libdbus-1">
648 <term><filename class="libraryfile">libdbus-1.so</filename></term>
649 <listitem>
650 <para>
651 contains the API functions used by the
652 <application>D-Bus</application> message daemon.
653 <application>D-Bus</application> is first a library that provides
654 one-to-one communication between any two applications;
655 <command>dbus-daemon</command> is an application that uses this
656 library to implement a message bus daemon.
657 </para>
658 <indexterm zone="dbus libdbus-1">
659 <primary sortas="c-libdbus-1">libdbus-1.so</primary>
660 </indexterm>
661 </listitem>
662 </varlistentry>
663
664 </variablelist>
665
666 </sect2>
667
668 <sect2 role="content" revision="systemd">
669 <title>Contents</title>
670
671 <para>
672 A list of the installed files, along with their short
673 descriptions can be found at
674 <ulink url="&lfs-rootd;/chapter06/dbus.html#contents-dbus"/>.
675 </para>
676
677 </sect2>
678
679
680</sect1>
681
Note: See TracBrowser for help on using the repository browser.