X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ian/git?a=blobdiff_plain;f=spec.html%2Fch-config.html;h=7647ad16087ab5c5c1849ae1dd35460593b52e92;hb=70d3947fb471e0e12ef89c35f915f6acec217f4a;hp=0612106db56e438fe0ffba2f3802e5d51f832200;hpb=d481e8196cc08ec6761f3a26da16d1e02dbbc712;p=userv.git diff --git a/spec.html/ch-config.html b/spec.html/ch-config.html index 0612106..7647ad1 100644 --- a/spec.html/ch-config.html +++ b/spec.html/ch-config.html @@ -1,40 +1,73 @@ -
+ + + + + +Which services may be run by whom and under what conditions is -controlled by configuration files.
+controlled by configuration files. +
+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.
+client or specifying which program to execute to provide the service. +
+The 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.
+only take effect if they are not overridden by a later directive. +
-The daemon will first read/etc/userv/system.default
. Then, by
+
+The daemon will first read /etc/userv/system.default. Then, by
default (this behaviour may be modified), it will read a per-user file
-~/.userv/rc
, if it exists and the service user's shell is in
-/etc/shells
. Finally it will read
-/etc/userv/system.override
.
+~/.userv/rc, if it exists and the service user's shell is in +/etc/shells. Finally it will read +/etc/userv/system.override. +
+When it has read all of these files it will act according to the currently values of of the execution settings. +
+
The configuration file is a series of directives, usually one per
-line. The portion of a line following a hash character #
is
+line. The portion of a line following a hash character # 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
@@ -42,77 +75,104 @@ required, a string in double quotes. Double-quoted strings may
contain the following backslash escapes:
\n
\t
\r
\
OOO
\x
XX
\
punctuation
\\
, \"
)\
newline
(ie, backslash at end of line)+
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 ~/
are taken to be
+Pathnames starting with the two characters ~/ are taken to be
relative to the service user's home directory.
+
The following directives take effect immediately:
cd
pathname
+
cd
is cumulative. It
+is an error if the directory cannot be changed to.
-cd should not be used between execute-from-directory and
+cd
should not be used between 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).
-eof
if
, catch-quit
or
+errors-push
) which were started in that file will be considered
finished. Parsing will continue in the file which caused the file
-containing the eof to be read.
-quit
include
filename
include-ifexist
filename
eof
to be read.
+
+quit
is subject to the
+catch-quit
control construct.
+
+include-ifexist
is used and the file does not exist, in which case the directive is
silently ignored.
-include-lookup
parameter
directory
include-lookup-all
parameter
directory
+ +
if
, Control structure directives, subsection 4.2.3). If parameter has several values they will
+be tried in order; with include-lookup
this search will stop
+when one is found, but with include-lookup-all
the search will
+continue and any files appropriate to other values will be read too.
If none of the parameter's values had a corresponding file then the
-file :default
will be read, if it exists. If parameter's
-list of values was empty then the file :none
will be tried first
-and read if it exists, otherwise :default
will be tried.
+file :default will be read, if it exists. If parameter's
+list of values was empty then the file :none will be tried first
+and read if it exists, otherwise :default will be tried.
-It is not an error for any of the files (including :default
) not
+It is not an error for any of the files (including :default) not
to exist, but it is an error if a file exists and cannot be read or if
the directory cannot be accessed.
-
+
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 :.
), colons will be doubled, and each
-slash will be replaced with a colon followed by a hyphen :-
. A
+a colon prepended (making :.), colons will be doubled, and each
+slash will be replaced with a colon followed by a hyphen :-. A
parameter value which is the empty string will be replaced with
-:empty
(note that this is different from a parameter not having
+:empty (note that this is different from a parameter not having
any values).
-
include-directory
directory
error
text ...
message
text ...
The following directives have no immediate effect, but are remembered and have an effect on later processing of the configuration files.
user-rcfile
filename
~/.userv/rc
. This does not happen immediately;
+system.default
configuration file has been read. This
directive has no effect in a user's configuration file or in the
-system.override file, as the user's configuration file has
+system.override
file, as the user's configuration file has
already been found and read by then and will not be re-read.
-errors-to-stderr
errors-to-file
filenameerrors-to-syslog
[facility [level]]user
; the default level is error
.syslog
. The default
+facility is user; the default level is error.
+
+
+
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.
if
condition
elif
condition
else
fi
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.+below. +
The conditions are:
glob
parameter
glob-pattern ...
range
parameter
min
max
$
to indicate
+
+grep
parameter
filename
!
condition
&
and |
( condition + +
+( condition & condition & condition ... -)-is true if all the listed conditions are true; where
|
is used it
+)
+
+
+is true if all the listed conditions are true; where | 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.+These conjunctions do not do lazy evaluation. + +
The parameters are:
service
calling-user
USERV_USER
, above) and the calling uid (represented in
decimal).
-calling-group
calling-user-shell
service-user
USERV_USER
, above).
+
+service-group
service-user-shell
u-
name
--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
-include-lookup
on it will read the :none
file, or
-:default
if :none
is not found.
+include-lookup on it will read the :none file, or
+:default if :none is not found.
+
errors-push
and
+srorre
.
-errors-push
filenamesrorre
catch-quit
hctac
+
quit
inside catch-quit
will merely cause the
+parsing to continue at hctac
instead. Any control constructs
+started since the catch-quit
will be considered finished if a
+quit
is found.
-If an error occurs inside catch-quit the execution settings
-will be reset (as if by the reset directive) and parsing will
-likewise continue at hctac.
+If an error occurs inside catch-quit
the execution settings
+will be reset (as if by the reset
directive) and parsing will
+likewise continue at hctac
.
If a lexical or syntax error is detected in the same configuration
-file as the catch-quit, while looking for the hctac
-after an error or quit, that new error will not be caught.
+file as the catch-quit
, while looking for the hctac
+after an error or quit
, that new error will not be caught.
+
+
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 last directive which modifies any particuar setting will take effect.
reject
execute
program [
argument ...]
execute
, execute-from-directory
and
+execute-from-path
will change this setting.
+
+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 program does not contain a slash it will
be searched for on the service user's path.
-execute-from-directory
pathname [
argument ...]
+must be non-empty), otherwise it is an error. 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).
+at its previous setting (or unset, if it was not set before). 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). -
execute-from-path
/
). This
+
+PATH
+(or as a pathname of an executable, if it contains a /). This
directive is very dangerous, and is only provided to make the
---override options effective. It should not normally be used.
+--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).
-execute-builtin
service-name
service-arguments
+Executes the builtin service 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 @@ -281,129 +385,166 @@ standard output (i.e., wherever file descriptor 1 is directed). The builtin services are:
execute
environment
parameter
parameter
version
reset
reset
is found in a configuration file, or when an error is caught by
-catch-quit).
-toplevel
catch-quit
).
+
+override
help
set-environment
no-set-environment
/etc/environment
to set the service user's environment.
+uservd
to shut down. Available only when the
+service user is root. This only affects new requests; it doesn't
+terminate any currently-running requests
+
+.../program arg arg arg ...+
+.../program arg arg arg ... ++ as -
/bin/sh -c '. /etc/environment; exec "$@"' - .../program arg arg arg ...-no-set-environment cancels the effect of -set-environment. -
no-suppress-args
suppress-args
require-fd
fd-range read|write
+/bin/sh -c '. /etc/environment; exec "$@"' - .../program arg arg arg ... ++ +
no-set-environment
cancels the effect of
+set-environment
.
+
+execute
,
+execute-from-directory
or execute-from-path
directive.
+suppress-args
undoes the effect of no-suppress-args
.
+
+
+separate setting, and the last one of require-fd
,
+allow-fd
, ignore-fd
, null-fd
or reject-fd
+which affected a particular file descriptor will take effect.
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
-stdin
, stdout
or stderr
. Open-ended file descriptor
-rangers are allowed only with reject-fd and ignore-fd,
+stdin, stdout or stderr. Open-ended file descriptor
+rangers are allowed only with reject-fd
and ignore-fd
,
as otherwise the service program would find itself with a very large
-number of file descriptors open.
+number of file descriptors open.
When the configuration has been parsed, and before the service is
about to be executed, stderr (fd 2) must be required or allowed
-(require-fd or allow-fd) for writing; this is so that
+(require-fd
or allow-fd
) for writing; this is so that
the error message printed by the server's child process if it cannot
-exec the service program is not lost.
-
allow-fd
fd-range [read|write]
read
nor write
is specified. If a
+exec
the service program is not lost.
+
+/dev/null
(for reading, writing, or both, depending on
-whether read
, write
or neither was specified).
-null-fd
fd-range [read|write]
read
nor write
+onto /dev/null (for reading, writing, or both, depending on
+whether read, write or neither was specified).
+
+/dev/null
for
+reading resp. writing, or both if neither read nor 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.
-reject-fd
fd-range
ignore-fd
fd-range
disconnect-hup
no-disconnect-hup
SIGHUP
if the
client disconnects before the main service process terminates.
-no-disconnect-hup cancels disconnect-hup.
+no-disconnect-hup
cancels disconnect-hup
.
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 SIGHUP will be delivered before the
+reason, then the SIGHUP
will be delivered 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.
-
reset
cd ~/ + +
+cd ~/ reject no-set-environment suppress-args allow-fd 0 read allow-fd 1-2 write reject-fd 3- -disconnect-hup+disconnect-hup + + -If no execute, execute-from-path, -execute-from-directory or builtin is interpreted before +If no
execute
, execute-from-path
,
+execute-from-directory
or builtin
is interpreted before
all the files are read then the request is rejected.
+
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 errors- family -of directives, above).
+error messages are currently being sent (see the errors-
family
+of directives, above).
+
The error will cause processing of the configuration files to cease at
-that point, unless the error was inside a catch-quit construct.
+that point, unless the error was inside a catch-quit
construct.
In this case the settings controlling the program's execution will be
-reset to the defaults as if a reset directive had been issued,
-and parsing continues after hctac.
+reset to the defaults as if a reset
directive had been issued,
+and parsing continues after hctac
.
+
The default configuration processing is as if the daemon were parsing an overall configuration file whose contents were as follows: -
reset ++ -If one of the --override options to the client is used then it ++reset user-rcfile ~/.userv/rc errors-to-stderr include /etc/userv/system.default @@ -415,23 +556,41 @@ if grep service-user-shell /etc/shells srorre fi include /etc/userv/system.override -quit+quit +
+If one of the --override
options to the client is used then it
will instead be as if the daemon were parsing an overall configuration
as follows:
-
reset ++ + ++reset errors-to-stderr include file containing configuration data sent by client -quit+quit +