forked from flexibeast/s6-man-pages
-
Notifications
You must be signed in to change notification settings - Fork 0
/
s6-local-service.7
142 lines (142 loc) · 4.88 KB
/
s6-local-service.7
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
.Dd September 29, 2021
.Dt S6-LOCAL-SERVICE 7
.Os
.Sh NAME
.Nm s6-local-service
.Nd daemon that listens to incoming connections on a Unix domain socket
.Sh DESCRIPTION
Clients of the service are programs connecting to a Unix domain socket: the
daemon performs operations on their behalf.
.Pp
The service is called
.Em local
because it is not accessible to clients from the network.
.Pp
A widely known example of a local service is the
.Ql syslogd
daemon.
On most implementations, it listens to the
.Pa /dev/log
socket.
Its clients connect to it and send their logs via the socket.
The
.Fn openlog
function is just a wrapper arround the
.Fn connect
system call, the
.Fn syslog
function a wrapper around
.Fn write ,
and so on.
.Ss Benefits
.Sy Privileges
.Pp
The most important benefit of a local service is that it permits
.Sy controlled privilege gains without using setuid programs .
The daemon is run as user S; a client running as user C and connecting
to the daemon asks it to perform operations: those will be done as
user S.
.Pp
Standard Unix permissions on the listening socket can be used to
implement some basic access control: to restrict access to clients
belonging to group G, change the socket to user S and group G, and
give it 0420 permissions.
This is functionally equivalent to the basic access control for setuid
programs: a program having user S, group G and permissions 4750 will
be executable by group G and run with S rights.
.Pp
But modern systems implement the
.Fn getpeereid
system call or library function.
This function allows the server to know the client's credentials: so
fine-grained access control is possible.
On those systems,
.Sy local services can do as much authentication as setuid programs, in a much more controlled environment .
.Sy Fd-passing
The most obvious difference between a local service and a network
service is that a local service does not serve network clients.
But local services have another nice perk: while network services
usually only provide you with a single channel (a TCP or UDP socket)
of communication between the client and the server, forcing you to
multiplex your data into that channel, local services allow you to
have as many communication channels as you want.
.Pp
(The SCTP transport layer provides a way for network services to use
several communication channels.
Unfortunately, it is not widely deployed yet, and a lot of network
services still depend on TCP.)
.Pp
The
.Em fd-passing
mechanism is Unix domain socket black magic that allows one peer of
the socket to send open file descriptors to the other peer.
So, if the server opens a pipe and sends one end of this pipe to a
client via this mechanism, there is effectively a socket
.Em and
a pipe between the client and the server.
.Ss UCSPI
The UCSPI[1] protocol is an easy way of abstracting clients and servers
from the network.
A server written as a UCSPI server, just as it can be run under inetd
or
.Xr s6-tcpserver 8 ,
can be run under
.Xr s6-ipcserver 8 :
choose a socket location and you have a local service.
.Pp
Fine-grained access control can be added by inserting
.Xr s6-ipcserver-access 8
in your server command line after
.Xr s6-ipcserver 8 .
.Pp
A client written as an UCSPI client, i.e. assuming it has descriptor 6
(resp. 7) open and reading from (resp. writing to) the server socket,
can be run under
.Xr s6-ipcclient 8 .
.Ss Use in skarnet.org software
skarnet.org libraries often use a separate process to handle
asynchronicity and background work in a way that's invisible to the
user.
Among them are:
.Bl -bullet -width x
.It
.Xr s6-ftrigrd 8 ,
managing the reception of notifications and only waking up the client
process when the notification pattern matches a regular expression.
.It
.Xr s6lockd 8 ,
handling time-constrained lock acquisition on client behalf.
.It
skadnsd[2],
performing asynchronous DNS queries and only waking up the client
process when an answer arrives.
.El
.Pp
Those processes are usually spawned from a client, via the
corresponding
.Ql *_startf*
library call.
But they can also be spawned from a
.Xr s6-ipcserver 8
program in a local service configuration.
In both cases, they need an additional control channel to be passed
from the server to the client: the main socket is used for synchronous
commands from the client to the server and their answers, whereas the
additional channel, which is now implemented as a socket as well (but
created by the server on-demand and not bound to a local path), is
used for asynchronous notifications from the server to the client.
The fd-passing mechanism is used to transfer the additional channel
from the server to the client.
.Sh SEE ALSO
.Xr s6-tcpserver 8
[1]
.Lk https://cr.yp.to/proto/ucspi.txt
.Pp
[2]
.Lk https://skarnet.org/software/s6-dns/skadns/skadnsd.html
.Pp
This man page is ported from the authoritative documentation at:
.Lk https://skarnet.org/software/s6/localservice.html
.Sh AUTHORS
.An Laurent Bercot
.An Alexis Ao Mt [email protected] Ac (man page port)