chiark / gitweb /
Upgrade licence to GPLv3+.
[userv.git] / userv.1
1 .\"
2 .\" This manpage is copyright, like the rest of userv, - see the
3 .\" copyright section, below.
4 .Dd November 3, 1999
5 .Dt USERV 1
6 .Os "userv"
7 .Sh NAME
8 .Nm userv
9 .Nd request user services
11 .Nm userv
12 .Op Ar option ...
13 .Op Fl -
14 .Ar service-user
15 .Ar service-name
16 .Op Ar argument ...
17 .Nm userv
18 .Op Ar option ...
19 .Fl B | -builtin
20 .Op Fl -
21 .Ar builtin-service
22 .Bk -words
23 .Op Ar info-argument ...
24 .Ek
26 .Nm userv
27 is used to have a task performed under different userid while
28 maintaining limited trust between caller and callee.
29 .Pp
30 .Ar service-user
31 specifies which user account is to perform the task.  The user may be
32 a login name or a numeric uid, or
33 .Ql -
34 to indicate that the service user is to be the same as the calling
35 user.
36 .Pp
37 The service name is interpreted by the userv daemon on behalf of the
38 service user.  This is controlled by configuration files in the
39 service user's filespace; consult the userv specification for details.
41 Single-letter options may be combined as is usual with Unix programs,
42 and the value for such an option may appear in the same argument or in
43 the next.
44 .Bl -tag -width Fl
45 .It Fl B | -builtin
46 Requests that a builtin service be provided.  This is equivalent to
47 using the
48 .Fl -override
49 option to specify a string consisting of
50 .Ql execute-builtin
51 followed by the
52 .Ar builtin-service
53 requested, and requesting a service user of 
54 .Ql -
55 (indicating the calling user).
56 .Pp
57 If the builtin service being requested requires a
58 .Ar service-argument
59 then this must be supplied to the client in the
60 same argument as the
61 .Ar builtin-service .
62 See the specification, or the output of
63 .Bd -literal -offset indent -compact
64 userv -B help
65 .Ed
66 for details of the builtin services available,
67 and below for details of the
68 .Fl -override
69 options.
70 .Pp
71 The actual service name passed will be the
72 .Ar builtin-service ;
73 note
74 that this actual service name (as opposed to the override data) and
75 the
76 .Ar info-argument Ns s
77 supplied will be ignored by most builtin
78 services; the override mechanism and
79 .Ql execute-builtin
80 will be
81 used to ensure that the right builtin service is called with the right
82 .Ar service-argument Ns s .
83 .It Xo
84 .Fl f | -file
85 .Sm off
86 .Ar fd Oo Ar fdmodifiers Oc = Ar filename
87 .Sm on
88 .Xc
89 Requests that data be copied in and out of the service using pipes.
90 For each file or descriptor this will be done by creating a pipe, one
91 end of which is passed to the service program and the other end of
92 which is passed to a copy of
93 .Nm cat
94 invoked by the client; the other file descriptor passed to
95 .Nm cat
96 will be one inherited by the client program from the caller or one
97 opened by the client program on behalf of the caller.
98 .Pp
99 The descriptor in the service program that should be connected must be
100 specified as
101 .Ar fd ,
102 either as a decimal number or as one of the
103 strings
104 .Ql stdin ,
105 .Ql stdout
106 or
107 .Ql stderr .
108 The next argument is a filename which will be opened by the client
109 with the privileges of the calling user.
110 .Pp
111 .Ar modifiers
112 is used to specify whether the file or descriptor is to be read from
113 or written to.  It consists of a series of words separated by commas.
114 A comma may separate the
115 .Ar modifiers
116 from
117 the
118 .Ar fd
119 and is required if
120 .Ar fd
121 is not numeric.
122 The modifier words are:
123 .Bl -tag -width Li
124 .It Ic read
125 .Dv O_RDONLY :
126 Allow reading and not writing.  May not be used with
127 .Ql write
128 or things that imply it.
129 .It Ic write
130 .Dv O_WRONLY :
131 Allow writing and not reading.
132 .Em Doesn't truncate or create
133 without
134 .Ql truncate
135 or
136 .Ql create .
137 .Ql write
138 or things that imply it may not be used with
139 .Ql read .
140 .It Ic overwrite
141 Equivalent to
142 .Ql write,create,truncate .
143 .It Ic create ,  creat
144 .Dv O_CREAT :
145 Creates the file if necessary.  Implies
146 .Ql write .
147 .It Ic exclusive , excl
148 .Dv O_EXCL:
149 Fails if the file already exists. Implies write and create. May
150 not be used with
151 .Ql truncate .
152 .It Ic truncate , trunc
153 .Dv O_TRUNC:
154 Truncate any existing file.  Implies
155 .Ql write .
156 May not be used with
157 .Ql exclusive .
158 .It Ic append
159 .Dv O_APPEND :
160 All writes will append to the file.  Implies
161 .Ql write
162 (but not
163 .Ql create ) .
164 .It Ic sync
165 .Dv O_SYNC :
166 Do writes synchronously.  Implies
167 .Ql write .
168 .It Ic wait , nowait , close
169 These modifiers control the behaviour of the client, with respect to
170 the pipes carrying data to and from the service, when the service
171 terminates.  See below.
172 .It Ic fd
173 The
174 .Ar filename
175 is not a filename but a numeric file descriptor.
176 One or both of
177 .Ql read
178 and
179 .Ql write
180 must be specified, and no
181 other words are allowed.  The
182 .Ar filename
183 may also be
184 .Ql stdin ,
185 .Ql stdout
186 or
187 .Ql stderr
188 for file descriptor 0, 1 or 2 respectively.
189 .El
190 .Pp
191 If no
192 .Ar modifiers
193 which imply
194 .Ql read
195 or
196 .Ql write
197 are used it is as if
198 .Ql write
199 had been specified, except that if the filedescriptor 0 of the service
200 is being opened (either specified numerically or with
201 .Ql stdin )
202 it is as if
203 .Ql overwrite
204 had been specified (or
205 .Ql write
206 if only
207 .Ql fd
208 was specified).
209 .Pp
210 The client will also use
211 .Dv O_NOCTTY
212 when opening files specified by the caller, to avoid changing its
213 controlling terminal.
214 .Pp
215 By default
216 .Va stdin ,
217 .Va stdout
218 and
219 .Va stderr
220 of the service will be connected to the corresponding descriptors on
221 the client.  Diagnostics from the client and daemon will also appear
222 on
223 .Va stderr .
224 .Pp
225 If
226 .Ql wait
227 is specified, the client will wait for the pipe to be closed, and only
228 exit after this has happened.  This means that either the receiving
229 end of the pipe connection was closed while data was still available
230 at the sending end, or that the end of file was reached on the reading
231 file descriptor.  Errors encountered reading or writing in the client
232 at this stage will be considered a system error and cause the client
233 to exit with status 255, but will not cause disconnection at the
234 service side since the service has already exited.
235 .Pp
236 If
237 .Ql close
238 is specified the client will immediately close the pipe connection by
239 killing the relevant copy of
240 .Nm cat .
241 If the service uses the descriptor it will get
243 (or
244 .Er EPIPE )
245 for a writing descriptor or end of file for a reading one; the
246 descriptor opened by or passed to the client will also be closed.
247 .Pp
248 If
249 .Ql nowait
250 is specified then the client will not wait and the
251 connection will remain open after the client terminates.  Data may
252 continue to be passed between the inheritors of the relevant
253 descriptor on the service side and the corresponding file or
254 descriptor on the client side until either side closes their
255 descriptor.  This should not usually be specified for
256 .Va stderr
257 (or
258 .Va stdout
259 if
260 .Ql "--signals stdout"
261 is used) since diagnostics from the service side may arrive after the
262 client has exited and be confused with expected output.
263 .Pp
264 The default is
265 .Ql wait
266 for writing file descriptors and
267 .Ql close
268 for reading ones.
269 .It Xo
270 .Fl w | -fdwait
271 .Ar fd Ns = Ns Ar action
272 .Xc
273 Sets the action on termination of the service for the specified file
274 descriptor;
275 .Ar action
276 must be
277 .Ql wait ,
278 .Ql nowait
279 or
280 .Ql close
281 as described above.  The file descriptor must be specified as open
282 when this option is encountered; this option is overridden by any
283 later
284 .Fl -file
285 or
286 .Fl -fdwait
287 option - even by a
288 .Fl -file
289 which does not specify an action on termination (in this case the
290 default will be used, as described above).
291 .It Xo
292 .Fl D | -defvar
293 .Ar name Ns = Ns Ar value
294 .Xc
295 Set a user-defined variable
296 .Ar name
297 to
298 .Ar value .
299 These
300 user-defined variables are made available in the configuration
301 language as the parameters
302 .Ql u- Ns Ar name
303 and are passed to the
304 service in environment variables
305 .Ev USERV_U_ Ns Ar name .
306 .Ar name
307 may contain only alphanumerics and underscores, and must start with a
308 letter.  If several definitions are given for the same
309 .Ar name
310 then only the last is effective.
311 .It Fl t | -timeout Ar seconds
312 Time out the service if it takes longer than
313 .Ar seconds
314 seconds (a positive integer, in decimal).  Timeout will produce a
315 diagnostic on stderr and an exit status of 255.  If
316 .Ar seconds
317 is zero then no timeout will be implemented (this is the default).
318 .It Fl S | -signals Ar method
319 Affects the handling of the exit status when the service terminates
320 due to a signal.  (The client will always finish by calling
321 .Fn _exit ,
322 so that only numbers from 0 to 255 can be returned and not the full
323 range of numbers and signal indications which can be returned by the
324 .Fn wait
325 family of system calls.)
326 .Pp
327 The
328 .Ar method
329 may be one of the following:
330 .Bl -tag -width Li
331 .It Ar status
332 The client's exit status will be
333 .Ar status .
334 This will not be distinguishable from the service really having exited
335 with code
336 .Ar status .
337 This method is the default, with a
338 .Ar status
339 of 254.
340 .It Ic number , number-nocore
341 The client's exit status will be the number of the signal which caused
342 the termination of the service.  If
343 .Ql number
344 is used rather than
345 .Ql number-nocore
346 then 128 will be added if the service dumped core.
347 .Ql number
348 is very like the exit code mangling done by the Bourne shell.
349 .It Ic highbit
350 The client's exit status will be the number of the signal with 128
351 added.  If the service exits normally with an exit code of greater
352 than 127 then 127 will be returned.
353 .It Ic stdout
354 The service's numeric wait status as two decimal numbers (high byte
355 first) and a textual description of its meaning will be printed to the
356 client's standard output.  It will be preceded by a newline and
357 followed by an extra newline, and the numbers are separated from each
358 other and from the textual description by single spaces.  The exit
359 status of the client will be zero, unless a system error occurs in
360 which case no exit status and description will be printed to
361 .Va stdout ,
362 and an error message will be printed to
363 .Va stderr
364 as usual.
365 .Pp
366 Problems such as client usage errors, the service not being found or
367 permission being denied or failure of a system call are system errors.
368 An error message describing the problem will be printed on the
369 client's
370 .Va stderr ,
371 and the client's exit status will be 255.  If the client dies due to a
372 signal this should be treated as a serious system error.
373 .El
374 .It Fl H | -hidecwd
375 Prevents the calling process's current directory name from being
376 passed to the service; the null string will be passed instead.
377 .It Fl P | -sigpipe
378 If the service program is terminated due to a
380 the exit status of the client will be zero, even if it would have been
381 something else according to the exit status method specified.  This
382 option has no effect on the code and description printed if the exit
383 status method
384 .Ql stdout
385 is in use.
386 .It Fl h | -help
387 Prints the client's usage message.
388 .It Fl -copyright
389 Prints the copyright and lack of warranty notice.
390 .El
392 There are also some options which are available for debugging and to
393 allow the system administrator to override a user's policy.  These
394 options are available only if the client is called by root or if the
395 calling user is the same as the service user.
396 .Bl -tag -width Fl
397 .It Fl -override Ar configuration-data
398 .It Fl -override-file Ar file
399 Do not read the usual configuration files.  Instead, the client sends
400 .Ar configuration-data
401 (followed by a newline) or the contents of
402 .Ar filename
403 (which is opened in the context of the client) to the daemon and the
404 daemon uses that data instead.  The
405 .Ar configuration-data
406 must all be in one argument.  It will have a single newline appended
407 so that a single directive can easily be given, but if more than one
408 directive is required it will have to contain one or more real
409 newlines.
410 .It Fl -spoof-user Ar user
411 Pretend to the service that it is being called by
412 .Ar user
413 (which may be a username or a uid).  This will also affect the group
414 and supplementary groups supplied to the service; they will be the
415 standard group and supplementary groups for
416 .Ar user .
417 The
418 .Fl -spoof-user
419 option will
420 .Em not
421 affect which user is chosen if the service user is specified as just
422 .Ql - ;
423 in this case the service user will be the real calling user.
424 .El
426 .Bl -tag -width Ev
428 These are used to determine the name of the calling user, to be passed
429 to the service in
430 .Ev USERV_USER .
431 Their values will only be used if they correspond to the calling UID.
432 .El
433 .Sh FILES
434 .Bl -tag -width Pa
435 .It Pa /var/run/userv/socket
436 .Ux Ns -domain
437 socket used for communication between
438 .Nm
439 and
440 .Nm uservd .
441 .It Pa /var/run/userv/%x.%x.%x
442 Pipes used for connecting file descriptors in the client and the
443 service.
444 .El
445 .Sh SEE ALSO
446 .Xr uservd 8
447 .Rs
448 .%T "User service daemon and client specification"
449 .%A Ian Jackson
450 .Re
452 GNU userv is Copyright 1996-2017 Ian Jackson; Copyright 2000 Ben
453 Harris; and Copyright 2016-2017 Peter Benie.
454 .Pp
455 GNU userv is licensed under the terms of the GNU General Public
456 Licence, version 3 or (at your option) any later version, and it comes
457 with NO WARRANTY, not even the implied warranty of MERCHANTABILITY or
458 FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
459 for details.
460 .Pp
461 You should have received a copy of the GNU General Public License
462 along with userv, if not, see
464 .Nm
465 was initially written in 1996 by Ian Jackson.  It became
466 .Tn GNU
467 .Nm
468 in 1999, and version 1.0 was released in 2000.