X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ian/git?p=userv.git;a=blobdiff_plain;f=spec.html%2Fch-client.html;fp=spec.html%2Fch-client.html;h=32c080bd7fd0e5a6a32b2e75b6023d806be456fd;hp=fe1b980cfe8d00ac852bb0d0a242159d519a3fa9;hb=80bd586772a9f17d9235801b4727136d94a96862;hpb=59fb8163fff0941358976353d6f98a7156e593f2 diff --git a/spec.html/ch-client.html b/spec.html/ch-client.html index fe1b980..32c080b 100644 --- a/spec.html/ch-client.html +++ b/spec.html/ch-client.html @@ -1,324 +1,407 @@ - + + + User service daemon and client specification - Client program usage +
-[back] - [Abstract] - [Copyright Notice] - [Contents] - [next] +[ previous ] +[ Contents ] +[ 1 ] +[ 2 ] +[ 3 ] +[ 4 ] +[ 5 ] +[ 6 ] +[ next ]

-User service daemon and client specification - Chapter 2
-Client program usage +User service daemon and client specification +
Chapter 2 - Client program usage

-
-

-userv options [--] service-user service-name [argument ...]
-userv options -B|--builtin [--] builtin-service [info-argument ...]
+     userv options [--] service-user service-name [argument ...]
+     userv options -B|--builtin [--] builtin-service [info-argument ...]
-

+ +
+

-service-user specifies which user is to provide the service. -The user may be a login name or a numeric uid, or - to indicate -that the service user is to be the same as the calling user. -

+service-user specifies which user is to provide the service. The +user may be a login name or a numeric uid, or - to indicate that +the service user is to be the same as the calling user.

-The service name is interpreted by the userv[1] -daemon on behalf of the service user. It will often be the name of a -program. -

+The service name is interpreted by the userv[1] daemon on behalf of the service user. It will often be the +name of a program.
-

-2.1 Options -

+ +

2.1 Options

-Single-letter options may be combined as is usual with Unix programs, -and the value for such an option may appear in the same argument or in -the next. - +Single-letter options may be combined as is usual with Unix programs, and the +value for such an option may appear in the same argument or in the next.

-

-B

--builtin
Requests that a builtin service be provided. This is equivalent to -using the --override option to specify a string consisting of +
-B
+
--builtin
+
+Requests that a builtin service be provided. This is equivalent to using the +--override option to specify a string consisting of execute-builtin followed by the builtin-service requested, and requesting a service user of - (indicating the calling user). -If the builtin service being requested requires a -service-argument then this must be supplied to the client in the -same argument as the builtin-service. See Directives for changing execution settings, subsection 4.2.4 for details of the builtin services available, -and Security-overriding options, section 2.2 for details of the --override -options. +

+If the builtin service being requested requires a service-argument +then this must be supplied to the client in the same argument as the +builtin-service. See Directives for changing execution +settings, Section 4.2.4 for details of the builtin services available, and +Security-overriding options, Section +2.2 for details of the --override options. +

The actual service name passed will be the builtin-service; note -that this actual service name (as opposed to the override data) and -the info-arguments supplied will be ignored by most builtin -services; the override mechanism and execute-builtin will be -used to ensure that the right builtin service is called with the right +that this actual service name (as opposed to the override data) and the +info-arguments supplied will be ignored by most builtin services; +the override mechanism and execute-builtin will be used to ensure +that the right builtin service is called with the right service-arguments. +

+
+
+
--file fd[modifiers]=filename
+
+Requests that data be copied in and out of the service using pipes. For each +file or descriptor this will be done by creating a pipe, one end of which is +passed to the service program and the other end of which is passed to a copy of +cat invoked by the client; the other file descriptor passed to +cat will be one inherited by the client program from the caller or +one opened by the client program on behalf of the caller. -

-ffd[modifiers]=filename

--file fd[modifiers]=filename
Requests that data be copied in and out of the service using pipes. -For each file or descriptor this will be done by creating a pipe, one -end of which is passed to the service program and the other end of -which is passed to a copy of cat invoked by the client; the -other file descriptor passed to cat will be one inherited by -the client program from the caller or one opened by the client program -on behalf of the caller. - +

The descriptor in the service program that should be connected must be -specified as fd, either as a decimal number or as one of the -strings stdin, stdout or stderr. The next argument is -a filename which will be opened by the client with the privileges of -the calling user. +specified as fd, either as a decimal number or as one of the strings +stdin, stdout or stderr. The next +argument is a filename which will be opened by the client with the privileges +of the calling user. -modifiers is used to specify whether the file or descriptor is -to be read from or written to. It consists of a series of words -separated by commas. A comma may separate the modifiers from -the fd and is required if fd is not numeric. +

+modifiers is used to specify whether the file or descriptor is to be +read from or written to. It consists of a series of words separated by commas. +A comma may separate the modifiers from the fd and is +required if fd is not numeric.

The modifier words are: -

-
read
O_RDONLY: Allow reading and not writing. May not be used with +
+
read
+
+O_RDONLY: Allow reading and not writing. May not be used with write or things that imply it. - -
write
O_WRONLY: Allow writing and not reading. Doesn't truncate or -create without truncate or create. write or things -that imply it may not be used with read. - -
overwrite
Equivalent to write,create,truncate. - -
create
creat
O_CREAT: Creates the file if necessary. Implies write. - -
exclusive
excl
O_EXCL: Fails if the file already exists. Implies write and -create. May not be used with truncate. - -
truncate
trunc
O_TRUNC: Truncate any existing file. Implies write. +
+
write
+
+O_WRONLY: Allow writing and not reading. Doesn't truncate or +create without truncate or create. +write or things that imply it may not be used with +read. +
+
overwrite
+
+Equivalent to write,create,truncate. +
+
create
+
creat
+
+O_CREAT: Creates the file if necessary. Implies +write. +
+
exclusive
+
excl
+
+O_EXCL: Fails if the file already exists. Implies +write and create. May not be used with +truncate. +
+
truncate
+
trunc
+
+O_TRUNC: Truncate any existing file. Implies write. May not be used with exclusive. - -
append
O_APPEND: All writes will append to the file. Implies write -(but not create). - -
sync
O_SYNC: Do writes synchronously. Implies write. - -
wait
nowait
close
These modifiers control the behaviour of the client, with respect to -the pipes carrying data to and from the service, when the service -terminates. See below. - -
fd
The filename is not a filename but a numeric file descriptor. -One or both of read and write must be specified, and no -other words are allowed. The filename may also be stdin, -stdout or stderr for file descriptor 0, 1 or 2 respectively. - +
+
append
+
+O_APPEND: All writes will append to the file. Implies +write (but not create). +
+
sync
+
+O_SYNC: Do writes synchronously. Implies write. +
+
wait
+
nowait
+
close
+
+These modifiers control the behaviour of the client, with respect to the pipes +carrying data to and from the service, when the service terminates. See below. +
+
fd
+
+The filename is not a filename but a numeric file descriptor. One +or both of read and write must be specified, and no +other words are allowed. The filename may also be +stdin, stdout or stderr for file +descriptor 0, 1 or 2 respectively. +
-

-If no modifiers which imply read or write are used it -is as if write had been specified, except that if the -filedescriptor 0 of the service is being opened (either specified -numerically or with stdin) it is as if overwrite had been +If no modifiers which imply read or write +are used it is as if write had been specified, except that if the +filedescriptor 0 of the service is being opened (either specified numerically +or with stdin) it is as if overwrite had been specified (or write if only fd was specified). -

The client will also use O_NOCTTY when opening files specified by the caller, to avoid changing its controlling terminal. -

-By default stdin, stdout and stderr of the service will be connected -to the corresponding descriptors on the client. Diagnostics from -the client and daemon will also appear on stderr. -

+By default stdin, stdout and stderr of the service will be connected to the +corresponding descriptors on the client. Diagnostics from the client and +daemon will also appear on stderr.

If wait is specified, the client will wait for the pipe to be -closed, and only exit after this has happened. This means that either -the receiving end of the pipe connection was closed while data was -still available at the sending end, or that the end of file was -reached on the reading file descriptor. Errors encountered reading or -writing in the client at this stage will be considered a system error -and cause the client to exit with status 255, but will not cause -disconnection at the service side since the service has already -exited. -

+closed, and only exit after this has happened. This means that either the +receiving end of the pipe connection was closed while data was still available +at the sending end, or that the end of file was reached on the reading file +descriptor. Errors encountered reading or writing in the client at this stage +will be considered a system error and cause the client to exit with status 255, +but will not cause disconnection at the service side since the service has +already exited.

If close is specified the client will immediately close the pipe connection by killing the relevant copy of cat. If the service -uses the descriptor it will get SIGPIPE (or EPIPE) for a -writing descriptor or end of file for a reading one; the descriptor +uses the descriptor it will get SIGPIPE (or EPIPE) +for a writing descriptor or end of file for a reading one; the descriptor opened by or passed to the client will also be closed. -

If nowait is specified then the client will not wait and the -connection will remain open after the client terminates. Data may -continue to be passed between the inheritors of the relevant -descriptor on the service side and the corresponding file or -descriptor on the client side until either side closes their -descriptor. This should not usually be specified for stderr (or -stdout if --signals stdout is used) since diagnostics from -the service side may arrive after the client has exited and be -confused with expected output. -

+connection will remain open after the client terminates. Data may continue to +be passed between the inheritors of the relevant descriptor on the service side +and the corresponding file or descriptor on the client side until either side +closes their descriptor. This should not usually be specified for stderr (or +stdout if --signals stdout is used) since diagnostics from the +service side may arrive after the client has exited and be confused with +expected output.

-The default is wait for writing file descriptors and close -for reading ones. -

- -
-wfd=action
--fdwaitfd=action
Sets the action on termination of the service for the specified file -descriptor; action must be wait, nowait or close -as described above. The file descriptor must be specified as open -when this option is encountered; this option is overridden by any -later --file or --fdwait option - even by a +The default is wait for writing file descriptors and +close for reading ones. +
+
+
+
-wfd=action
+
--fdwaitfd=action
+
+Sets the action on termination of the service for the specified file +descriptor; action must be wait, nowait or +close as described above. The file descriptor must be specified +as open when this option is encountered; this option is overridden by any later +--file or --fdwait option - even by a --file which does not specify an action on termination (in this case the default will be used, as described above). - -
-Dname=value
--defvar name=value
Set a user-defined variable name to value. These -user-defined variables are made available in the configuration -language as the parameters u-name and are passed to the -service in environment variables USERV_U_name. name -may contain only alphanumerics and underscores, and must start with a -letter. If several definitions are given for the same name then -only the last is effective. - -
-t seconds
--timeout seconds
Time out the service if it takes longer than seconds seconds (a -positive integer, in decimal). Timeout will produce a diagnostic on -stderr and an exit status of 255. If seconds is zero then no -timeout will be implemented (this is the default). - -
-S method
--signals method
Affects the handling of the exit status when the service terminates -due to a signal. (The client will always finish by calling -_exit, so that only numbers from 0 to 255 can be returned and -not the full range of numbers and signal indications which can be -returned by the wait family of system calls.) +
+
+
+
-Dname=value
+
--defvar name=value
+
+Set a user-defined variable name to value. These +user-defined variables are made available in the configuration language as the +parameters u-name and are passed to the service in +environment variables USERV_U_name. name +may contain only alphanumerics and underscores, and must start with a letter. +If several definitions are given for the same name then only the +last is effective. +
+
+
+
-t seconds
+
--timeout seconds
+
+Time out the service if it takes longer than seconds seconds (a +positive integer, in decimal). Timeout will produce a diagnostic on stderr and +an exit status of 255. If seconds is zero then no timeout will be +implemented (this is the default). +
+
+
+
--signals method
+
+Affects the handling of the exit status when the service terminates due to a +signal. (The client will always finish by calling _exit, so that +only numbers from 0 to 255 can be returned and not the full range of numbers +and signal indications which can be returned by the wait family of +system calls.)

The method may be one of the following: -

-
status
The client's exit status will be status. This will not be +
+
status
+
+The client's exit status will be status. This will not be distinguishable from the service really having exited with code -status. This method is the default, with a status of 254. - -
number
number-nocore
The client's exit status will be the number of the signal which caused -the termination of the service. If number is used rather than +status. This method is the default, with a status of +254. +
+
number
+
number-nocore
+
+The client's exit status will be the number of the signal which caused the +termination of the service. If number is used rather than number-nocore then 128 will be added if the service dumped core. number is very like the exit code mangling done by the Bourne shell. - -
highbit
The client's exit status will be the number of the signal with -128 added. If the service exits normally with an exit code of greater -than 127 then 127 will be returned. - -
stdout
The service's numeric wait status as two decimal numbers (high byte -first) and a textual description of its meaning will be printed to the -client's standard output. It will be preceded by a newline and -followed by an extra newline, and the numbers are separated from each -other and from the textual description by single spaces. The exit -status of the client will be zero, unless a system error occurs in -which case no exit status and description will be printed to stdout, -and an error message will be printed to stderr as usual. - +
+
highbit
+
+The client's exit status will be the number of the signal with 128 added. If +the service exits normally with an exit code of greater than 127 then 127 will +be returned. +
+
stdout
+
+The service's numeric wait status as two decimal numbers (high byte first) and +a textual description of its meaning will be printed to the client's standard +output. It will be preceded by a newline and followed by an extra newline, and +the numbers are separated from each other and from the textual description by +single spaces. The exit status of the client will be zero, unless a system +error occurs in which case no exit status and description will be printed to +stdout, and an error message will be printed to stderr as usual. +
-

-Problems such as client usage errors, the service not being found or -permission being denied or failure of a system call are system errors. -An error message describing the problem will be printed on the -client's stderr, and the client's exit status will be 255. If the -client dies due to a signal this should be treated as a serious system -error. -

- -
-H
--hidecwd
Prevents the calling process's current directory name from being -passed to the service; the null string will be passed instead. - -
-P
--sigpipe
If the service program is terminated due to a SIGPIPE the exit -status of the client will be zero, even if it would have been -something else according to the exit status method specified. This -option has no effect on the code and description printed if the exit -status method stdout is in use. - -
-h
--help
--copyright
-h or --help prints the client's usage message; +Problems such as client usage errors, the service not being found or permission +being denied or failure of a system call are system errors. An error message +describing the problem will be printed on the client's stderr, and the client's +exit status will be 255. If the client dies due to a signal this should be +treated as a serious system error. +
+
+
+
-H
+
--hidecwd
+
+Prevents the calling process's current directory name from being passed to the +service; the null string will be passed instead. +
+
+
+
-P
+
--sigpipe
+
+If the service program is terminated due to a SIGPIPE the exit +status of the client will be zero, even if it would have been something else +according to the exit status method specified. This option has no effect on +the code and description printed if the exit status method stdout +is in use. +
+
+
+
-h
+
--help
+
--copyright
+
+-h or --help prints the client's usage message; --copyright prints the copyright and lack of warranty notice. - +
-

-

-2.2 Security-overriding options -

+ +

2.2 Security-overriding options

-There are also some options which are available for debugging and to -allow the system administrator to override a user's policy. These -options are available only if the client is called by root or if the -calling user is the same as the service user. - +There are also some options which are available for debugging and to allow the +system administrator to override a user's policy. These options are available +only if the client is called by root or if the calling user is the same as the +service user.

-

--override configuration-data

--override-file filename
Do not read the usual configuration files. Instead, the client sends +
--override configuration-data
+
--override-file filename
+
+Do not read the usual configuration files. Instead, the client sends configuration-data (followed by a newline) or the contents of filename (which is opened in the context of the client) to the daemon and the daemon uses that data instead. The configuration-data must all be in one argument. It will have a -single newline appended so that a single directive can easily be -given, but if more than one directive is required it will have to -contain one or more real newlines. - -

--spoof-user user
Pretend to the service that it is being called by user (which -may be a username or a uid). This will also affect the group and -supplementary groups supplied to the service; they will be the -standard group and supplementary groups for user. The ---spoof-user option will not affect which user is chosen if -the service user is specified as just -; in this case the service -user will be the real calling user. - +single newline appended so that a single directive can easily be given, but if +more than one directive is required it will have to contain one or more real +newlines. +
+
+
+
--spoof-user user
+
+Pretend to the service that it is being called by user (which may be +a username or a uid). This will also affect the group and supplementary groups +supplied to the service; they will be the standard group and supplementary +groups for user. The --spoof-user option will +not affect which user is chosen if the service user is specified as +just -; in this case the service user will be the real calling +user. +
-

-[back] - [Abstract] - [Copyright Notice] - [Contents] - [next] +[ previous ] +[ Contents ] +[ 1 ] +[ 2 ] +[ 3 ] +[ 4 ] +[ 5 ] +[ 6 ] +[ next ]
-User service daemon and client specification
+

+User service daemon and client specification

-1.0.1
-Ian Jackson ian@davenant.greenend.org.uk +1.0.3
+Ian Jackson ian@davenant.greenend.org.uk
+
+