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