userdb/userdb.8.in

   1 .\"  <!-- $Id: userdb.sgml,v 1.5 2007/04/22 15:05:16 mrsam Exp $ -->
   2 .\"  <!-- Copyright 1998 - 2007 Double Precision, Inc.  See COPYING for -->
   3 .\"  <!-- distribution information. -->
   4 .\"     Title: userdb
   5 .\"    Author:
   6 .\" Generator: DocBook XSL Stylesheets v1.73.2 <http://docbook.sf.net/>
   7 .\"      Date: 08/23/2008
   8 .\"    Manual: Double Precision, Inc.
   9 .\"    Source: Double Precision, Inc.
  10 .\"
  11 .TH "USERDB" "8" "08/23/2008" "Double Precision, Inc." "Double Precision, Inc."
  12 .\" disable hyphenation
  13 .nh
  14 .\" disable justification (adjust text to left margin only)
  15 .ad l
  16 .SH "NAME"
  17 userdb - manipulate @userdb@
  18 .SH "SYNOPSIS"
  19 .HP 7
  20 \fBuserdb\fR {\fIaddr\fR} set {\fIfield\fR=\fIvalue\fR...}
  21 .HP 7
  22 \fBuserdb\fR {\fIaddr\fR} unset {\fIfield\fR...}
  23 .HP 7
  24 \fBuserdb\fR {\fIaddr\fR} del
  25 .HP 7
  26 \fBuserdb\fR {\fIpath/addr\fR} [set | unset | del] \.\.\.
  27 .HP 7
  28 \fBuserdb\fR \-f {\fIfile\fR} {\fIadr\fR} [set | unset | del] \.\.\.
  29 .HP 7
  30 \fBuserdb\fR \-show {\fIpath\fR}
  31 .HP 7
  32 \fBuserdb\fR \-show {\fIpath\fR} {\fIaddr\fR}
  33 .HP 7
  34 \fBuserdb\fR \-show \-f {\fIfile\fR}
  35 .HP 7
  36 \fBuserdb\fR \-show \-f {\fIfile\fR} {\fIaddr\fR}
  37 .SH "DESCRIPTION"
  38 .PP
  39
  40 \fBuserdb\fR
  41 is a convenient script to individually manipulate entries in
  42 \fI@userdb@\fR\. See
  43 \fI\fBmakeuserdb\fR(8)\fR\&[1]
  44 for a description of its contents\.
  45 \fI@userdb@\fR
  46 can always be edited using any text editor, but
  47 \fBuserdb\fR
  48 is a convenient way to modify this file from another script\.
  49 .PP
  50
  51 \fI@userdb@\fR
  52 can also be a subdirectory, instead of a file\. Specify
  53 \fB\fIfoo/bar/addr\fR\fR
  54 to manipulate
  55 \fB\fIaddr\fR\fR
  56 in the file
  57 \fI@userdb@\fR\fI\fI/foo/bar\fR\fR\. You can also use the
  58 \fB\-f\fR
  59 flag:
  60 \fB\-f \fR\fB\fI@userdb@/foo/bar\fR\fR
  61 is equivalent\. Use whatever form makes the most sense to you\.
  62 .PP
  63
  64 \fI@userdb@\fR
  65 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)\.
  66 .PP
  67 Each line in
  68 \fI@userdb@\fR
  69 takes following form:
  70 .PP \fIaddr\fR<TAB>\fIfield\fR=\fIvalue\fR|\fIfield\fR=\fIvalue\fR\.\.\.
  71 .PP
  72
  73 \fIaddr\fR
  74 specifies a unique virtual address\. It is followed by a single tab character, then a list of
  75 \fIfield\fR=\fIvalue\fR
  76 pairs, separated by vertical slash characters\. See
  77 \fI\fBmakeuserdb\fR(8)\fR\&[1]
  78 for field definitions\.
  79 .PP
  80 A text editor can be used to add blank lines or comments in
  81 \fI@userdb@\fR\. Any blank lines or comments are ignored by the
  82 \fBuserdb\fR
  83 script\.
  84 .PP
  85 The names of the actual fields, and their contents, are defined entirely by applications that use the
  86 \fI@userdb@\fR
  87 database, the
  88 \fBuserdb\fR
  89 command just adds or removes arbitrary fields\.
  90 .PP
  91 For example:
  92 .sp
  93 .RS 4
  94 .nf
  95 \fBuserdb default/info set mail=/home/mail/info\fR
  96 .fi
  97 .RE
  98 .PP
  99 This command accesses the address "info" in
 100 \fI@userdb@/default\fR\.
 101 .PP
 102 If the second argument to
 103 \fBuserdb\fR
 104 is "\fIset\fR", the remaining arguments are taken as
 105 \fI\fIfield\fR\fR\fI=\fR\fI\fIvalue\fR\fR
 106 pairs, which are added to the record for
 107 \fIaddr\fR\. If there is no record for
 108 \fIaddr\fR, a new record will be appended to the file\. If
 109 \fIaddr\fR
 110 exists, any existing values of any specified fields are removed\. If
 111 \fI=\fR\fI\fIvalue\fR\fR
 112 is missing,
 113 \fBuserdb\fR
 114 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
 115 \fBps\fR(1)
 116 command\. If
 117 \fBuserdb\fR
 118 is being executed by a script, the value can be provided on standard input\.
 119 .PP
 120 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\.
 121 .SS "DISPLAYING \fI@userdb@\fR"
 122 .PP
 123 If the first argument to userdb is
 124 \fI\-show\fR,
 125 \fBuserdb\fR
 126 displays the contents of
 127 \fI@userdb@\fR\. If
 128 \fI@userdb@\fR
 129 is a subdirectory,
 130 \fI\fIpath\fR\fR
 131 must refer to a specific file in
 132 \fI@userdb@\fR\. The
 133 \fI\-f\fR
 134 option can be used instead of
 135 \fI\fIpath\fR\fR
 136 in order to specify an arbitrary file\.
 137 .PP
 138 If
 139 \fI\fIaddr\fR\fR
 140 is not specified,
 141 \fBuserdb\fR
 142 produces a list, on standard output, containing all addresses found in the file, on per line\. If
 143 \fI\fIaddr\fR\fR
 144 is specified,
 145 \fBuserdb\fR
 146 produces a list, on standard output, of all the fields in
 147 \fI@userdb@\fR
 148 for this
 149 \fI\fIaddr\fR\fR\.
 150 .SS "REBUILDING \fI@userdb@\.dat\fR"
 151 .PP
 152 The actual virtual account/address database is
 153 \fI@userdb@\.dat\fR\. This is a binary database file\.
 154 \fB@userdb@\fR
 155 is the plain text version\. After running
 156 \fBuserdb\fR, execute the
 157 \fI\fBmakeuserdb\fR(8)\fR\&[1]
 158 command to rebuild
 159 \fI@userdb@\.dat\fR
 160 for the changes to take effect\.
 161 .SH "BUGS"
 162 .PP
 163
 164 \fI\fIaddr\fR\fR
 165 must be unique\. If
 166 \fI@userdb@\fR
 167 is a subdirectory, it\'s possible to create the same
 168 \fI\fIaddr\fR\fR
 169 in different files in the subdirectory\. This is an error that is not currently detected by
 170 \fBuserdb\fR, however the subsequent
 171 \fI\fBmakeuserdb\fR(8)\fR\&[1]
 172 command will fail with an error message\.
 173 .SH "FILES"
 174 .PP
 175
 176 \fI @userdb@\fR
 177 \- plain text file, or directory of plain text files
 178 .PP
 179
 180 \fI \.lock\.filename\fR
 181 \- lock file for
 182 \fIfilename\fR
 183 .PP
 184
 185 \fI \.tmp\.filename\fR
 186 \- temporary file used to create new contents of
 187 \fIfilename\fR
 188 .SH "SEE ALSO"
 189 .PP
 190
 191 \fI\fBmakeuserdb\fR(8)\fR\&[1],
 192 \fI\fBuserdbpw\fR(8)\fR\&[2]
 193 .SH "NOTES"
 194 .IP " 1." 4
 195 \fBmakeuserdb\fR(8)
 196 .RS 4
 197 \%makeuserdb.html
 198 .RE
 199 .IP " 2." 4
 200 \fBuserdbpw\fR(8)
 201 .RS 4
 202 \%userdbpw.html
 203 .RE