vchk(1M) vchk(1M)
NAME
vchk - version checkup
SYNOPSIS
vchk [-a] [-Asysid] [-b] [-c] [-d] [-D] [-e] [-ffilename]
[-i] [-I] [-k] [-l] [-m] [-ppw_file] [-Psysid] [-r] [-s]
[-S] [-v] [-x] ...
DESCRIPTION
vchk is a highly specialized form of make(1) designed to
check and maintain the modes, ownerships, and versions of a
set of files specified in the description file. The
description file is essentially a "photograph" of what a
healthy system (i.e., one with all its components in the
correct state) looks like. It contains a list of pathnames
(for both files and directories) that should exist and have
specific protections and contents. vchk reads the
description file, checks each item specified and prints
error messages when a file does not match its description.
Many problems can be fixed directly by vchk, such as
incorrect mode and/or owner and missing link names. All
other problems involve actually replacing a file, detected
by comparing some combination of checksum, length, and/or
version number (from the description file) with the value
generated from the actual file being checked. When a file
needs to be replaced vchk invokes the command named by the
REMAKE macro (see ``MACROS'' below).
Each argument is either a definition or an option. Option
arguments begin with the character - and consist of a string
of letters (called flags) from the set
``ADIPSabcdefiklmprstvx''. The f and t flags cause the next
argument to be considered specially. The p and P flags
cause the rest of the argument in which they appear to be
considered specially. Other arguments are either macro de-
finitions (i.e., name=string pairs) or simply strings which
are saved as numeric macros. Briefly, the flags are as fol-
lows:
-Asysid
specifies an alternate sysid rather than using the one
found in /etc/sysid.
-D enables debugging messages.
-I process control lines only.
-Psysid
preprocess the description file; sysid is optional and
is explained below under ``PREPROCESSING.''
-S suppress printing of non-fatal error messages.
Page 1 (last mod. 1/15/87)
vchk(1M) vchk(1M)
-a checks all lines in the description file. Modifies the
b, P, and k options.
-b build a description file for the current directory.
-c print shell commands to fix the file system.
-d suppress re-installation commands and error messages.
-e suppress checks for everything but existence.
-f filename
cause vchk to read filename instead of /etc/vchktree.
-i go interactive: modifies b, c, and x options.
-k perform checksums on files having checksum field.
-l suppress listing of files left in directories.
-m allow multiple copies of files.
-ppw_file
force vchk to re-evaluate and/or use an alternate pass-
word file.
-r allow redundant password entries (user ID).
-s remain silent about trivial problems.
-v suppress checking of version numbers.
-x execute shell commands to fix the file system (cf. the
-c option which prints rather than executes).
DESCRIPTION FILE SYNTAX
Lines in the description file are either comments, control
lines, specifications, or commands. Control lines provide a
simple ifdef mechanism for selectively ignoring specifica-
tion lines. Specification lines describe files and/or direc-
tories that need to be checked. Commands are not processed
by vchk but (in the spirit of make(1)) are used when the
file specified above them is found to need replacing.
Several conventions are observed to maintain the readability
of the description file; for example, a trailing backslash
and all leading white space on the following line are ig-
nored when processed. In addition, backslash may be used to
delay the expansion of macros (in macro definitions only)
and, as described below, to alter the evaluation of
parentheses and braces in pathnames.
Page 2 (last mod. 1/15/87)
vchk(1M) vchk(1M)
COMMENTS
Comment lines always start with a ``#''. If the second char-
acter on a comment line is also a ``#'', then that line is
printed on the standard error when read by vchk. Any line
may have a trailing comment, which is universally ignored.
CONTROL LINES
Control lines start with a ``.'' (period). The mechanism is
similar to the C language pre-processor except that defined
words do not have values associated with them; words are
simply defined or not. The control commands supported are
as follows:
.define wordlist
where wordlist is a list of white-space-separated words
to be defined which have no associated values. Note that
only the first twelve letters of defined words are signi-
ficant. Storage for defined words is static. There is a
maximum of sixty defined words at any given time.
.ifdef define_expression
where define_expression is an infix boolean expression
involving defined words and the operators !, &, and |,
which mean ``not'', ``and'', and ``or'', respectively.
The value of each word evaluates to a boolean ``yes'' if
that word is defined and ``no'' if not. If the expression
evaluates to be false, lines are ignored until the match-
ing .endif or .else control line is read. ifndef is also
supported and reverses the sense of the expression test.
.include filename
is very similar the C pre-processor include with the ex-
ception that there are no default searching places and
that the filename is not enclosed in double quotes or an-
gle brackets. In addition, if the first character of the
filename is an exclamation mark (!), then the rest of
line is considered to be a shell command and its standard
output is what gets included.
.undef wordlist
undefines each word in the wordlist.
.unset wordlist
frees the storage associated with macro definitions (de-
tailed in a following section) for the given wordlist
(which is composed of macro names). Words in wordlist
that are already unset (or were never set) are silently
ignored.
.chdir directory_name
changes the current directory to the one specified and
alters the starting location of pathnames anchored from
Page 3 (last mod. 1/15/87)
vchk(1M) vchk(1M)
the current directory.
.exit message
causes vchk to print the message and exit immediately.
As an aid to debugging the description file, a single `.' on
a line by itself causes vchk to print the currently defined
control symbols on the standard error when it reads that
line.
MACROS
A macro processing facility very similar to the one used by
make(1) is provided. Macros are defined when a line con-
taining the macro name, an equal sign, and the value is
read. The value may be null or include macro invocations.
Unlike ``defined'' words, macro names are fully significant
and are saved in dynamic memory. Macros are invoked by the
``$'' character. As in make scripts, macro names must be
surrounded by ()s when they are longer than a single letter.
There is a special macro (named ``.'', thus referenced with
``$.'') which always expands to the name of the current
directory. It is useful in the construction of link names
since most files have their links close by.
Except in the definition of a new macro (where interpreta-
tion may need to be delayed) and in comments, it is always
an error for a macro to be used if it is undefined. Since
the ``##'' comment is printed after macro substitution, it
is a useful debugging tool. In keeping with the spirit of
the ``dump control words'' command (.), a single ``$'' on a
line by itself prints all the currently defined macros and
their values.
Note that lines are re-scanned once a macro has been substi-
tuted so that a macro may be defined to expand to a control
line, comment, or even a macro definition. Note that this
degenerates to a recursive loop if the definition of a macro
contains a reference to that macro.
Two predefined macros exist. The first, called REMAKE, con-
tains the name (and options) of the program to use to re-
place damaged or missing files. If the file /etc/sysid ex-
ists and is not empty, it is assumed to contain the UniSoft
code name assigned to your system and vchk will setup the
REMAKE macro to be the command take -iN where N is the name
found in /etc/sysid. This allows systems that reside at
UniSoft to be updated automatically over a direct tty line
via the take(1C) program. If the /etc/sysid file has a
single empty line in it, then REMAKE will be set to take -i.
This allows remote systems to be updated automatically over
phone lines. If the /etc/sysid file does not exist, vchk
sets the REMAKE macro to be install. Note that the descrip-
Page 4 (last mod. 1/15/87)
vchk(1M) vchk(1M)
tion file may redefine the REMAKE macro at any time.
The second predefined macro is called ARGS and can be set
but not referenced. Strings assigned to ARGS are treated as
command line options. The - preceding option keyletters is
still required, and enables that option. A plus sign,
``+'', must be used instead to disable a keyletter option.
Resetting the b, p, and r is not allowed.
DESCRIPTION LINES
Each line that is not a comment, control line, macro defini-
tion, or command is considered to be the specification for a
particular file or directory. These have a simple and regu-
lar syntax: the first and only mandatory field is the path-
name, which must begin at the root (/) or the current direc-
tory (./). In practice we find that starting all lines with
a macro allows easy relocation of the entire tree described
and is very readable.
The rest of the line contains optional information about the
contents and protection of the file. Contents specifica-
tions are separated from the pathname by white space. The
entire protection specification is bracketed to separate it
from the rest of the line.
PATHNAMES
Pathnames refer to directories (if and only if they end in a
``/'' character) or files (if they do not end in a ``/'').
Use of shell metacharacters (globbing) is not supported but
two mechanisms are provided to allow variable pathnames:
braces, {}s, and parentheses. Braces are interpreted just
as in csh(1); each of the expanded pathnames must exist and
must match the description given. Parentheses in pathnames
are interpreted similarly, except that exactly one of the
resulting pathnames must exist. This feature is useful, for
example, to allow a program to be in either /bin or
/usr/bin, but not both.
Parentheses and braces are expanded left to right; for exam-
ple, the construction (a,b){x,y} means either ax and ay must
exist or bx and by. Backslashes may be used to delay or
prevent the interpretation of ()s and {}s. For example,
\(a,b\){x,y} means one of ax or bx and one of ay or by must
exist. One layer of backslashes are removed for each pass
through the pathname and each time an unescaped parenthesis
or bracket is detected and expanded, another pass is made.
Note that when alternative paths are used (i.e., parentheses
occur in the pathname) the first one is considered the one
to be rebuilt in the event that all are missing. For exam-
ple, the pathname (/usr)/bin/ls would look first in /usr/bin
for ``ls'', then in /bin, and try to ``REMAKE /usr/bin/ls''
Page 5 (last mod. 1/15/87)
vchk(1M) vchk(1M)
if both are missing. The reverse is true for
(,/usr)/bin/ls.
SPECIFICATIONS
Two kinds of specifications are implemented. The first kind
deals with the contents of the file or directory and follows
the pathname (separated from it by white space). The second
kind deals with the files protection; these are enclosed in
some type of parentheses to separate them from contents
specifications. The kind of parentheses used, ()s, []s,
<>s, or {}s, modify the action taken by vchk according to
the table below:
() Enables checking and replacing of the file.
[] Enables checking but never replacing. If the file is
missing, vchk will complain but not try to rebuild it.
<> Enables checking (if and only if the file exists or the
-a command line option is given) and never replacing.
{} Enables checking but not repairing, (i.e., if the file
is missing then it will be remade, but if it exists and
is incorrect it will not be remade).
Associated with each directory is a default mode and owner-
ship for the files and directories contained within it. Un-
less explicitly given, each directory inherits its defaults
from its parent directory. If unspecified, the uppermost
directory (either the root or current directory) sets the
mode and ownership of its contents from its own mode and
ownership. These defaults may be reset at any time simply
by following the directory name with a mode and/or user
name.
Regular files have three optional contents specification
fields: length, checksum, and version number. These may be
specified with a word (either Length, Checksum, or Version),
an optional space, or a numeric value. The word may be any
prefix, for example, ``Length34'' or ``L34''. The checksums
used are the same as those produced by sum(1). The length
checked is that returned by stat(2). These checks do not
apply to device files (only block and character devices are
supported); thus their contents specification field must be-
gin with either b or c and must be followed by the major and
minor device number (separated by white space). If x is used
instead of either the major or minor device number, vchk
will allow the device to have any value.
The protection specification consists of a list of command
prefixes separated by semicolons. The commands supported
are chmod, chown, and link to. If angle brackets (i.e.,
Page 6 (last mod. 1/15/87)
vchk(1M) vchk(1M)
<>s) are used instead of parentheses to enclose the protec-
tion specification, the file or directory so referenced is
optional and will not generate diagnostics if it is missing.
It can be raised to the status of []s by giving the -a com-
mand line option. If square brackets (i.e., []s) are used,
the referenced file cannot be replaced automatically, as for
example, the password file. If curly brackets (i.e., {}s)
are used, the referenced file will be replaced only if it is
missing, not if it exists and is wrong (according to the
description file). This is useful for files like
/etc/termcap.
Any other information in the protection specification is
treated as a special comment that is printed with error mes-
sages about that file.
OPERATION
In order for vchk to check the ownership of files it must
map user ID numbers onto login names. The password file is
normally used for this mapping but it is too expensive to
look up each name every time it is used so vchk creates a
temporary file (/etc/vchkpw) the first time it is run;
whenever its temporary is out of date with respect to the
real password file, vchk recreates the temporary file.
In the process of reading the password file vchk inspects
each account and prints diagnostics when it finds question-
able data there. These messages are warnings or simply si-
tuations which bear reporting; the format of these messages
is "Line <number>: message". The word "Error:" is prefixed
to the warnings for a particular line if vchk has decided to
ignore that line of the password file.
The -p[pw_file] option is provided to allow users who do not
have write permission in /etc to use vchk. If specified
with a filename after it, vchk will get the saved password
information from that file. If the file does not exist, vchk
will create it. Use of the -p option without a filename in-
forms vchk to reprocess the password file even if it is not
out of date.
vchk normally expects the description file to be
/etc/vchktree, but if the standard input to vchk is a regu-
lar file, that file will be read instead.
Instead of redirecting the standard input, the -f option can
be used to respecify the description file. It is an error
to use both.
The best way to build a new description file is to chdir to
the appropriate directory and run vchk with the -b option. A
description file for the current directory will be produced
Page 7 (last mod. 1/15/87)
vchk(1M) vchk(1M)
on the standard output. The -i option may also be used,
causing vchk to ask before descending each directory.
In addition to reporting errors, the -c flag prints shell
commands to correct the detected error. The -i option can
be used with the -c option to ask before outputting a com-
mand.
It is inadvisable to use the -x flag until the description
file has been used and debugged. This flag allows vchk to
execute the chmod(1), chown(1), and ln(1) commands internal-
ly, saving much time. Re-installation commands (cf. the
REMAKE macro) are executed via the system(3S) call.
PREPROCESSING
The -Psysid command line option provides a means for simpli-
fying a complex description file. Everything except macro
substitution is suppressed and after each line is parsed, it
is printed on the standard output instead of being used to
check the filesystem.
If a sysid is given after the -P flag, then it is used to
lookup a line from the (/etc/takelist) file. (See take(1C)
for a more complete description of the function of the
/etc/takelist file.)
The lines in /etc/takelist are composed of any number of
fields (called alternates) separated by colons (:s). The
first alternate in a line is a list of system names separat-
ed by or bars (|s). The sysid above is compared with each
of the system names in the first alternate of each line un-
til it is found. If not found, then vchk exits with an ap-
propriate error message.
When the line from /etc/takelist for the current sysid is
found, then each of the additional alternates are considered
lists of root directories (separated by colons or bars) to
be prefixed to filenames in the tree file before looking for
them.
If a file is found in more or less than exactly 1 place in
the list, then an error is reported and that line is not in-
clude in the preprocessed output. If it is found, then the
checksum, length, and version number are computed from that
file and replaced in the preprocessed output.
EXAMPLE
Following are some excerpts from a typical description file.
B = (/usr)/bin # programs can be in
/bin or /usr/bin
/ bin 755 (chmod 755)
$B/ar Version 1.0
Page 8 (last mod. 1/15/87)
vchk(1M) vchk(1M)
$B/awk Version 1.3
$B/more Version 1.0 (link to $./page)
$B/sccsdiff C54686 L1253 (shell script)
$B/su Version 1.0 (chown root; chmod 4755)
/etc/ root 644
/etc/passwd [password file]
/etc/group [group file]
/etc/init Version 1.0 (chmod 700)
/etc/update Version 1.1 (chmod 700)
/etc/ddate <dump dates>
The first line of the above example defines a macro, B, to
be the string (/usr)/bin. This macro is then invoked on
lines 3 through 7 of the example to allow the programs men-
tioned to be in either /usr/bin or /bin.
The second line specifies that the root directory (/) should
have mode 755 and that the default mode and owner for files
found in it be 755 and bin.
The third line specifies that the ar program should be ver-
sion 1.0, owned by bin and have mode 755. The mode and own-
er are implied in the following way. Each directory inher-
its its mode and ownership from its parent. Thus /bin in-
herits the owner of root (which is unspecified in the exam-
ple and thus defaults to whatever the owner of the root (/)
is when the example is run). The mode of the root directory
is specified as 755.
FILES
/usr/bin/vchk
/etc/vchkpw the file where vchk saves the password
file summary.
/etc/passwd the password file.
/etc/vchktree the default description file.
/dev/tty where vchk prints questions and gets the
responses (when the -i option is used).
<standard error> used to print all diagnostics.
<standard output> used to print shell commands and the new-
ly built description file (when using the
-b option).
<standard input> considered the default description file
if it is a regular file.
SEE ALSO
Page 9 (last mod. 1/15/87)
vchk(1M) vchk(1M)
chmod(1), ln(1), chown(1).
BUGS
There is no way (except tediously via the -i option) to ex-
clude directories from inspection when building a new
description file. There is also no way to automatically up-
date an existing description file (i.e., to tell vchk to fix
the description file instead of the filesystem).
Page 10 (last mod. 1/15/87)