NetAuth

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.

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 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....

Download the self extracting archive from netwinsite "netauth40a.exe".
From the command prompt type...
netauth40a.exe
cd\natemp

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

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....

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:
http://mysite.com/scripts/netauth.exe?cmd=login
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
http://mysite.com/nademo.htm

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"

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

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...

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	<templates>	/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	<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 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).

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:
http://mysite.com/cgi-bin/netauth.cgi?cmd=login
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
http://mysite.com/nademo.htm

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...

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:

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:

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

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:
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 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.

In addition to a POST and QUERY NetAuth can now be executed from command prompt. To find out how, please click here

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 a user provided that the name is unique, 'user_add' is set as '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).
alias_save	Yes	alias_name	create_as_alias, user	This command adds an alias for the user or the selected user account (when admin / power user selects one). If 'user' is given and 'create_as_alias' is 'true' then a new account is created and becomes an alias for 'alias_name'.
alias_delete	Yes	alias_name	none	This command deletes an alias for the user or the selected user account (when admin / power user selects one).
alias_check	Yes	none	none	This command scans the database for any aliases for the user or the selected user account (when admin / power user selects one).
check	No	none	none	This command displays the check.tpl page.
check1	No	user	full_name	This command checks the provided 'user' name against current users. If no other user / mailing list has that name, the user is presented with the new.tpl page. Otherwise, they are given the again.tpl page with some suggested alternative names.
del	Yes	utoken	none	This command deletes the user account. The user must be logged in, and user_del must be set to true.
fwd1	Yes	utoken	none	This command loads the user's 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) and the option of keeping a copy 'fwd_copyself', this is simply a checkbox. There is the option of having an automatic 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 against 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 except that it logs users into DMailWeb.
mail3	Yes / No	none	utoken, name, pass	This command is the same as the above two except that it logs users into WebMail.
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 to the 'passwd.tpl' page.
passwd1	Yes	utoken, pass, repass	none	This command changes the user's 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 user's list of questions/answers for password retrieval.
passwd3	Yes	utoken, pq_*, ...	none	This command removes question x from the user's list of questions / answers. X is given as pq_1, or pq_3, etc... and is simply a checkbox.
passwd4	No	none	name, panswer	This command returns to the 'forgot.tpl' page. If name is specified then a password retrieval question is also given. This process can only be undertaken 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. If it is correct it changes the user's 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 user's quota field, limiting the email space which is 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 and then 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 user's 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 file so that the 'begin_stat' template command (see Template Files) can give up to date information.

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.

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...
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.

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...

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...

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....

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

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

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.

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.

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.

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.

The "admin" setting determines which accounts are administrators. If you have no accounts in the NWAuth database, you will need to add one before you can attempt to login and administrate. The administration setting must match the Database name of the account. If this is a name with a prefix like a_bob then administration 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 only administrate a certain virtual domain, place the administration setting inside a vhost section of the netauth.ini file. For example...

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.

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.

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".

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.

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.

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...

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 ...

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.