.\" Generated by scdoc 1.11.3
.\" Complete documentation for this program is not available as a GNU info page
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.nh
.ad l
.\" Begin generated content:
.TH "greetd-ipc" "7" "2024-04-22"
.PP
.SH NAME
.PP
greetd-ipc - IPC protocol for greetd
.PP
.SH DESCRIPTION
.PP
This details the interprocess communication (IPC) protocol for \fBgreetd\fR(1).\&
This IPC protocol can be used to create and manage sessions under greetd.\&
.PP
The IPC protocol uses a UNIX socket as a method of communication.\& The path
to the socket is stored in the environment variable \fIGREETD_SOCK\fR.\&
.PP
.SH MESSAGE AND REPLY FORMAT
.PP
The format for messages and replies is:
.nf
.RS 4
<payload-length> <payload>
.fi
.RE
Where
.nf
.RS 4
<payload-length> is a 32-bit integer in native byte order
<payload> is a UTF-8-encoded JSON string\&.
.fi
.RE
.PP
For example, sending the "create_session" command would look like the
following hexdump:
.nf
.RS 4
00000000  2c 00 00 00 7b 22 74 79  70 65 22 3a 20 22 63 72  |,\&.\&.\&.{"type": "cr|
00000010  65 61 74 65 5f 73 65 73  73 69 6f 6e 22 2c 20 22  |eate_session", "|
00000020  75 73 65 72 6e 61 6d 65  22 3a 20 22 6d 65 22 7d  |username": "me"}|
.fi
.RE
.PP
.SH MESSAGES
.PP
.SS Requests
.PP
.TS
allbox;l l lx
l l lx
l l lx
l l lx
l l lx.
T{
\fBMESSAGE TYPE\fR
T}	T{
\fBFIELDS\fR
T}	T{
\fBPURPOSE\fR
T}
T{
create_session
T}	T{
username (string)
T}	T{
Creates a session and initiates a login attempted for the given user.\& The session is ready to be started if a success is returned.\&
T}
T{
post_auth_message_response
T}	T{
response (string, optional)
T}	T{
Answers an authentication message.\& If the message was informative (info, error), then a response does not need to be set in this message.\& The session is ready to be started if a success is returned.\&
T}
T{
start_session
T}	T{
cmd (array of strings), env (array of strings)
T}	T{
Requests for the session to be started using the provided command line, adding the supplied environment to that created by PAM.\& The session will start after the greeter process terminates.\&
T}
T{
cancel_session
T}	T{

T}	T{
Cancels the session that is currently under configuration.\&
T}
.TE
.sp 1
.SS Responses
.TS
allbox;l l lx
l l lx
l l lx
l l lx.
T{
\fBMESSAGE TYPE\fR
T}	T{
\fBFIELDS\fR
T}	T{
\fBPURPOSE\fR
T}
T{
success
T}	T{

T}	T{
Indicates that the request succeeded.\&
T}
T{
error
T}	T{
error_type (enum as string), description (string)
T}	T{
Indicates that the request failed.\&
T}
T{
auth_message
T}	T{
auth_message_type (enum as string), auth_message (string)
T}	T{
Indicates that an authentication message needs to be answered to continue through the authentication flow.\& There are no limits on the number and type of messages that may be required for authentication to succeed, and a greeter should not make any assumptions about the messages.\& Must be answered with either post_auth_message_response or cancel_session.\&
T}
.TE
.sp 1
.SS Authentication message type enums
.PP
.TS
allbox;l l
l l
l l
l l
l l.
T{
\fBAUTH MESSAGE TYPE\fR
T}	T{
\fBPURPOSE\fR
T}
T{
visible
T}	T{
Indicates that input from the user should be visible when they answer this question.\&
T}
T{
secret
T}	T{
Indicates that input from the user should be considered secret when they answer this question.\&
T}
T{
info
T}	T{
Indicates that this message is informative, not a question.\&
T}
T{
error
T}	T{
Indicates that this message is an error, not a question.\&
T}
.TE
.sp 1
.SS Error enums
.PP
.TS
allbox;l l
l l
l l.
T{
\fBERROR TYPE\fR
T}	T{
\fBPURPOSE\fR
T}
T{
auth_error
T}	T{
Indicates that authentication failed.\& This is not a fatal error, and is likely caused by incorrect credentials.\& Handle as appropriate.\&
T}
T{
error
T}	T{
A general error.\& See the error description for more information.\&
T}
.TE
.sp 1
.SH AUTHORS
.PP
Maintained by Kenny Levinsen <contact@kl.\&wtf>.\& For more information about
greetd development, see https://git.\&sr.\&ht/~kennylevinsen/greetd.\&
.PP
.SH SEE ALSO
\fBgreetd\fR(1)