1greetd-ipc(7) Miscellaneous Information Manual greetd-ipc(7)
2
6 greetd-ipc - IPC protocol for greetd
7
9 This details the interprocess communication (IPC) protocol for
10 greetd(1). This IPC protocol can be used to create and manage sessions
11 under greetd.
12 The IPC protocol uses a UNIX socket as a method of communication. The
14 path to the socket is stored in the environment variable GREETD_SOCK.
15
17 The format for messages and replies is:
18 <payload-length> <payload>
19 Where
20 <payload-length> is a 32-bit integer in native byte order
21 <payload> is a UTF-8-encoded JSON string.
22 For example, sending the "create_session" command would look like the
24 following hexdump:
25 00000000 2c 00 00 00 7b 22 74 79 70 65 22 3a 20 22 63 72 |,...{"type": "cr|
26 00000010 65 61 74 65 5f 73 65 73 73 69 6f 6e 22 2c 20 22 |eate_session", "|
27 00000020 75 73 65 72 6e 61 6d 65 22 3a 20 22 6d 65 22 7d |username": "me"}|
28
30 Requests
31 ┌───────────────┬────────────────────┬─────────────────────────────────┐
32 │MESSAGE TYPE │ FIELDS │ PURPOSE │
33 ├───────────────┼────────────────────┼─────────────────────────────────┤
34 │create_session │ username (string) │ Creates a session and initiates │
35 │ │ │ a login attempted for the given │
36 │ │ │ user. The session is ready to │
37 │ │ │ be started if a success is re‐ │
38 │ │ │ turned. │
39 ├───────────────┼────────────────────┼─────────────────────────────────┤
40 │post_auth_mes‐ │ response (string, │ Answers an authentication mes‐ │
41 │sage_response │ optional) │ sage. If the message was infor‐ │
42 │ │ │ mative (info, error), then a │
43 │ │ │ response does not need to be │
44 │ │ │ set in this message. The ses‐ │
45 │ │ │ sion is ready to be started if │
46 │ │ │ a success is returned. │
47 ├───────────────┼────────────────────┼─────────────────────────────────┤
48 │start_session │ cmd (array of │ Requests for the session to be │
49 │ │ strings), env (ar‐ │ started using the provided com‐ │
50 │ │ ray of strings) │ mand line, adding the supplied │
51 │ │ │ environment to that created by │
52 │ │ │ PAM. The session will start af‐ │
53 │ │ │ ter the greeter process termi‐ │
54 │ │ │ nates. │
55 ├───────────────┼────────────────────┼─────────────────────────────────┤
56 │cancel_session │ │ Cancels the session that is │
57 │ │ │ currently under configuration. │
58 └───────────────┴────────────────────┴─────────────────────────────────┘
59 Responses
61 ┌─────────────┬─────────────────────┬──────────────────────────────────┐
62 │MESSAGE TYPE │ FIELDS │ PURPOSE │
63 ├─────────────┼─────────────────────┼──────────────────────────────────┤
64 │success │ │ Indicates that the request suc‐ │
65 │ │ │ ceeded. │
66 ├─────────────┼─────────────────────┼──────────────────────────────────┤
67 │error │ error_type (enum as │ Indicates that the request │
68 │ │ string), descrip‐ │ failed. │
69 │ │ tion (string) │ │
70 ├─────────────┼─────────────────────┼──────────────────────────────────┤
71 │auth_message │ auth_message_type │ Indicates that an authentication │
72 │ │ (enum as string), │ message needs to be answered to │
73 │ │ auth_message │ continue through the authentica‐ │
74 │ │ (string) │ tion flow. There are no limits │
75 │ │ │ on the number and type of mes‐ │
76 │ │ │ sages that may be required for │
77 │ │ │ authentication to succeed, and a │
78 │ │ │ greeter should not make any as‐ │
79 │ │ │ sumptions about the messages. │
80 │ │ │ Must be answered with either │
81 │ │ │ post_auth_message_response or │
82 │ │ │ cancel_session. │
83 └─────────────┴─────────────────────┴──────────────────────────────────┘
84 Authentication message type enums
86 ┌──────────────────┬────────────────────────────┐
87 │AUTH MESSAGE TYPE │ PURPOSE │
88 ├──────────────────┼────────────────────────────┤
89 │visible │ Indicates that input from │
90 │ │ the user should be visible │
91 │ │ when they answer this │
92 │ │ question. │
93 ├──────────────────┼────────────────────────────┤
94 │secret │ Indicates that input from │
95 │ │ the user should be consid‐ │
96 │ │ ered secret when they an‐ │
97 │ │ swer this question. │
98 ├──────────────────┼────────────────────────────┤
99 │info │ Indicates that this mes‐ │
100 │ │ sage is informative, not a │
101 │ │ question. │
102 ├──────────────────┼────────────────────────────┤
103 │error │ Indicates that this mes‐ │
104 │ │ sage is an error, not a │
105 │ │ question. │
106 └──────────────────┴────────────────────────────┘
107 Error enums
109 ┌───────────┬────────────────────────────┐
110 │ERROR TYPE │ PURPOSE │
111 ├───────────┼────────────────────────────┤
112 │auth_error │ Indicates that authentica‐ │
113 │ │ tion failed. This is not a │
114 │ │ fatal error, and is likely │
115 │ │ caused by incorrect cre‐ │
116 │ │ dentials. Handle as appro‐ │
117 │ │ priate. │
118 ├───────────┼────────────────────────────┤
119 │error │ A general error. See the │
120 │ │ error description for more │
121 │ │ information. │
122 └───────────┴────────────────────────────┘
123
125 Maintained by Kenny Levinsen <contact@kl.wtf>. For more information
126 about greetd development, see https://git.sr.ht/~kennylevinsen/greetd.
127
129 greetd(1)
130 2023-07-20 greetd-ipc(7)