NetAuth

Web-Based Email Management System

NetAuth allows...

• Users to create and manage their own email accounts.
• Power users to create and manage x accounts, where x is specified on account creation.
• Domain administrators to manage accounts on their domain.
• System administrators to manage all email accounts.

NetAuth works best with DMail Mail Server and CWMail email client program, but can be used with any mail server providing one of the following is true:

NetAuth has several special features if you are using CWMail, DMailWeb or WebMail, but otherwise still creates POP or IMAP accounts which can be used to recieve and send email with other email client programs.

Installation and management guide

This guide is intended for system administrators who are installing / customising or managing a site running NetAuth. NetAuth can be customised extensively to provide a tool which works seamlessly with your mail server and client email software. NetAuth can be extensively customized to provide distinctive web based email account creation and management service for your customers. The web pages which the client sees are easily modifiable to suit your particular needs. This allows them to be used as they are, or to be completely rewritten to provide a particular look and feel which matches other web pages from your site.

The following sections describe... Additional information...
NT Installation

The NetAuth CGI must be installed on your WEB server, in a directory which has already been  set up as containing CGI programs.  If you are unsure of how to set up a cgi program you should read your web server documentation. Normally, a server will have a special directory for storing CGI's. It may be called something similar to:
SERVER_ROOT\cgi-bin
or c:\inetpub\scripts
or "FrontPage Webs\Content\cgi-bin"

The self_extracting archive which has been downloaded will normally run nasetup once it has unpacked the files to a temporary directory. All you need to do is answer the questions in order to complete the installation.
If you want to handle the installation manually, use the following instructions....

From the command prompt type...
netauth40a.exe
cd\natemp

mkdir \netauth
copy * \netauth

mkdir \inetpub\wwwroot\nwimg
copy *.gif \inetpub\wwwroot\nwimg
copy *.jpg \inetpub\wwwroot\nwimg

copy netauth.exe \inetpub\scripts
copy netauth.ini \inetpub\scripts

cd ..
del \natemp\*
rmdir \natemp

Next you should edit the live copy of the configuration file "netauth.ini". This can be found in the \inetpub\scripts directory. You have a backup copy of the origional in the \netauth directory and it is suggested that, once you have the system running, you backup the live copy to the \netauth directory. So to edit the netauth.ini file use notepad, or another suitable text editor, and ensure that these settings are correct....

 Setting label Default value Example Explaination templates \netauth \netauth\tpl This is the path to the NetAuth .tpl files. These simple HTML files are used to display the pages which users see when they connect to Netauth.exe workarea \netauth\users This is the path to where NetAuth is allowed to store it's user information, and any other working information it requires. logpath \netauth\log This is where NetAuth will create it's logging files. These files can contain error, info or debugging messages depending on the value of the 'loglevel' ini setting. domain funkymail.com This is the mail domain name. pophost 121.2.33.45 This is the IP number or name of the pophost. Users are verified using this pophost. smtphost 121.2.33.45 This is the IP number or name of the smtphost. Any email sent by NetAuth is done using this smtp server. nwimg \nwimg \nwimg This is a relative URL to the directory where the NetAuth images are stored. prefix NULL abc_ This is the username prefix for created users. If authent_domain is set to true you will need to remove this setting. authent_process \dmail\nwauth.exe \dmail\nwauth.exe This is the full path to the NWAuth external authentication database. This should be the same as the authent_process in dmail.conf

Key
<templates> - This means that the value for this setting ( if none is given) is taken to be the value of the templates setting.
<vhost> - This means that the value for this setting ( if none is given) is taken to be the value of the vhost setting. This setting is a special setting which is specified if you are supporting multiple domains (see Supporting Virtual Domains).

If you plan to customize the template files (as most people do :-) then you should probably keep a copy of the original set so that you can later compare them with future releases. This may save you much effort when adding  new features into your customized set.

To test the installed NetAuth cgi you use a web browser. To use the user page, enter a url of the following form:
http://mysite.com/scripts/netauth.exe
To use the administrator's page, enter a url of the following form:
Then login as the account you set as the administration in netauth.ini, and NetAuth will give you administrative options

Alternatively, you can try the demonstration page nademo.htm supplied with NetAuth. This page contains several URL's to NetAuth in a form such as would appear on an ISP main page. So try

Unix Installation

The NetAuth CGI must be installed on your WEB server, in a directory which has already been set up as containing CGI programs.  If you are unsure of how to set up a cgi program you should read your web server documentation. Normally, a server will have a special directory for storing CGI's. It may be called something like....
SERVER_ROOT/cgi-bin or
"/home/httpd/cgi-bin"

The self_extracting archive which has been downloaded will normally run nasetup once it has unpacked the files to a temporary directory. All you need to do is answer the questions in order to complete the installation.
If you want to handle the installation manually, use the following instructions:

From the command prompt type..
uncompress netauth40a_linux.tar.Z
mkdir /natemp
tar -xvf netauth40a_linux.tar /natemp
cd /natemp

mkdir /var/spool/netauth
cp * /var/spool/netauth

cp *.gif /home/httpd/html/nwimg
cp *.jpg /home/httpd/html/nwimg

cp netauth.cgi /home/httpd/cgi-bin
cp netauth.ini /home/httpd/cgi-bin

cd ..
rm -rf /natemp/*
rm -rf /natemp

Next, the live copy of the configuration file "netauth.ini"should be edited. This can be found in the /home/httpd/cgi-bin directory. You have a backup copy of the origional in the /var/spool/netauth directory and it is suggested that, once you have the system running, you backup the live copy to the  /var/spool/netauth directory. So in order to edit the netauth.ini file, use vi or another suitable text editor and ensure that these settings are correct....

NOTE - The NetAuth CGI needs permission in order to create / edit and remove files in certain directories. These directories include the DMail directory where NWAuth is located, the DList directory, it's own workarea and the workarea of CWMail. In order to allow it access to the DMail directory it has to execute as root user, or the owner of the DMail directory. In order to do this in two commands...

chown root:root netauth.cgi
chmod +s netauth.cgi

 Setting label Default value Example Explaination templates /var/spool/ /var/spool/netauth/tpl This is the path to the NetAuth .tpl files. These simple HTML files are used to display the pages which users see when they connect to Netauth.exe workarea /var/spool/netauth/users This is the path to the place where NetAuth is allowed to store it's user information, and any other working information it requires. logpath /var/spool/netauth/log This is where NetAuth will create it's logging files. These files can contain error, info or debugging messages, depending on the value of the 'loglevel' ini setting. domain funkymail.com This is the mail domain name. pophost 121.2.33.45 This is the IP number or name of the pophost. Users are verified using this pophost. smtphost 121.2.33.45 This is the IP number or name of the smtphost. Any email sent by NetAuth is done using this smtp server. nwimg \nwimg \nwimg This is a relative URL to the directory where the NetAuth images are stored. prefix NULL abc_ This is the username prefix for created users. If authent_domain is set to true you will need to remove this setting. authent_process /usr/local/dmail/nwauth /usr/local/dmail/nwauth This is the full path to the NWAuth external authentication database. This should be the same as the authent_process in dmail.conf

Key
<templates> - This means that the value for this setting (if none is given) is taken to be the value of the templates setting.
<vhost> - This means that the value for this setting (if none is given) is taken to be the value of the vhost setting. This setting is a special setting which is specified if you are supporting virtual domains (see Supporting Virtual Domains).

If you plan to customize the template files (as most people do :-) then you should probably keep a copy of the original set so that you can later compare them with future releases. This may save you much effort when adding  new features into your customized set.

In order to test the installed NetAuth cgi you use a web browser. In order to use the user page, enter a url of the following form:
http://mysite.com/cgi-bin/netauth.cgi
In order to use the administrator's page, enter a url of the following form:
Then login as the account which has been set as the administration in netauth.ini, and NetAuth will give you administrative options.

Alternatively, you can try the demonstration page nademo.htm which is supplied with NetAuth. This page contains several URL's to NetAuth in a form such as would appear on an ISP main page. So try

General Usage

NetAuth is a CGI, written in compiled C. Therefore,  it's basic operation is carried out by executing it with a browser. As it's output comes from a set of template files, you can make it do just about anything you want within the restriction of html and the commands offered by the CGI. The templates can be used as they are, but you may find that you want to change them around and modify the look or operation of form elements buttons etc. So this section and the following sections will describe the various parts of Netauth's operation.

NOTE - By default when you query NetAuth you will see the check.tpl page, this is because by default NetAuth allows anonymous user adds to disable that and make the default page the login page set the user_add setting to false in netauth.ini

NOTE - The NetAuth CGI needs permission to create / edit and remove files in certain directories. These directories include the DMail directory where NWAuth is located, the DList directory, it's own workarea and the workarea of CWMail. In order to allow it access to the DMail directory, it has to execute as root user. Alternatively, the owner of the DMail directory can do this in two commands...

chown root:root netauth.cgi
chmod +s netauth.cgi

There is another way to execute NetAuth you can now execute NetAuth from command prompt. This is very useful if you need to carry out something NetAuth does in a script or a batch file at another time. Basically to do it you just type it in with a flag -query followed by a query string. For example:

Note: Sometimes the operating system will require you enclose the query in quotes this is because the query contains characters with significant meaning to the operating system. In that case the command would be more like this:

NetAuth will not output a page as a result but instead reply with a single line containing either "-ERR Command failed" or "+OK command successful", in the case of a command where a utoken is returned then in addition to the "+OK command successful" you will get the utoken enclosed in sqaure braces like this:

+OK command successful [utoken]

So if you then take the utoken you can carry out further commands that require a logged in user, like resetting passwords and so on. Below is an example of how to use this to reset a users password:

<retrieve the utoken returned "+OK command successful [utoken]">
netauth.exe -query "cmd=passwd1&utoken=<utoken>&name=<user>&pass=<newpass>&repass=<newpass>

Replacing the <utoken>, <user> and <newpass> with appropriate values.

Commands

NetAuth accepts several commands. Some may be given as POST commands, some as QUERY commands and some are special template operated commands. These are described in the section Template Files.

POST - A post command is where a form is submitted to the CGI via a web-page, so basically the web-server executes NetAuth and feeds it the form data. This is a useful way of sending a large amout of data to NetAuth, and has the added bonus that no information appears in the URL string at the top of the browser window.

QUERY - These are commonly undertaken with an href, where the CGI is stated followed by a ? character to mark a query. Next comes data in this form label=value and seperated by &'s. For example:
The disadvantage of using query strings is that the above will appear in the browser's URL window, and will be saved to the computers memory. This means that if another user uses the browser, the query string can be retrieved and, in this case, the password found out. This is always a problem though some query strings contain harmless information.

NetAuth can accept all it's commands as either a POST or a QUERY, although some commands require certain data and other conditions which must be met before they will continue. Here is a list of the commands and what they require...

The general rule is that if there is an error, you will always recieve the 'error.tpl' page, otherwise the standard page for each function will be shown. The only exception to this is if you specify show=page.tpl then 'page.tpl' will be shown. Any extra information given by a function will be stored in the 'message' variable.

Configuration settings

A complete list of Netauth's configuration settings can be found in the distributed netauth.ini file. There settings are "commented out". This means that there is a # as the first character of the line, and NetAuth will ignore these lines.
Some settings are only allowed one value, others can have multiple values, meaning that you can specify several. An example of this is the "admin" setting, in cases like this you can specify settings comma seperating the values like so...
Or you can have more than one occurance of the setting like so...
These two variations are treated the same.
Below you will find a description of all the NetAuth settings.

 Setting Default Description admin The account name of the administrator. This must be the name exactly as it appears in the database, so if this includes a prefix or domain name then this setting also includes the prefix or domain name. This setting can have mulitple values admin_list *@%d This setting specifies the format of list name which admininistators / power users can create. The default allows administrators / power users to create mailing lists of any name as long as the listname ends in @domain, where the domain name is dependant on the domain configuration setting. anon_search false This setting allows users to search for email addresses on your system - please note that this can be hazardous as spammers may use it to gather email addresses to spam. allow../ false This setting allows users to type ../ or ..\ as part of their username. This can cause problems, as NetAuth creates a file called /.dat. For example, if you have /var/spool/netauth as a workarea, the user might type ../../important/file as a username and NetAuth will try to write a file called /var/spool/netauth/../../important/file.dat, which could be an important file of some kind. allow_signup 123.231.222.*,mail.* If you have set restrict_signup to limit signups from any one ip, then you can use this setting in order to allow an unlimited number of signups from a wildcard, comma seperated list of ip's and / or domains. alias_counts_as_account true If this is set to true then when an power user creates an new account as an alias it will count toward the total number of accounts they are allowed. authent_process /usr/local/dmail/nwauth or \dmail\nwauth.exe This setting is the full path to the executable database which NetAuth uses to create accounts. This can be one of several supplied with DMail or available on NetwinSite http://www.netwinsite.com/. NetAuth MUST have permission to execute this process or it will not be able to add accounts. authent_domain true This setting tells NetAuth to create users as @, this is the default method for creating user names - please note that the dmail.conf setting 'authent_domain' must match this setting. clear_smtp 30 This setting specifies the number of minutes between user cache clears for the SMTP server. cwmail_url /cgi-bin/cwmail.cgi or /scripts/cwmail.exe This is the URL to the CWMail CGI. If you do not use CWMail then ignore this setting, but make sure that you do not execute the "mail1" command. cwmail_workarea /var/spool/cwmail or \cwmail This is the full path to the CWMail workarea. If you do not use CWMail, ignore this setting, and make sure that you do not execute the "mail1" command. dmailweb_url /cgi-bin/dmailweb.cgi or /scripts/dmailweb.exe This is the URL to the DMailWeb CGI. If you do not use DMailWeb, ignore this setting and make sure that you do not execute the "mail2" command. dmailweb_workarea /var/spool/dmailweb or \dmailweb This is the full path to the DMailWeb workarea. If you do not use DMailWeb, ignore this setting and make sure that you do not execute the "mail2" command. default_action This is the value of the ||action|| variable. You are only required to set this if the generated ||action|| variable is not correct, and the full_action true setting also does not generate a correct ||action|| domain This is the mail domain name. This string is added to usernames, creating @domain. If this is not required you still specify the domain but also add the "prefix NULL" setting. drop_path /var/spool/mail or \dmail\in This is the mail server's user drop path.  Combined with the hash_spool setting, this path determines which directory NetAuth places the user's forwarding information in, if fwd_method is set to "drop". It is the same as the dmail.conf 'drop_path'. dpop_path /usr/local/dmail or \dmail The path to the DPOP and DSMTP executable files. drop_prefix true This setting attaches the 'prefix' to the drop filename of the user.fwd file created when using fwd_method drop. email_create false This sets NetAuth up to create accounts by sending the account password to a new user's existing email account, specified on the account creation page. email_create_verify false This sets NetAuth up to create accounts by sending the administrator an email containing the new user's password. The manager accepts the account by replying, and sending the new user their password. full_action false This setting causes NetAuth to generate the ||action|| variable with a complete http:// path. This should only be set if required, or if the default ||action|| generated is incorrect. fwd_method external This setting decides where the user's forwarding information will be saved. It has three values - "external", "drop" or "home" (unix only). "external" forces NetAuth to save the information in the 'authent_process' database, "drop" creates a .fwd file in the user's 'drop_path', and "home", the unix only option, creates a .forward file in the user's home directory. hash_spool 0 This setting instructs NetAuth on how to find the user's drop_path. It is the same as the dmail.conf setting 'hash_spool'. hash_method 0 This is the hash_method setting from CWMail / DMailWeb or WebMail. It instructs NetAuth on how to find the user's mail data file. home_url /nademo.htm This is the URL which NetAuth will refresh to if the "home" command is given. home_path /home This is the user's home path (unix only). This is where the user's .forward file is stored. illegal_char This is a string of illegal characters in usernames. An example "illegal char @#$%&^" will stop users from using any of these characters - @#$%&^ - in their username. illegal_name This setting is a comma separated list of illegal words or phrases. It is also a good idea to add the administration account name to this list in order to stop users from creating the adminisration account if it gets deleted. imaphost This is the IP number / name for the IMAP server. imapport 143 This is the IMAP port number. ini_dump false This setting forces NetAuth to dump it's ini values into three files. One file is the data loaded from the .ini file, another file contains all the data from a post or query and the third is the result of combining the two. ipsignup_var REMOTE_ADDR This setting tells NetAuth which enviroment variable to get the ip of any remote connection from. It uses this ip for the restrict_signup and allow_signup settings. To find out values for enviroment variables you can use netauth's cmd=test1 to list all enviroment variables present. key This is the NetAuth registration key. language_file This is the full path to the lang.dat file, usually stored in the NetAuth templates or workarea directory. This file is used in order to translate the mesages which NetAuth supplies to languages other than English. If no translation is required, ignore this setting. list_max This setting specifies a maximum number of mailing lists allowed. list_path /usr/local/dmail/dlist This setting specifies the path to the lists.dat file used by dlist. list_fullname true This setting displays the user's full name as in the NWAuth database on the accounts page. This is necessary if you are using subdomains because otherwise NetAuth trims users and user "fred@domain.com" and "fred@fred.domain.com" will appear identically. logpath This is the directory where NetAuth will create it's log file. This logging information may provide help when tracking down errors in Netauth'e execution. loglevel info This is the level of logging information to record. It has three values - "error", "info" and "debug". "error" provides only error messages, while "info" explains the major steps in execution, and "debug" displays all the little pieces of data as they flow through the program. nwimg /nwimg This is the relative URL to the NetAuth image files. pass_lowercase false This setting forces NetAuth to use lowercase for the user's password. pophost This is the IP number / name of your POP3 server. port This is the port number of the POP3 server. It is important that you set this, it is typically "110". pop_command /usr/local/dmail/tellpop reload or \dmail\tellpop reload This is the command which causes the POP server to reload it's authentication database. prefix vd_ This is the prefix added to usernames when creating accounts.Old versions of NetAuth use the prefix setting of NULL to enfore an authent_domain false, which creates users as rather than @. que_cleanup 100000 This is the number of bytes in the user.add file, used when creating power users. When the file reaches this size, it and the user.que files are refreshed and old uids thrown away. re-enter_pass true This adds a re-enter password field to the new.tpl page and forces the user to type their password twice correctly in order to create an account. reload_smtp 60 This is the number of minutes between reloads of the SMTP server. reload_pop 240 This is the number of minutes between reloads of the POP server. remove_old_signups true This setting tells NetAuth to remove it's old list of ip signups which are stored in the workarea. If you do not want to use the lists, set this to true and NetAuth will automatically clean up after itself. report_account This is the account to which NetAuth sends it's addition and deletion reports. This report is emailed and comes in the form specified by the report_add.tpl and report_del.tpl files. report_adds 10 After the specified number of accounts have been added, NetAuth will send a report to the above account. report_deletes 5 After the specified number of deletes, NetAuth will send a report to the 'report_account'. require_cookies false This forces the user to have a valid NetAuth cookie in order to use netauth. restrict_signup 6 A positive value forces NetAuth to remember signup ip's and restrict the number allowed to the value of this setting. The setting allow_signup is used to allow signups from particular ip(s) or domain(s). Other settings of use are signup_var and remove_old_signups. responder /usr/local/dmail/drespond or \dmail\drespond.exe This is the path to the auto-responder process. smtp_command /usr/local/dmail/tellsmtp clear_cache_all or \dmail\tellsmtp clear_cache_all This command clears the smtp server's cache. smtp_command2 /usr/local/dmail/tellsmtp reload or \dmail\tellsmtp reload This is the command which reloads the SMTP server. smtphost This is the IP name / number of your SMTP server. smtpport 25 This is the port number of the SMTP server. suffix This is the username suffix used for authentication on the POP server. search_not true This setting dissables netauth's filtering of users so that it does not remove users from the list with prefix's or suffix's matching other vhost sections. test_routines true This setting enables / disables the cmd=test debugging tests. templates /var/spool/netauth or \netauth This is the directory into which you installed NetAuth. This is where the .tpl file are kept. These files determine the output from the NetAuth CGI. user_alias true This allows users to create alias names for their account. user_hash 0 This is the method NetAuth will use in order to create it's user directories. Possible values are 0, 1, 2. user_lowercase false This forces all usernames into lowercase. user_add true This setting allows / disallows users to add their own accounts. If it is set to "false" then NetAuth defaults to it's login page. user_del true This setting allows / diallows users to delete their own account. user_max This setting specifies a maximum number of user accounts in a domain. user_reqd This setting is a comma separated list of fields which must be filled before an account can be created. user_sort true This setting forces NetAuth to sort it's users before outputting them onto the accounts.tpl page. user_list list-%u@%d This is the format of list names which a user must match when creating a mailing list. The default forces a user "bob" to create the list "list-bob@domain", no other list name is allowed. This setting uses special %u, %d, and * characters. A %u means username, a %d means domain name, and a * means any character or characters. user_create_prefix false This setting forces NetAuth to add a prefix to the username which it creates in the 'authent_process' database. user_subdomain false This allows you to create users in a given subdomain of their making. For example, if you host a site domain.com, you can create your own domains *.domain.com so that you can allow fred to have an account called fred@fred.domain.com. This process requires a template modification, see Subdomains user_maxlen 40 This is the maximum length allowed for a username before it will be rejected. utok_cookie false This tells NetAuth to pass the user's utoken as a cookie. This cookie can be used instead of the utoken form variable. vhost This setting is set upon execution of NetAuth. It uses the 'vhost_match' value in order to get an environment variable which contains the url host. From this, NetAuth can distinguish mail domains. vhost_match SERVER_NAME This is the name of the environment variable which contains the URL host name. The default will work in most cases. If it doesn't, HTTP_HOST can give better results. If this fails, use cmd=test1 to find an environment variable that matches the host in the URL and use this. workarea The directory where NetAuth is allowed to store it's working files and user information. It defaults to the value of the templates directory. web_login false This allows NetAuth to use the web servers authentication username and password. NetAuth understands the Basic method of webserver authentication. If it finds a username and password, it will automatically log that user in, unless they are logged in as another user already. webimap_url /cgi-bin/webmail.cgi This the URL to the WebMail CGI. If you do not use WebMail, ignore this setting. webimap_workarea /var/spool/webmail or \webmail This is the full path to the WebMail Workarea. If you do not use WebMail, ignore this setting. webserver_out This is the path where NetAuth creates the log showing the output to the web browser.

Supporting Virtual Domains

If you are planning on using virtual domains, NetAuth needs to be set up in order to create user accounts in the correct format for each domain. There are also several other settings which you may want to set differently for each domain. In order to do this, use vhost sections. Vhost sections are sections of the ini file starting with "vhost www.domain.com" and ending in another "vhost www.domain2.com" or a "vend". For example...

 templates \netauth vhost www.domain2.com vhost www.domain3.com vend

In the example, NetAuth will try to match the URL string obained from the SERVER_NAME enviroment variable, or another specified by the vhost_match setting which you should place in the ini file before all the vhost sections. If a vhost line matches, NetAuth continues to load settings. If it doesn't match, NetAuth ignores the settings until it finds a vend or another vhost line. When it does, it tries to match again and either loads or ignores settings depending on the result. Therefore, there should always be a vend at the end of the last vhost section.

You can place any settings you like inside the vhost section, even the templates setting if you want to use different templates for each domain. Inside these sections you will be placing prefix, suffix and domain settings to determine the format of usernames.

The format of usernames differs when you are using virtual domains. It depends on two dmail.configuration settings - the authent_domain setting, which can be set to true or false (if you don't have one it is assumed to be false), and the same way  as the vdomain lines were done.
In the following explanation it is assumed that you have vdomain lines like this, and a host domain called "domain.com"
vdomain a /d2.com domain3.com \dmail\in
vdomain b /d3.com domain3.com \dmail\in
OR
vdomain a mail.domain2.com domain2.com \dmail\in
vdomain b mail.domain3.com domain3.com \dmail\in
With these vdomain lines we are only interested in the first three parameters, the last parameter is the drop_path. You will need to specify this drop_path in netauth.ini if it differs from the host_domains drop_path.
Notice that the second parameter can be  either an IP number or name or it can be a suffix. If you have more than one IP and you are using an IP number or name here then you have IP based domains. If it is a suffix, it typically begins with a / symbol, this means that you have Suffix based domains.

If you have IP based domains, you will be specifying different pophosts inside the vhost sections. For example...

 authent_domain true authent_domain false templates \netauth domain domain.com pophost mail.domain.com port 25 vhost www.domain2.com pophost mail.domain2.com domain domain2.com vhost www.domain3.com pophost mail.domain3.com domain domain2.com vend templates \netauth domain domain.com pophost mail.domain.com port 25 prefix NULL vhost www.domain2.com pophost mail.domain2.com domain domain2.com prefix a_ vhost www.domain3.com pophost mail.domain3.com domain domain2.com prefix b_ vend

The pophosts will match the second vhost parameter, which is the IP number or name of the pophost.
In the above examples, the user "bob" would be referenced with these usernames....

authent_domain true

 POP name Database name host domain bob bob@domain.com www.domain2.com bob bob@domain2.com www.domain3.com bob bob@domain3.com

authent_domain false

 POP name Database name host domain bob bob www.domain2.com bob a_bob www.domain3.com bob b_bob

If you are using suffix based domains, you will be specifying suffix settings inside the vhost sections. For example....

 authent_domain true authent_domain false templates \netauth domain domain.com pophost mail.domain.com port 25 vhost www.domain2.com domain domain2.com suffix /d2.com vhost www.domain3.com domain domain3.com suffix /d3.com vend templates \netauth domain domain.com pophost mail.domain.com port 25 prefix NULL vhost www.domain2.com domain domain2.com suffix /d2.com prefix a_ vhost www.domain3.com domain domain3.com suffix /d3.com prefix b_ vend

The suffix settings will always match the second vhost parameter.
In the above examples, the user "bob" would be referenced with these usernames.....

authent_domain true

 POP name Database name host domain bob bob@domain.com www.domain2.com bob/d2.com bob@domain2.com www.domain3.com bob/d3.com bob@domain3.com

authent_domain false

 POP name Database name host domain bob bob www.domain2.com bob/d2.com a_bob www.domain3.com bob/d3.com b_bob

So NetAuth will create users in the database as shown above in the 'Database name' column, and verify them as shown in the 'POP name' column.

If you have CWMail / DMailWeb or WebMail you will need to add vhost sections to their ini files as well. In these vhost sections you will need to either specify the pophost or the suffix for each virtual domain. This means that users can log in with "bob", and CWMail will either connect to the correct pophost or automatically add the suffix when verifying the user.

Power Users

NetAuth has special user accounts called power users. A power user is treated the same as an administrator except that they have limited control. Power users can create / modify / delete a certain number of accounts and mailing lists. In order to create power users you should append to the file "user.que" in the NetAuth workarea <templates> directory. In this file you write a line like so....

NOTE - It is important that the line written into the "user.que" file is always in this form....
<uid>:<account_max>:<list_max>:<other>:<other>:etc...<newline>

Following this, query the NetAuth CGI with the "uid" variable set to 12345, so
http://you.site.com/cgi-bin/netauth.cgi?uid=12345
The NetAuth template has a hidden field which remembers this uid so that the user can choose a name and then add their account. Once the account is created they can login and will be given the administrator's screen.

If the user clicks "accounts" (like an administrator can) instead of recieving a list of ALL the accounts, they recieve a list of all the accounts they have created. This may be none at this point in time but the user can then create up to 20 accounts. This number is variable and is part of the line which was written into the "user.que" file. It is the second part ,<account_max>. NetAuth remembers the accounts which have been created by the user and will only allow that user to change / delete them.

If the user clicks "list page" (like an ordinary user can), they are shown the current mailing lists, BUT instead of being restricted by the 'user_list' setting they are restricted by the 'admin_list' setting. This means that they can create lists as an administrator would but, in this case, only 4 lists maximum. This is also variable and is set as the third part of the line, <list_max> which was written into the "user.que" file.

The <other> part of this line is for additional information which you may want to store in the user's data file. In the above example, the user info "address" would be stored as "104 fred street". There is no restriction on the number of information fields which can be added here, but they must all be seperated by :'s.

SPECIAL NOTE - Once a uid has been used, an entry is written into the user.add file. This denotes the uid as taken, and it cannot be re-used until the user.add and user.que files have been cleaned up. This happens when the user.add file reaches 'que_cleanup' bytes. que_cleanup is a configuration setting. If you are expecting a lot of power users then either use unique uid numbers, or have a small que_cleanup setting.

Subdomains

This allows you to create users in a given subdomain of their making. For example, if you host a site domain.com then you can create your own domains *.domain.com so that you can allow fred to have an account called fred@fred.domain.com.

This process requires a setting and a template modification...

1. First set "user_subdomain" to "true" in the netauth.ini.
2. On the add, login and check templates you need to add a subdomain text field i.e.

3.   <input type=text name=subdomain value="||subdomain||">
4. On the rest of the templates add a hidden subdomain field i.e.

5.   <input type=hidden name=subdomain value="||subdomain||">

Note: You should also set the list_fullname setting to true. Otherwise, when you list users on the accounts page, "fred@domain.com" and "fred@fred.domain.com" will appear identically.

 templates \netauth domain 123.com vhost www.virtual.com domain virtual.com admin bob@virtual.com vend

In this example the user "bob", Database name "bob@virtual.com" is the administrator for the virtual domain "virtual.com" which is reached by the URL "www.virtual.com".

Administrators do not follow all the restrictions that users must follow. The admin_list setting is one example of this. If an administrator creates a mailing list, it's name must match the admin_list setting rather than the user_list setting.
An administrator can edit / delete / add any and all accounts inside the domains which he/she is an administrator for. They have the right to list all the accounts in their domain.

Template files

The NetAuth template files determine the output of the CGI. They are basically HTML files with small added extras which the CGI manipulates. The extra's are all preceeded by ||....and end with || . These extras can be text variables, select lists, or functions. An example of a text variable is the ||name|| variable, which displays the user's name. An example of a select list is the ||vhost_list|| variable used in the login.tpl and other files. An example of a function is the ||begin_accounts|| function, which can be found in the accounts.tpl file.

Text variables

These are values which are given to the CGI, recieved from the CGI or passed through the CGI. NetAuth uses several variables in order to carry out operations. An example is "name", this variable can be retrieved and displayed in any template by placing a ||name|| where you want it to be. You can pass variables to the CGI and it will return these varaibles so that you can display them on the next page from the CGI. In order to do this, simply submit the variable in a port or query, and use ||<variable_name>|| to retrieve it again. For example, if you had a text input called "fred" with a value of "bob", then on the next output page from NetAuth you could place a ||fred|| and it would be replaced by "bob".

Select lists

NetAuth uses very few select lists. Most can be generated within functions on the template, so a select list is not neccessary. One select list that is used is "vhost_list". This is generated on any execution of NetAuth. This list contains the names of all the domains and their matching vhost values and with this you can choose a domain. A select list which is generated within a function is the available mailing lists, found on the "lists.tpl" page. This is a good example of how to create your own select lists using NetAuth functions.

Functions

Template functions are special, as the CGI carries them out while it is outputting the HTML page. These functions come in several types. There are functions that take parameters, funtions that loop through from the beginning to an end label and it is also possible to have functions which take parameters and loop to an end label.
An example of a function with a parameter is the "timestr" function, which takes one parameter, like so ||timestr||<input>||.
An example of a function with an end label is "begin_accounts", it's end label is ||end_accounts|| so that the text between these labels is displayed each time the function loops around. In this case, each time it returns a user account name it displays the text, so that ten accounts means that the text is displayed ten times.

The following list is of all the template functions...

 Function name End label Parameters Description begin_suggest end_suggest 1 This function generates suggestion for usernames, ensuring that they are available. The parameter is the user's full name, or another text string to generate names from. For each suggestion it will display the text between the "begin_suggest" and "end_suggest" labels. An example can be found on the again.tpl page begin_accounts end_accounts 1 This function returns all account names for the current domain. The parameter specifies how many to display in a row, and the function will return a variable called "num", telling you which position in the row it is up to. So it will count 1,2,3,4,1,2,3,4,etc...if you specify 4 as the parameter. It is like the above function in that it loops and displays all the text between start and end for each account returned. An example can be found on the accounts.tpl page begin_lists end_lists 0 This function returns all the mailing lists in the current domain. An example of its use is the lists.tpl page. begin_members end_members 1 This function lists the members of the "mlist_name" list. Like the begin_accounts funtion, it's parameter specifies how many columns to display. An example can be found on the member.tpl page. account_info end_info 0 This function returns a piece of user information each time it loops, until all user information is displayed. This user information can be save with the "save" function. In order to return information for a user other than the current logged in user, the logged in user must be an administrator and the 'name' variabe must be set to the required user's name. An example of this exists on the stats.tpl page. begin_pqlist end_pqlist 0 This function returns all the user's password questions. begin_stat end_stat 0 This function returns the DPOP statistics for the "name" user. In order to update these  statistics, the function "stats1" will flush the DPOP statistics and update the information returned by this function. is_member 1 This function determines whether the current user is a member of the current list "mlist_name", and sets the variable designated by it's parameter to "true" or "false". An example of it's uses is the lists.tpl page. allowed_list 0 This function sets the "mlist_allowed" variable to the format of mailing list name which the current user is allowed to create. timestr 1 This function converts it's parameter - which must be a string representing the number of seconds elapsed since midnight Jan 1 1970, coordinated universal time - into a date like "Jan 5 1999 12:45 pm".

When modifying template files, it is important to remember the variables involved in these functions, and to ensure that they are set to the correct value or values. If you do not, the results of these function calls may differ from what you were expecting. In addition, be careful not to change important template variables as this may effect other parts of templates in erratic or unusual ways.

In addition to the above functions, there are several basic functions which you may have seen used throughout the template files. These functions perform basic logical operations such as making choices deciding which part or parts of a template to display. In additon to the function names, there are two other labels ||else|| and ||endif|| which become very useful. If a function makes a choice which is "true", it will display the following lines of the file. If it reaches an ||else||, it will stop displaying until it reaches an ||endif||, and vice versa. The ||else|| label basically means otherwise. For example...

||ifdef||fred||
<p>hello</p>
||else||
<p>goodbye</p>
||endif||

In the above example, the function ||ifdef|| takes a single parameter and decides "true" or "false". If it decides "true" it will display <p>hello</p> , otherwise it will display <p>goodbye</p>. There are several functions which you can use. Some are "decision" functions, others are "action" functions. The decision functions act like the above example, action functions perform a task, and will not function with the ||else|| or ||endif|| labels. The below is a complete list of functions ...

 Function Parameters Type Description ifdef 1 decision This function takes it's parameter and decides "true" if that variable exists and has a value, or "false" if it doesn't. ifndef 1 decision This function does the exact opposite of the above function. ifinstr 2 decision This function takes the second parameter, and looks for it inside the first parameter. If either parameter is a variable with a value then it uses the value for the search. iflower 2 decision This function compares it's two parameters. If the first parameter is greater than the second, it returns "true". If either parameter is a variable with a value, it uses the value for the comparison. ifequal 2 decision This function takes the two parameters and, if they are equal, returns "true". Otherwise, it returns "false". If either parameter is a variable with a value, it uses the value for the comparison. ifgreater 2 decision This function compares it's two parameters. If the first parameter is lower than the second,  it returns "true". If either parameter is a variable with a value, it uses the value for the comparison. define 2 action This function creates a new variable by the name of the first parameter. It assigns to it the value of the second parameter. If the second parameter is a variable already, the new variable is assigned the same value as that variable. undef 1 action This function removes a variable. include 1 action This function includes the file specified and displays it directly onto the page. This file must exist in or under the directory. do special action This function executes the command given. The command must be an executable or a batch file and cannot be a system function like "ls" or "dir". In order to use these, you must create a batch / script file. The results from this command are displayed directly and content type headers are removed.

Troubleshooting

Most problems can be solved by you without too much fuss or energy. Most are caused by setup problems, and these are usually easy to fix. Most of the time, NetAuth will tell you what it's problem is, often with a page entitled "Error". On this page, you will recieve a message informing you of what it wrong. If this doesn't  help, you need to look for a file called "netauth.log", this can usually be found in the NetAuth templates directory. If this file doesn't exist then look on your system for a file called "init.log", this is most commonly found in the webserver scripts / cgi-bin directory. One of these files will exist, if neither of them do then the NetAuth CGI is not being executed and you have a problem with your web server, the web server should have a log file somewhere with an explanation.