conf/README.md

   1 Configuration of af-main using systemd
   2 ======================================
   3
   4 Mechanism to start user sessions
   5 --------------------------------
   6
   7 The mechanism to start a session for the user of **UID** is
   8 to start the service **afm-user-session@UID.service**.
   9
  10 This has the effect of starting a session.
  11
  12 To achieve that goal the first is to start the user session.
  13 This is done using the 2 systemd directives [1]:
  14
  15     User=%i
  16     PAMName=afm-user-session
  17
  18 The first tells what is the user. %i is replaced by the parameter
  19 of the service: UID. So the user is referenced here by its number.
  20
  21 For this user, the PAM script **afm-user-session** is evaluated.
  22 It is implmented by the file */etc/pam.d/afm-user-session*.
  23 That script MUST refer to *pam_systemd.so* for opening the session
  24 with systemd. It often takes the form of a line of the form:
  25
  26     session     optional      pam_systemd.so
  27
  28 that is directly or indirectly (through includes) activated by
  29 **afm-user-session**. [2] [3]
  30
  31 The effect of starting a systemd user session is to start the
  32 user services and the most important one: dbus.
  33
  34 When the user session is started, the service
  35 **afm-user-session@UID.service** enters its second phase:
  36 activation of the user session for the framework.
  37
  38 This is achieved by activating the target **afm-user-session@.target**.
  39 But activating a *system* unit from a *user* session is a
  40 thing that has to be safe. This is done by the program
  41 **afm-user-session**. This program runs as rot (with the set-uid)
  42 and simply execute *systemctl --wait start afm-user-session@UID.target*.
  43 Where *UID* is the user id of the calling process.
  44
  45 [1] https://www.freedesktop.org/software/systemd/man/systemd.exec.html
  46 [2] https://www.freedesktop.org/software/systemd/man/pam_systemd.html
  47 [3] https://linux.die.net/man/5/pam.conf