rubbos/app/httpd-2.0.64/docs/man/htdbm.1

   1 .\" XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
   2 .\" DO NOT EDIT! Generated from XML source.
   3 .\" XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
   4 .de Sh \" Subsection
   5 .br
   6 .if t .Sp
   7 .ne 5
   8 .PP
   9 \fB\\$1\fR
  10 .PP
  11 ..
  12 .de Sp \" Vertical space (when we can't use .PP)
  13 .if t .sp .5v
  14 .if n .sp
  15 ..
  16 .de Ip \" List item
  17 .br
  18 .ie \\n(.$>=3 .ne \\$3
  19 .el .ne 3
  20 .IP "\\$1" \\$2
  21 ..
  22 .TH "HTDBM" 1 "2005-04-07" "Apache HTTP Server" "htdbm"
  23
  24 .SH NAME
  25 htdbm \- Manipulate DBM password databases
  26
  27 .SH "SYNOPSIS"
  28
  29 .PP
  30 \fBhtdbm\fR [ -\fBT\fR\fIDBTYPE\fR ] [ -\fBc\fR ] [ -\fBm\fR | -\fBd\fR | -\fBp\fR | -\fBs\fR ] [ -\fBt\fR ] [ -\fBv\fR ] [ -\fBx\fR ] \fIfilename\fR \fIusername\fR
  31
  32 .PP
  33 \fBhtdbm\fR -\fBb\fR [ -\fBT\fR\fIDBTYPE\fR ] [ -\fBc\fR ] [ -\fBm\fR | -\fBd\fR | -\fBp\fR | -\fBs\fR ] [ -\fBt\fR ] [ -\fBv\fR ] \fIfilename\fR \fIusername\fR \fIpassword\fR
  34
  35 .PP
  36 \fBhtdbm\fR -\fBn\fR [ -\fBc\fR ] [ -\fBm\fR | -\fBd\fR | -\fBp\fR | -\fBs\fR ] [ -\fBt\fR ] [ -\fBv\fR ] \fIusername\fR
  37
  38 .PP
  39 \fBhtdbm\fR -\fBnb\fR [ -\fBc\fR ] [ -\fBm\fR | -\fBd\fR | -\fBp\fR | -\fBs\fR ] [ -\fBt\fR ] [ -\fBv\fR ] \fIusername\fR \fIpassword\fR
  40
  41 .PP
  42 \fBhtdbm\fR -\fBv\fR [ -\fBT\fR\fIDBTYPE\fR ] [ -\fBc\fR ] [ -\fBm\fR | -\fBd\fR | -\fBp\fR | -\fBs\fR ] [ -\fBt\fR ] [ -\fBv\fR ] \fIfilename\fR \fIusername\fR
  43
  44 .PP
  45 \fBhtdbm\fR -\fBvb\fR [ -\fBT\fR\fIDBTYPE\fR ] [ -\fBc\fR ] [ -\fBm\fR | -\fBd\fR | -\fBp\fR | -\fBs\fR ] [ -\fBt\fR ] [ -\fBv\fR ] \fIfilename\fR \fIusername\fR \fIpassword\fR
  46
  47 .PP
  48 \fBhtdbm\fR -\fBx\fR [ -\fBT\fR\fIDBTYPE\fR ] [ -\fBm\fR | -\fBd\fR | -\fBp\fR | -\fBs\fR ] \fIfilename\fR \fIusername\fR
  49
  50 .PP
  51 \fBhtdbm\fR -\fBl\fR [ -\fBT\fR\fIDBTYPE\fR ]
  52
  53
  54 .SH "SUMMARY"
  55
  56 .PP
  57 htdbm is used to manipulate the DBM format files used to store usernames and password for basic authentication of HTTP users via mod_auth_dbm\&. See the dbmmanage documentation for more information about these DBM files\&.
  58
  59
  60 .SH "OPTIONS"
  61
  62
  63 .TP
  64 -b
  65 Use batch mode; \fIi\&.e\&.\fR, get the password from the command line rather than prompting for it\&. This option should be used with extreme care, since \fBthe password is clearly visible\fR on the command line\&.
  66 .TP
  67 -c
  68 Create the \fIpasswdfile\fR\&. If \fIpasswdfile\fR already exists, it is rewritten and truncated\&. This option cannot be combined with the -n option\&.
  69 .TP
  70 -n
  71 Display the results on standard output rather than updating a database\&. This option changes the syntax of the command line, since the \fIpasswdfile\fR argument (usually the first one) is omitted\&. It cannot be combined with the -c option\&.
  72 .TP
  73 -m
  74 Use MD5 encryption for passwords\&. On Windows, Netware and TPF, this is the default\&.
  75 .TP
  76 -d
  77 Use crypt() encryption for passwords\&. The default on all platforms but Windows, Netware and TPF\&. Though possibly supported by htdbm on all platforms, it is not supported by the httpd server on Windows, Netware and TPF\&.
  78 .TP
  79 -s
  80 Use SHA encryption for passwords\&. Facilitates migration from/to Netscape servers using the LDAP Directory Interchange Format (ldif)\&.
  81 .TP
  82 -p
  83 Use plaintext passwords\&. Though htdbm will support creation on all platforms, the httpd daemon will only accept plain text passwords on Windows, Netware and TPF\&.
  84 .TP
  85 -l
  86 Print each of the usernames and comments from the database on stdout\&.
  87 .TP
  88 -t
  89 Interpret the final parameter as a comment\&. When this option is specified, an additional string can be appended to the command line; this string will be stored in the "Comment" field of the database, associated with the specified username\&.
  90 .TP
  91 -v
  92 Verify the username and password\&. The program will print a message indicating whether the supplied password is valid\&. If the password is invalid, the program exits with error code 3\&.
  93 .TP
  94 -x
  95 Delete user\&. If the username exists in the specified DBM file, it will be deleted\&.
  96 .TP
  97 \fIfilename\fR
  98 The filename of the DBM format file\&. Usually without the extension \&.db, \&.pag, or \&.dir\&. If -c is given, the DBM file is created if it does not already exist, or updated if it does exist\&.
  99 .TP
 100 \fIusername\fR
 101 The username to create or update in \fIpasswdfile\fR\&. If \fIusername\fR does not exist in this file, an entry is added\&. If it does exist, the password is changed\&.
 102 .TP
 103 \fIpassword\fR
 104 The plaintext password to be encrypted and stored in the DBM file\&. Used only with the -b flag\&.
 105 .TP
 106 -T\fIDBTYPE\fR
 107 Type of DBM file (SDBM, GDBM, DB, or "default")\&.
 108
 109 .SH "BUGS"
 110
 111 .PP
 112 One should be aware that there are a number of different DBM file formats in existence, and with all likelihood, libraries for more than one format may exist on your system\&. The three primary examples are SDBM, NDBM, GNU GDBM, and Berkeley/Sleepycat DB 2/3/4\&. Unfortunately, all these libraries use different file formats, and you must make sure that the file format used by \fIfilename\fR is the same format that htdbm expects to see\&. htdbm currently has no way of determining what type of DBM file it is looking at\&. If used against the wrong format, will simply return nothing, or may create a different DBM file with a different name, or at worst, it may corrupt the DBM file if you were attempting to write to it\&.
 113
 114 .PP
 115 One can usually use the file program supplied with most Unix systems to see what format a DBM file is in\&.
 116
 117 .SH "EXIT STATUS"
 118
 119 .PP
 120 htdbm returns a zero status ("true") if the username and password have been successfully added or updated in the DBM File\&. htdbm returns 1 if it encounters some problem accessing files, 2 if there was a syntax problem with the command line, 3 if the password was entered interactively and the verification entry didn't match, 4 if its operation was interrupted, 5 if a value is too long (username, filename, password, or final computed record), 6 if the username contains illegal characters (see the Restrictions section), and 7 if the file is not a valid DBM password file\&.
 121
 122 .SH "EXAMPLES"
 123
 124 .nf
 125
 126       htdbm /usr/local/etc/apache/\&.htdbm-users jsmith
 127
 128 .fi
 129
 130 .PP
 131 Adds or modifies the password for user jsmith\&. The user is prompted for the password\&. If executed on a Windows system, the password will be encrypted using the modified Apache MD5 algorithm; otherwise, the system's crypt() routine will be used\&. If the file does not exist, htdbm will do nothing except return an error\&.
 132
 133 .nf
 134
 135       htdbm -c /home/doe/public_html/\&.htdbm jane
 136
 137 .fi
 138
 139 .PP
 140 Creates a new file and stores a record in it for user jane\&. The user is prompted for the password\&. If the file exists and cannot be read, or cannot be written, it is not altered and htdbm will display a message and return an error status\&.
 141
 142 .nf
 143
 144       htdbm -mb /usr/web/\&.htdbm-all jones Pwd4Steve
 145
 146 .fi
 147
 148 .PP
 149 Encrypts the password from the command line (Pwd4Steve) using the MD5 algorithm, and stores it in the specified file\&.
 150
 151 .SH "SECURITY CONSIDERATIONS"
 152
 153 .PP
 154 Web password files such as those managed by htdbm should \fInot\fR be within the Web server's URI space -- that is, they should not be fetchable with a browser\&.
 155
 156 .PP
 157 The use of the -b option is discouraged, since when it is used the unencrypted password appears on the command line\&.
 158
 159 .SH "RESTRICTIONS"
 160
 161 .PP
 162 On the Windows and MPE platforms, passwords encrypted with htdbm are limited to no more than 255 characters in length\&. Longer passwords will be truncated to 255 characters\&.
 163
 164 .PP
 165 The MD5 algorithm used by htdbm is specific to the Apache software; passwords encrypted using it will not be usable with other Web servers\&.
 166
 167 .PP
 168 Usernames are limited to 255 bytes and may not include the character :\&.
 169