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 < <STRONG> > on</STRONG>(default) | off > > </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
