chiark / gitweb /
time-util: Fix overflow check introduce in commit f977849 (#5216)
[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 We like systemd.  We realize that there are people out there that hate
58 it.  You're welcome to use elogind for whatever purpose you like --
59 as-is, or as a jumping-off point for other things -- but please don't
60 use it as part of some anti-systemd vendetta.  Systemd hackers are
61 smart folks that are trying to solve interesting problems on the free
62 desktop, and their large adoption is largely because they solve
63 problems that users and developers of user-focused applications care
64 about.  We are appreciative of their logind effort and think that
65 everyone deserves to run it if they like, even if they use a different
66 PID 1.
67
68 Differences relative to systemd
69 -------------------------------
70
71 The pkg-config file is called libelogind, not libsystemd or
72 libsystemd-logind.
73
74 The headers are in <elogind/...>, so like <elogind/sd-login.h> instead
75 of <systemd/sd-login.h>.
76
77 Libelogind just implements login-related functionality.  It also
78 provides the sd-bus API.
79
80 Unlike systemd, whose logind arranges to manage resources for user
81 sessions via RPC calls to systemd, in elogind there is no systemd so
82 there is no global cgroup-based resource management.  This has a few
83 implications:
84
85   * Elogind does not create "slices" for users.  Elogind will not
86     record that users are associated with slices.
87
88   * The /run/systemd/slices directory will always be empty.
89
90   * Elogind does not have the concept of a "scope", internally, as
91     it's the same as a session.  Any API that refers to scopes will
92     always return an error code.
93
94 On the other hand, elogind does use a similar strategy to systemd in
95 that it places processes in a private cgroup for organizational
96 purposes, without installing any controllers (see
97 http://0pointer.de/blog/projects/cgroups-vs-cgroups.html).  This
98 allows elogind to map arbitrary processes to sessions, even if the
99 process does the usual double-fork to be reparented to PID 1.
100
101 Elogind does not manage virtual terminals.
102
103 Elogind does monitor power button and the lid switch, like systemd,
104 but instead of doing RPC to systemd to suspend, poweroff, or restart
105 the machine, elogind just does this directly.  For suspend, hibernate,
106 and hybrid-sleep, elogind uses the same code as systemd-sleep.
107 Instead of using a separate sleep.conf file to configure the sleep
108 behavior, this is included in the [Sleep] section of
109 /etc/elogind/login.conf.  See the example login.conf for more.  For
110 shutdown, reboot, and kexec, elogind shells out to "halt", "reboot",
111 and "kexec" binaries.
112
113 The loginctl command has the poweroff, reboot, sleep, hibernate, and
114 hybrid-sleep commands from systemd, as well as the --ignore-inhibitors
115 flag.
116
117 The PAM module is called pam_elogind.so, not pam_systemd.so.
118
119 Elogind and the running cgroup controller
120 -----------------------------------------
121 While 'configure' runs, it will detect which controller is in place.
122 If no controller is in place, configure will determine, that elogind
123 should be its own controller, which will be a very limited one.
124
125 This approach should generally work, but if you just have no cgroup
126 controller in place, yet, or if you are currently switching to
127 another one, this approach will fail.
128
129 In this case you can do one of the two following things:
130
131  1) Boot your system with the target init system and cgroup
132     controller, before configuring and building elogind, or
133  2) Use the --with-cgroup-controller=name option.
134
135 Example: If you plan to use openrc, but openrc has not yet booted
136          the machine, you can use
137          --with-cgroup-controller=openrc
138          to let elogind know that openrc will be the controller
139          in charge.
140
141 However, if you set the controller at configure time to something
142 different than what is in place, elogind will not start until that
143 controller is actively used as the primary controller.
144
145 License
146 -------
147
148 LGPLv2.1+ for all code
149
150   - except src/shared/MurmurHash2.c which is Public Domain
151   - except src/shared/siphash24.c which is CC0 Public Domain
152   - except src/journal/lookup3.c which is Public Domain
153
154 Dependencies
155 ------------
156
157   glibc >= 2.14
158   libcap
159   libmount >= 2.20 (from util-linux)
160   libseccomp >= 1.0.0 (optional)
161   libblkid >= 2.24 (from util-linux) (optional)
162   PAM >= 1.1.2 (optional)
163   libacl (optional)
164   libselinux (optional)
165   make, gcc, and similar tools
166
167 During runtime, you need the following additional dependencies:
168
169   dbus >= 1.4.0 (strictly speaking optional, but recommended)
170   PolicyKit (optional)
171
172 When building from git, you need the following additional
173 dependencies:
174
175   pkg-config
176   docbook-xsl
177   xsltproc
178   automake
179   autoconf
180   libtool
181   intltool
182   gperf
183   gtkdocize (optional)