afm-user-daemon: Remove it by default
[src/app-framework-main.git] / 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