1greetd-ipc(7)          Miscellaneous Information Manual          greetd-ipc(7)
2
3
4

NAME

6       greetd-ipc - IPC protocol for greetd
7

DESCRIPTION

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
13       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

MESSAGE AND REPLY FORMAT

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
23       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

MESSAGES

30   Requests
31       ┌───────────────┬────────────────────┬─────────────────────────────────┐
32MESSAGE 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
60   Responses
61       ┌─────────────┬─────────────────────┬──────────────────────────────────┐
62MESSAGE 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
85   Authentication message type enums
86       ┌──────────────────┬────────────────────────────┐
87AUTH 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
108   Error enums
109       ┌───────────┬────────────────────────────┐
110ERROR 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

AUTHORS

125       Maintained by Kenny Levinsen <contact@kl.wtf>. For more information
126       about greetd development, see https://git.sr.ht/~kennylevinsen/greetd.
127

SEE ALSO

129       greetd(1)
130
131
132
133                                  2023-07-20                     greetd-ipc(7)
Impressum