Products Downloads Prices Support Company
DMailWeb and CWMail
Common Links
Download Now
Features
FAQ
Customer Comments
Example Gallery
Updates
License
WAP/WML Support
CWMail Links
Email Support
Demo
Users guide
Manual
DMailWeb Links
Email Support
Demo
Users guide
Manual
   


DMailWeb - Installation and Management Guide

NOTE: This product is frozen, and only supported for existing customers, new customers should use WebMail instead.

http://netwinsite.com/webmail

This guide is intended for system administrators who are installing, customizing or managing a DMailWeb site. DMailWeb works in conjunction with a web server and your normal email POP and SMTP servers. DMailWeb can be extensively customized to provide distinctive web based email service for your customers. The web pages the clients see are based on a series of template files which can be modified to suit your particular needs. These template files make use of template variables to refer to all the configuration, user or message specific items. This allows the templates provided to be used as they are, or completely re-written to provide a particular look and feel which matches other web pages from your site. For the users, processing their email from a web-browser has the advantages that they do not need to setup an email client package, and that they can access their email from a web-browser running on any computer located anywhere which has access to the web server.

The following sections describe:


NT Installation

The self_extracting archive you have downloaded will normally run WMSetup 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:

You must install the DMailWeb 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"

You also need to copy all the template files to a directory on your system, it can be anywhere as long as you define the templates variable in dmailweb.ini to point to the same place. Note: By default the DMailWeb user files are stored below the template directory. Therefore the template directory should not be in the web-pages tree as direct access to user files could be a security risk.

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.

Example:

    download the self extracting archive from netwinsite

    dmweb10.exe          # Unzip the self extracting archive into tempdir

    cd \dmtemp             # Change to temporary unpack directory

 

    mkdir \dmweb          # Create a directory for templates

    copy * \dmweb        # Copy docs etc to destination

    copy *.tpl \dmweb	 # Copy the templates to destination

    copy *.gif \dmweb	 # Copy the template gifs to destination

    copy dmailweb.exe "inetpub\scripts"   # Copy cgi file

    copy dmailweb.ini "inetpub\scripts"    # Copy ini file (must be with .exe)

    del  \dmtemp                                         # Remove temp files

Now edit dmailweb.ini and define values for the four settings shown below:

  • notepad \SERVER_ROOT\cgi-bin\DMailWeb.ini
Symbol Example Explanation
pophost pop.your.domain The name or IP number of your POP server
templates \dmweb The directory where you have copied the *.tpl files
smtphost mail.your.domain The name or IP number of your SMTP server
domain acme.com Your domain, this will be used to contruct email addresses

If you wish, you can tailor the template files to give DMailWeb the same look and feel as your own web pages. It is assumed you know how to edit raw html files, in addition there are some variables that you can use. The list of variables depends on which page DMailWeb is showing. For example the %%h_subject%% variable only works when displaying an item, or directory listing.


Unix Installation

 

Normally you just download the distribution set uncompress and untar it
and then run the installation setup wizard WMSetup. For example

  • download the distribution set from netwinsite to a temp directory
  • uncompress dmweb10.tar                      # Uncompress tar file
  • tar -xvf dmweb10.tar                           # Extract distribuition files to dmisp sub-directory
  • cd dmisp                                            # Change to temporary dmisp sub-directory
  • ./wmsetup                                          # Run setup wizard

Then just answer the questions to complete the installation. If you want to perform the installation by hand rather than using the setup wizard use the following instructions:

You must install the DMailWeb 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"

You also need to copy all the template files to a directory on your system, it can be anywhere as long as you define the templates variable in dmailweb.ini to point to the same place. Note: By default the DMailWeb user files are stored below the template directory. Therefore the template directory should not be in the web-pages tree as direct access to user files could be a security risk.

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.

If you happen to be using httpd and it's in /home/httpd then the command file install.sh supplied will do the installation or upgrade for you. Note: It will not overwrite templates or the ini file in case you already have modified ones.

Example:

    download the distribution set from netwinsite to a temporary directory

    uncompress dmweb10.tar          # Uncompress tar file

    tar -xvf dmweb10.tar            # Extract distribuition files to dmisp sub-directory

    cd dmisp                        # Change to temporary dmisp sub-directory



    mkdir /var/spool/dmweb                 # Create a directory for template files etc.

    chown nobody /var/spool/dmweb          # Set appropriate ownership

    cp -i ./tpl/* /var/spool/dmweb         # Copy template files over

    cp * /var/spool/dmweb                  # Copy docs etc.

    cp dmailweb.cgi /home/httpd/cgi-bin    # Copy cgi

    cp -i dmailweb.ini /home/httpd/cgi-bin # Copy ini file  

    rm -r -f ../dmisp                      # Remove the temp files

Note:  .ini must be with .cgi 

Now edit dmailweb.ini and define values for the four settings listed below:

  • vi /SERVER_ROOT/cgi-bin/DMailWeb.ini
Symbol Example Explanation
pophost pop.your.domain The name or IP number of your POP server
templates /var/spool/dmweb The directory where you have copied the *.tpl files
smtphost mail.your.domain The name or IP number of your SMTP server
domain acme.com Your domain, this will be used to construct email addresses

If you wish, you can tailor the template files to give DMailWeb the same look and feel as your own web pages. It is assumed you know how to edit raw html files, in addition there are some variables that you can use. The list of variables depends on which page DMailWeb is showing. For example the %%h_subject%% variable only works when displaying an item, or directory listing.


Address Books:

CWMail/DMailWeb supports both private and shared address books and a pick list of recently used email addresses. The address books themselves are simple text files with one substituion per line.  The following are example lines:

bill=bill@sitcom.co

john=MrJohn@vet.doc.uk

friends=bill@whatsit,john@the.uni,dad@home

When processing to, cc and bcc lines the translations are made. For each entry in a to line which does not contain an @ symbol the following sequence of searches are performed.

  1. Search each of the users private address books for a match (ie those in addr_books)
  2. Search each of the public address books this user has entered in gadd_books
  3. Just add the local domain on

The search stops on the first match. So if bill is found in my own address book it takes preference. If no entry is found in any address book then the name is assumed to be for a local user and @localdomain  is added to the entry.

Public address books are just normal user address books but with the prefix public_

So if user john@netwin.co wants to share his home address book with pete he just stores it with the name public_home and then Pete can make an entry in his pick list page: john@netwin.co/public_home

If you as system administrator want to give everyone access to a company address book then you need to pick a user to administer it, eg. admin@my.company.co and then create the address book, say public_company then set in default.dat and/or use the system administrator page to add the line:

gaddr_books admin@my.company.co/public_company

The files used for address books always have an extension .abk and can only be stored in user directories.


Supporting Virtual Hosts or multiple email domains.

If you have multiple groups of users you can support them with CWMail in a variety of different ways. The method you choose will depend largely on the POP and SMTP server you have an how they support virtual domains.

Let's consider two groups of users; domain.one and domain.two. They both have a user called fred.

If you only have a few virtual domains you can just duplicate the CWMail cgi and ini file and run multiple copies specifying different pophost, smpthost and domain settings.

You can make users enter a pop-host as part of the login page. Either as a seperate field or as part of the username. Eg username ralph@domain2

The most powerful method is to use the vhost vend ini settings (requires version 2.1h or later). After all the common settings in the in file you can have sections for different virtual hosts. So if users from domain one use the url http://domain.one/cgi-bin/cwmail.cgi and users from domain two user the url http://domain.two/cgi-bin/cwmail.cgi both access the same copy of cwmail.cgi  but will be kept seperate by the vhost sections of cwmail.ini.

A typical example might be

 

vhost domain.one
domain domain.one
pophost pop.domain.one
vhost domain.two
domain domain.two
pophost pop.domain.two
vend

In the line
    vhost xxx
the xxx is matched against the host name in the url. (This is usually taken from the cgi environment variable SERVER_NAME but you can match against anything else - say HTTP_HOST by adding an ini setting vhost_match HTTP_HOST)

If the same pophost is to be used but with a username suffix the above would be changed to:

vhost domain.two
suffix /d2            or          suffix @domain.two
vend

The vhost - vend can bracket any ini settings to be applied to users from that domain, so for example to use different templates for domain one we might have:

vhost domain.two
suffix /d2            or          suffix @domain.two
templates \cwmail\domain2
vend


Using multiple template sets.

DMailWeb can be setup to use multiple sets of templates. You might choose to do this to allow for the use of multiple languages or just to allow individual users to select a set of templates they like working with. For example you might have a very simple set for use by young children or those new to computing, and an extended set for advanced users.

As an example the addition of a second set of templates referred to as Nicks Templates is described below. These can be retrieved from our website and then unpacked.

For NT, download   the self extracting archive dmw_ntpl10.exe and unpack it then follow the directions below.

For Unix, download the file dmw_ntpl10.tar.Z and then

uncompress dmw_ntpl10.tar

tar -xvf dmw_ntpl10.tar

then follow the directions below:

Nick's DMailWeb Templates Version 1.0 1/12/98
-------------------------------------------

This is an additional set of templates for use with DMailWeb
It can be used as a second set of templates which individual users may select at login time or from the config page. ALternatively it can replace the original set of templates.

To replace the original set of templates just copy the full contents of this directory into your existing templates directory and copy the .gif, .wav and .jpg files into your nwimg directory.

Alternatively if you have DMailWeb version 2.0h or later you can copy this directory to a directory like \dmailweb\ntpl, copy the .gif .wav and .jpg files to nwimg directory and then add a line to dmailweb.ini as follows
tpl_set 2 \dmailweb\ntpl

Individual users can then choose to use these templates from the login or configuration page.

To allow selection from the login page you add a line like this to login.tpl in the main templates directory.
<input type="checkbox" name="tpl_set2" value="ON">Use template set 2
Using this method of selection requires the choice to be made at each login.

An alternative is to allow the selection to be made from the config page. To allow this add the following line to the form in the login page.
<input type="hidden" name="tpl_set" value="config">


Allowing Users to change their passwords

The config.tpl page from version 2.1b onwards allows users to change their password by pressing a change password button. Note; at present this function is only available if the particular pop host also supports the poppassd protocol. See poppassd for an example of the unix source for poppassd.


Multi-Language Support:

The template files can be edited to provide an interface in a language other than English. In addition, the names of folders such as Trash, Copies to Self, etc. can be changed using ini file settings.

To translate error and informational messages place the following line in the ini file

language_file lang.dat

Then edit the lang.dat file as required. This contains two lines for each error or informational message contained in the package. Lines begining with a # are considered comments. The lines look like this:

I23 %d of %d users from %s user directories deleted successfully
Translation of: I23 %d of %d users from %s user directories deleted successfully

The I23 identifies the particular message, normally I is used for information and E for errors, W for warnings. The second of each pair of lines should be replaced with a translation into whatever language you want to use. When editing the line be careful not to remove the %d %s parts of the line as these are replaced at run time with relevant information. In the example above the actual message shown might be:

I23: 1 of 1234 users from c:\dmweb\u_* user directories deleted successfully


Diskuse and Diskquotas

One feature of DMailWeb is that it does not keep users message files on the web server and hence you do not need to worry about managing user disk space on the machine it runs on. For each user it keeps a small file with the users configuration options in it. This is a text file that you can edit directly or with a command script of some form.

With Version 1.4 of DMailWeb you can provide your users with a 'trashcan' and a 'copies to self' box. This allows them to restore deleted messages and to check and view messages they have sent without the overhead of always sending a cc to themselves. However, these two new features also mean the user is storing message files on your server. If you don't want them to be able to do this:

  • For trashcan you can include one of two settings in the ini file:
    1. no_trash true This will prevent user from putting anything in the trash. You would also need to remove references in the templates to trashcan so they don't think they have one.
    2. empty_trash_on_exit This will force an empty of trashcan on logout and login ( after 12 hours)
  • For the copies to self, just remove the references to this feature from the template files and they will not be able to use it.
  • Don't use the pop_delete_default true setting. This automatically removes messages from pop host after download BUT also means cache of new messages is not deleted on logout.

If you do want to use these features then:

  • include no_trash false setting in the ini file
  • You can limit the maximum disk space each user can make use of. If they exceed this limit they will no longer be able to put messages into either of these areas until they have emptied the trash or deleted messages from the 'copies to self' area. A setting in dmailweb.ini for default_quota which is copied into each user's user.dat file when they first use the system. You can either modify this global setting or the quota setting in individual user.dat files. The value is given in kilobytes.

Template Files:

Here is a list of the key template files, and a brief description of each. Each file may optionally have a frame version which has the same name with the suffix f for frames. For a frame login frame.tpl is loaded and menubar.tpl is placed in the top frame.

File Name Description
login.tpl The first page shown when DMailWeb is run, this handles the user login
list.tpl A list of new mail messages
item.tpl A single mail item
send.tpl Sending a new mail message
sent.tpl Confirmation message when a message has been sent
forward.tpl Forwarding one or more messages
error.tpl Used to display any error messages

There are also other example sets of template files available. If you create a particularly nice set you might like to share them with others. If so send them to netwin@netwinsite.com and we will add them to this list.

Download Page


Template Commands

The template files contain ordinary html plus %%variables%% plus various commands to the cgi. The commands may take the form of a submit button with a particular name or a defined variable of the form cmd=xyz. Most commands can be used in either format.   Normally if the command is used as a button name in a form, hidden fields are used to include other required information such as the user token and folder.

Example:

<form  name="List" method="POST" action="||b_action||" >
<input type=hidden name="utoken" value="||utoken||">
<input type=hidden name="fld" value="||fld||">
<input type=input name="list" value="Show New Mail Folder">

The same function can be used as an href, thus:

<a href="||b_action||?cmd=list&utoken=||utoekn||&fld=||fld||&&">Show New Mail Folder</a>

For common functions a preformatted version of this href is available. For example, the list new mail href  can be used thus:

<a href=||b_list||>Show New Mail Folder</a>

In addition a variable of the form set_xyz=abc or name="set_xyz" value="abc"
can be used to create a template variable with a value abc for the template page which is to be returned. Thus for example send message form could be changed to add the following variable
<input type=hidden name="fred" value="send message page">

In a similar way a form can contain a hidden value to perform the same function as in:

<input type="hidden" name="set_fred" value="bill">

The error.tpl page could then include :
Error processing ||fred||
to add send page specific information to the general error.tpl page.

If these set constructs are used with variables starting u_ then the value is also stored permanently in the user.dat file. an href finishing &u_fred=bill will add a line

u_fred bill

to the user.dat file and will replace ||u_fred|| in any template served with the value bill

 

The cmd=xyz forms are listed in the table below:

cmd = b_ Function
delitem   Delete msg and return to mail list page list.tpl
delitemn   Delete msg and show next message or message list if no next item.
list b_list Show list of New Mail folder
list_copy   Show list of copies to self folder
list_waste   Show list of waste folder
show&page=xyz   Display template page xyz.tpl
&set_fred=bill   Set template variable fred to contain bill and serve out as part of next template displayed
cmd=lg&url=xyz   Logout and then go to url xyz using the loaction: header

Template Variables

Here is a list of some of the variables that you can use in these template files. Note: in the template file each variable has the form %%variable_name%%

Variable Description Typically used in
%%do(program params)%% will execute any program and pass it parameters including translated template variables and replace with output from the program. For example:
||do(\cwmail\lookup.exe ||user||@||h_pophost||)|| might be replaced by
"Mr Smith"smith@our.site  using lookup.exe to access some database.
Note: The output from the program must be terminated with a newline character.
any
%%ifdef%%var%% Conditional inclusion if variable is defined any
%%ifndef%%var%% Conditional inclusion if variable is not defined any
%%ifequal%%var%%val%% Conditional inclusion if template variable equals val, case sensitive. eg.
%%ifequal%%nitems%%0%%
<h2> sorry no mail for you today
%%endif%%
any
%%ifnequal%%var%%val%% Conditional inclusion if template variable does no equal val, case sensitive. any
%%ifinstr%%var%%val%% Conditional inclusion if template variable contains val, case sensitive any
%%ifninstr%%var%%val%% Conditional inclusion if template variable var does not contain string val, case sensitive any
%%include%%file%% Reads the named file in which may include template variables any
%%include%%$fred%% Reads the file whos name is stored in the user variable  fred. note variable must contain whatever.tpl and file must be located in template directory any
%%var%%left%%nn%% return left nn chars of variable var any
%%var%%left+%%nn%% return left nn chars of variable var with trailing ...   eg left 4 of meeting is meet... any
||set||fred||bill|| sets template fred to value bill which will be served in next template and in the following lines of this template any
abook Content of currently selected address book pick.tpl
abook_edit Address book to edit pick.tpl
checknew If set on login page then cgi will check for new mail on login login.tpl frame.tpl
copyright An href and copyright notice. Must remain somewhere on login or menubar page any
copyright2 similar but not an href any
add_br add <br> to end of each line in a message being sent. send.tpl
addr_books Pick list of current address books stored in user.dat variable addr_books pick.tpl
gaddr_books Group address book list as a comma seperated list stored in user.dat variable gaddr_books. Note prefix public_ and sufix .abk are added automatically pick.tpl
attachment_names List of attachments to message being forwarded (set when forwarding using the forward_edit command). fwdedit.tpl,fwdeditf.tpl
attachments List of links to display/save attachments. If inline is true then %%attachments%% is not defined. item.tpl
action, b_action Ref to DMailWeb. Example <img src="%%action%%/myimage.gif"> Will load file from templates directory which user does not normally have access to. list.tpl
begin_list Starts list of new mail messages list.tpl
begin_flist Starts list of folders within list use variables:
f_name folder name
f_msgs number of messages in folder
f_size   size of folder in kbytes
f_new number of new messages in folder
f_unread number of unread messages
f_del href to delete folder
||fld_rename||f_id|| button name to rename folder
f_name||f_id|| variable to contain new name for a folder
f_delete complete <a> to delete folder but blank for non deleteable folders ie new trash copies tos self
f_rename complete <input tag for rename ///ly blank for 0,1,2
f_newname complete <input tag for new name ///ly blank...
f_tmsgs, f_tsize, f_tnew, f_tunread   totals for all folders
folders.tpl
b_follow Goes to form for posting followup messages item.tpl
b_forward Ref, forward this message to someone  
b_forward_edit Ref, forward and edit this message to someone. Uses fwdedit.tpl list.tpl
b_item Show a specific mail message list.tpl
b_list Ref, List new mail  
b_list_next List next page of messages in a folder any
b_list_prev List previous page of messages in a folder any
b_next Next mail message item.tpl
bn item number for b_next so that you can roll your own with b_action?cmd=item&item=||bn|| etc. item.tpl
b_prev Previous mail message item.tpl
bp item number for previous mail message for roll your own b_brev item.tpl
b_reply Ref, send a reply to this person  
b_replyall Ref, Send a reply to everyone whom this message was to  
b_send Ref, Send a new message to someone  
disk_quota_kbytes Disk quota in kbytes *.tpl
disk_used_kbytes Disk used in message files in kbytes *.tpl
docmd When a href include variable newframe= then query - newframe= is put into docmd and passed to frame.tpl for later action. This allows all frames to be refreshed and something other than list put in list frame. frame.tpl
end_list Ends list of new items list.tpl
end_flist Ends list of folders folders.tpl
error_do If set then on error do this command rather than servng error.tpl eg in send.tpl adding <input type="hidden" name="error_do" value="list"> would return to send page if to: was not specified *.tpl
from This user's email address  
fwdedit Set during command forward_edit so spell-check will return to correct fwdedit template. fwdedit.tpl, fwdeditf.tpl, sp_show.tpl, sp_edit.tpl
fwdedit_attachments Used to preserve the state of forward edit attachments checkbox fwdedit.tpl, fwdeditf.tpl, sp_show.tpl, sp_edit.tpl
fwdedit_headers Set during command forward_edit. Allows inclusion of 'one-time' initialisation code in fwdedit templates. fwdedit.tpl, fwdeditf.tpl
h_subject The subject for a given mail message list.tpl,item.tpl
h_date The date for a given item items.tpl
h_date_d 1 to 31
h_date_y 2001 etc
h_date_m jan feb mar etc.
Broken out date for a given item items.tpl
h_date_time The time from h_date in this format 1:15:06 pm list.tpl
h_date_t24 The time from h_date in 24 hour format ie 13:15:06 list.tpl
h_flags    
h_from The "From:" header from the current message list.tpl
h_isreplied 0 or 1 if message has been replied to
h_sender Sender: header line
h_to To: header line
h_xfrom The "From:" header from message we are forwarding fwdedit.tpl
h_lines The number of lines in this message list.tpl
http First part of protocol variable ie http:// or https:// or wml:// as appropriate any
info_msg Informational message such as "Quota exceeded 23 messages left on server" *.tpl
item The UID (Unique Identifier of this message assigned by DMailWeb)  
item_id The number of this item ( ie msg) eg 3 or 4 item.tpl
last_login Time of last login. This is only served the first time list.tpl is displayed after a login list.tpl
list_i The message number on this page ie 3rd of 10 on this page list.tpl
list_m The message number as in the 13th of 20 list.tpl
logged_out If user  is logged out this is set to "true" any
max_download_msgs Maximum number of messages to download at one time config.tpl
max_download_kbytes Maximum message size to download from pop host config.tpl
nitems Number of items in this folder  
nnew Number of new messages (new from pop server on this check)  
nm_sound url reference for sound to play when new mail arrives eg. /nwimg/nmsound1.wav config.tpl stub.tpl list.tpl
nosortaddr is checked if address book should not be sorted. read from config.tpl set in all templates config.tpl  read
all write
nosortpick is checked if picklist should not be sorted. read from config.tpl set in all templates config.tpl  read
all write
pages The number of pages of messages available in list.tpl nmsgs/page_size list.tpl
page_num The page we are on if multiple pages are being used in list.tpl list.tpl
page The name of the template file being served any
page_size Number of messages to show on each list page. Default 10 config.tpl list.tpl
pop_name0 Main pophost for this user any
pop_user0 Username for main pophost for this user any
real_name This user's real name, for use in friendly From: "User Smith"<usmith@abc.z>  
refresh time in seconds between auto-refresh of list.tpl for checking mail 0 means no autorefresh. Cant be set to < fetch_min which defaults to 200 seconds. list.tpl
remote_addr ip address connection came from any
reply This user's email address  
roffset Offset to first character not shown when a message is truncated due to body_limit. When read as part of a cmd=item command it specifies the offset. The line containing this character is the first one show as part of message body. Used in Next Section command in item.wml item.tpl
server vhost server name. Can be used with b_action to make it an absolute url rather than a relative reference. any
sort_on  sort_field and sort_direction returns field name messages are being sorted on with - prefix for descending

sort_field is just field name and direction is ascending or descending
these all appear in lang.dat so can be translated to foreign languages.

any
time time in seconds  (as returned by c time(NULL)) any
topick list of recent email addresses send.tpl
tolist list of recent email addresses and entries from address books send.tpl
tpl_setn tick boxes for tpl_set1 to tpl_set10 see below  
tunread Number of unread messages in a folder list.tpl
tpl_set Template set to use 1-10  defined in ini file Read from config and login. Set for config.tpl
uaddress users address any
uage users age  
upto message number to start display at in list.tpl list.tpl
usex users sex (as in male female boy girl ie a string)  
user Current username (excluding prefix or sufix)  
fuser Current username including prefix or sufix  
user_agent Contents of environment variable http_user_agent. Useful for picking up what browser is being used. Example:

%%ifinstr%%user_agent%%msie 3.02%%

any
umax_attach max size of attachment which can be sent  
uvar1-4 User variables stored for each user and initialized for new users from default.dat Can be used to add additional user options and field defaults. Note to clear a uvar from a form field a single - character is used as empty fields cannot be distunguished from non existent fields. any
v_asis Show page as it is so that html refs interpreted as is  
vhost vhost name being used instead of server name to match vhost lines in ini file.  
vhost_port vhost port number, enables use of vhosts with web-servers running on non-standard ports.  
var1-8 From ini file settings var1 to var8  

Message Headers available as variables:

Variable Description
a_from address only part of h_from so if h_from="Ralph Pugmire"rhp@netmail.com a_from=rhp@netmail.com
h_from From: header line
h_to To: header line
h_from_trim2 same as h_from_trim but if result is ralph@whatsit.com just return ralph
h_from_trim Just realname of from header ie john for "john"<jpc@a.b.c>
h_to_trim Just realname of to header i.e. john for "john"<jpc@a.b.c>
a_reply address only part of h_reply so if h_reply="Ralph Pugmire"rhp@netmail.com a_reply=rhp@netmail.com
h_reply Reply: header line
h_reference  
h_resent_from Resent-from: header line found in forwarded messages
h_subject Re: subject header line, Truncated values available h_subject_30, h_subject_40, h_subject_60
h_subject_raw Raw subject header line
h_date
h_date_mn
h_date_time
h_date_24
h_date_day h_date_d h_date_y h_date_m
date header from a message and various parts of that header using variables below
month as number 1 to 12
time am/pm
time in 24 hour clock
day in Mon, Tues, Wed...
day as a number 1 to 7
year
month
h_content-type  
a_cc address only part of CC header line
h_cc cc header line
h_lines Number of lines in message including header lines
h_bytes Number of bytes in message including headers
h_popn The number (in the users config page pophost list) of the pop host this message came from
h_priority if in send.tpl contents will be sent as Priority: header
h_kbytes Number of kilobytes in message, including headers

Obscure/Internal data

Variable Description
utoken Current login information for this user, must be carried thru all forms
fwdlist The list of items to be forwarded in a multiple forward operation
nfwd Number of items being forwarded

 

Hidden variables passed in from forms:

Variable Description
utoken Current login information for this user, must be carried thru all forms
fld The folder number being processed
vhost Value of vhost to use instead of actual server name when matching vhost lines in ini file
send_date On send use this value rather than servers date_time for date: header on message. Usefull if user are in a different timezone from the server.

True/False Settings

Variable Description
autoadd add addresses to pick list automatically
autoadda add addresses to address book  addr_booksa automatically
v_myfrom use users from address instead of original from address when forwarding a message

Note this is read from forward.tpl so if you do not provide a tick box and want it todefault true then you have to put it in as a hidded field with value "on"

v_font display variable width font, set to true or false, valid in config.tpl, item.tpl
fwdlist show all the headers or not, valid in items.tpl
v_inline show images inline, or as a list of attachments, items.tpl
sig Config setting, add signature to message.

Detailed Descriptions of Template variables:

%%include%%advert.htm%%

Useful for displaying adverts, you would setup a cron job (or program that runs every 10 minutes) to change the advert file, thus displaying a new advert each time someone reads their mail.


%%ifinstr%%var%%val%%

Conditional inclusion if variable var contains string val, case sensitive.

Example:

%%ifinstr%%folder%%New%%

<hf> This is the New folder</h4>

%%else%%

<hf> This is some other folder</h4>

%%endif%%

v_asis

Show page as it is so that html refs are interpreted as is.


User Settings

The settings for each user are stored in user.dat files one for each user. Each user has a directory which is a subdirectory of the template or work directory. So for example if the templates are stored in \cwmail a user ralph@myfirm.co would have a directory \cwmail\u_ra\ralph@myfirm.co which would contain a user.dat file containing the settings for user ralph. (Alternative hash methods can be set in the ini file to use more complex methods for creating user directories.) This user.dat file is a text file which can be edited by the system administrator. The default settings come either from global ini file setings or from the default user.dat file which is called default.dat and is stored in the main template directory. (Note you will need to create default.dat if it does not already exist) For example you might create a default.dat to change the default reply to address from the users login name to some prompt string such as "Enter your email address here" to do this just create default.dat with the single line"

dflt_reply Enter your email address here

You could also create batch scripts or programs to modify the contents of the user.dat files to do things like updating users disk quotas or changing their "Real name" based on the contents of some central user database.

You may also use the variable %%user%% within the default.dat file. For example to set uvar1 to fax-username you could add a line

uvar fax-%%user%%

A manager page is also provided as part of the cwmail/dmailweb cgi to enable the system administrator to change settings in the user.dat files. It allows you to change a setting for a wildcard selection of users and to perform other manager tasks. For example you might want to change the name of the "Trashcan" folder for all existing users, having changed the name for new users by modifying the waste_name ini file setting. To access the manager page you enter a url of the following form:

http://my.site.com/cgi-bin/dmailweb.exe?cmd=manager

It also requires the use of a manager_password which must match the corresponding setting in the cwmail.ini or dmailweb.ini configuration file. Note; if you put a manager password in the ini file you need to ensure web users cannot read this file. The directory should be set execute only for web users. The file should only allow owner read access so only CWMail or DMailWeb can read it. Or change to new form manager_password @file

The manager.tpl like other template files, can be completely tailored by the system administrator. It uses the following %%variables%%

Manager variables

Variable Description
uadd If checked then user.dat files not containing any value for the setting being modified will have a setting line added.
ub_only If checked only modify user.dat files for which this setting is blank or missing.
upurge If checked a purge of all cached new mail messages for the selected users will be performed. This is essentially a forced logout for matching users who have been logged in for more than 12 hours.
uwild Wildcard selection of users to process. Note: user name includes both username and pop account of the form: ralph@netwin.co.nz so to change ralph settings for all accounts use ralph* and to change all users with accounts on netwin.co.nz use *@netwin.co.nz
uset User setting to change. Examine user.dat file with a text editor to see what settings can be modified.
uval New value for setting uset to be entered into user.dat for each matching user.
last_purge Time of last purge of cached new mail messages.
nmatches Number of matching user/host name combinations
nusers Total number of user/host name combinations found on system
nadded Number of user.dat files which had a setting line added to them
nmodified Total number of lines in user.dat files which were modified to the new value (uval)

Manager Page:

An example of the manager page is shown below:

DMailWeb Management

This form allows you to modify user settings for a wild card selection of users by modifying the values stored in their users.dat files. These files store settings for a variety of options from disk quotas to default reply addresses. The user.dat files are simple text files and can also be edited directly with any text editor.

Manager Password:
1 of 2 user.dat files purged
2 of 2 user.dat files updated successfully
Apply to users matching: Setting to Change: New Value
Add a line for users with no curent matching setting Purge cache for timed out users

Results:

Number of users   2
Matching users   2
Lines modified   2
Files added to   0
Last purge   Mon Jun 29 20:41:15 1998

CWMail 1.7b Copyright NetWin Ltd


Hashing of User Directories:

For most systems the simple approach of using directories of the form workarea/u_fr/fred@netwin_co_nz for user fred at netwin.co.nz is best. This provides a spread of user directories and an easy way to find the user.dat for any given user. On some very large unix systems the directory lookups can be slow if there are more than about 800 entries in a directory. For these systems a second hashing more complex hasing method is provided. It is set by putting:
hash_method nhash
or
hash_method 2

in the ini file. This new method allows any characters in usernames and uses a two level directory structure    eg. workarea/n_a9/b4/encoded_user@domain.name
rather than just workarea/u_xx/user@domain_name
It provides a very flat distribution and will produce less than 800 directories per directory even on systems with many milliions of user accounts.
Note1: Most large systems even on unix do not see a problem with existing hash method which is more transparent.
Note2: As changeing the hashing method will make the cgi look in a different directory for a users files it should not be done on a working system. (Users would loose their messages and settings)
A utility wmcd which returns a user_directory for a given username@domain is included in the new distribution.

Example

wmcd ralph/a@domain.one%.two
.\n_i5\l9\ralph_Ja_Pdomain_Ione_9_Itwo

Later a change hash method utility will be provided to move user files should this become  necessary.


DMailWeb.INI settings

General configuration settings are stored in dmailweb.ini which must be in the same directory and have the same root name as the executable. So if the the cgi is renamed xmail.cgi then the configuration file will be xmail.ini

Symbol Example Default Explanation
@pop true false Allows user to enter pop host by using user@pophost in the username field in login.tpl. Without this setting user@pophost would be passed to the pop server as a username.
add_header <META HTTP-EQUIV="Pragma" CONTENT="no-cache"><META
HTTP-EQUIV="cache-control" CONTENT="no-cache">
blank Can be used to add html to the <head> section of all template files. The example shown would stop pages being cached by a browser on a public computer.
allow_java true false Allows the execution of java applets included in  html email messages. If the setting is false applets are effectively commented out of the message. The default is false to prevent trojan horse attacks.
allow_script true false Allows the interpretation of java scripts in html email messages. If the setting is false java scripts are effectively commented out of the message. The default is false to prevent trojan horse attacks.
allow_form true false Allows the interpretation of html forms in email messages. If the seting is false forms are effectively commented out of the message. The default is false to prevent trojan horse attacks.
allow_script true false Allows the interpretation of java scripts in html email messages (default is disabled (false) as this can be a security risk)
auto_login 1 netauth.exe $(workarea)/../netauth show=passwd.tpl none Allows auto_login to another product with a template href like this <a href="||action||?cmd=send_auto_login&n=1&utoken=||utoken||&&">Netauth</a>
See listf.tpl for examples of links and default ini files for example in settings. This method can also be used by third party cgi's Uses pass_file auto_login method.

Note: If the last parameter starts with a , it is inserted directly after cmd=auto_login rather than at the end - this enables one to send for example
cmd=auto_login,fwd1&othertuff=value to give multiple commands to netauth.

auto_logout_mins 200 60 Time since last activity for logged in user before cache of new mail messages is purged
body_add http://xxx.yyy.zzz blank Adds the line given to the body of all outgoing email messages. You can have multiple body_add lines to produce a multi-line addition. To add blank lines use a body_add line with trailing spaces.
Extended body_add functionality - requires version 2.8a
body_add ~command - execute 'command' and append it's output to the message.
body_add @file.txt - append the contents of the file file.txt from the templates directory to the message.
body_limit 2000 nolimit If set it will limit the number of characters served in message body in item.tpl or item.wml Used for browsers like wap phones which can only handle limitted number of characters. It can also be used as a form variable to make it user dependent and even agent dependant so it can vary when user connects from another device. See wbl for interaction.
cache_posts false true If false send the html headers to browser to stop it caching responses to POSTS headers sent are:
Pragma: no-cache
Cache-Control: no-cache
cache_posts true false If false (default) send the html headers to browser to stop it caching responses to POSTS headers sent are:

Pragma: no-cache
Cache-Control: no-cache
Expires: Tue,31 Dec 1996...

content_type text/x-html text/html HTML MIME content type, some servers allow 'special' features for documents with a modified type.
cookie_ipcheck 4 3 Determines how many sections of ip from address is matched when checking for use of cookie based login
copy_name sent_messages copies to self The name of the folder to store copies to self items in
cgi_path http://my.server.com/scripts/dmailweb.exe env var Sets the cgi_path. Only needed if Web Server does not set the appropriate environment variable for cgi's
date_format dmy mdy Sets the date format to month first or day first
debug True false Enables verbose debug output.
default_max_dkbytes 100000 4000 Used for initial setting and to limit users setting of max_download_kbytes. Messages larger than this will not be downloaded from pop server
default_max_dmsgs 20 100 Used for initial setting and to limit users setting of max_download_msgs. Only this many messages will be downloaded from pop server at one time.
default_quota 100000 100000 Initial disk quota for new users. Users quotas can be changed by modifying setting in each users user.dat file. Given in kilobytes
domain acme.com this host Used to create the email 'from address' for each user. Can be $pophost to signify use the pophost setting entered by user on login page or i default.dat
empty_passwords true false If you have some accounts without passwords and you want cwmail/dmailweb to  allow logins to these accounts then this setting must be set true in ini file.
empty_trash_on_exit true false Force an "empty trash can" on logout and login (after 12 hours)
extended_index true false Added in 2.7a If false it limits headers stored in index to keep it compatible with 2.6k and before.
For new systems this should be set true to enable all new features to work.
fetch_min 600 200 Minimum time before rechecking POP host for new mail for mail list page
fix_from true false When true the reply-to field is only used for reply_to header inside sent messages. The from header and envelope header are fixed as user@domain
fld_maxlength 20 14 Sets the max length for folder names which will be accepted
force_primary true false Insists that the user logs into your local pop server first.
frames_default true false If true then the default login is a frames login. In IE pressing Enter on login page performs a default login.
hash_num 5 2 The number of characters to use in hashing username for user files.
With setting 2 user johns files will be in workarea/u_jo/john@pop_domain etc.
hash_method 2  or nhash 1 Changes hashing method for user directories. Note! Dont change  on existing systems as user files wont be found after change.
hide_ip true false When true this setting stops this header being added to outgoing mail:
X-User-Info: ip.addrs.of.machine.running.dmw
hide_host true false When true this setting removes the  POP host name from the error message the user will see if their login fails. 
hide_x_mailer true false Removes the x-mailer dmailweb... header on sent messages if registered
ipcheck 4 3 Number of bytes of ip address to match when checking from address matches. For example if set to 3 from address 161.22.3.2 will match with 161.22.3.7
item_pre1 <p> <pre> The tag sent before a mail message body
item_post1 </p> </pre> The tag sent after a message body
item_pre2 <p> none The tag sent before a mail message body when variable_width_font display setting is in effect.
item_post2 </p> none The tag sent after a mail message body when variable_width_font display setting is in effect.
inline_options target="newpage" none Allows options to be set for inline http references in messages. Example target="newpage" will force a new browser window to be created when an inline reference is clicked.
keep_index true false Keep the index of new messages on logout so that message read and other flags are not lost. This requires storage on web server of about 100 bytes per message.
key 2222-333-44-222 1 month Registration key
language_file lang.dat none If included then lang.dat file will be used to translate information and error messages
last_first true false If true then when retrieving message from POP server the last message will be downloaded first. This is less efficient but if a user has 1000 messages and it is set to only download 100 at a time users may prefer to see the last(ie most recent) 100
limit_list true false if true then in list of mails when expanding begin_list end_list we check chars printed and if reach body limit we stop even if page size has not been reached. Usefull for wap phones.
lock_id 123 first part of hostname When seting up a server farm with several machines running CWMail and sharing a work area each must have a unique lock_id. THis will normally happen by default as the lock_id is set to this first part of the hostname. eg for netwin.co.nz it would be NetWin. If you are running two machines with shared cgi-bin  and hence shared ini file then you must NOT have this set in the ini file.
lock_old 100 300 A lock older than this (secs) is ignored. Too large a value means an account takes to long to free up after a problem occurs. Too small means user.dat can get overwritten just because POP server takes a long time to respond or transfer of file to user over slow link takes too long.
lock_wait 2 5 When waiting for a lock give up and return an error after this time in secs. Too short and you get cant get lock errors. Too long and load increases due to many copies of cgi waiting for locks.
log send,rules,cookie,user_rw,locks,dotlocks,query,environ,purge,body_limit
,top_reply,stat_reply,uidl_reply,list_reply,index
none list of extra items to log (when debug true)
log_file /logs/DMailWeb ini dir Directory to store the log file in
logout_time 16:30 or 2000 0 user utokens normal expire at midnight use this setting to make them expire at some other time of day hh:mm or seconds
lowercase_pophost true false Always lowecase pophost so Whatsit.com is same as whatsit.com
lowercase_password true false Always lowercase password so password secret is the same as Secret and SECRET
lowercase_username true false Always lowercase username so user ralph is same as Ralph and RALPH
no_manager true false Disable all manager access to cgi.
manager_ip 163.4.5.55 any wildcard list of ip addresses to accept cmd=manager from
manager_password mysecretpassword

or

@filename

none Password for access to manager.tpl manager page. Note if you put a manager password in the ini file you need to ensure web users cannot read this file. If you use @filename then you must put the password in a text file in template directory called filename.dat
match match headername matchstring variablename htmlvalue none match headername matchstring variablename htmlvalue

eg. match from "@netwin" fromnetwin bgcolor="#EE0000"
    would create a template variable ||fromnetwin|| with value bgcolour="EE0000" on lines in listf.tpl which have a from header containing string @netwin
  if "!@netwin" was used instead of "@netwin" then it would match lines which have a header name which does not contain @netwin

  as headername you can also use _flags which will contain some of
  read, unseen, new, file

max_sends 20 500 Maximum number of messages a user may send in one day.
mcache_kbytes 200 10 Messages larger than this initially only have their headers downloaded or cached
=0 means always leave body on server - never cache body
<0 means never leave body on server - always cache body
mcache_kbytes 200 10 Messages larger than this initially only have their headers cached
new_mail_name inbox New Mail The name for the folder that new messages are put in
no_checksum true false Normally when reading user.dat files a checksum is used and if its wrong the  read is aborted. If a third party application is being used to add setting to user.dat you may want turn this check off.
no_cmd_url true false If true then http links in a message dont use the form ?cmd=url&url=link
This fails on some servers but is more secure as it stop referer logs from capturing email cgi calls.
no_cookie_domain true true If true cookies are generated for a specific domain. THis is more secure as calls to other domains will not return the cookies.
no_delete mrbig@whatsit.com none User cannot setup delete rules which filter messages based on a string contained in no_delete. EG if no_delete=me@a.com then user cannot auto delete messages from me@a.com
no_quoted_printable true false Disable conversion to quoted printable when sending messages
no_ipcheck true false If true don't check for same ip from address during session.
no_new_users true false Disables new user account creation
no_sender true false If true then no sender header is generated for  new messages..
no_rename true false Disables use of rename file for updating user.dat. Needed on some shared nfs systems.
no_tcode true false Disables the use of tcode in login.tpl
This will reduce security but allows the use of a static  login page. The tcode is placed in the login page by the cgi and is checked at login. Each tcode is only allowed once. This prevents a cached login page being used again.
no_trash false true Disable delete actions from doing an auto copy to trashcan.
noedit_reply_to true false Prevents users from editing their default reply to field
noedit_real_name true false Prevents users from editing their real_name field
no_slash_filename true false When an attachment is shown within a message the url used contains /filename after the cwmail.cgi and before the parameter list eg. http://myplace.com/cgi-bin/cwmail.cgi/letter.doc?cmd=...
If you try to save the attachment to disk  this helps some browsers know what filename to suggest. However some web servers dont like anything after the cgi name and before the ?   This setting allows you to disable this feature if you have such a web server.
nwimg /images/nwimg ||b_action|| Relative url to use for locating images used in templates. These are normally stored in /nwimg in main web server directory but can be elsewhere. If no nwimg setting is included in the ini file then ||b_action|| is used which is the cgi path and the cgi will serve the images from the templates directory.
peruser_pophost true false If set then never refresh users pop_host setting from the ini file. ie always use the one from user.dat pophost 0 line. This allows each user to have a different pop host (stored in user.dat) even for DMailWeb
pick_abook_max 100 250 Max number of items from address books to be displayed in pick list
port 1100 110 POP port to connect on
poplist_width 20 no limit Limits the width of entries displayed in poplist list of pop hosts.
pophost pop.your.domain this host The name or number of your POP mail server
original_pophost my.test.com none When users are first created a directory for each userame@pophost is created. If you later change the pophost setting in the ini file they will be connecting to a newpophost but there settings are stored in username@oldpophost. By having an ini setting for original_pophost (which should never be changed)  you can change the pophost setting and DMailWeb will automatically translate as appropriate between newpophost and oldpophost.
pop_delete_default true false Sets the default setting for each new user. True implies delete message after download. If true then newmail cache is not removed on logout.
pop_retry 5 1 Number of times to retry connecting to POP when its busy. 1 second sleep between attempts
pop_busy locked by another user please try again try again If we see this string in a failed login reply from POP server then try again after a 1 sec sleep
pop_timeout 90 30 Timeout in seconds to wait for response to command from POP and SMTP servers.
purge_mins 600 no purges The time between purges of cached new mail messages for logged in users who have reached the auto_logout time
read_status true false If true then check the status header for  O for opened and if found set our read flag so we see message read elsewhere as read in cwmail/dmailweb
read_flag R O use with read_status true to tell it what to check for in status header - some POP servers use R for read and some O for opened
read_wrap 75 85 Wraps message lines in received messages at this point. Use -1 to set no_wrap
replyto_fixed true false Stops the user from modifying their 'reply to' field in user config.
reply_prefix false   or  ---    any string > The prefix used in ||quote_body|| for each line of message body used in reply
require_cookies true false If set true then it will only talk to clients with cookies enabled
rset true false Send POP server an RSET command before quit to stop it marking messages as read when read by cwmail/dmailweb but not deleted.
send_wrap 80 75 Wraps long message lines before sending them
set_charset false true When set we set the charset in content type header based on charset found in msg header. Used for displaying messages with special character sets.
set_status true false When true and RSET ini setting also true. On connection to pop server we only get headers using top n 0 and then send rset before quit. This makes pop server leave Read/unread flag in status header alone. Then when user reads message the flag will be set.
show_tiff true false Enable inline view of tiff images assumes browser supports tiff images.
smtphost mail.your.domain this host The name or ip number of your SMTP mail gateway
smtp_auth true false Enables authentication when connecing to the smtp server
stats true false if true then everytime a template file (eg fred.tpl) is served one byte is added to a file called stat_fred_tpl.s in workarea or fred_tpl.s in stats_path if that is defined
stats_path /var/spool/stats none Path for daily stats file. one line per login. default is no collection of stats. Logs:
  1. timestamp in seconds
  2. login username@pop_address
  3. connection from ip address
  4. messages served
  5. disk space used by messages
stream_max 10 1 Sends up to this many top commands at once to pop server. Some pop servers can't handle this but if yours can this will provide faster response on checknew when there are lots of new messages - eg 100's
suffix /domain.two none Appends a suffix to the username as used in tokens, user.dat directory name and pop host logins. Usually used with vhost sections.
templates /dmweb NONE The directory where you have copied the *.tpl files
text_stdin true false Set to true for buggy webservers that dont use binary for attachments. One javawebserver needs it.
top myframe _top On logout etc. target = top so if CWMail is to be run in a frame as part of some other page this will need to be set.
tpl_set n 2 /var/spool/cwmail/french NONE Set the path for an alternative set of template files. 1<n<10
timezone nzst GMT offset An alternative string to append to local time in date header of sent messages. eg nzst instead of -1200 for Wellington, New Zealand
use_page_size true false If true then lists of message are shown a page at a time. The default number of messages is 10 but can be set by user on config page.
user_prefix saveit_ u_ Any fields in forms which have a name starting with this prefix will have their values stored in user.dat and can be used in any template
uvar1-4 users computer type none Four general purpose user variables which you can store any user specific stuff in.
utok_cookie true false Allow user to move from within CWMail to other web pages and then return without logging in or keeping utoken
We serve utoken as a cookie on login with a 1 hour timeout and accept in queries and posts without utokens
u_eight_bit true false This is actually stored in user.dat If it is set then when displaying a message character codes greater than 127 are passed thru directly rather than converting into &#nn; format. See list.wml for an expample of its use.
valid_pop my.pop.host none limits pop hosts users can connect to
valid_to ralph*,*.nz none limits email adresses users can send email to
valid_user *smith,ralph,john none limits usernames which may be used to a wildcard list
var1-8 my_setting_for_var1 NONE Settings for user variables defined in ini file and used as variables in templates
vhost my.domain.two none Starts a section of ini settings which apply to a virtual host my.domain.two Note vhost sections must follow any general settings.
vhost_match HTTP_HOST SERVER_NAME The environment variable that is matched against vhost lines.
vend Ends a section of ini setting which apply to a particular virtual host
waste_name rubish bin Trash Can The name of the folder into which deleted messages are put
body_limit

wbl

2000 nolimit If set it will limit the number of characters served in message body in item.tpl or item.wml Used for browsers like wap phones which can only handle limited number of characters. It can also be used as a form variable to make it user dependent and even agent dependant so it can vary when user connects from another device. Can be set from login page and list page as wbl variable. ie if login page contains hidden variable wbl with value 10 then on login body_limit will be set to 10

Note: in ini file there can be a setting body_limit
        it is also stored in user.dat so ini file default is
        overwritten by user.dat value.
        It can also be set in template files (where it is called wbl rather than body_limit) template value overwrites user.dat value

work fred-george /work2 none For users with usernames between fred and george use work area /work2
workarea /var/spool/dmw_work templates The directory to create DMailWeb work files and user subdirectories in.