<?xml version="1.0"?>

<!DOCTYPE modulesynopsis SYSTEM "/style/modulesynopsis.dtd">

<?xml-stylesheet type="text/xsl" href="/style/manual.en.xsl"?>

<modulesynopsis metafile="mod_authn_anon.xml.meta">

<name>mod_authn_anon</name>

<description>Allows "anonymous" user access to authenticated

areas</description>

<status>Extension</status>

<sourcefile>mod_authn_anon.c</sourcefile>

<identifier>authn_anon_module</identifier>

<compatibility>Available in Apache 2.1 and later</compatibility>

<summary>

<p>This module provides authentication front-ends such as

<module>mod_auth_basic</module> to authenticate users similar

to anonymous-ftp sites, <em>i.e.</em> have a 'magic' user id

'anonymous' and the email address as a password. These email

addresses can be logged.</p>

<p>Combined with other (database) access control methods, this

allows for effective user tracking and customization according

to a user profile while still keeping the site open for

'unregistered' users. One advantage of using Auth-based user

tracking is that, unlike magic-cookies and funny URL

pre/postfixes, it is completely browser independent and it

allows users to share URLs.</p>

<p>When using <module>mod_auth_basic</module>, this module is invoked

via the <directive module="mod_auth_basic">AuthBasicProvider</directive>

directive with the <code>anon</code> value.</p>

</summary>

<section id="example"><title>Example</title>

<p>The example below is combined with "normal" htpasswd-file based

authentication and allows users in additionally as 'guests' with the

following properties:</p>

<ul>

<li>It insists that the user enters a userID.

(<directive module="mod_authn_anon"

>Anonymous_NoUserID</directive>)</li>

<li>It insists that the user enters a password.

(<directive module="mod_authn_anon"

>Anonymous_MustGiveEmail</directive>)</li>

<li>The password entered must be a valid email address, <em>i.e.</em>

contain at least one '@' and a '.'.

(<directive module="mod_authn_anon"

>Anonymous_VerifyEmail</directive>)</li>

<li>The userID must be one of <code>anonymous guest www test

welcome</code> and comparison is <strong>not</strong> case

sensitive. (<directive module="mod_authn_anon"

>Anonymous</directive>)</li>

<li>And the Email addresses entered in the passwd field are

logged to the error log file.

(<directive module="mod_authn_anon"

>Anonymous_LogEmail</directive>)</li>

</ul>

<example><title>Example</title>

<highlight language="config">

&lt;Directory /var/www/html/private&gt;

AuthName "Use 'anonymous' &amp; Email address for guest entry"

AuthType Basic

AuthBasicProvider file anon

AuthUserFile /path/to/your/.htpasswd

Anonymous_NoUserID off

Anonymous_MustGiveEmail on

Anonymous_VerifyEmail on

Anonymous_LogEmail on

Anonymous anonymous guest www test welcome

Require valid-user

&lt;/Directory&gt;

</highlight>

</example>

</section>

<directivesynopsis>

<name>Anonymous</name>

<description>Specifies userIDs that are allowed access without

password verification</description>

<syntax>Anonymous <var>user</var> [<var>user</var>] ...</syntax>

<contextlist><context>directory</context><context>.htaccess</context>

</contextlist>

<override>AuthConfig</override>

<usage>

<p>A list of one or more 'magic' userIDs which are allowed

access without password verification. The userIDs are space

separated. It is possible to use the ' and " quotes to allow a

space in a userID as well as the \ escape character.</p>

<p>Please note that the comparison is

<strong>case-IN-sensitive</strong>.<br />

It's strongly recommended that the magic username

'<code>anonymous</code>' is always one of the allowed

userIDs.</p>

<example><title>Example:</title>

Anonymous anonymous "Not Registered" "I don't know"

</example>

<p>This would allow the user to enter without password

verification by using the userIDs "anonymous",

"AnonyMous", "Not Registered" and "I Don't Know".</p>

<p>As of Apache 2.1 it is possible to specify the userID as

"<code>*</code>". That allows <em>any</em> supplied userID to be

accepted.</p>

</usage>

</directivesynopsis>

<directivesynopsis>

<name>Anonymous_LogEmail</name>

<description>Sets whether the password entered will be logged in the

error log</description>

<syntax>Anonymous_LogEmail On|Off</syntax>

<default>Anonymous_LogEmail On</default>

<contextlist><context>directory</context><context>.htaccess</context>

</contextlist>

<override>AuthConfig</override>

<usage>

<p>When set <code>On</code>, the default, the 'password' entered

(which hopefully contains a sensible email address) is logged in

the error log.</p>

</usage>

</directivesynopsis>

<directivesynopsis>

<name>Anonymous_MustGiveEmail</name>

<description>Specifies whether blank passwords are allowed</description>

<syntax>Anonymous_MustGiveEmail On|Off</syntax>

<default>Anonymous_MustGiveEmail On</default>

<contextlist><context>directory</context><context>.htaccess</context>

</contextlist>

<override>AuthConfig</override>

<usage>

<p>Specifies whether the user must specify an email address as

the password. This prohibits blank passwords.</p>

</usage>

</directivesynopsis>

<directivesynopsis>

<name>Anonymous_NoUserID</name>

<description>Sets whether the userID field may be empty</description>

<syntax>Anonymous_NoUserID On|Off</syntax>

<default>Anonymous_NoUserID Off</default>

<contextlist><context>directory</context><context>.htaccess</context>

</contextlist>

<override>AuthConfig</override>

<usage>

<p>When set <code>On</code>, users can leave the userID (and

perhaps the password field) empty. This can be very convenient for

MS-Explorer users who can just hit return or click directly on the

OK button; which seems a natural reaction.</p>

</usage>

</directivesynopsis>

<directivesynopsis>

<name>Anonymous_VerifyEmail</name>

<description>Sets whether to check the password field for a correctly

formatted email address</description>

<syntax>Anonymous_VerifyEmail On|Off</syntax>

<default>Anonymous_VerifyEmail Off</default>

<contextlist><context>directory</context><context>.htaccess</context>

</contextlist>

<override>AuthConfig</override>

<usage>

<p>When set <code>On</code> the 'password' entered is checked for

at least one '@' and a '.' to encourage users to enter valid email

addresses (see the above <directive

module="mod_authn_anon">Anonymous_LogEmail</directive>).</p>

</usage>

</directivesynopsis>

</modulesynopsis>