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 be │
37 │ │ │ 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 re‐ │
43 │ │ │ sponse does not need to be set │
44 │ │ │ in this message. The session is │
45 │ │ │ ready to be started if a success │
46 │ │ │ is returned. │
47 ├───────────────┼───────────────────┼──────────────────────────────────┤
48 │start_session │ cmd (array of │ Requests for the session to be │
49 │ │ strings) │ started using the provided com‐ │
50 │ │ │ mand line. The session will │
51 │ │ │ start after the greeter process │
52 │ │ │ terminates. │
53 ├───────────────┼───────────────────┼──────────────────────────────────┤
54 │cancel_session │ │ Cancels the session that is cur‐ │
55 │ │ │ rently under configuration. │
56 └───────────────┴───────────────────┴──────────────────────────────────┘
57 Responses
59 ┌─────────────┬─────────────────────┬──────────────────────────────────┐
60 │MESSAGE TYPE │ FIELDS │ PURPOSE │
61 ├─────────────┼─────────────────────┼──────────────────────────────────┤
62 │success │ │ Indicates that the request suc‐ │
63 │ │ │ ceeded. │
64 ├─────────────┼─────────────────────┼──────────────────────────────────┤
65 │error │ error_type (enum as │ Indicates that the request │
66 │ │ string), descrip‐ │ failed. │
67 │ │ tion (string) │ │
68 ├─────────────┼─────────────────────┼──────────────────────────────────┤
69 │auth_message │ auth_message_type │ Indicates that an authentication │
70 │ │ (enum as string), │ message needs to be answered to │
71 │ │ auth_message │ continue through the authentica‐ │
72 │ │ (string) │ tion flow. There are no limits │
73 │ │ │ on the number and type of mes‐ │
74 │ │ │ sages that may be required for │
75 │ │ │ authentication to succeed, and a │
76 │ │ │ greeter should not make any as‐ │
77 │ │ │ sumptions about the messages. │
78 │ │ │ Must be answered with either │
79 │ │ │ post_auth_message_response or │
80 │ │ │ cancel_session. │
81 └─────────────┴─────────────────────┴──────────────────────────────────┘
82 Authentication message type enums
84 ┌──────────────────┬────────────────────────────┐
85 │AUTH MESSAGE TYPE │ PURPOSE │
86 ├──────────────────┼────────────────────────────┤
87 │visible │ Indicates that input from │
88 │ │ the user should be visible │
89 │ │ when they answer this │
90 │ │ question. │
91 ├──────────────────┼────────────────────────────┤
92 │secret │ Indicates that input from │
93 │ │ the user should be consid‐ │
94 │ │ ered secret when they an‐ │
95 │ │ swer this question. │
96 ├──────────────────┼────────────────────────────┤
97 │info │ Indicates that this mes‐ │
98 │ │ sage is informative, not a │
99 │ │ question. │
100 ├──────────────────┼────────────────────────────┤
101 │error │ Indicates that this mes‐ │
102 │ │ sage is an error, not a │
103 │ │ question. │
104 └──────────────────┴────────────────────────────┘
105 Error enums
107 ┌───────────┬────────────────────────────┐
108 │ERROR TYPE │ PURPOSE │
109 ├───────────┼────────────────────────────┤
110 │auth_error │ Indicates that authentica‐ │
111 │ │ tion failed. This is not a │
112 │ │ fatal error, and is likely │
113 │ │ caused by incorrect cre‐ │
114 │ │ dentials. Handle as appro‐ │
115 │ │ priate. │
116 ├───────────┼────────────────────────────┤
117 │error │ A general error. See the │
118 │ │ error description for more │
119 │ │ information. │
120 └───────────┴────────────────────────────┘
121
123 Maintained by Kenny Levinsen <contact@kl.wtf>. For more information
124 about greetd development, see https://git.sr.ht/~kennylevinsen/greetd.
125
127 greetd(1)
128 2022-05-03 greetd-ipc(7)