You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

README.md 9.4 KiB

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