httpd-docs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Ben Laurie <...@algroup.co.uk>
Subject Re: Strawman XML
Date Tue, 07 Sep 1999 22:29:50 GMT
Dirk-Willem van Gulik wrote:
> 
> As a sequel on the previous question.. "has anyone parsed/recorded the
> apache documentation into a semantic format (such as one could use
> for the configurators) or automatic generation of, say a PDF version of
> the documents ??".. here is a followup:
> 
> Does anyone see great error or fundamental wrongs with the attached
> strawman ? It is the result of half an hour of perl hacking and 10 minutes
> of touch up. The script more or less works for all module mod_*.html
> files. The example below should be complete; i.e. there is no information
> lost in the transformation; and the orignal HTML can be reconstructed.
> 
> I'd like to hear some noice from people writing configurators, just to see
> where they are heading.. and from people thinking of improving the doc's,
> having multiple language variants, etc.
> 
> Dw
> 
> <MODULE id="manual/mod/mod_auth">
> <TITLE>
>         Apache module mod_auth
> </TITLE>
> <SUMMARY>
>         This module is contained in the <CODE>mod_auth.c</CODE> file, and
>         is compiled in by default. It provides for user authentication using
>         textual files.
> </SUMMARY>
> <SUMMARY LANG="nl">
>         De mod_auth module voorziet in toegangs controle op basis van text
>         bestanden met gebruikersnaam en wachtwoord gegevens.
>         <p>
>         Deze code voor deze module bevindt zich in het bestand <CODE>mod_auth.c</CODE>
>         en maakt deel uit van de groep die standaard mee gecompileerd
>         wordt.
> </SUMMARY>
> <DIRECTIVE id="AuthGroupFile">
>         <NAME>
>                 AuthGroupFile
>         </NAME>
>         <SYNTAX TYPE="TAKEONE">
>                 <ARGUMENT TYPE="filename">
>                         <DESCRIPTION>
>                                 AuthGroupFile <EM>filename</EM>
>                         </DESCRIPTION>

This can't be right: the description for the whole line is nested within
a single argument.

>                 </ARGUMENT>
>         <CONTEXT>
>                 directory, .htaccess
>         </CONTEXT>
>         <OVERRIDE>
>                 AuthConfig
>         </OVERRIDE>
>         <STATUS>
>                 Base
>         </STATUS>
>         <MODULE>
>                 mod_auth
>         </MODULE>
>         <TOKEN>
>                 The AuthGroupFile directive sets the name of a textual file containing
the list
>                 of user groups for user authentication. <EM>Filename</EM>
is the path

<EM>Filename</EM> should be a reference to the argument (forgot how you
do that in XML). Not sure about including things like <EM> at all,
anyway.

>                 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 ServerRoot.
>                 <P>
>                 Each line of the group file contains a groupname followed by a colon,
followed
>                 by the member usernames separated by spaces.
>                 <EXAMPLE>
>                         mygroup: bob joe anne
>                 </EXAMPLE>
>                 Note that searching large text files is <EM>very</EM> inefficient;
>                 <IA REF="AuthDBMGroupFile/> should be used instead.
>                 <P>
>         </TOKEN>
>         <SECURITY>
>                 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.
>         <SECURITY>
>         <RELATED>
>                 <A HREF="core.html#authname">AuthName</A>,

XML refs, not HTML refs, surely?

>                 <A HREF="core.html#authtype">AuthType</A>
>                 <A HREF="#authuserfile">AuthUserFile</A>
>         <RELATED>
> </DIRECTIVE>
> <DIRECTIVE id="AuthUserFile</A>">
>         <NAME>AuthUserFile</A></NAME>
>         <SYNTAX TYPE="TAKEONE">
>                 <ARGUMENT TYPE="filename">
>                         <DESCRIPTION>
>                                 AuthUserFile <EM>filename</EM>
>                         </DESCRIPTION>
>                 </ARGUMENT>
>         </SYNTAX>

Same problem as above

>         <CONTEXT>
>                  directory, .htaccess
>         </CONTEXT>
>         <OVERRIDE>
>                  AuthConfig
>         </OVERRIDE>
>         <STATUS>
>                  Base
>         </STATUS>
>         <MODULE>
>                  mod_auth
>         </MODULE>
>         <TOKEN>
>                 The AuthUserFile directive sets the name of a textual file containing
>                 the list of users and passwords for user
>                 authentication. <EM>Filename</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 ServerRoot.
>                 <P>
>                 Each line of the user file file contains a username followed
>                 by a colon, followed by the crypt() encrypted password. The behavior
>                 of multiple occurrences of the same user is undefined.
>                 <P>
>                 The utility <code>htpasswd</code> 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.
>                 <EXAMPLE>
>                         <code>htpasswd -c Filename username</code><br>
>                         Create a password file 'Filename' with 'username'
>                         as the initial ID. It will prompt for the password.
>                         <code>htpasswd Filename username2</code><br>
>                         Adds or modifies in password file 'Filename' the 'username'.
>                 </EXAMPLE>
>                 <P> Note that
>                 searching large text files is <EM>very</EM> inefficient;
>                 <IA REF="AuthDBMUserFile"> should be used instead.
>                 <P>
>         </TOKEN>
>         <SECURITY>
>                 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>
>         </SECURITY>
>         <RELATED>
>                 <A HREF="core.html#authname">AuthName</A>,
>                 <A HREF="core.html#authtype">AuthType</A>
>                 <A HREF="#authgroupfile">AuthGroupFile</A>
>         </RELATED>
> </DIRECTIVE>
> 
> <DIRECTIVE id="AuthAuthoritative</A>">
>         <NAME>AuthAuthoritative</A></NAME>
>         <SYNTAX TYPE="TAKEONE">
>                 <ARGUMENT TYPE="flag">
>                         <DEFAULT VALUE="On"/>
>                         <DESCRIPTION>
>                                 AuthAuthoritative &lt; <STRONG> on</STRONG>(default)
| off &gt;
>                         </DESCRIPTION>
>                 </ARGUMENT>
>         </SYNTAX>
>         <CONTEXT>
>                  directory, .htaccess
>         </CONTEXT>
>         <OVERRIDE>
>                  AuthConfig
>         </OVERRIDE>
>         <STATUS>
>                  Base
>         </STATUS>
>         <MODULE>
>                  mod_auth
>         </MODULE>
>         <DEFAULT>
>                  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.
>         </DEFAULT>
>         <TOKEN>
>                 Setting the AuthAuthoritative 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>
>                 So if a userID appears in the database of more than one module; or if
>                 a valid require 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>
>                 A common use for this is in conjunction with one of the database
>                 modules; such as <A
>                 HREF="mod_auth_db.html"><CODE>mod_auth_db.c</CODE></A>,
<A
>                 HREF="mod_auth_dbm.html"><CODE>mod_auth_dbm.c</CODE></A>,
>                 <CODE>mod_auth_msql.c</CODE>, and <A
>                 HREF="mod_auth_anon.html"><CODE>mod_auth_anon.c</CODE></A>.
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 AuthUserFile.
>                 <P>
>         </TOKEN>
>         <SECURITY>
>                 Security: 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 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.
>         </SECURITY>
>         <RELATED>
>                 <A HREF="core.html#authname">AuthName</A>,
>                 <A HREF="core.html#authtype">AuthType</A>
>                 <A HREF="#authgroupfile">AuthGroupFile</A>
>         </RELATED>
> </DIRECTIVE>
> <NOTES>
> </NOTES>
> </MODULE>

--
http://www.apache-ssl.org/ben.html

"My grandfather once told me that there are two kinds of people: those
who work and those who take the credit. He told me to try to be in the
first group; there was less competition there."
     - Indira Gandhi

Mime
View raw message