2 .\" This manpage is copyright, like the rest of userv, - see the
3 .\" copyright section, below.
9 .Nd request user services
23 .Op Ar info-argument ...
27 is used to have a task performed under different userid while
28 maintaining limited trust between caller and callee.
31 specifies which user account is to perform the task. The user may be
32 a login name or a numeric uid, or
34 to indicate that the service user is to be the same as the calling
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
46 Requests that a builtin service be provided. This is equivalent to
49 option to specify a string consisting of
53 requested, and requesting a service user of
55 (indicating the calling user).
57 If the builtin service being requested requires a
59 then this must be supplied to the client in the
62 See the specification, or the output of
63 .Bd -literal -offset indent -compact
66 for details of the builtin services available,
67 and below for details of the
71 The actual service name passed will be the
74 that this actual service name (as opposed to the override data) and
76 .Ar info-argument Ns s
77 supplied will be ignored by most builtin
78 services; the override mechanism and
81 used to ensure that the right builtin service is called with the right
82 .Ar service-argument Ns s .
86 .Ar fd Oo Ar fdmodifiers Oc = Ar filename
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
94 invoked by the client; the other file descriptor passed to
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.
99 The descriptor in the service program that should be connected must be
102 either as a decimal number or as one of the
108 The next argument is a filename which will be opened by the client
109 with the privileges of the calling user.
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
122 The modifier words are:
126 Allow reading and not writing. May not be used with
128 or things that imply it.
131 Allow writing and not reading.
132 .Em Doesn't truncate or create
138 or things that imply it may not be used with
142 .Ql write,create,truncate .
143 .It Ic create , creat
145 Creates the file if necessary. Implies
147 .It Ic exclusive , excl
149 Truncate any existing file. Implies
155 All writes will append to the file. Implies
161 Do writes synchronously. Implies
163 .It Ic wait , nowait , close
164 These modifiers control the behaviour of the client, with respect to
165 the pipes carrying data to and from the service, when the service
166 terminates. See below.
170 is not a filename but a numeric file descriptor.
175 must be specified, and no
176 other words are allowed. The
183 for file descriptor 0, 1 or 2 respectively.
194 had been specified, except that if the filedescriptor 0 of the service
195 is being opened (either specified numerically or with
199 had been specified (or
205 The client will also use
207 when opening files specified by the caller, to avoid changing its
208 controlling terminal.
215 of the service will be connected to the corresponding descriptors on
216 the client. Diagnostics from the client and daemon will also appear
222 is specified, the client will wait for the pipe to be closed, and only
223 exit after this has happened. This means that either the receiving
224 end of the pipe connection was closed while data was still available
225 at the sending end, or that the end of file was reached on the reading
226 file descriptor. Errors encountered reading or writing in the client
227 at this stage will be considered a system error and cause the client
228 to exit with status 255, but will not cause disconnection at the
229 service side since the service has already exited.
233 is specified the client will immediately close the pipe connection by
234 killing the relevant copy of
236 If the service uses the descriptor it will get
240 for a writing descriptor or end of file for a reading one; the
241 descriptor opened by or passed to the client will also be closed.
245 is specified then the client will not wait and the
246 connection will remain open after the client terminates. Data may
247 continue to be passed between the inheritors of the relevant
248 descriptor on the service side and the corresponding file or
249 descriptor on the client side until either side closes their
250 descriptor. This should not usually be specified for
255 .Ql "--signals stdout"
256 is used) since diagnostics from the service side may arrive after the
257 client has exited and be confused with expected output.
261 for writing file descriptors and
266 .Ar fd Ns = Ns Ar action
268 Sets the action on termination of the service for the specified file
276 as described above. The file descriptor must be specified as open
277 when this option is encountered; this option is overridden by any
284 which does not specify an action on termination (in this case the
285 default will be used, as described above).
288 .Ar name Ns = Ns Ar value
290 Set a user-defined variable
295 user-defined variables are made available in the configuration
296 language as the parameters
298 and are passed to the
299 service in environment variables
300 .Ev USERV_U_ Ns Ar name .
302 may contain only alphanumerics and underscores, and must start with a
303 letter. If several definitions are given for the same
305 then only the last is effective.
306 .It Fl t | -timeout Ar seconds
307 Time out the service if it takes longer than
309 seconds (a positive integer, in decimal). Timeout will produce a
310 diagnostic on stderr and an exit status of 255. If
312 is zero then no timeout will be implemented (this is the default).
313 .It Fl S | -signals Ar method
314 Affects the handling of the exit status when the service terminates
315 due to a signal. (The client will always finish by calling
317 so that only numbers from 0 to 255 can be returned and not the full
318 range of numbers and signal indications which can be returned by the
320 family of system calls.)
324 may be one of the following:
327 The client's exit status will be
329 This will not be distinguishable from the service really having exited
332 This method is the default, with a
335 .It Ic number , number-nocore
336 The client's exit status will be the number of the signal which caused
337 the termination of the service. If
341 then 128 will be added if the service dumped core.
343 is very like the exit code mangling done by the Bourne shell.
345 The client's exit status will be the number of the signal with 128
346 added. If the service exits normally with an exit code of greater
347 than 127 then 127 will be returned.
349 The service's numeric wait status as two decimal numbers (high byte
350 first) and a textual description of its meaning will be printed to the
351 client's standard output. It will be preceded by a newline and
352 followed by an extra newline, and the numbers are separated from each
353 other and from the textual description by single spaces. The exit
354 status of the client will be zero, unless a system error occurs in
355 which case no exit status and description will be printed to
357 and an error message will be printed to
361 Problems such as client usage errors, the service not being found or
362 permission being denied or failure of a system call are system errors.
363 An error message describing the problem will be printed on the
366 and the client's exit status will be 255. If the client dies due to a
367 signal this should be treated as a serious system error.
370 Prevents the calling process's current directory name from being
371 passed to the service; the null string will be passed instead.
373 If the service program is terminated due to a
375 the exit status of the client will be zero, even if it would have been
376 something else according to the exit status method specified. This
377 option has no effect on the code and description printed if the exit
382 Prints the client's usage message.
384 Prints the copyright and lack of warranty notice.
386 .Ss Security-overriding options
387 There are also some options which are available for debugging and to
388 allow the system administrator to override a user's policy. These
389 options are available only if the client is called by root or if the
390 calling user is the same as the service user.
392 .It Fl -override Ar configuration-data
393 .It Fl -override-file Ar file
394 Do not read the usual configuration files. Instead, the client sends
395 .Ar configuration-data
396 (followed by a newline) or the contents of
398 (which is opened in the context of the client) to the daemon and the
399 daemon uses that data instead. The
400 .Ar configuration-data
401 must all be in one argument. It will have a single newline appended
402 so that a single directive can easily be given, but if more than one
403 directive is required it will have to contain one or more real
405 .It Fl -spoof-user Ar user
406 Pretend to the service that it is being called by
408 (which may be a username or a uid). This will also affect the group
409 and supplementary groups supplied to the service; they will be the
410 standard group and supplementary groups for
416 affect which user is chosen if the service user is specified as just
418 in this case the service user will be the real calling user.
422 .It Ev LOGNAME , USER
423 These are used to determine the name of the calling user, to be passed
426 Their values will only be used if they correspond to the calling UID.
429 .It Pa /var/run/userv/socket
431 socket used for communication between
435 .It Pa /var/run/userv/%x.%x.%x
436 Pipes used for connecting file descriptors in the client and the
442 .%T "User service daemon and client specification"
446 GNU userv is Copyright (C)1996-2000 Ian Jackson, except that this
447 manpage is Copyright (C)2000 Ben Harris.
449 GNU userv is licensed under the terms of the GNU General Public
450 Licence, version 2 or (at your option) any later version, and it comes
451 with NO WARRANTY, not even the implied warranty of MERCHANTABILITY or
452 FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
455 You should have received a copy of the GNU General Public License
456 along with userv, if not, write to the Free Software Foundation, 59
457 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
460 was initially written in 1996 by Ian Jackson. It became
463 in 1999, and version 1.0 was released in 2000.
~ian / userv.git / blob