chiark / gitweb /
Build arrangements changed some more - check in distritubed files.
[userv.git] / spec.html / ch-client.html
1 <html><head>
2 <title>User service daemon and client specification - Client program usage
3 </title>
4 <link rev=made href="mailto:ian@davenant.greenend.org.uk">
5 </head><body>
6 <h1>
7 User service daemon and client specification - chapter 2<br>
8 Client program usage
9
10 </h1>
11 <pre>userv <var>options</var> [--] <var>service-user</var> <var>service-name</var> [<var>argument</var> ...]
12 userv <var>options</var> -B|--builtin [--] <var>builtin-service</var> [<var>info-argument</var> ...]</pre><P>
13
14 <var>service-user</var> specifies which user is to provide the service.
15 The user may be a login name or a numeric uid, or <code>-</code> to indicate
16 that the service user is to be the same as the calling user.<P>
17
18 The service name is interpreted by the userv<A href="footnotes.html#1" name="fr1">[1]</A>
19 daemon on behalf of the service user.  It will often be the name of a
20 program.
21 <hr>
22 <h2><A name="s2.1">
23 2.1 Options
24 </A></h2>
25
26 Single-letter options may be combined as is usual with Unix programs,
27 and the value for such an option may appear in the same argument or in
28 the next.
29
30 <dl>
31 <dt><code>-B</code><dt><code>--builtin</code><dd>Requests that a builtin service be provided.  This is equivalent to
32 using the <kbd>--override</kbd> option to specify a string consisting of
33 <kbd>execute-builtin</kbd> followed by the <var>builtin-service</var>
34 requested, and requesting a service user of <code>-</code> (indicating the
35 calling user).<P>
36
37 If the builtin service being requested requires a
38 <var>service-argument</var> then this must be supplied to the client in the
39 same argument as the <var>builtin-service</var>.  See <A href="ch-config.html#s-dirs-execution">Directives for changing execution settings, subsection 4.2.4</A> for details of the builtin services available,
40 and <A href="#s-optoverride">Security-overriding options, section 2.2</A> for details of the <kbd>--override</kbd>
41 options.<P>
42
43 The actual service name passed will be the <var>builtin-service</var>; note
44 that this actual service name (as opposed to the override data) and
45 the <var>info-argument</var>s supplied will be ignored by most builtin
46 services; the override mechanism and <kbd>execute-builtin</kbd> will be
47 used to ensure that the right builtin service is called with the right
48 <var>service-argument</var>s.
49 <p><dt><code>-f</code><var>fd</var><code>[</code><var>modifiers</var><code>]=</code><var>filename</var><code></code><dt><code>--file </code><var>fd</var><code>[</code><var>modifiers</var><code>]=</code><var>filename</var><code></code><dd>Requests that data be copied in and out of the service using pipes.
50 For each file or descriptor this will be done by creating a pipe, one
51 end of which is passed to the service program and the other end of
52 which is passed to a copy of <kbd>cat</kbd> invoked by the client; the
53 other file descriptor passed to <kbd>cat</kbd> will be one inherited by
54 the client program from the caller or one opened by the client program
55 on behalf of the caller.<P>
56
57 The descriptor in the service program that should be connected must be
58 specified as <var>fd</var>, either as a decimal number or as one of the
59 strings <code>stdin</code>, <code>stdout</code> or <code>stderr</code>.  The next argument is
60 a filename which will be opened by the client with the privileges of
61 the calling user.
62 <P>
63 <var>modifiers</var> is used to specify whether the file or descriptor is
64 to be read from or written to.  It consists of a series of words
65 separated by commas.  A comma may separate the <var>modifiers</var> from
66 the <var>fd</var> and is required if <var>fd</var> is not numeric.
67 <P>
68 The modifier words are:
69 <dl compact>
70 <dt><code>read</code><dd><code>O_RDONLY</code>: Allow reading and not writing.  May not be used with
71 <code>write</code> or things that imply it.
72 <dt><code>write</code><dd><code>O_WRONLY</code>: Allow writing and not reading.  <em>Doesn't truncate or
73 create</em> without <code>truncate</code> or <code>create</code>.  <code>write</code> or things
74 that imply it may not be used with <code>read</code>.
75 <dt><code>overwrite</code><dd>Equivalent to <code>write,create,truncate</code>.
76 <dt><code>create</code><dt><code>creat</code><dd><code>O_CREAT</code>: Creates the file if necessary.  Implies <code>write</code>.
77 <dt><code>exclusive</code><dt><code>excl</code><dd><code>O_EXCL</code>: Fails if the file already exists.  Implies <code>write</code> and
78 <code>create</code>.  May not be used with <code>truncate</code>.
79 <dt><code>truncate</code><dt><code>trunc</code><dd><code>O_TRUNC</code>: Truncate any existing file.  Implies <code>write</code>.
80 May not be used with <code>exclusive</code>.
81 <dt><code>append</code><dd><code>O_APPEND</code>: All writes will append to the file.  Implies <code>write</code>
82 (but not <code>create</code>).
83 <dt><code>sync</code><dd><code>O_SYNC</code>: Do writes synchronously.  Implies <code>write</code>.
84 <dt><code>wait</code><dt><code>nowait</code><dt><code>close</code><dd>These modifiers control the behaviour of the client, with respect to
85 the pipes carrying data to and from the service, when the service
86 terminates.  See below.
87 <dt><code>fd</code><dd>The <var>filename</var> is not a filename but a numeric file descriptor.
88 One or both of <code>read</code> and <code>write</code> must be specified, and no
89 other words are allowed.  The <var>filename</var> may also be <code>stdin</code>,
90 <code>stdout</code> or <code>stderr</code> for file descriptor 0, 1 or 2 respectively.
91 </dl>
92 <P>
93
94 If no <var>modifiers</var> which imply <code>read</code> or <code>write</code> are used it
95 is as if <code>write</code> had been specified, except that if the
96 filedescriptor 0 of the service is being opened (either specified
97 numerically or with <code>stdin</code>) it is as if <code>overwrite</code> had been
98 specified (or <code>write</code> if only <code>fd</code> was specified).<P>
99
100 The client will also use <code>O_NOCTTY</code> when opening files specified by
101 the caller, to avoid changing its controlling terminal.<P>
102
103 By default stdin, stdout and stderr of the service will be connected
104 to the corresponding descriptors on the client.  Diagnostics from
105 the client and daemon will also appear on stderr.<P>
106
107 If <code>wait</code> is specified, the client will wait for the pipe to be
108 closed, and only exit after this has happened.  This means that either
109 the receiving end of the pipe connection was closed while data was
110 still available at the sending end, or that the end of file was
111 reached on the reading file descriptor.  Errors encountered reading or
112 writing in the client at this stage will be considered a system error
113 and cause the client to exit with status 255, but will not cause
114 disconnection at the service side since the service has already
115 exited.<P>
116
117 If <code>close</code> is specified the client will immediately close the pipe
118 connection by killing the relevant copy of <kbd>cat</kbd>.  If the service
119 uses the descriptor it will get <kbd>SIGPIPE</kbd> (or <kbd>EPIPE</kbd>) for a
120 writing descriptor or end of file for a reading one; the descriptor
121 opened by or passed to the client will also be closed.<P>
122
123 If <code>nowait</code> is specified then the client will not wait and the
124 connection will remain open after the client terminates.  Data may
125 continue to be passed between the inheritors of the relevant
126 descriptor on the service side and the corresponding file or
127 descriptor on the client side until either side closes their
128 descriptor.  This should not usually be specified for stderr (or
129 stdout if <code>--signals stdout</code> is used) since diagnostics from
130 the service side may arrive after the client has exited and be
131 confused with expected output.<P>
132
133 The default is <code>wait</code> for writing file descriptors and <code>close</code>
134 for reading ones.
135 <dt><code>-w</code><var>fd</var><code>=</code><var>action</var><code></code><dt><code>--fdwait</code><var>fd</var><code>=</code><var>action</var><code></code><dd>Sets the action on termination of the service for the specified file
136 descriptor; <var>action</var> must be <code>wait</code>, <code>nowait</code> or <code>close</code>
137 as described above.  The file descriptor must be specified as open
138 when this option is encountered; this option is overridden by any
139 later <kbd>--file</kbd> or <kbd>--fdwait</kbd> option - even by a
140 <kbd>--file</kbd> which does not specify an action on termination (in this
141 case the default will be used, as described above).
142 <dt><code>-D</code><var>name</var><code>=</code><var>value</var><code></code><dt><code>--defvar </code><var>name</var><code>=</code><var>value</var><code></code><dd>Set a user-defined variable <var>name</var> to <var>value</var>.  These
143 user-defined variables are made available in the configuration
144 language as the parameters <code>u-</code><var>name</var><code></code> and are passed to the
145 service in environment variables <code>USERV_U_</code><var>name</var><code></code>.  <var>name</var>
146 may contain only alphanumerics and underscores, and must start with a
147 letter.  If several definitions are given for the same <var>name</var> then
148 only the last is effective.
149 <dt><code>-t </code><var>seconds</var><code></code><dt><code>--timeout </code><var>seconds</var><code></code><dd>Time out the service if it takes longer than <var>seconds</var> seconds (a
150 positive integer, in decimal).  Timeout will produce a diagnostic on
151 stderr and an exit status of 255.  If <var>seconds</var> is zero then no
152 timeout will be implemented (this is the default).
153 <dt><code>-S</code> <var>method</var><dt><code>--signals</code> <var>method</var><dd>Affects the handling of the exit status when the service terminates
154 due to a signal.  (The client will always finish by calling
155 <kbd>_exit</kbd>, so that only numbers from 0 to 255 can be returned and
156 not the full range of numbers and signal indications which can be
157 returned by the <kbd>wait</kbd> family of system calls.)<P>
158
159 The <var>method</var> may be one of the following:
160 <dl compact>
161 <dt><var>status</var><dd>The client's exit status will be <var>status</var>.  This will not be
162 distinguishable from the service really having exited with code
163 <var>status</var>.  This method is the default, with a <var>status</var> of 254.
164 <dt><code>number</code><dt><code>number-nocore</code><dd>The client's exit status will be the number of the signal which caused
165 the termination of the service.  If <code>number</code> is used rather than
166 <code>number-nocore</code> then 128 will be added if the service dumped core.
167 <code>number</code> is very like the exit code mangling done by the Bourne
168 shell.
169 <dt><code>highbit</code><dd>The client's exit status will be the number of the signal with
170 128 added.  If the service exits normally with an exit code of greater
171 than 127 then 127 will be returned.
172 <dt><code>stdout</code><dd>The service's numeric wait status as two decimal numbers (high byte
173 first) and a textual description of its meaning will be printed to the
174 client's standard output.  It will be preceded by a newline and
175 followed by an extra newline, and the numbers are separated from each
176 other and from the textual description by single spaces.  The exit
177 status of the client will be zero, unless a system error occurs in
178 which case no exit status and description will be printed to stdout,
179 and an error message will be printed to stderr as usual.</dl>
180
181 <P>
182 Problems such as client usage errors, the service not being found or
183 permission being denied or failure of a system call are system errors.
184 An error message describing the problem will be printed on the
185 client's stderr, and the client's exit status will be 255.  If the
186 client dies due to a signal this should be treated as a serious system
187 error.
188 <dt><code>-H</code><dt><code>--hidecwd</code><dd>Prevents the calling process's current directory name from being
189 passed to the service; the null string will be passed instead.
190 <dt><code>-P</code><dt><code>--sigpipe</code><dd>If the service program is terminated due to a <kbd>SIGPIPE</kbd> the exit
191 status of the client will be zero, even if it would have been
192 something else according to the exit status method specified.  This
193 option has no effect on the code and description printed if the exit
194 status method <code>stdout</code> is in use.
195 <dt><code>-h</code><dt><code>--help</code><dt><code>--copyright</code><dd><code>-h</code> or <code>--help</code> prints the client's usage message;
196 <code>--copyright</code> prints the copyright and lack of warranty notice.
197 </dl>
198
199 <hr>
200 <h2><A name="s-optoverride">
201 2.2 Security-overriding options
202 </A></h2>
203
204 There are also some options which are available for debugging and to
205 allow the system administrator to override a user's policy.  These
206 options are available only if the client is called by root or if the
207 calling user is the same as the service user.
208
209 <dl>
210 <dt><code>--override </code><var>configuration-data</var><code></code><dt><code>--override-file </code><var>filename</var><code></code><dd>Do not read the usual configuration files.  Instead, the client sends
211 <var>configuration-data</var> (followed by a newline) or the contents of
212 <var>filename</var> (which is opened in the context of the client) to the
213 daemon and the daemon uses that data instead.  The
214 <var>configuration-data</var> must all be in one argument.  It will have a
215 single newline appended so that a single directive can easily be
216 given, but if more than one directive is required it will have to
217 contain one or more real newlines.
218 <p><dt><code>--spoof-user </code><var>user</var><code></code><dd>Pretend to the service that it is being called by <var>user</var> (which
219 may be a username or a uid).  This will also affect the group and
220 supplementary groups supplied to the service; they will be the
221 standard group and supplementary groups for <var>user</var>.  The
222 <code>--spoof-user</code> option will <em>not</em> affect which user is chosen if
223 the service user is specified as just <code>-</code>; in this case the service
224 user will be the real calling user.
225 <p></dl>
226
227
228 <hr>
229 User service daemon and client specification
230 - <A href="index.html#copyright"><kbd>userv</kbd> is Copyright 1996-1999 Ian Jackson.</A>
231 <br>
232 <A href="index.html#toc">Contents</A>; <A href="index.html#abstract">abstract</A>; <A href="ch-envir.html">next</A>; <A href="ch-intro.html">back</A>.
233 <br>
234 <address>0.61.1<br>
235 Ian Jackson <A href="mailto:ian@davenant.greenend.org.uk">ian@davenant.greenend.org.uk</A></address>
236 </body></html>