netauth.jpg (4631 bytes)
Web-Based Email Management System

Netauth allows

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 WebImap 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 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 the client sees are easily modifiable to suit your particular needs. This allows them to be used as is or completely rewritten to provide a particular look and feel which matches other web pages from your site.

The following sections describe...

  1. NT Installation.
  2. Unix Installation.
  3. General usage.
  4. Commands
  5. Configuration settings.
  6. Supporting Virtual Domains.
  7. Power Users
  8. Administrators
  9. Template files.
  10. Updates and version information.
  11. Troubleshooting.
  12. Netauth and NFS Drives

Additional information...

  1. How to set up a hotmail system?
  2. How to register Netauth?
  3. Netauth downloads

NT Installation

You must install the netauth CGI on your WEB server, in a directory that you have already set up as containing CGI programs, you should read your web server documentation if you don't currently know how to set up a cgi program. Normally a server will have a special directory for storing CGI's it may be called something like
SERVER_ROOT\cgi-bin     
or c:\inetpub\scripts
or "FrontPage Webs\Content\cgi-bin"

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

Download the self extracting archive from netwinsite "netauth40a.exe".
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

  copy nademo.htm \inetpub\wwwroot

  cd ..
  del \natemp\*
  rmdir \natemp

Next you have to 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, it is suggested once you have the system running that 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 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 users see when they connect to Netauth.exe
workarea <templates> \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 <templates> \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 <vhost> funkymail.com This is the mail domain name.
pophost <vhost> 121.2.33.45 This is the IP number or name of the pophost, users are verified using this pophost.
smtphost <vhost> 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 and 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 (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 form:
    http://mysite.com/scripts/netauth.exe
To use the administrator page enter a url of the form:
    http://mysite.com/scripts/netauth.exe?adminpage=true

Or you can try the demonstration page nademo.htm supplied with netauth, this page contains several URL's to netauth in a form like would appear on an ISP main page. So try
   http://mysite.com/nademo.htm


Unix Installation

You must install the netauth CGI on your WEB server, in a directory that you have already set up as containing CGI programs, you should read your web server documentation if you don't currently know how to set up a cgi program. 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 you have downloaded will normally run nasetup once it has unpacked the files to a temporary directory. All you need to do is answer the questions to complete the installation.
If you want to handle the installation manually use the following instructions:

Download the self extracting archive from netwinsite "netauth40a_<system>.tar.Z".
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
 
  cp nademo.htm /home/httpd/html

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

Next you have to edit the live copy of the configuration file "netauth.ini", 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, it is suggested once you have the system running that you backup the live copy to the  /var/spool/netauth directory. So to edit the netauth.ini file use notepad or another suitable text editor and ensure these settings are correct.

NOTE - The Netauth CGI needs permission to create / edit and remove files in certain directories, these directories include the dmail directory where nwauth is, the dlist directory, it's own workarea and the workarea of cwmail. To allow it access to the dmail directory it has to execute as root user, or the owner of the dmail directory 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 users see when they connect to Netauth.exe
workarea <templates> /var/spool/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 <templates> /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 <vhost> funkymail.com This is the mail domain name.
pophost <vhost> 121.2.33.45 This is the IP number or name of the pophost, users are verified using this pophost.
smtphost <vhost> 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 and 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 (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 form:
    http://mysite.com/cgi-bin/netauth.cgi
To use the administrator page enter a url of the form:
    http://mysite.com/cgi-bin/netauth.cgi?adminpage=true

Or you can try the demonstration page nademo.htm supplied with netauth, this page contains several URL's to netauth in a form like would appear on an ISP main page. So try
   http://mysite.com/nademo.htm


General Usage

Netauth is a CGI, written in compiled C. So 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 is but you may find you want to change them around and modify the look or operation of form elements buttons etc. So this section and the following sections are going to describe the various parts of Netauth's operation.

NOTE - The Netauth CGI needs permission to create / edit and remove files in certain directories, these directories include the dmail directory where nwauth is, the dlist directory, it's own workarea and the workarea of cwmail. To allow it access to the dmail directory it has to execute as root user, or the owner of the dmail directory to do this in two commands...

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


Commands

Netauth accepts several commands some can 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 a commonly done 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. As an example
http://mysite.com/scripts/netauth.exe?cmd=add1&name=fred&pass=fred
The disadvantage of using query strings is that the above will appear in the browsers URL window and saved to the computers memory so if another users uses the browser the query string can be retrieved and in this case the password found out. This is always a problem 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.

Command Requires login Required fields Optional fields Description
accounts Yes utoken none This command displays the accounts.tpl page, an administration / power user page which lists user accounts.
add No none none This command displays the new.tpl page
add1 No user, pass full_name This command adds the user provided the name is unique, 'user_add' is 'true', there are less than 'user_max' accounts, the 'user_reqd' fields have been entered, and the username doesn't contain an 'illegal_char' or 'illegal_name' (see Configuration Settings). A 'uid' has been given (see Power Users), or the administrator / power user is logged in and is adding a user account to a domain he/she has access to (see Administrators).
check No none none This command displays the check.tpl page.
check1 No user full_name This command checks the provide 'user' name against current users if no other user / mailing list has that name the user is presented with the new.tpl page, otherwise given the again.tpl page with sugghested alternative names.
del Yes utoken none This command deletes the user account, the user must be logged in, and user_del must be true.
fwd1 Yes utoken none This command loads the users current forwarding information, it returns fwd_address, fwd_copyself, fwd_respond, fwd_h_*, fwd_message fields, explained below.
fwd2 Yes utoken fwd_address, fwd_copyself, fwd_respond, fwd_h_*, fwd_message This command saves the given forwarding information, this can include addresses 'fwd_address' these are comma seperated, the option of keeping a copy 'fwd_copyself', this is simply a checkbox. The option to have an auto-matic reply sent 'fwd_respond', this is also a checkbox. The response message 'fwd_message' and it's headers 'fwd_h_*', like 'fwd_h_subject' or 'fwd_h_reply_to'.
login No name, pass none This command logs the user in, it checks the username and password again the given pophost / imaphost.
logout Yes utoken none This command logs the current user out.
main Yes utoken none This command returns the user to the main page, "user.tpl" or "admin.tpl".
mdel Yes utoken, cb_<name>, ... none This command can only be executed by a logged in administrator / power user, it deletes all accounts specified by the cb_* varibles, so a checkbox named cb_netwin which was checked would remove the user netwin, from the current domain.
mail No none none This command displays the "mail.tpl" page which refreshes to the cwmail login page.
mail1 Yes / No none utoken, name, pass This command logs the user into CWMail, if the user is logged in and has logged into CWMail before otherwise the user will see the login page of CWMail.

If 'user' and 'pass' are given (this is only possible during an add1) then the user is logged into CWMail and sees the newuser page.

mail2 Yes / No none utoken, name, pass This command is the same as the one above only it logs users into DMailWeb.
mail3 Yes / No none utoken, name, pass This command is the same as the one above only it logs users into WebImap.
home No none none This command displays the 'home.tpl' page and refreshes to the home_url setting.
next No none start, total This command increments 'start' by the value of 'total', start defaults to 0, and total defaults to 20.
next2 No none name This command finds the next user on the list after 'name', this is only possible on the accounts.tpl page where an accout_list command (see Template Files) has been carried out.
passwd Yes utoken none This command returns the 'passwd.tpl' page.
passwd1 Yes utoken, pass, repass none This command changes the users password to 'pass', 'pass' and 'repass' must be the same.
passwd2 Yes utoken, pquestion, panswer none This command adds the 'pquestion' and 'panswer' to the users list of questions/answers for password retrieval.
passwd3 Yes utoken, pq_*, ... none This command removes question x from the users list of questions /   andswers. X is given as pq_1, or pq_3, etc... And is simply a checkbox.
passwd4 No none name, panswer This command returns the 'forgot.tpl' page, if name is specified then a password retrieval question is also given. This process can only be done if the user has previously set password question / answers (see passwd2 above).

If user 'name' does not exist a question is still given from the quest.dat file if present in the Netauth workarea otherwise a question is supplied internally.

If 'panswer' is present Netauth checks the answer and if correct changes the users password to a temporary password, logs the user in and displays the 'passwd.tpl' page, allowing the user to re-set a new password.

prev No none start, total This command decrements start by a value of total, it will not reduce below zero.
prev2 No none name This command finds the user before user 'name', this is only possible on the accounts.tpl page where an 'account_list' command (see Template Files) has been carried out.
quota Yes utoken, name, user_quota none This command can only be carried out by an administrator / power user. It sets the users quota field limiting the email space they are allowed on the server.
rebuild Yes none none This command is restricted to the administrator, it removes the status file and the record of adds / deletes then it rebuilds the status file. This will often fix problems with user limits, list limits or report email.
save Yes utoken u_* This command updates the users information, this can be any u_* fields set on user creation, as well as the u_full_name variable.
save2 Yes utoken, name u_* This command can only be used by an administrator / power user. It saves the given u_* fields for user 'name'.
stats Yes utoken none This command displays the 'stats.tpl' page. This can only be done by an administrator / power user.
stats1 Yes utoken none This command flushes the current stats to fil so that the 'begin_stat' template command (see Template Files) can give up to date information.

The general rule is 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 is if you specify show=page.tpl then 'page.tpl' will be shown. Any extra information a function wishes to tell you 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 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, meanig 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...
admin bob,fred,joe
Or you can have more than one occurance of the setting like so...
admin bob
admin fred
admin joe
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.
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.
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 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 then ignore this setting, and 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 then ignore this setting and 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 then ignore this setting and 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 <vhost> This is the mail domain name, this string is added to usernames createing <user>@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 servers user drop path, this path plus the hash_spool setting determine which directory Netauth places the users forwarding information, if fwd_method is set to "drop". It is the same as the dmail.conf 'drop_path'.
drop_prefix false This setting attaches the 'prefix' to the drop filename of the user.fwd file created when using fwd_method drop.
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 users forwarding information is 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 <user>.fwd file in the users 'drop_path'. And "home" the unix only option creates a .forward file in the users home directory.
hash_spool 0 This setting instructs Netauth how to find the users 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 WebImap it instructs Netauth on how to find the users mail data file.
home_url /nademo.htm This is the URL Netauth will refresh to if the "home" command is given.
home_path /home This is the users home path (unix only), this is where the users .forward file is stored.
illegal_char   This is a string of illegal characters in usernames, an example "illegal char @#$%&^" will stop users using any of these characters @#$%&^ in thier username.
illegal_name   This setting is a comma seperated list or illegal words of phrases, it is also a good idea to add the admin account name to this list to stop users creating the admin account if it gets deleted.
imaphost <vhost> This is the IP number / name for the IMAP server.
imapport 143 This is the IMAP port number.
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 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.
logpath <templates> 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 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.
pophost <vhost> The IP number / name or your POP3 server.
port   The port number of the POP3 server, it is important you set this, it is typically "110".
pop_command /usr/local/dmail/tellpop reload or \dmail\tellpop reload The command that causes the POP server to reload it's authentication database.
prefix   The prefix added to usernames when creating accounts.
que_cleanup 100000 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.
reload_smtp 60 The number of minutes between reloads of the SMTP server.
reload_pop 240 The number of minutes between reloads of the POP server.
report_account   The account where 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 this many accounts have been added Netauth will send a report to the above account.
report_deletes 5 After this many deletes Netauth will send a report to the 'report_account'.
responder /usr/local/dmail/drespond or
\dmail\drespond.exe
The path to the auto-responder process.
smtp_command2 /usr/local/dmail/tellsmtp reload or
\dmail\tellsmtp reload
The command which reloads the SMTP server.
smtphost <vhost> The IP name / number of your SMTP server.
smtpport 25 The port number of the SMTP server.
suffix   The username suffix used for authentication on the POP server.
test_routines true This setting enables / disables the cmd=test debugging tests.
templates /var/spool/netauth or \netauth The directory where you installed Netauth, this is where the .tpl file are kept, these files determine the output from the Netauth CGI.
user_hash 0 This is the method Netauth will use 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 thier 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 thier own account.
user_max   This setting specifies a maximum number of user accounts in a domain.
user_reqd   This setting is a comma seperated list of fields that must be filled before an account can be created.
user_list list-%u@%d This is the format of list names 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 the prefix to the username it creates in the 'authent_process' database.
vhost <vhost_match> This setting is set upon execution of Netauth it uses the 'vhost_match' value to get an enviroment variable which contains the url host, from this Netauth can distinguish mail domains.
vhost_match SERVER_NAME This is the name of the enviroment varaible with the URL host name in it. The default will in most cases work, if not HTTP_HOST can give better results, if this fails use cmd=test1 to find an enviroment variable that matches the host in the URL and use this.
workarea <templates> The directory where Netauth is allowed to store it's working files, and user information. It defaults to the value of the templates directory.
webimap_url /cgi-bin/webimap.cgi This the URL to the WebImap CGI, if you do not use WebImap ignore this setting.
webimap_workarea /var/spool/webimap or
\webimap
This is the full path to the WebImap Workarea, if you do not use WebImap ignore this setting.
webserver_out <logpath> 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 then Netauth needs to be set up to create user accounts in the correct format for each domain, and there are several other settings you may want to set differently for each domain. To do this you 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", as an 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 varaible, 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 then Netauth continues to load settings, if it doesn't match Netauth ignores the settings until it finds a vend or another vhost line in which case 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.conf settings, the authent_domain setting which can be true or false, if you don't have one it is assumed to be false. And the way you have done your vdomain lines.
For the below explaination I will be assuming 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 the seccond parameter it can be an IP number or name or it can be a suffix, if you have more than one IP and you are using and IP number or name here then you have IP based domains, if it is a suffix it typically begins with a / symbol, this means you have Suffix based domains.

If you have IP based domains then inside the vhost sections you will be specifying different pophosts, 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 seccond 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 then inside the vhost sections you will be specifying suffix settings, 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 seccond 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 WebImap you will need to add vhost sections to thier ini files as well, in these vhost sections you will need to either specify the pophost or suffix for each virtual domain, this means users can log in with "bob" and CWMail will connect to the correct pophost or automatically add the suffix when verifying the user.


Power Users

Netauth has special user accounts, these are called power users. A power user is treated just like an administrator only they have limited control. Power users can create / modify / delete a certain number of accounts, and mailing lists. To create power users you need to append to a file in the Netauth workarea <templates> directory it is called "user.que", in this file you would write a line like so:

12345:20:4:address=104 fred street

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

Then you would 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 the user can choose a name and then add thier account. Once the account is created they can login and they will be given the administrators screen.

If this 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.Which may be none at this point in time, this 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 seccond part <account_max>. Netauth remembers the accounts created by this user and will only allow them to change / delete these accounts.

If this user clicks "list page" like any 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 so 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 you want to store in the users 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 you can add 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 reused 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.


Administrators

The "admin" setting determines which accounts are administrators, if you have no accounts in the nwauth database then you will need to add one before you can attempt to login and administrate. The admin setting must match the Database name of the account if this is a name with a prefix like a_bob then admin must be "admin a_bob". If you want multiple administrators then you can list them like so...."admin bob@123.com,fred@123.com". If you want to create an administrator who can administrate only a certain virtual domain then place the admin setting inside a vhost section of the netauth.ini file, example...

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 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 domains he/she is an administrator for, they have the right to list all the accounts in thier 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 || also. These extras can be text variables, select lists, or functions. An example of a text variable is the ||name|| varaible which displays the users 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 given to the CGI, recieved from the CGI or passed through the CGI. Netauth uses several variables to carryout operations, an example is "name" this variables can be retrieved and displayed in any template by placing a ||name|| where you want it. You can pass variables to the CGI and it will return these varaibles so as you can display them on the next page from the CGI. To do this simply submit the variable in a port or query, and use ||<variable_name>|| to retrieve it again. As an 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 used is "vhost_list" this is generated on any execution of Netauth, this list contains the names of all the domains and thier matching vhost values, with this you can choose a domain. A select list which is generated with a function is the select list of 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, functions that take parameters and funtions that loop though from beggining to an end label. It is also possible to have a function which takes parameters and loops to an end label.
An example of a function with a parameter is "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 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 ten accounts means the text is displayed ten times.

Here is a list of all the template functions...

Function name End label Parameters Description
begin_suggest end_suggest 1 This function generates suggestion usernames ensuring they are available, the parameter is the users 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's 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 it's 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 info can be save with the "save" function. To return info 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 users password questions.
begin_stat end_stat 0 This function returns the DPOP statistics for the "name" user, 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 deisgnated by it's parameter to "true" or "false", an example of it's use is the lists.tpl page.
allowed_list   0 This function sets the "mlist_allowed" varaible 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 secconds elapsed since midnight Jan 1 1970, coordinated universal time, in to a date like "Jan 5 1999 12:45 pm".

When modifying template files it is important that you remember the variables involved in these functions and ensure they are set to the correct value or values otherwise the results of these function calls might not be what you are expecting. Also 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 function perform basic logical operations, like 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" then it will display the following lines of the file but if it reaches an ||else|| it will stop displaying until it reaches an ||endif|| and vice versa, the ||else|| label basically means otherwise, as an 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 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, a complete list of functions are ...

Function Parameters Type Description
ifdef 1 decision This function takes it's parameter and decides "true" is that variable exists and has a value, or "false" if it doesn't.
ifndef 1 decision This function does the exact oposite of the above function.
ifinstr 2 decision This function takes the seccond 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
ifequal 2 decision This function takes the two parameters and if they are equal returns "true", otherwise "false". If either parameter is a variable with a value then it uses the value for the comparison.
ifgreater 2 decision This function compares it's two parameters if the first parameter is lower it returns "true". If either parameter is a variable with a value then 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 it the value of the seccond parameter, if the seccond parameter is a variable already then 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, it displays it directly onto the page. This file must exist in or under the <templates> directory.
do special action This function executes the command given, the command is must be an executable or a batch file, the command cannot be a system function like "ls" or "dir", 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 and energy, some (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, it will often do this with a page entitled "Error", on this page you will get a message telling you what it wrong. If this isn't very helpful then 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 explaination.