httpd-cvs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From sl...@apache.org
Subject cvs commit: httpd-2.0/docs/manual/mod mod_asis.xml mod_auth.xml mod_alias.xml
Date Mon, 18 Feb 2002 00:18:50 GMT
slive       02/02/17 16:18:50

  Added:       docs/manual/mod mod_asis.xml mod_auth.xml mod_alias.xml
  Log:
  Convert a few more modules to xml format.  The transformations are
  not yet live.
  
  Revision  Changes    Path
  1.1                  httpd-2.0/docs/manual/mod/mod_asis.xml
  
  Index: mod_asis.xml
  ===================================================================
  <?xml version="1.0"?>
  <?xml-stylesheet type="text/xsl" href="../style/manual.xsl"?>
  <modulesynopsis>
  
  <name>mod_asis</name>
  <description>Sends files that contain their own
  HTTP headers</description>
  <status>Base</status>
  <sourcefile>mod_asis.c</sourcefile>
  <identifier>asis_module</identifier>
  
  <summary>
      <p>This module provides the handler <code>send-as-is</code>
      which causes Apache to send the document without adding most of
      the usual HTTP headers.</p>
  
      <p>This can be used to send any kind of data from the server,
      including redirects and other special HTTP responses, without
      requiring a cgi-script or an nph script.</p>
  
      <p>For historical reasons, this module will also process any
      file with the mime type <code>httpd/send-as-is</code>.</p>
  </summary>
  
  <section><title>Usage</title>
  
      <p>In the server configuration file, associate files with the
      <code>send-as-is</code> handler <em>e.g.</em></p>
  
  <example>AddHandler send-as-is asis</example>
  
      <p>The contents of any file with a <code>.asis</code> extension
      will then be sent by Apache to the client with almost no
      changes. Clients will need HTTP headers to be attached, so do
      not forget them. A Status: header is also required; the data
      should be the 3-digit HTTP response code, followed by a textual
      message.</p>
  
      <p>Here's an example of a file whose contents are sent <em>as
      is</em> so as to tell the client that a file has
      redirected.</p>
  
  
  <example>Status: 301 Now where did I leave that URL<br />
         Location: http://xyz.abc.com/foo/bar.html<br />
         Content-type: text/html<br />
        <br />
         &lt;HTML&gt;<br />
         &lt;HEAD&gt;<br />
         &lt;TITLE&gt;Lame excuses'R'us&lt;/TITLE&gt;<br />
         &lt;/HEAD&gt;<br />
         &lt;BODY&gt;<br />
         &lt;H1&gt;Fred's exceptionally wonderful page has moved
        to<br />
         &lt;A
        HREF="http://xyz.abc.com/foo/bar.html"&gt;Joe's&lt;/A&gt;
        site.<br />
         &lt;/H1&gt;<br />
         &lt;/BODY&gt;<br />
         &lt;/HTML&gt;
  </example>
  
      <p>Notes: the server always adds a Date: and Server: header to
      the data returned to the client, so these should not be
      included in the file. The server does <em>not</em> add a
      Last-Modified header; it probably should. </p>
  </section>
  
  </modulesynopsis>
  
  
  
  1.1                  httpd-2.0/docs/manual/mod/mod_auth.xml
  
  Index: mod_auth.xml
  ===================================================================
  <?xml version="1.0"?>
  <?xml-stylesheet type="text/xsl" href="../style/manual.xsl"?>
  <modulesynopsis>
  
  <name>mod_auth</name>
  <description>User authentication using text files</description>
  <status>Base</status>
  <sourcefile>mod_auth.c</sourcefile>
  <identifier>auth_module</identifier>
  
  <summary>
  
      <p>This module allows the use of HTTP Basic Authentication to
      restrict access by looking up users in plain text password and
      group files. Similar functionality and greater scalability is
      provided by <module>mod_auth_dbm</module>.  HTTP Digest
      Authentication is provided by
      <module>mod_auth_digest</module>.</p>
  
  </summary>
  <seealso><directive module="core">Require</directive></seealso>
  <seealso><directive module="core">Satisfy</directive></seealso>
  <seealso><directive module="core">AuthName</directive></seealso>
  <seealso><directive module="core">AuthType</directive></seealso>
  
  <directivesynopsis>
  <name>AuthGroupFile</name>
  <description>Sets the name of a text file containing the list
  of user groups for authentication</description>
  <syntax>AuthGroupFile <em>file-path</em></syntax>
  <contextlist><context>directory</context><context>.htaccess</context>
  </contextlist>
  <override>AuthConfig</override>
  
  <usage>
      <p>The <directive>AuthGroupFile</directive> directive sets the
      name of a textual file containing the list of user groups for user
      authentication.  <em>File-path</em> is the path to the group
      file. If it is not absolute (<em>i.e.</em>, if it doesn't begin
      with a slash), it is treated as relative to the <directive
      module="core">ServerRoot</directive>.</p>
  
      <p>Each line of the group file contains a groupname followed by a
      colon, followed by the member usernames separated by spaces.
      Example:</p> 
  
  <example>mygroup: bob joe anne</example> 
  
      <p>Note that searching large text files is <em>very</em>
      inefficient; <directive
      module="mod_auth_dbm">AuthDBMGroupFile</directive> should be used
      instead.</p>
  
  <note><title>Security</title>
      <p>Make sure that the AuthGroupFile is stored outside
      the document tree of the web-server; do <em>not</em> put it in
      the directory that it protects. Otherwise, clients will be able
      to download the AuthGroupFile.</p>
  </note>
  </usage>
  </directivesynopsis>
  
  <directivesynopsis>
  <name>AuthUserFile</name>
  <description>Sets the name of a text file containing the list of users and
  passwords for authentication</description>
  <syntax>AuthUserFile <em>file-path</em></syntax>
  <contextlist><context>directory</context><context>.htaccess</context>
  </contextlist>
  <override>AuthConfig</override>
  
  <usage>
      <p>The <directive>AuthUserFile</directive> directive sets the name
      of a textual file containing the list of users and passwords for
      user authentication. <em>File-path</em> is the path to the user
      file. If it is not absolute (<em>i.e.</em>, if it doesn't begin
      with a slash), it is treated as relative to the <directive
      module="core">ServerRoot</directive>.</p>
  
      <p>Each line of the user file file contains a username followed by
      a colon, followed by the <code>crypt()</code> encrypted
      password. The behavior of multiple occurrences of the same user is
      undefined.</p>
  
      <p>The utility <a href="../programs/htpasswd.html">htpasswd</a>
      which is installed as part of the binary distribution, or which
      can be found in <code>src/support</code>, is used to maintain
      this password file. See the <code>man</code> page for more
      details. In short:</p>
  
      <p>Create a password file 'Filename' with 'username' as the
      initial ID. It will prompt for the password:</p>
  <example>htpasswd -c Filename username</example>
  
  <p>Adds or modifies in password file 'Filename' the 'username':</p>
  <example>htpasswd Filename username2</example>
  
      <p>Note that searching large text files is <em>very</em>
      inefficient; <directive
      module="mod_auth_dbm">AuthDBMUserFile</directive> should be used
      instead.</p>
  
  <note><title>Security</title><p>Make sure that the AuthUserFile
is
  stored outside the document tree of the web-server; do <em>not</em>
  put it in the directory that it protects. Otherwise, clients will be
  able to download the AuthUserFile.</p></note>
  
  </usage>
  </directivesynopsis>
  
  <directivesynopsis>
  <name>AuthAuthoritative</name>
  <description>Sets whether authorization and authentication are
  passed to lower level modules</description>
  <syntax>AuthAuthoritative on|off</syntax>
  <default>AuthAuthoritative on</default>
  <contextlist><context>directory</context><context>.htaccess</context>
  </contextlist>
  <override>AuthConfig</override>
  
  <usage>
  
  <note>This information has not been updated for Apache 2.0, which
  uses a different system for module ordering.</note>
  
      <p>Setting the <directive>AuthAuthoritative</directive> directive
      explicitly to <strong>'off'</strong> allows for both
      authentication and authorization to be passed on to lower level
      modules (as defined in the <code>Configuration</code> and
      <code>modules.c</code> files) if there is <strong>no
      userID</strong> or <strong>rule</strong> matching the supplied
      userID. If there is a userID and/or rule specified; the usual
      password and access checks will be applied and a failure will give
      an Authorization Required reply.</p>
  
      <p>So if a userID appears in the database of more than one module;
      or if a valid <directive module="core">Require</directive>
      directive applies to more than one module; then the first module
      will verify the credentials; and no access is passed on;
      regardless of the AuthAuthoritative setting.</p>
  
      <p>A common use for this is in conjunction with one of the
      database modules; such as <module>auth_dbm</module>,
      <code>mod_auth_msql</code>, and <module>mod_auth_anon</module>.
      These modules supply the bulk of the user credential checking; but
      a few (administrator) related accesses fall through to a lower
      level with a well protected <directive
      module="mod_auth">AuthUserFile</directive>.</p>
  
      <p>By default; control is not passed on; and an unknown userID or
      rule will result in an Authorization Required reply. Not setting
      it thus keeps the system secure; and forces an NCSA compliant
      behaviour.</p>
  
      <note><title>Security</title> Do consider the implications of
      allowing a user to allow fall-through in his .htaccess file; and
      verify that this is really what you want; Generally it is easier
      to just secure a single .htpasswd file, than it is to secure a
      database such as mSQL. Make sure that the <directive
      module="mod_auth">AuthUserFile</directive> is stored outside the
      document tree of the web-server; do <em>not</em> put it in the
      directory that it protects. Otherwise, clients will be able to
      download the <directive module="mod_auth">AuthUserFile</directive>.
      </note>
  </usage>
  </directivesynopsis>
  
  </modulesynopsis>
  
  
  1.1                  httpd-2.0/docs/manual/mod/mod_alias.xml
  
  Index: mod_alias.xml
  ===================================================================
  <?xml version="1.0"?>
  <?xml-stylesheet type="text/xsl" href="../style/manual.xsl"?>
  <modulesynopsis>
  
  <name>mod_alias</name>
  <description>Provides for mapping different parts of the host
      filesystem in the document tree and for URL redirection</description>
  <status>Base</status>
  <sourcefile>mod_alias.c</sourcefile>
  <identifier>alias_module</identifier>
  
  <summary>
      <p>The directives contained in this module allow for manipulation
      and control of URLs as requests arrive at the server. The
      <directive module="mod_alias">Alias</directive> and <directive
      module="mod_alias">ScriptAlias</directive> directives are used to
      map between URLs and filesystem paths.  This allows for content
      which is not directly under the <directive
      module="core">DocumentRoot</directive> served as part of the web
      document tree. The <directive
      module="mod_alias">ScriptAlias</directive> directive has the
      additional effect of marking the target directory as containing
      only CGI scripts.</p>
  
      <p>The <directive module="mod_alias">Redirect</directive>
      directives are used to instruct clients to make a new request with
      a different URL. They are often used when a resource has moved to
      a new location.</p>
  
      <p>A more powerful and flexible set of directives for
      manipulating URLs is contained in the <module>mod_rewrite</module>
      module.</p>
  </summary>
  
  <directivesynopsis>
  <name>Alias</name>
  <description>Maps URLs to filesystem locations</description>
  <syntax> Alias <em>URL-path
      file-path</em>|<em>directory-path</em></syntax>
  <contextlist><context>server config</context><context>virtual host</context>
  </contextlist>
  
  <usage>
  
      <p>The <directive>Alias</directive> directive allows documents to
      be stored in the local filesystem other than under the 
      <directive module="core">DocumentRoot</directive>. URLs with a
      (%-decoded) path beginning with <em>url-path</em> will be mapped
      to local files beginning with <em>directory-filename</em>.</p>
  
      <p>Example:</p>
  
  <example>Alias /image /ftp/pub/image</example>
  
      <p>A request for http://myserver/image/foo.gif would cause the
      server to return the file /ftp/pub/image/foo.gif.</p>
  
      <p>Note that if you include a trailing / on the
      <em>url-path</em> then the server will require a trailing / in
      order to expand the alias. That is, if you use <code>Alias
      /icons/ /usr/local/apache/icons/</code> then the url
      <code>/icons</code> will not be aliased.</p>
  
      <p>Note that you may need to specify additional <directive
      module="core">&lt;Directory&gt;</directive> sections which cover
      the <em>destination</em> of aliases.  Aliasing occurs before
      <directive module="core">&lt;Directory&gt;</directive> sections
      are checked, so only the destination of aliases are affected.
      (Note however <directive module="core">&lt;Location&gt;</directive>
      sections are run through once before aliases are performed, so
      they will apply.)</p>
  
  </usage>
  </directivesynopsis>
  
  <directivesynopsis>
  <name>AliasMatch</name>
  <description>Maps URLs to filesystem locations using regular 
  expressions</description>
  <syntax>AliasMatch <em>regex
      file-path</em>|<em>directory-path</em></syntax>
  <contextlist><context>server config</context><context>virtual host</context>
  </contextlist>
  
  <usage>
      <p>This directive is equivalent to <directive
      module="mod_alias">Alias</directive>, but makes use of standard
      regular expressions, instead of simple prefix matching. The
      supplied regular expression is matched against the URL-path, and
      if it matches, the server will substitute any parenthesized
      matches into the given string and use it as a filename. For
      example, to activate the <code>/icons</code> directory, one might
      use:</p>
  <example>
      AliasMatch ^/icons(.*) /usr/local/apache/icons$1
  </example>
  </usage>
  </directivesynopsis>
  
  <directivesynopsis>
  <name>Redirect</name>
  <description>Sends an external redirect asking the client to fetch
  a different URL</description>
  <syntax>Redirect [<em>status</em>] <em>URL-path URL</em></syntax>
  <contextlist><context>server config</context><context>virtual host</context>
  <context>directory</context><context>.htaccess</context></contextlist>
  <override>FileInfo</override>
  
  <usage>
      <p>The Redirect directive maps an old URL into a new one. The
      new URL is returned to the client which attempts to fetch it
      again with the new address. <em>URL-path</em> a (%-decoded)
      path; any requests for documents beginning with this path will
      be returned a redirect error to a new (%-encoded) URL beginning
      with <em>URL</em>.</p>
  
      <p>Example:</p>
  
  <example>Redirect /service http://foo2.bar.com/service</example>
  
      <p>If the client requests http://myserver/service/foo.txt, it
      will be told to access http://foo2.bar.com/service/foo.txt
      instead.</p>
  
  <note><title>Note</title> <p>Redirect directives take precedence
over
  Alias and ScriptAlias directives, irrespective of their ordering in
  the configuration file. Also, <em>URL-path</em> must be an absolute
  path, not a relative path, even when used with .htaccess files or
  inside of <directive module="core">&lt;Directory&gt;</directive>
  sections.</p></note>
  
      <p>If no <em>status</em> argument is given, the redirect will
      be "temporary" (HTTP status 302). This indicates to the client
      that the resource has moved temporarily. The <em>status</em>
      argument can be used to return other HTTP status codes:</p>
  
      <dl>
        <dt>permanent</dt>
  
        <dd>Returns a permanent redirect status (301) indicating that
        the resource has moved permanently.</dd>
  
        <dt>temp</dt>
  
        <dd>Returns a temporary redirect status (302). This is the
        default.</dd>
  
        <dt>seeother</dt>
  
        <dd>Returns a "See Other" status (303) indicating that the
        resource has been replaced.</dd>
  
        <dt>gone</dt>
  
        <dd>Returns a "Gone" status (410) indicating that the
        resource has been permanently removed. When this status is
        used the <em>url</em> argument should be omitted.</dd>
      </dl>
  
      <p>Other status codes can be returned by giving the numeric
      status code as the value of <em>status</em>. If the status is
      between 300 and 399, the <em>url</em> argument must be present,
      otherwise it must be omitted. Note that the status must be
      known to the Apache code (see the function
      <code>send_error_response</code> in http_protocol.c).</p>
  </usage>
  </directivesynopsis>
  
  <directivesynopsis>
  <name>RedirectMatch</name>
  <description>Sends an external redirect asking the client to fetch
  a different URL based on a regular expression match of the 
  current URL</description>
  <syntax>RedirectMatch [<em>status</em>] <em>regex URL</em></syntax>
  <contextlist><context>server config</context><context>virtual host</context>
  <context>directory</context><context>.htaccess</context></contextlist>
  <override>FileInfo</override>
  
  <usage>
      <p>This directive is equivalent to <directive
      module="mod_alias">Redirect</directive>, but makes use of standard
      regular expressions, instead of simple prefix matching. The
      supplied regular expression is matched against the URL-path, and
      if it matches, the server will substitute any parenthesized
      matches into the given string and use it as a filename. For
      example, to redirect all GIF files to like-named JPEG files on
      another server, one might use:</p>
  <example>
      RedirectMatch (.*)\.gif$ http://www.anotherserver.com$1.jpg
  </example>
  </usage>
  </directivesynopsis>
  
  <directivesynopsis>
  <name>RedirectTemp</name>
  <description>Sends an external temporary redirect asking the client to fetch
  a different URL</description>
  <syntax>RedirectTemp <em>URL-path URL</em></syntax>
  <contextlist><context>server config</context><context>virtual host</context>
  <context>directory</context><context>.htaccess</context></contextlist>
  <override>FileInfo</override>
  
  <usage>
      <p>This directive makes the client know that the Redirect is
      only temporary (status 302). Exactly equivalent to
      <code>Redirect temp</code>.</p>
  </usage>
  </directivesynopsis>
  
  <directivesynopsis>
  <name>RedirectPermanent</name>
  <description>Sends an external permanent redirect asking the client to fetch
  a different URL</description>
  <syntax>RedirectPermanent <em>URL-path URL</em></syntax>
  <contextlist><context>server config</context><context>virtual host</context>
  <context>directory</context><context>.htaccess</context></contextlist>
  <override>FileInfo</override>
  
  <usage>
      <p>This directive makes the client know that the Redirect is
      permanent (status 301). Exactly equivalent to <code>Redirect
      permanent</code>.</p>
  </usage>
  </directivesynopsis>
  
  <directivesynopsis>
  <name>ScriptAlias</name>
  <description>Maps a URL to a filesystem location and designates the
  target as a CGI script</description>
  <syntax>ScriptAlias 
  <em>URL-path file-path</em>|<em>directory-path</em></syntax>
  <contextlist><context>server config</context><context>virtual host</context>
  </contextlist>
  
  <usage>
      <p>The <directive>ScriptAlias</directive> directive has the same
      behavior as the <directive module="mod_alias">Alias</directive>
      directive, except that in addition it marks the target directory
      as containing CGI scripts that will be processed by <module
      >mod_cgi</module>'s cgi-script handler. URLs with a
      (%-decoded) path beginning with <em>URL-path</em> will be mapped
      to scripts beginning with the second argument which is a full
      pathname in the local filesystem.</p>
  
      <p>Example:</p>
  
  <example>ScriptAlias /cgi-bin/ /web/cgi-bin/</example>
  
      <p>A request for <code>http://myserver/cgi-bin/foo</code> would cause
the
      server to run the script <code>/web/cgi-bin/foo</code>.</p>
  </usage>
  </directivesynopsis>
  
  <directivesynopsis>
  <name>ScriptAliasMatch</name>
  <description>Maps a URL to a filesystem location using a regular expression
  and designates the target as a CGI script</description>
  <syntax>ScriptAliasMatch
  <em>regex file-path</em>|<em>directory-path</em></syntax>
  <contextlist><context>server config</context><context>virtual host</context>
  </contextlist>
  
  <usage>
      <p>This directive is equivalent to <directive module="mod_alias"
      >ScriptAlias</directive>, but makes use of standard
      regular expressions, instead of simple prefix matching. The
      supplied regular expression is matched against the URL-path,
      and if it matches, the server will substitute any parenthesized
      matches into the given string and use it as a filename. For
      example, to activate the standard <code>/cgi-bin</code>, one
      might use:</p>
  <example>
      ScriptAliasMatch ^/cgi-bin(.*) /usr/local/apache/cgi-bin$1
  </example>
  </usage>
  </directivesynopsis>
  
  </modulesynopsis>
  
  
  
  

Mime
View raw message