userdb/userdb.8.in

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