chiark / gitweb /
Prep v239: Unmask inotify_add_watch_fd()
[elogind.git] / README
1 Elogind User, Seat and Session Manager
2
3 Introduction
4 ------------
5
6 Elogind is the systemd project's "logind", extracted out to be a
7 standalone daemon.  It integrates with PAM to know the set of users
8 that are logged in to a system and whether they are logged in
9 graphically, on the console, or remotely.  Elogind exposes this
10 information via the standard org.freedesktop.login1 D-Bus interface,
11 as well as through the file system using systemd's standard
12 /run/systemd layout.  Elogind also provides "libelogind", which is a
13 subset of the facilities offered by "libsystemd".  There is a
14 "libelogind.pc" pkg-config file as well.
15
16 All of the credit for elogind should go to the systemd developers.
17 For more on systemd, see
18 http://www.freedesktop.org/wiki/Software/systemd.  All of the blame
19 should go to Andy Wingo, who extracted elogind from systemd.
20
21 Contributing
22 ------------
23
24 Elogind was branched from systemd version 219, and preserves the git
25 history of the systemd project.  The version of elogind is the
26 upstream systemd version, followed by the patchlevel of elogind.  For
27 example version 219.12 is the twelfth elogind release, which aims to
28 provide a subset of the interfaces of systemd 219.
29
30 To contribute to elogind, fork the current source code from github:
31
32   https://github.com/elogind/elogind
33
34 Send a pull request for the changes you like.
35
36 To chat about elogind:
37
38   #guix on irc.freenode.org
39
40 Finally, bug reports:
41
42   https://github.com/elogind/elogind/issues
43
44 Why bother?
45 -----------
46
47 Elogind has been developed for use in GuixSD, the OS distribution of
48 GNU Guix.  See http://gnu.org/s/guix for more on Guix.  GuixSD uses a
49 specific init manager (DMD), for reasons that are not relevant here,
50 but still aims to eventually be a full-featured distribution that can
51 run GNOME and other desktop environments.  However, to run GNOME these
52 days means that you need to have support for the login1 D-Bus
53 interface, which is currently only provided by systemd.  That is the
54 origin of this project: to take the excellent logind functionality
55 from systemd and provide it as a standalone package.
56
57 You're welcome to use elogind for whatever purpose you like --
58 as-is, or as a jumping-off point for other things -- but please don't
59 use it as part of some anti-systemd vendetta. We are appreciative of
60 the systemd developers logind effort and think that everyone deserves
61 to run it if they like. Not matter what kind of PID1 they use.
62
63 Differences relative to systemd
64 -------------------------------
65
66 The pkg-config file is called libelogind, not libsystemd or
67 libsystemd-logind.
68
69 The headers are in <elogind/...>, so like <elogind/sd-login.h> instead
70 of <systemd/sd-login.h>.
71
72 Libelogind just implements login-related functionality.  It also
73 provides the sd-bus API.
74
75 Unlike systemd, whose logind arranges to manage resources for user
76 sessions via RPC calls to systemd, in elogind there is no systemd so
77 there is no global cgroup-based resource management.  This has a few
78 implications:
79
80   * Elogind does not create "slices" for users.  Elogind will not
81     record that users are associated with slices.
82
83   * The /run/systemd/slices directory will always be empty.
84
85   * Elogind does not have the concept of a "scope", internally, as
86     it's the same as a session.  Any API that refers to scopes will
87     always return an error code.
88
89 On the other hand, elogind does use a similar strategy to systemd in
90 that it places processes in a private cgroup for organizational
91 purposes, without installing any controllers (see
92 http://0pointer.de/blog/projects/cgroups-vs-cgroups.html).  This
93 allows elogind to map arbitrary processes to sessions, even if the
94 process does the usual double-fork to be reparented to PID 1.
95
96 Elogind does not manage virtual terminals.
97
98 Elogind does monitor power button and the lid switch, like systemd,
99 but instead of doing RPC to systemd to suspend, poweroff, or restart
100 the machine, elogind just does this directly.  For suspend, hibernate,
101 and hybrid-sleep, elogind uses the same code as systemd-sleep.
102 Instead of using a separate sleep.conf file to configure the sleep
103 behavior, this is included in the [Sleep] section of
104 /etc/elogind/login.conf.  See the example login.conf for more.  For
105 shutdown, reboot, and kexec, elogind shells out to "halt", "reboot",
106 and "kexec" binaries.
107
108 The loginctl command has the poweroff, reboot, sleep, hibernate, and
109 hybrid-sleep commands from systemd, as well as the --ignore-inhibitors
110 flag.
111
112 The PAM module is called pam_elogind.so, not pam_systemd.so.
113
114 Elogind and the running cgroup controller
115 -----------------------------------------
116 While 'configure' runs, it will detect which controller is in place.
117 If no controller is in place, configure will determine, that elogind
118 should be its own controller, which will be a very limited one.
119
120 This approach should generally work, but if you just have no cgroup
121 controller in place, yet, or if you are currently switching to
122 another one, this approach will fail.
123
124 In this case you can do one of the two following things:
125
126  1) Boot your system with the target init system and cgroup
127     controller, before configuring and building elogind, or
128  2) Use the --with-cgroup-controller=name option.
129
130 Example: If you plan to use openrc, but openrc has not yet booted
131          the machine, you can use
132          --with-cgroup-controller=openrc
133          to let elogind know that openrc will be the controller
134          in charge.
135
136 However, if you set the controller at configure time to something
137 different than what is in place, elogind will not start until that
138 controller is actively used as the primary controller.
139
140 License
141 -------
142
143 LGPLv2.1+ for all code
144
145   - except src/basic/siphash24.c which is CC0 Public Domain
146
147 Dependencies
148 ------------
149
150   glibc >= 2.16
151   libcap
152   libmount >= 2.27.1 (from util-linux)
153           (util-linux < 2.29 *must* be built with --enable-libmount-force-mountinfo,
154           and later versions without --enable-libmount-support-mtab.)
155   libseccomp >= 2.3.1 (optional)
156   libblkid >= 2.24 (from util-linux) (optional)
157   PAM >= 1.1.2 (optional)
158   libacl (optional)
159   libselinux (optional)
160   libpython (optional)
161   pkg-config
162   gperf >= 3.1
163   docbook-xsl (optional, required for documentation)
164   xsltproc    (optional, required for documentation)
165   python-lxml (optional, required to build the indices)
166   python, meson, ninja
167   gcc, awk, sed, grep, m4, and similar tools
168
169 During runtime, you need the following additional dependencies:
170
171   util-linux >= v2.27.1 required
172   dbus >= 1.4.0 (strictly speaking optional, but recommended)
173           NOTE: If using dbus < 1.9.18, you should override the default
174           policy directory (--with-dbuspolicydir=/etc/dbus-1/system.d).
175   PolicyKit (optional)
176
177   To build in directory build/:
178     meson build/ && ninja -C build
179
180   Any configuration options can be specified as -Darg=value... arguments
181   to meson. After the build directory is initially configured, the configuration
182   can be changed with:
183     meson configure -Darg=value... build/
184   'meson configure' without any arguments will print out available options and
185   their current values.
186
187   Useful commands:
188     ninja -v some/target
189     ninja test
190     sudo ninja install
191     DESTDIR=... ninja install
192
193   A tarball can be created with:
194     git archive --format=tar --prefix=elogind-238/ v238 | xz > elogind-238.tar.xz