.\"  <!-- $Id: userdb.sgml,v 1.1 2001/11/24 20:49:56 mrsam Exp $ -->
.\"  <!-- Copyright 1998 - 2001 Double Precision, Inc.  See COPYING for -->
.\"  <!-- distribution information. -->
.\" This manpage has been automatically generated by docbook2man 
.\" from a DocBook document.  This tool can be found at:
.\" <http://shell.ipoline.com/~elmert/comp/docbook2X/> 
.\" Please send any bug reports, improvements, comments, patches, 
.\" etc. to Steve Cheng <steve@ggi-project.org>.
.TH "USERDB" "8" "19 February 2004" "Double Precision, Inc." ""

.SH NAME
userdb \- manipulate /etc/userdb
.SH SYNOPSIS

\fBuserdb\fR \fB\fIaddr\fB\fR \fBset\fR \fB\fIfield\fB=\fIvalue\fB\fR\fI ...\fR


\fBuserdb\fR \fB\fIaddr\fB\fR \fBunset\fR \fB\fIfield\fB\fR\fI ...\fR


\fBuserdb\fR \fB\fIaddr\fB\fR \fBdel\fR


\fBuserdb\fR \fB\fIpath/addr\fB\fR [ \fBset\fR | \fBunset\fR | \fBdel\fR ] \fB\&...\fR


\fBuserdb\fR \fB-f\fR \fB\fIfile\fB\fR \fB\fIadr\fB\fR [ \fBset\fR | \fBunset\fR | \fBdel\fR ] \fB\&...\fR


\fBuserdb\fR \fB-show\fR \fB\fIpath\fB\fR


\fBuserdb\fR \fB-show\fR \fB\fIpath\fB\fR \fB\fIaddr\fB\fR


\fBuserdb\fR \fB-show\fR \fB-f\fR \fB\fIfile\fB\fR


\fBuserdb\fR \fB-show\fR \fB-f\fR \fB\fIfile\fB\fR \fB\fIaddr\fB\fR

.SH "DESCRIPTION"
.PP
\fBuserdb\fR is a convenient script to individually manipulate
entries in \fI/etc/userdb\fR\&. See
\fBmakeuserdb\fR(8)
for a description of its contents.  \fI/etc/userdb\fR can always
be edited using any text editor, but \fBuserdb\fR is a
convenient way to modify this file from another script.
.PP
\fI/etc/userdb\fR can also be a subdirectory, instead of a file.
Specify \fB\fIfoo/bar/addr\fB\fR to manipulate
\fB\fIaddr\fB\fR in the file
\fI/etc/userdb/foo/bar\fR\&.  You can
also use the
\fB-f\fR flag: \fB-f
\fI/etc/userdb/foo/bar\fB\fR is equivalent.  Use
whatever form makes the most sense to you.
.PP
\fI/etc/userdb\fR must not have any group or world
permissions. That's
because its contents may include system passwords (depending upon the
application which uses this virtual user account database).
.PP
Each line in \fI/etc/userdb\fR takes following form:
.sp
.RS
.PP
\fIaddr\fR<TAB>\fIfield\fR=\fIvalue\fR|\fIfield\fR=\fIvalue\fR\&...
.RE
.PP
\fIaddr\fR specifies a unique virtual address. It
is followed by a single
tab character, then a list of
\fIfield\fR=\fIvalue\fR pairs,
separated by
vertical slash characters. See
\fBmakeuserdb\fR(8)
for field definitions.
.PP
A text editor can be used to add blank lines or comments in
\fI/etc/userdb\fR\&.  Any blank lines or comments are ignored by the
\fBuserdb\fR script.
.PP
The names of the actual fields, and their contents, are defined entirely by
applications that use the \fI/etc/userdb\fR database, the
\fBuserdb\fR command just adds or removes arbitrary fields.
.PP
For example:
.sp
.RS
.PP

.nf
\fBuserdb default/info set mail=/home/mail/info\fR
.fi
.RE
.PP
This command accesses the address "info" in
\fI/etc/userdb/default\fR\&.
.PP
If the second argument to \fBuserdb\fR is
"\fIset\fR", the
remaining arguments are taken as
\fIfield=value\fR pairs, which are
added to the record for \fIaddr\fR\&. If there is no
record for \fIaddr\fR, a
new record will be appended to the file. If
\fIaddr\fR exists, any existing
values of any specified fields are removed. If
\fI=value\fR is missing,
\fBuserdb\fR stops and prompts for it. This is useful if
you're setting
a password field, where you do not want to specify the password on the command
line, which can be seen by the
\fBps\fR(1)
command. If \fBuserdb\fR is being
executed by a script, the value can be provided on standard input.
.PP
Use "\fIunset\fR" to delete fields from an existing
record. Use
"\fIdel\fR" to delete all fields in the existing record,
plus the record itself.
.SS "DISPLAYING /ETC/USERDB"
.PP
If the first argument to userdb
is \fI-show\fR, \fBuserdb\fR
displays the contents of \fI/etc/userdb\fR\&. If
\fI/etc/userdb\fR is a
subdirectory,
\fIpath\fR must refer to a
specific file in \fI/etc/userdb\fR\&. The
\fI-f\fR option can be used instead of
\fIpath\fR in order to specify an
arbitrary file.
.PP
If
\fIaddr\fR is not specified,
\fBuserdb\fR produces a list, on standard
output, containing all addresses found in the file, on per line. If
\fIaddr\fR is specified,
\fBuserdb\fR produces a list, on standard output, of
all the fields in \fI/etc/userdb\fR for this
\fIaddr\fR\&.
.SS "REBUILDING /ETC/USERDB.DAT"
.PP
The actual virtual account/address database is
\fI/etc/userdb.dat\fR\&.
This is a binary database file. \fB/etc/userdb\fR is the plain text
version. After running \fBuserdb\fR, execute the
\fBmakeuserdb\fR(8) command to rebuild
\fI/etc/userdb.dat\fR for the changes to take effect.
.SH "BUGS"
.PP
\fIaddr\fR must be unique.
If \fI/etc/userdb\fR is a subdirectory,
it's possible to create the same
\fIaddr\fR
in different files in the subdirectory.
This is an error that is not currently detected by \fBuserdb\fR,
however the subsequent
\fBmakeuserdb\fR(8) command
will fail with an error message.
.SH "FILES"
.PP
\fI /etc/userdb\fR - plain text file, or directory of plain text files
.PP
\fI .lock.filename\fR - lock file for \fIfilename\fR
.PP
\fI .tmp.filename\fR - temporary file used to create new contents of \fIfilename\fR
.SH "SEE ALSO"
.PP
\fBmakeuserdb\fR(8),
\fBuserdbpw\fR(8)