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
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
|
---
title: SOCKET-ACTIVATE
section: 1
header: User Commands
footer: Feb 2019
---
NAME
====
`socket-activate` - open sockets and `exec` a socket-activated service
SYNOPSIS
========
**socket-activate** [**-v**] [*socketinfo* ...] [**\-\-**] *prog* [*args*]
where *socketinfo* is of the form:
\-\-*family*:[*option*=*value*,...]:*address*
See `EXAMPLES` below.
DESCRIPTION
===========
The `socket-activate` program opens the requested sockets and then
waits for incoming activity on them. When this happens, it execs
*prog*, which inherits these open file descriptors. The first
requested socket will be opened on file descriptor 3, and subsequent
ones follow in order.
If `-v` or `--verbose` is present, `socket-activate` will write
details of what it is doing to stderr before it execs *prog*.
*prog* is the first argument that does not start with a `-`, or the
first argument after a `--`.
SOCKET FAMILIES
===============
*family* can be one of several different values.
For the following values of *family*, if *address* is a single decimal
number, it is treated as a port number and socket-activate will bind to all
available addresses on that port. If *address* contains a /, the part
before the / is interpreted as a network address of the requested
family, and the part after the / is treated as a port number.
- `tcp`: TCP on IPv4 and/or IPv6
- `udp`: UDP on IPv4 and/or IPv6
For the following values of *family*, *address* is interpreted as a
filesystem path.
- `unix`: Unix-domain streaming socket
- `unix-dgram`: Unix-domain datagram socket
SOCKET OPTIONS
==============
Each *socketinfo* can have 0 or more options appended to it, separated
by the comma character (`,`) with their value appended after an equals
sign (`=`).
Available options are:
- `label`: simple text string to identify this socket to the
inheriting process
- `backlog`: For streaming sockets (`tcp` and `unix`), the maximum
queue for pending connections (see listen(2) -- defaults
to `SOMAXCONN`).
- `mode`: octal mode for Unix-domain socket (defaults to relying on
umask(2))
- `user`: a numeric User ID value for Unix-domain socket ownership
- `group`: a numeric Group ID value for Unix-domain socket ownership
EXIT CODES
==========
`socket-activate` exits 100 when called with unparseable options. It prints an
error message to stderr and exits 11 if it cannot successfully bind
all of the requested sockets. It prints an error message to stderr
and exits with the value of errno if it is unable to exec(3) the
intended process. Otherwise, its exit code is the same as that of
*prog*.
ENVIRONMENT VARIABLES
=====================
`socket-activate` stores the number of opened file descriptors in the
environment variable `$LISTEN_FDS`, sets `$LISTEN_PID` to getpid(2),
and stores the list of colon-separated labels in `$LISTEN_FDNAMES`.
These environment variables follow the convention understood by
libsystemd (see sd_listen_fds(3)) so it should be usable with any
socket-activated daemon that expects this behavior.
EXAMPLES
========
Run a webserver as a non-privileged user, using privileged ports, and
indicating to the webserver which ports should offer HTTPS:
socket-activate --tcp::80 --tcp:label=tls:443 -- \
runuser -u httpd -- \
webserver
Expose a foregrounded (supervised) pulseaudio daemon to the network:
socket-activate --tcp:backlog=5:1000 -- \
pulseaudio --daemonize=no
Run a network daemon only on the IPv4 loopback:
socket-activate --tcp::127.0.0.1/9999 -- \
network-daemon
Run a network daemon over a unix-domain socket instead of IP:
socket-activate --unix::/srv/network-access -- \
network-daemon
Run a public-facing network daemon with a local socket for the local
administrator to control it:
socket-activate --tcp::443 --unix:label=control,user=1000,mode=0600:/run/xyz/control -- \
xyzd
BUGS AND LIMITATIONS
====================
`socket-activate` does not do any sort of name-to-number resolution: network
addresses, user ids, group ids, and port numbers must all be specified
numerically. Hostnames, user names, group names, service names are
not interpreted.
`socket-activate` produces its error messages in English and is not
internationalized.
`socket-activate` cannot provide a `label` that contains either a colon (`:`)
or a comma (`,`).
`socket-activate` cannot reliably listen on a link-local network address
because it has no way to specify the particular network interface.
`socket-activate` only opens sockets for (and launches) a single
service, so it can't be used for robust system-wide synchronization.
In particular, there may be a race condition during startup of
concurrent services that talk to each other.
`socket-activate` doesn't clearly indicate to its caller when the
sockets have been successfully bound, it simply remains foregrounded.
SEE ALSO
========
exec(3), listen(2), runuser(1), sd_listen_fds(3), umask(2)
AUTHOR
======
Daniel Kahn Gillmor <dkg@fifthhorseman.net>
|
