File: spec.sgml.in

package info (click to toggle)
userv 1.2.0
  • links: PTS
  • area: main
  • in suites: bullseye, buster, sid, stretch
  • size: 700 kB
  • ctags: 1,013
  • sloc: ansic: 4,220; lex: 287; sh: 207; makefile: 206
file content (1434 lines) | stat: -rw-r--r-- 54,785 bytes parent folder | download
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
<!doctype debiandoc system>

<book>
<title>User service daemon and client specification
<author>Ian Jackson <email>ian@davenant.greenend.org.uk
<version></version>

<abstract>
This is a specification for a Unix system facility to allow one
program to invoke another when only limited trust exists
between them.

<copyright>
<prgn/userv/ is
Copyright 1996-2017 Ian Jackson;
Copyright 2000 Ben Harris;
Copyright 2016-2017 Peter Benie.
<p>

<prgn/userv/ is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 3 of the License, or (at
your option) any later version.
<p>

This program is distributed in the hope that it will be useful, but
<em/without any warranty/; without even the implied warranty of
<em/merchantability/ or <em/fitness for a particular purpose/.  See
the GNU General Public License for more details.
<p>

You should have received a copy of the GNU General Public License
along with <prgn/userv/; if not, see
<tt>http://www.gnu.org/licenses/</tt>.

<toc sect>

<chapt id="intro">Introduction
<p>
There is a daemon which invokes user service programs (henceforth
`services') in response to requests by callers of a companion client
program (henceforth the `client') and according to rules set forth in
system-wide and user-specific configuration files.  The companion
client program is setuid root, and negotiates with the daemon through
an <prgn/AF_UNIX/ socket and associated objects in a system-wide
private directory set aside for the purpose.  The user who wishes the
service to be performed and calls the client is called the `calling
user'; the process which calls the client is called the `calling
process'.

<p>
The daemon and the client are responsible for ensuring that
information is safely carried across the security boundary between the
two users, and that the processes on either side cannot interact with
each other in any unexpected ways.

<chapt id="client">Client program usage

<p>
<example>
userv <var/options/ [--] <var/service-user/ <var/service-name/ [<var/argument/ ...]
userv <var/options/ -B|--builtin [--] <var/builtin-service/ [<var/info-argument/ ...]
</example>
<p>

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

The service name is interpreted by the userv<footnote><prgn/userv/ is
short for `user services', and is pronounced `you-serve'.</footnote>
daemon on behalf of the service user.  It will often be the name of a
program.

<sect>Options
<p>

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.

<taglist>
<tag/<tt/-B//
<tag/<tt/--builtin//
<item>
Requests that a builtin service be provided.  This is equivalent to
using the <prgn/--override/ option to specify a string consisting of
<prgn/execute-builtin/ followed by the <var/builtin-service/
requested, and requesting a service user of <tt/-/ (indicating the
calling user).
<p>

If the builtin service being requested requires a
<var/service-argument/ then this must be supplied to the client in the
same argument as the <var/builtin-service/.  See <ref
id="dirs-execution"> for details of the builtin services available,
and <ref id="optoverride"> for details of the <prgn/--override/
options.
<p>

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

<tag/<tt/-f<var/fd/[<var/modifiers/]=<var/filename///
<tag/<tt/--file <var/fd/[<var/modifiers/]=<var/filename///
<item>
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 <prgn/cat/ invoked by the client; the
other file descriptor passed to <prgn/cat/ will be one inherited by
the client program from the caller or one opened by the client program
on behalf of the caller.
<p>

The descriptor in the service program that should be connected must be
specified as <var/fd/, either as a decimal number or as one of the
strings <tt/stdin/, <tt/stdout/ or <tt/stderr/.  The next argument is
a filename which will be opened by the client with the privileges of
the calling user.

<p>
<var/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 <var/modifiers/ from
the <var/fd/ and is required if <var/fd/ is not numeric.

<p>
The modifier words are:
<taglist compact>
<tag/<tt/read//
<item>
<tt/O_RDONLY/: Allow reading and not writing.  May not be used with
<tt/write/ or things that imply it.

<tag/<tt/write//
<item>
<tt/O_WRONLY/: Allow writing and not reading.  <em/Doesn't truncate or
create/ without <tt/truncate/ or <tt/create/.  <tt/write/ or things
that imply it may not be used with <tt/read/.

<tag/<tt/overwrite//
<item>
Equivalent to <tt/write,create,truncate/.

<tag/<tt/create//
<tag/<tt/creat//
<item>
<tt/O_CREAT/: Creates the file if necessary.  Implies <tt/write/.

<tag/<tt/exclusive//
<tag/<tt/excl//
<item>
<tt/O_EXCL/: Fails if the file already exists.  Implies <tt/write/ and
<tt/create/.  May not be used with <tt/truncate/.

<tag/<tt/truncate//
<tag/<tt/trunc//
<item>
<tt/O_TRUNC/: Truncate any existing file.  Implies <tt/write/.
May not be used with <tt/exclusive/.

<tag/<tt/append//
<item>
<tt/O_APPEND/: All writes will append to the file.  Implies <tt/write/
(but not <tt/create/).

<tag/<tt/sync//
<item>
<tt/O_SYNC/: Do writes synchronously.  Implies <tt/write/.

<tag/<tt/wait//
<tag/<tt/nowait//
<tag/<tt/close//
<item>

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.

<tag/<tt/fd//
<item>
The <var/filename/ is not a filename but a numeric file descriptor.
One or both of <tt/read/ and <tt/write/ must be specified, and no
other words are allowed.  The <var/filename/ may also be <tt/stdin/,
<tt/stdout/ or <tt/stderr/ for file descriptor 0, 1 or 2 respectively.

</taglist>
<p>

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

The client will also use <tt/O_NOCTTY/ when opening files specified by
the caller, to avoid changing its controlling terminal.
<p>

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.
<p>

If <tt/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.
<p>

If <tt/close/ is specified the client will immediately close the pipe
connection by killing the relevant copy of <prgn/cat/.  If the service
uses the descriptor it will get <prgn/SIGPIPE/ (or <prgn/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.
<p>

If <tt/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 <tt/--signals stdout/ is used) since diagnostics from
the service side may arrive after the client has exited and be
confused with expected output.
<p>

The default is <tt/wait/ for writing file descriptors and <tt/close/
for reading ones.

<tag/<tt/-w<var/fd/=<var/action///
<tag/<tt/--fdwait<var/fd/=<var/action///
<item>
Sets the action on termination of the service for the specified file
descriptor; <var/action/ must be <tt/wait/, <tt/nowait/ or <tt/close/
as described above.  The file descriptor must be specified as open
when this option is encountered; this option is overridden by any
later <prgn/--file/ or <prgn/--fdwait/ option - even by a
<prgn/--file/ which does not specify an action on termination (in this
case the default will be used, as described above).

<tag/<tt/-D<var/name/=<var/value///
<tag/<tt/--defvar <var/name/=<var/value///
<item>
Set a user-defined variable <var/name/ to <var/value/.  These
user-defined variables are made available in the configuration
language as the parameters <tt/u-<var/name// and are passed to the
service in environment variables <tt/USERV_U_<var/name//.  <var/name/
may contain only alphanumerics and underscores, and must start with a
letter.  If several definitions are given for the same <var/name/ then
only the last is effective.

<tag/<tt/-t <var/seconds///
<tag/<tt/--timeout <var/seconds///
<item>
Time out the service if it takes longer than <var/seconds/ seconds (a
positive integer, in decimal).  Timeout will produce a diagnostic on
stderr and an exit status of 255.  If <var/seconds/ is zero then no
timeout will be implemented (this is the default).

<tag/<tt/-S/ <var/method//
<tag/<tt/--signals/ <var/method//
<item>
Affects the handling of the exit status when the service terminates
due to a signal.  (The client will always finish by calling
<prgn/_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 <prgn/wait/ family of system calls.)
<p>

The <var/method/ may be one of the following:
<taglist compact>
<tag/<var/status/
<item>
The client's exit status will be <var/status/.  This will not be
distinguishable from the service really having exited with code
<var/status/.  This method is the default, with a <var/status/ of 254.

<tag/<tt/number//
<tag/<tt/number-nocore//
<item>
The client's exit status will be the number of the signal which caused
the termination of the service.  If <tt/number/ is used rather than
<tt/number-nocore/ then 128 will be added if the service dumped core.
<tt/number/ is very like the exit code mangling done by the Bourne
shell.

<tag/<tt/highbit//
<item>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.

<tag/<tt/stdout//
<item>
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.
</taglist>

<p>
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.

<tag/<tt/-H//
<tag/<tt/--hidecwd//
<item>
Prevents the calling process's current directory name from being
passed to the service; the null string will be passed instead.

<tag/<tt/-P//
<tag/<tt/--sigpipe//
<item>
If the service program is terminated due to a <prgn/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 <tt/stdout/ is in use.

<tag/<tt/-h//
<tag/<tt/--help//
<tag/<tt/--copyright//
<item>
<tt/-h/ or <tt/--help/ prints the client's usage message;
<tt/--copyright/ prints the copyright and lack of warranty notice.

</taglist>

<sect id="optoverride">Security-overriding options
<p>

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.

<taglist>

<tag/<tt/--override <var/configuration-data///
<tag/<tt/--override-file <var/filename///
<item>
Do not read the usual configuration files.  Instead, the client sends
<var/configuration-data/ (followed by a newline) or the contents of
<var/filename/ (which is opened in the context of the client) to the
daemon and the daemon uses that data instead.  The
<var/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.

<tag/<tt/--spoof-user <var/user///
<item>
Pretend to the service that it is being called by <var/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 <var/user/.  The
<tt/--spoof-user/ option will <em/not/ affect which user is chosen if
the service user is specified as just <tt/-/; in this case the service
user will be the real calling user.

</taglist>


<chapt id="envir">Execution environment of the service program
<p>

The daemon which is handling the service user side of things will read
configuration files to decide what to do.  If it decides to allow the
service to be provided it will fork a subprocess to execute the
service.
<p>

The service will have no controlling terminal, but it will be a
process group leader.
<p>

If the client is killed or times out or a file or descriptor being
read or written by the client process gets an error then the service
will be disconnected from the client.  The client will return an exit
status of 255 and some the service's pipes may be closed at the other
end.  The service will become a child of <prgn/init/.  The service may
well not notice the disconnection, though writing to a pipe after this
may produce a <prgn/SIGPIPE/ and the facility exists to have a
<prgn/SIGHUP/ sent to the service on disconnection.

<sect>File descriptors
<p>

The service program's standard filedescriptors, and possibly other
file descriptors, will be connected to pipes or to
<prgn>/dev/null</>.  The <prgn/userv/ client/daemon pair will arrange
that data is copied between the files or file descriptors specified to
to the client by the caller and these these pipes.
<p>

Pipes which may be written to will be closed if a write error occurs
on the corresponding client-side file or descriptor, which may result
in a <prgn/SIGPIPE/ in the service program; pipes open for reading
will get <prgn/EOF/ if the client-side file descriptor gets <prgn/EOF/
or an error.
<p>

If the service closes one of its reading file descriptors the writing
end of the corresponding pipe will generate a <prgn/SIGPIPE/ when
attempts are made by the client/daemon pair to write to it.  This will
not be considered an error; rather, the relevant pipe will be
discarded and the corresponding file or file descriptor held by the
client will be closed.
<p>

Likewise, if one of the file descriptors held by the client for
writing by the service is a pipe whose other end is closed by the
caller then the client/daemon pair will see an error when trying to
copy data provided by the service.  This too will not be considered an
error; rather, the pipe correspondong to that descriptor will be
closed and any further writes will cause the service to get a
<prgn/SIGPIPE/.
<p>

Note that not all write errors or broken pipes on file descriptors may
be visible to the service, since buffered data may be discarded by the
operating system and there will be a finite interval between the error
happening and the service being disconnected from the client or the
next write causing a <prgn/SIGPIPE/.
<p>

Read errors on file descriptors (and disconnection) will only be
visible to the service and distinguishable from normal end of file if
<prgn/disconnect-hup/ is in effect.
<p>

Read and write errors (other than broken pipes, as described above)
will always be visible to the caller; they are system errors, and will
therefore cause the client to print an error message to stderr and
return with an exit status of 255.
<p>

If the main service program process exits while it still has running
children any file descriptors held by those children can remain open,
depending on the use of <tt/wait/, <tt/nowait/ or <tt/close/ for the
relevant file descriptor in the client's arguments.  By default
writing filedescriptors remain open and the client will wait for them
to be closed at the service end, and reading file descriptors are
closed immediately.  These leftover child processes will not get a any
<prgn/SIGHUP/ even if a read or write error occurs or the client
disconnects before then.

<sect>Environment
<p>

The service will have some information in environment variables:
<taglist compact>
<tag/<tt/USERV_USER//
<item>
The login name of the calling user.  If the <prgn/LOGNAME/ variable is
set (or, if that is unset, if the <prgn/USER/ variable is set) in the
environment passed to the client by the caller then the password entry
for that login name will be looked up; if that password entry's uid is
the same as that of the calling process then that login name will be
used, otherwise (or if neither <prgn/LOGNAME/ nor <prgn/USER/ is set)
the calling process's uid will be looked up to determine their login
name (and if this lookup fails then the service will not be invoked).

<tag/<tt/USERV_UID//
<item>
The uid of the calling process.

<tag/<tt/USERV_GID//
<item>
The gid and supplementary group list of the calling process: first the
group in gid and then those in the supplementary group list, in
decimal, separated by spaces.

<tag/<tt/USERV_GROUP//
<item>
The group names of the calling process, listed in the same way as the
ids are in <prgn/USERV_GID/.  If no name can be found for any of the
calling process's group(s) then the service will not be invoked.

<tag/<tt/USERV_CWD//
<item>
The client's current working directory name (this directory may not be
accessible to the service).  If it could not be determined or the
<prgn/--hidecwd/ flag was used then this variable will be set to an
empty string (this is not considered an error).

<tag/<tt/USERV_SERVICE//
<item>
The service name requested by the caller.

<tag/<tt/USERV_U_<var/name///
<item>
The value supplied to the client by the caller using -D<var/name/.

</taglist>

<prgn/HOME/, <prgn/PATH/, <prgn/SHELL/, <prgn/LOGNAME/ and <prgn/USER/
will be set appropriately (according to the details of the service
user).


<chapt id="config">Service-side configuration
<p>

Which services may be run by whom and under what conditions is
controlled by configuration files.
<p>

The daemon will read these files in order.  Certain directives in the
files modify the daemon's execution settings for invoking the service,
for example allowing certain file descriptors to be specified by the
client or specifying which program to execute to provide the service.
<p>

The <em/last/ instance of each such setting will take effect.  The
directives which specify which program to execute will not stop the
configuration file from being read; they will be remembered and will
only take effect if they are not overridden by a later directive.
<p>

The daemon will first read <tt>/etc/userv/system.default</>.  Then, by
default (this behaviour may be modified), it will read a per-user file
<tt>~/.userv/rc</>, if it exists and the service user's shell is in
<tt>/etc/shells</>.  Finally it will read
<tt>/etc/userv/system.override</>.
<p>

When it has read all of these files it will act according to the
currently values of of the execution settings.

<sect>Configuration file syntax
<p>

The configuration file is a series of directives, usually one per
line.  The portion of a line following a hash character <tt/#/ is
taken as a comment and ignored.  Each directive consists of a series
of tokens separated by linear whitespace (spaces and tabs); tokens may
be words consisting of non-space characters, or, where a string is
required, a string in double quotes.  Double-quoted strings may
contain the following backslash escapes:

<taglist compact>
<tag/<tt/\n//<item>newline
<tag/<tt/\t//<item>tab
<tag/<tt/\r//<item>carriage return
<tag/<tt/\<var/OOO///<item>character whose octal code is <var/OOO/
<tag/<tt/\x<var/XX///<item>character whose hex code is <var/XX/
<tag/<tt/\<var/punctuation///<item>literal punctuation character (eg <tt/\\/, <tt/\"/)
<tag/<tt/\<var/newline// (ie, backslash at end of line)/
<item>string continues on next line
</taglist>
<p>

Relative pathnames in directives are relative to the service program's
current directory (usually the service user's home directory).
Pathnames starting with the two characters <tt>~/</> are taken to be
relative to the service user's home directory.

<sect id="directives">Configuration file directives
<p>

<sect1 id="dirs-immediate">Immediate directives
<p>

The following directives take effect immediately:

<taglist>
<tag/<tt/cd <var/pathname///
<item>
Change directory in the service program.  <prgn/cd/ is cumulative.  It
is an error if the directory cannot be changed to.
<p>

<prgn/cd/ should not be used between <prgn/execute-from-directory/ and
the invocation of the service program, as the test for the
availability of the service program would be done with the old current
directory and the actual execution with the new (probably causing an
error).

<tag/<tt/eof//
<item>
Stop reading the configuration file in question, as if end of file had
been reached.  Any control constructs (<prgn/if/, <prgn/catch-quit/ or
<prgn/errors-push/) which were started in that file will be considered
finished.  Parsing will continue in the file which caused the file
containing the <prgn/eof/ to be read.

<tag/<tt/quit//
<item>
Stop reading configuration files and act immediately on the current
settings.  The behaviour of <prgn/quit/ is subject to the
<prgn/catch-quit/ control construct.

<tag/<tt/include <var/filename///
<tag/<tt/include-ifexist <var/filename///
<item>
Read the configuration file <var/filename/, and then return to this
file and continue parsing it with the next directive.  It is an error
if the file cannot be opened and read, unless <prgn/include-ifexist/
is used and the file does not exist, in which case the directive is
silently ignored.

<tag/<tt/include-lookup <var/parameter/ <var/directory///
<tag/<tt/include-lookup-all <var/parameter/ <var/directory///
<item>
Read the configuration file in <var/directory/ whose name is the value
of <var/parameter/ (see the description of <prgn/if/, <ref
id="dirs-control">).  If <var/parameter/ has several values they will
be tried in order; with <prgn/include-lookup/ this search will stop
when one is found, but with <prgn/include-lookup-all/ the search will
continue and any files appropriate to other values will be read too.
<p>

If none of the parameter's values had a corresponding file then the
file <tt/:default/ will be read, if it exists.  If <var/parameter/'s
list of values was empty then the file <tt/:none/ will be tried first
and read if it exists, otherwise <tt/:default/ will be tried.
<p>

It is not an error for any of the files (including <tt/:default/) not
to exist, but it is an error if a file exists and cannot be read or if
the directory cannot be accessed.

<p>
A translation will be applied to values before they are used to
construct a filename, so that the lookup cannot access dotfiles or
files in other directories: values starting with full stops will have
a colon prepended (making <tt/:./), colons will be doubled, and each
slash will be replaced with a colon followed by a hyphen <tt>:-</>.  A
parameter value which is the empty string will be replaced with
<tt/:empty/ (note that this is different from a parameter not having
any values).

<p>
(In older versions of userv, a different translation was applied:
See <tt>https://bugs.debian.org/837391</tt>.  The old translation
can be requested (for subsequent directives) with
<tt/include-lookup-quote-old/, which is undone by
<tt/include-lookup-quote-new/ and <tt/reset/.)

<tag/<tt/include-directory <var/directory///
<item>
Read configuration from all files in directory <var/directory/ which
are plain files whose names consist only of alphanumerics and hyphens
and start with an alphanumeric.  They will be read in lexical order.
It is an error for the directory not to exist or for it or any of the
files found not to be read successfully, or for anything with an
appropriate name not to be a plain file or a symbolic link to a plain
file.

<tag/<tt/error <var/text ...///
<item>
Causes an error whose message includes the descriptive string
<var/text/.  <var/text/ may consist of several tokens with intervening
whitespace.  The whitespace will be included in the message as found
in the configuration file: all the characters until the end of the
line will be included verbatim, unless they are part of a
double-quoted string, in which case the usual meaning of the string
(i.e., after backslash escape processing) will be used.  Comments and
linear whitespace at the end of the line (or just before the comment)
will still be ignored.

<tag/<tt/message <var/text ...///
<item>
Causes a message including the descriptive string <var/text/ to be
delivered as if it were an error message, but does not actually cause
an error.
</taglist>

<sect1 id="dirs-delayed">Directives with delayed effect
<p>

The following directives have no immediate effect, but are remembered
and have an effect on later processing of the configuration files.

<taglist>
<tag/<tt/user-rcfile <var/filename///
<item>
Specifies that the file <var/filename/ should be read instead of the
user's <tt>~/.userv/rc</>.  This does <em/not/ happen immediately;
instead, the setting is remembered and used after the
<prgn/system.default/ configuration file has been read.  This
directive has no effect in a user's configuration file or in the
<prgn/system.override/ file, as the user's configuration file has
already been found and read by then and will not be re-read.

<tag/<tt/errors-to-stderr//
<item>
Causes error messages to be delivered to the client's stderr.

<tag/<tt/errors-to-file/ <var/filename//
<item>
Error messages will be written to <var/filename/, which will be opened
in the context of and with the privileges of the service user.

<tag/<tt/errors-to-syslog/ [<var/facility/ [<var/level/]]/
<item>
Error messages will be delivered using <prgn/syslog/.  The default
<var/facility/ is <tt/user/; the default <var/level/ is <tt/error/.
</taglist>

<sect1 id="dirs-control">Control structure directives
<p>

The following directives are used to create control structures.  If
the end of the file is encountered before the end of any control
structure which was started inside it then that control structure is
considered finished.  This is not an error.

<taglist>
<tag/<tt/if <var/condition///
<tag/<tt/elif <var/condition///
<tag/<tt/else//
<tag/<tt/fi//
<item>
Lines following <prgn/if/ are interpreted only if the condition is
true.  Many conditions are properties of parameter values.  Most
parameters have a single string as a value; however, some may yield
zero or several strings, in which case the condition is true if it is
true of any of the strings individually.  Parameters are described
below.
<p>

The conditions are:

<taglist compact>
<tag/<tt/glob <var/parameter/ <var/glob-pattern/ ...//
<item>
The value of the parameter whose name is given matches one of the glob
patterns (anchored at both ends; backslashes can be used to escape
metacharacters).

<tag/<tt/range <var/parameter/ <var/min/ <var/max///
<item>
The value of the parameter is a nonnegative integer and lies within
the range specified.  <var/min/ or <var/max/ may be <tt/$/ to indicate
no lower or upper limit, respectively.

<tag/<tt/grep <var/parameter/ <var/filename///
<item>
The <var/filename/ refers to a file one of whose lines is the value of
the parameter (leading or trailing whitespace on each line and empty
lines in the file are ignored).  It is an error for the file not to be
opened and read.

<tag/<tt/! <var/condition///
<item>
The <var/condition/ is <em/not/ true.

<tag/Conjunctions: <tt/&amp;/ and <tt/|//
<item>
<example>
( <var/condition/
&amp; <var/condition/
&amp; <var/condition/
...
)
</example>
is true if all the listed conditions are true; where <tt/|/ is used it
is true if any of them is true.  Newlines must be used to separate one
condition from the next, as shown, and the parentheses are mandatory.
These conjunctions do not do lazy evaluation.
</taglist>
<p>

The parameters are:

<taglist compact>
<tag/<tt/service//
<item>
The service name specified when the client was called.

<tag/<tt/calling-user//
<item>
Two strings: the login name of the calling user (determined as for
<prgn/USERV_USER/, above) and the calling uid (represented in
decimal).

<tag/<tt/calling-group//
<item>
Several strings: the primary and supplementary group names and gids
(in decimal) of the calling process.  All the group names come first,
and then the gids.  If the first supplementary group is the same as
the primary group then it is elided.

<tag/<tt/calling-user-shell//
<item>
The calling user's shell, as listed in the password entry for the
calling login name (as determined for <prgn/USERV_USER/, above).

<tag/<tt/service-user//
<item>
Two strings: the name of the service user (as specified to the client)
and their uid (represented in decimal).

<tag/<tt/service-group//
<item>
Several strings: the primary and supplementary group names and gids
(in decimal) of the service user.

<tag/<tt/service-user-shell//
<item>
The service user's shell, as listed in their password entry.

<tag/<tt/u-<var/name///
<item>
The value of the user-defined variable <var/name/ passed by the caller
using the <prgn/--defvar/ command-line option to the client.  If the
variable was not defined then this parameter is an empty list of
strings; in this case any condition which tests it will be false, and
<tt/include-lookup/ on it will read the <tt/:none/ file, or
<tt/:default/ if <tt/:none/ is not found.

</taglist>

<tag/<tt/errors-push//
<tag/<tt/srorre//
<item>
Stacks the error handling behaviour currently in effect.  Any changes
to error handling will take effect only between <prgn/errors-push/ and
<prgn/srorre/.

<tag/<tt/catch-quit//
<tag/<tt/hctac//
<item>
Any use of <prgn/quit/ inside <prgn/catch-quit/ will merely cause the
parsing to continue at <prgn/hctac/ instead.  Any control constructs
started since the <prgn/catch-quit/ will be considered finished if a
<prgn/quit/ is found.
<p>

If an error occurs inside <prgn/catch-quit/ the execution settings
will be reset (as if by the <prgn/reset/ directive) and parsing will
likewise continue at <prgn/hctac/.
<p>

If a lexical or syntax error is detected in the same configuration
file as the <prgn/catch-quit/, while looking for the <prgn/hctac/
after an error or <prgn/quit/, that new error will not be caught.

</taglist>

<sect1 id="dirs-execution">Directives for changing execution settings
<p>

The following directives modify the execution settings; the server
will remember the fact that the directive was encountered and act on
it only after all the configuration has been parsed.  The <em/last/
directive which modifies any particuar setting will take effect.

<taglist>
<tag/<tt/reject//
<item>
Reject the request.  <prgn/execute/, <prgn/execute-from-directory/ and
<prgn/execute-from-path/ will change this setting.

<tag/<tt/execute <var/program/ [<var/argument/ ...]//
<item>
Execute the program <var/program/, with the arguments as specified,
followed by any arguments given to the client if
<prgn/no-suppress-args/ is in effect.  It is an error for the
execution to fail when it is attempted (after all the configuration
has been parsed).  If <var/program/ does not contain a slash it will
be searched for on the service user's path.

<tag/<tt/execute-from-directory <var/pathname/ [<var/argument/ ...]//
<item>
Take all the characters after the last slash of the service name
specified when the client was called, and execute that program in the
directory named by <var/pathname/ as if it had been specified for
<var/execute/.  The part of the service name used may contain only
alphanumerics and hyphens and must start with an alphanumeric (and it
must be non-empty), otherwise it is an error.
<p>

This directive is ignored if the relevant program does not exist in
the directory specified; in this case the program to execute is left
at its previous setting (or unset, if it was not set before).
<p>

It is an error for the test for the existence of the program to fail
other than with a `no such file or directory' indication.  It is also
an error for the execution to fail if and when it is attempted (after
all the configuration has been parsed).

<tag/<tt/execute-from-path//
<item>
<var/service/ is interpreted as a program on the default <prgn/PATH/
(or as a pathname of an executable, if it contains a <tt>/</>).  This
directive is <em/very dangerous/, and is only provided to make the
<prgn/--override/ options effective.  It should not normally be used.
It is an error for the execution to fail when it is attempted (after
all the configuration has been parsed).

<tag/<tt/execute-builtin <var/service-name/ <var/service-arguments//
<item>
Executes the builtin service <var/service-name/.  These builtin
services display information about the server and/or the request, and
ignore any arguments passed from the service side except possibly to
print them as part of their output.  They write their results to their
standard output (i.e., wherever file descriptor 1 is directed).  The
builtin services are:

<taglist compact>
<tag/<tt/execute//
<item>
Displays the execution settings, defined variables,
arguments, etc. with which the builtin service was invoked.

<tag/<tt/environment//
<item>
Displays the environment variable settings with which the builtin
service was invoked.

<tag/<tt/parameter <var/parameter///
<item>
Displays the values of the service configuration language parameter
specified.

<tag/<tt/version//
<item>
Displays the version string and compilation details of the uservd
server program.

<tag/<tt/reset//
<item>
Displays the default reset configuration (evaluated when <prgn/reset/
is found in a configuration file, or when an error is caught by
<prgn/catch-quit/).

<tag/<tt/toplevel//
<item>
Displays the top-level default configuration (the configuration data,
evaluated by the server, which calls all the other configuration
files).

<tag/<tt/override//
<item>
Displays the top-level override configuration (the configuration data,
evaluated by the server, which causes all the other configuration data
to be parsed).

<tag/<tt/help//
<item>
Displays a list of the understood builtin service names and arguments.
</taglist>

In the future other builtin services may be defined which do more than
just print information.

<tag/<tt/set-environment//
<tag/<tt/no-set-environment//
<item>
Runs <tt>/etc/environment</> to set the service user's environment.
This adds the overhead of invoking a shell, but doesn't cause any
shell (de)mangling of the service's arguments.  This is achieved by
invoking
<example>
.../program arg arg arg ...
</example>
as
<example>
/bin/sh -c '. /etc/environment; exec "$@"' - .../program arg arg arg ...
</example>
<prgn/no-set-environment/ cancels the effect of
<prgn/set-environment/.

<tag/<tt/no-suppress-args//
<tag/<tt/suppress-args//
<item>
Include any arguments given to the client as arguments to the program
invoked as a result of an <prgn/execute/,
<prgn/execute-from-directory/ or <prgn/execute-from-path/ directive.
<prgn/suppress-args/ undoes the effect of <prgn/no-suppress-args/.

<tag/<tt/require-fd <var/fd-range/ read|write//
<item>
Insist that the filedescriptor(s) be opened for reading resp. writing.
It is an error if any descriptor marked as required when the service
is about to be invoked (after the configuration has been parsed) was
not specified when the client was invoked.  Each file descriptor has a
separate setting, and the last one of <prgn/require-fd/,
<prgn/allow-fd/, <prgn/ignore-fd/, <prgn/null-fd/ or <prgn/reject-fd/
which affected a particular file descriptor will take effect.
<p>

<var/fd-range/ may be a single number, two numbers separated by a
hyphen, or one number followed by a hyphen (indicating all descriptors
from that number onwards).  It may also be one of the words
<tt/stdin/, <tt/stdout/ or <tt/stderr/.  Open-ended file descriptor
rangers are allowed only with <prgn/reject-fd/ and <prgn/ignore-fd/,
as otherwise the service program would find itself with a very large
number of file descriptors open.
<p>

When the configuration has been parsed, and before the service is
about to be executed, stderr (fd 2) must be required or allowed
(<prgn/require-fd/ or <prgn/allow-fd/) for writing; this is so that
the error message printed by the server's child process if it cannot
<prgn/exec/ the service program is not lost.

<tag/<tt/allow-fd <var/fd-range/ [read|write]//
<item>
Allow the descriptor(s) to be opened for reading resp. writing, or
either if neither <tt/read/ nor <tt/write/ is specified.  If a
particular descriptor not specified by the client then it will be open
onto <tt>/dev/null</> (for reading, writing, or both, depending on
whether <tt/read/, <tt/write/ or neither was specified).

<tag/<tt/null-fd <var/fd-range/ [read|write]//
<item>
Specify that the descriptor(s) be opened onto <prgn>/dev/null</> for
reading resp. writing, or both if neither <tt/read/ nor <tt/write/
is specified.  Any specification of these file descriptors by the
client will be silently ignored; the client will see its ends of the
descriptors being closed immediately.

<tag/<tt/reject-fd <var/fd-range///
<item>
Do not allow the descriptor(s) to be specified by the client.  It is
an error if any descriptor(s) marked for rejection are specified when
the service is about to be invoked (after the configuration has been
parsed).

<tag/<tt/ignore-fd <var/fd-range///
<item>
Silently ignore any specification by the client of those
descriptor(s).  The pipes corresponding to these descriptors will be
closed just before the service is invoked.

<tag/<tt/disconnect-hup//
<tag/<tt/no-disconnect-hup//
<item>
Causes the service's process group to get a <prgn/SIGHUP/ if the
client disconnects before the main service process terminates.
<prgn/no-disconnect-hup/ cancels <prgn/disconnect-hup/.
<p>

If one of the reading descriptors specified when the client is called
gets a read error, or if the service is disconnected for some other
reason, then the <prgn/SIGHUP/ will be delivered <em/before/ the
writing end(s) of the service's reading pipe(s) are closed, so that
the client can distinguish disconnection from reading EOF on a pipe.

<tag/<tt/reset//
<item>
Resets the execution settings to the default.  This is equivalent to:
<example>
cd ~/
reject
no-set-environment
suppress-args
allow-fd 0 read
allow-fd 1-2 write
reject-fd 3-
disconnect-hup
</example>

</taglist>

If no <prgn/execute/, <prgn/execute-from-path/,
<prgn/execute-from-directory/ or <prgn/builtin/ is interpreted before
all the files are read then the request is rejected.


<sect id="configerrors">Errors in the configuration file
<p>

If a syntax error or other problem occurs when processing a
configuration file then a diagnostic will be issued, to wherever the
error messages are currently being sent (see the <prgn/errors-/ family
of directives, above).
<p>

The error will cause processing of the configuration files to cease at
that point, unless the error was inside a <prgn/catch-quit/ construct.
In this case the settings controlling the program's execution will be
reset to the defaults as if a <prgn/reset/ directive had been issued,
and parsing continues after <prgn/hctac/.


<sect id="defaults">Defaults
<p>

The default configuration processing is as if the daemon were parsing
an overall configuration file whose contents were as follows:

<example>
reset
user-rcfile ~/.userv/rc
errors-to-stderr
include /etc/userv/system.default
if grep service-user-shell /etc/shells
   errors-push
     catch-quit
       include-ifexist <var/file specified by most recent user-rcfile directive/
     hctac
   srorre
fi
include /etc/userv/system.override
quit
</example>
<p>

If one of the <prgn/--override/ options to the client is used then it
will instead be as if the daemon were parsing an overall configuration
as follows:

<example>
reset
errors-to-stderr
include <var/file containing configuration data sent by client/
quit
</example>


<chapt id="ipass">Information passed through the client/daemon combination
<p>

The information described below is the only information which passes
between the caller and the service.

<list>
<item>
The service name supplied by the caller is available in the
configuration language for deciding whether and which service program
to invoke, in the <prgn/service/ parameter, and is used by the
<prgn/execute-from-directory/ and <prgn/execute-from-path/
configuration directives.  It is usually used to select which service
program to invoke.  It is also passed to the service program in the
<prgn/USERV_SERVICE/ environment variable.

<item>
File descriptors specified by the client and allowed according to the
configuration language will be connected.  Each file descriptor is
opened for reading or writing.  Communication is via pipes, one end of
each pipe being open on the appropriate file descriptor in the service
program (when it is invoked) and the other end being held by the
client process, which will read and write files it opens on behalf of
its caller or file descriptors it is passed by its caller.
<p>

Data may be passed into the service through reading pipes and out of
it through writing pipes.  These pipes can remain open only until the
service and client have terminated, or can be made to stay open after
the client has terminated and (if the service program forks) the main
service process has exited; the behaviour is controlled by options
passed to the client by its caller.
<p>

The caller can arrange that a writing pipe be connected to a pipe or
similar object and cause attempts to write to that descriptor by the
service to generate a <prgn/SIGPIPE/ (or <prgn/EPIPE/ if
<prgn/SIGPIPE/ is caught or ignored) in the service.
<p>

Likewise, the service can close filedescriptors specified for reading,
which will cause the corresponding filedescriptors passed by the
caller to be closed, so that if these are pipes processes which write
to them will receive <prgn/SIGPIPE/ or <prgn/EPIPE/.

<item>
If <prgn/no-suppress-args/ is set then arguments passed to the client
by its caller will be passed on, verbatim, to the service.

<item>
Fatal signals and system call failures experienced by the client will
result in the disconnection of the service from the client and
possibly some of the communication file descriptors described above;
if <prgn/disconnect-hup/ is set then the service will also be sent a
<prgn/SIGHUP/.

<item>
The value of the <prgn/LOGNAME/ (or <prgn/USER/) environment variable
as passed to the client will be used as the login name of the calling
user if the uid of the calling process matches the uid corresponding
to that login name.  Otherwise the calling uid's password entry will
be used to determine the calling user's login name.
<p>

This login name and the calling uid are available in the configuration
language in the <prgn/calling-user/ parameter and are passed to the
service program in environment variables <prgn/USERV_USER/ and
<prgn/USERV_UID/.
<p>

The shell corresponding to that login name (according to the password
entry) is available as in the configuration language's
<prgn/calling-user-shell/ parameter.
<p>

If no relevant password entry can be found then no service will be
invoked.

<item>
The numeric values and textual names for calling gid and supplementary
group list are available in the configuration language in the
<prgn/calling-group/ parameter and are passed to the service in
environment variables.
<p>

If no name can be found for a numeric group to which the calling
process belongs then no service will be invoked.

<item>
The name of the current working directory in which the client was
invoked is passed, if available and not hidden using <prgn/--hidecwd/,
to the service program in the <prgn/USERV_CWD/ variable.  This grants no
special access to that directory unless it is a subdirectory of a
directory which is executable (searchable) but not readable by the
service user.

<item>
Settings specified by the caller using the <tt/--defvar
<var/name/=<var/value// option to the client are available in the
configuration language as the corresponding <tt/u-<var/name//
parameters and are passed to the service program in environment
variables <tt/USERV_U_<var/name//.

<item>
If the calling user is root or the same as the service user then
options may be given to the client which bypass the usual security
features; in this case other information may pass between the caller
and the service.

</list>

<chapt id="notes">Applications and notes on use
<p>

<sect id="examples">Examples
<p>

The companion package, <prgn/userv-utils/, contains a selection of
example services, some of which are useful tools in their own right.
See the <prgn/README/ in its top-level directory for details.

<sect id="standards">Standard services and directory management
<p>

In later versions of this specification standard service names and
interfaces for common services such as mail delivery and WWW CGI
scripts may be specified.
<p>

<prgn/userv/-using applications and system services which hide
<prgn/userv/ behind wrapper scripts may need to store information in
the user's filespace to preserve the correct placement of the security
perimiters.  Such applications should usually do so in a directory
(created by them) <tt>~/.userv/<var/service/</>, where <var/service/
is the service name or application in question.
<p>

If desired, a dot-directory inside <tt>~/.userv</> may be used to
avoid the user becoming confused by finding parts of a semi-privileged
application's internal state in their filespace, and/or discourage
them from fiddling with and thus corrupting it.
<p>

However, <prgn/userv/ applications should of course not rely for their
global integrity and security on the integrity of the data on the
user's side of the security boundary.

<sect id="reducepriv">Reducing the number of absolutely privileged subsystems
<p>

Currently most Unix systems have many components which need to run as
root, even though most of their activity does not strictly require
it.  This gives rise to a large and complex body of code which must be
trusted with the security of the system.
<p>

If they were to use <prgn/userv/, many of these subsystems would no
longer need any unusual privilege.  <p>

<prgn/cron/ and <prgn/at/, <prgn/lpr/ and the system's mail transfer
agent (<prgn/sendmail/, <prgn/smail/, <prgn/exim/ or the like) all
fall into this category, though <prgn/userv/-based versions of these
programs are not currently available.

<sect id="noexcess">Do not give away excessive privilege to <prgn/userv/-using facilities
<p>

There is a danger that people reimplementing the facilities I mention
above using <prgn/userv/ will discard much of the security benefit by
using a naive implementation technique.  This will become clearer with
an example:
<p>

Consider the <prgn/lpr/ program.  In current systems this needs to
have an absolutely privileged component in order to support delayed
printing without copying: when the user queues a file to be printed
the filename is stored in the print queue, rather than a copy of it,
and the printer daemon accesses the file directly when it is ready to
print the job.  In order that the user can print files which are not
world-readable the daemon is given root privilege so that it can open
the file in the context of the user, rather than its own.
<p>

A simple-minded approach to converting this scheme to use <prgn/userv/
might involve giving the printer daemon (the <prgn/lp/ user) the
ability to read the file by allowing them to run <prgn/cat/ (or a
special-purpose file-reading program) as any user.  The <prgn/lpr/
program would use a <prgn/userv/ service to store the filename in the
printer daemon's queues, and the daemon would read the file later when
it felt like it.
<p>

However, this would allow the printer daemon to read any file on the
system, whether or not someone had asked for it to be printed.  Since
many files will contain passwords and other security-critical
information this is nearly as bad as giving the daemon root access in
the first place.  Any security holes in the print server which allow a
user to execute commands as the <prgn/lp/ user will give the user the
ability to read any file on the system.
<p>

Instead, it is necessary to keep a record of which files the daemon
has been asked to print <em/outside/ the control of the print daemon.
This record could be kept by a new root-privileged component, but this
is not necessary: the record of which files a user has asked to be
printed can be kept under the control of the user in question.  The
submission program <prgn/lpr/ will make a record in an area under the
user's control before communicating with the print server, and the
print server would be given the ability to run a special file-reading
program which would only allow files to be read which were listed in
the user's file of things they'd asked to print.
<p>

Now security holes in most of the printing system do not critically
affect the security of the entire system: they only allow the attacker
to read and interfere with print jobs.  Bugs in the programs run by the
print server to read users' files (and to remove entries from the list
of files when it has done with them) will still be serious, but this
program can be quite simple.
<p>

Similar considerations apply to many <prgn/userv/-based versions of
facilities which currently run as root.
<p>

It is debatable whether the user-controlled state should be kept in
the user's filespace (in dotfiles, say) or kept in a separate area set
aside for the purpose; however, using the user's home directory (and
possibly creating a separate subdirectory of it as a dotfile to
contain subsystem state) has fewer implications for the rest of the
system and makes it entirely clear where the security boundaries lie.

<sect id="notreally"><prgn/userv/ can often replace <prgn/sudo/, but not <prgn/really/
<p>

<prgn/userv/ is not intended as a general-purpose system
administration tool with which system administrators can execute
arbitrary programs like text editors as root (or other system users)
when they need to.  It is unsuitable for this purpose precisely
because it enforces a strong separation between the calling and the
called program, which is undesirable in this context.
<p>

However, its use when restricted to running particular programs in
particular ways is very similar to many common uses of
<prgn/sudo/<footnote><prgn/sudo/ is a program which allows users to
execute certain programs as root, according to configuration files
specified by the system administrator.</footnote>.  <prgn/userv/ is
generally much better than restricted <prgn/sudo/, because it protects
the called program much more strongly from bad environmental
conditions set up by the caller.  Most programs that one might want to
run via restricted <prgn/sudo/, have not been designed to run in a
partially hostile environment.  <prgn/userv/ allows these programs to
be run in a safer environment and should be used instead.

<sect id="stdinerr">Error handling and input streams (eg stdin)
<p>

When the service program is reading from a file descriptor connected
to the calling side, the fd that the service program refers to a pipe
set up by <prgn/userv/ and not to the same object as was presented by
the caller.
<p>

Therefore if there is some kind of error it is possible for the
service-side fd to give premature end of file.  If it is important to
tell whether all of the intended data has been received by the service
program, the datastream must contain an explicit end-of-file
indication of some kind.
<p>

For example, consider a <prgn/userv/ service for submitting a mail
message, where message is supplied on the service's stdin.  However,
if the calling process is interrupted before it has written all of the
message, the service program will get EOF on the message data.  In a
naive arrangement this would cause a half-complete message to be
sent.  To prevent this, it is necessary to adopt some kind of explicit
end indication; for example, the end of the message could be signalled
by a dot on a line by itself, and dots doubled, as in SMTP.  Then the
service program would know when the entire message had been received,
and could avoid queueing incomplete messages.

<sect id="nogeneral">Don't give access to general-purpose utilities
<p>

Do not specify general purpose programs like <prgn/mv/ or <prgn/cat/
in <prgn/execute-/ directives without careful thought about their
arguments, and certainly not if <prgn/no-suppress-args/ is specified.
If you do so it will give the caller much more privilige than you
probably intend.
<p>

It is a shame that I have to say this here, but inexperienced
administrators have made similar mistakes with programs like
<prgn/sudo/.

</book>