granicus.if.org Git - apache/blob - docs/manual/programs/htpasswd.xml

   1 <?xml version='1.0' encoding='UTF-8' ?>
   2 <!DOCTYPE manualpage SYSTEM "../style/manualpage.dtd">
   3 <?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
   4 <manualpage metafile="htpasswd.xml.meta">
   5 <parentdocument href="./">Programs</parentdocument>
   6
   7 <title>htpasswd - Manage user files for basic authentication</title>
   8
   9 <summary>
  10     <p><code>htpasswd</code> is used to create and update the flat-files used to
  11     store usernames and password for basic authentication of HTTP users. If
  12     <code>htpasswd</code> cannot access a file, such as not being able to write
  13     to the output file or not being able to read the file in order to update it,
  14     it returns an error status and makes no changes.</p>
  15
  16     <p>Resources available from the Apache HTTP server can be restricted to
  17     just the users listed in the files created by <code>htpasswd</code>. This
  18     program can only manage usernames and passwords stored in a flat-file. It
  19     can encrypt and display password information for use in other types of data
  20     stores, though. To use a DBM database see <a
  21     href="dbmmanage.html">dbmmanage</a>.</p>
  22
  23     <p><code>htpasswd</code> encrypts passwords using either a version of MD5
  24     modified for Apache, or the system's <code>crypt()</code> routine. Files
  25     managed by <code>htpasswd</code> may contain both types of passwords; some
  26     user records may have MD5-encrypted passwords while others in the same file
  27     may have passwords encrypted with <code>crypt()</code>.</p>
  28
  29     <p>This manual page only lists the command line arguments. For details of
  30     the directives necessary to configure user authentication in
  31     <a href="httpd.html">httpd</a> see the Apache manual, which is part of the
  32     Apache distribution or can be found at <a href="http://httpd.apache.org"
  33     >http://httpd.apache.org/</a>.</p>
  34 </summary>
  35 <seealso><a href="httpd.html">httpd</a></seealso>
  36 <seealso><p>The scripts in support/SHA1 which come with the
  37 distribution.</p></seealso>
  38
  39 <section id="synopsis"><title>Synopsis</title>
  40     <p><code><strong>htpasswd</strong>
  41     [ -<strong>c</strong> ]
  42     [ -<strong>m</strong> ] <var>passwdfile</var> <var>username</var></code></p>
  43
  44     <p><code><strong>htpasswd</strong> -<strong>b</strong>
  45     [ -<strong>c</strong> ]
  46     [ -<strong>m</strong> |
  47       -<strong>d</strong> |
  48       -<strong>p</strong> |
  49       -<strong>s</strong> ] <var>passwdfile</var> <var>username</var>
  50     <var>password</var></code></p>
  51
  52     <p><code><strong>htpasswd</strong> -<strong>n</strong>
  53     [ -<strong>m</strong> |
  54       -<strong>d</strong> |
  55       -<strong>s</strong> |
  56       -<strong>p</strong> ] <var>username</var></code></p>
  57
  58     <p><code><strong>htpasswd</strong> -<strong>nb</strong>
  59     [ -<strong>m</strong> |
  60       -<strong>d</strong> |
  61       -<strong>s</strong> |
  62       -<strong>p</strong> ] <var>username</var> <var>password</var></code></p>
  63 </section>
  64
  65 <section id="options"><title>Options</title>
  66     <dl>
  67     <dt><code>-b</code></dt>
  68     <dd>Use batch mode; <em>i.e.</em>, get the password from the command line
  69     rather than prompting for it. This option should be used with extreme care,
  70     since <strong>the password is clearly visible</strong> on the command
  71     line.</dd>
  72
  73     <dt><code>-c</code></dt>
  74     <dd>Create the <var>passwdfile</var>. If <var>passwdfile</var> already
  75     exists, it is rewritten and truncated. This option cannot be combined with
  76     the <code>-n</code> option.</dd>
  77
  78     <dt><code>-n</code></dt>
  79     <dd>Display the results on standard output rather than updating a file.
  80     This is useful for generating password records acceptable to Apache for
  81     inclusion in non-text data stores. This option changes the syntax of the
  82     command line, since the <var>passwdfile</var> argument (usually the first
  83     one) is omitted. It cannot be combined with the <code>-c</code> option.</dd>
  84
  85     <dt><code>-m</code></dt>
  86     <dd>Use MD5 encryption for passwords. On Windows, Netware and TPF, this is
  87     the default.</dd>
  88
  89     <dt><code>-d</code></dt>
  90     <dd>Use <code>crypt()</code> encryption for passwords. The default on all
  91     platforms but Windows, Netware and TPF. Though possibly supported by
  92     <code>htpasswd</code> on all platforms, it is not supported by the
  93     <a href="httpd.html">httpd</a> server on Windows, Netware and TPF.</dd>
  94
  95     <dt><code>-s</code></dt>
  96     <dd>Use SHA encryption for passwords. Facilitates migration from/to Netscape
  97     servers using the LDAP Directory Interchange Format (ldif).</dd>
  98
  99     <dt><code>-p</code></dt>
 100     <dd>Use plaintext passwords. Though <code>htpasswd</code> will support
 101     creation on all platforms, the <a href="httpd.html">httpd</a> daemon will
 102     only accept plain text passwords on Windows, Netware and TPF.</dd>
 103
 104     <dt><code><var>passwdfile</var></code></dt>
 105     <dd>Name of the file to contain the user name and password. If
 106     <code>-c</code> is given, this file is created if it does not already exist,
 107     or rewritten and truncated if it does exist.</dd>
 108
 109     <dt><code><var>username</var></code></dt>
 110     <dd>The username to create or update in <var>passwdfile</var>. If
 111     <var>username</var> does not exist in this file, an entry is added. If it
 112     does exist, the password is changed.</dd>
 113
 114     <dt><code><var>password</var></code></dt>
 115     <dd>The plaintext password to be encrypted and stored  in the file. Only
 116     used with the <code>-b</code> flag.</dd>
 117     </dl>
 118 </section>
 119
 120 <section id="exit"><title>Exit Status</title>
 121     <p><code>htpasswd</code> returns a zero status ("true") if the username and
 122     password have been successfully added or updated in the
 123     <var>passwdfile</var>. <code>htpasswd</code> returns <code>1</code> if it
 124     encounters some problem accessing files, <code>2</code> if there was a
 125     syntax problem with the command line, <code>3</code> if the password was
 126     entered interactively and the verification entry didn't match,
 127     <code>4</code> if its operation was interrupted, <code>5</code> if a value
 128     is too long (username, filename, password, or final computed record),
 129     <code>6</code> if the username contains illegal characters (see the
 130     <a href="#restrictions">Restrictions section</a>), and <code>7</code>
 131     if the file is not a valid password file.</p>
 132 </section>
 133
 134 <section id="examples"><title>Examples</title>
 135     <example>
 136       htpasswd /usr/local/etc/apache/.htpasswd-users jsmith
 137     </example>
 138
 139     <p>Adds or modifies the password for user <code>jsmith</code>. The user
 140     is prompted for the password. If executed on a Windows system, the password
 141     will be encrypted using the  modified Apache MD5 algorithm; otherwise, the
 142     system's <code>crypt()</code> routine will be used. If the file does not
 143     exist, <code>htpasswd</code> will do nothing except return an error.</p>
 144
 145     <example>
 146       htpasswd -c /home/doe/public_html/.htpasswd jane
 147     </example>
 148
 149     <p>Creates a new file and stores a record in it for user <code>jane</code>.
 150     The user is prompted for the password. If the file exists and cannot be
 151     read, or cannot be written, it is not altered and <code>htpasswd</code>
 152     will display a message and return an error status.</p>
 153
 154     <example>
 155       htpasswd -mb /usr/web/.htpasswd-all jones Pwd4Steve
 156     </example>
 157
 158     <p>Encrypts the password from the command line (<code>Pwd4Steve</code>)
 159     using the MD5 algorithm, and stores it in the specified file.</p>
 160 </section>
 161
 162 <section id="security"><title>Security Considerations</title>
 163     <p>Web password files such as those managed by <code>htpasswd</code> should
 164     <em>not</em> be within the Web server's URI space -- that is, they should
 165     not be fetchable with a browser.</p>
 166
 167     <p>The use of the <code>-b</code> option is discouraged, since when it is
 168     used the unencrypted password appears on the command line.</p>
 169 </section>
 170
 171 <section id="restrictions"><title>Restrictions</title>
 172     <p>On the Windows and MPE platforms, passwords encrypted with
 173     <code>htpasswd</code> are limited to no more than <code>255</code>
 174     characters in length. Longer passwords will be truncated to 255
 175     characters.</p>
 176
 177     <p>The MD5 algorithm used by <code>htpasswd</code> is specific to the Apache
 178     software; passwords encrypted using it will not be usable with other Web
 179     servers.</p>
 180
 181     <p>Usernames are limited to <code>255</code> bytes and may not include the
 182     character <code>:</code>.</p>
 183 </section>
 184
 185 </manualpage>