		    NList 1.2.1
	Copyright (C) 1997 Erich Menge
	Significantly enhanced by Gabor Paller
	    (paller@javasite.bme.hu) (C) 1998

Introduction:

NList is a mailing list maintaining software that was made to be simple
yet full of features. Nlist has been tested on Linux and Solaris
platforms but it should be easy to port it to any decent Unix
platform.

i. 	Files of NList

Nlist uses the following files (mylist is the name of the list,
can be any string):
mylist.deny - people to deny, ALL or * means anyone - optional
mylist.approve - only useful to override a deny - optional
mylist.members - file containing users - required
mylist.config - configuration file - required, detailed later
mylist.spamfilt - spam filter rules, optional

In addition, every action nlist takes generates a reply letter
that goes back to the sender of the letter. The text of these
reply letters are stored in files. All these files are optional,
if any of them is not created, no reply letter will be generated
for that event. The body of the text file undergoes a simple
substitution scheme. Every occurence of [sender] string is substituted
with the sender of the provoking message, [listname]
substituted with the name of the list. The files are the
following:

mylist.already_on_list - subscribe was received for an address
                         already on the list
mylist.bad_subscribe -   Subscribe request cannot be processed
			 because it was sent to a common list
			 management address without listname.
mylist.bad_unsubscribe - Unsubscribe request cannot be processed.
mylist.banner - 	 Banner string appended to every letter
		         that the list processor sends out.
mylist.help -		 Reply sent back for help requests
mylist.list_disabled -   The list administrator disabled
                         the list, no subscription is allowed.
mylist.no_list - 	 A subscribe or unsubscribe request was
		         sent to a common list management
			 address but that list doesn't exist.
mylist.not_allowed -	 User is in the .deny file.
mylist.not_on_list -	 User unsubscribed but he or she was
			 not subscribed.
mylist.subs_message -	 Message sent back after successful
			 subscription.
mylist.unsubs_message -  Message sent back after successful
			 unsubscription.

There is a special listname called "control" for which help,
bad_subscribe and bad_unsubscribe files can be created. This
listname is used if nlist is configured with separate
address for control commands.

ii. 	Configuration file

Nlist requires that a configuration file be created for every list.
Its name is mylist.config and it contains configuration directives,
one directive for each line. Permission rights for the
config file should allow writing - nlist never writes
this file but obtains write lock for it to protect other
writable files. There is a special config file called
control.config that may be necessary to create. The
control.config is used only if nlist works in
separate control address-list address mode, in this case
configuration for the control address is stored in this
config file.

Lines in the configuration file beginning with # are treated
comments. If the value of a parameter is denoted as <address>,
the following substitution names are available.

sender - address of the sender of the message
addressee - address of the addressee of the message
list - address of the list

Any other string is treated as e-mail address not to be
substituted.

The following directives are available:
closed=yes/no
    If the parameter is yes, writing to the list is allowed
    only for subscribed members. Default: no.
subscribe=yes/no
    Controls whether subscription is allowed. Default: yes
senderbanner=yes/no
    If sender banner is switched on, each letter sent by the
    list processor starts with a line that contains the sender
    name. It is useful if the list is configured so that the
    sender address is not included into the e-mail headers
    (from=list, no replyto). config.h sets the sender banner
    text. Default: no
loglevel=<logging level>
    Sets the logging level. Logging level is a number between
    0 and 5. Each message is assigned a priority and is written
    into the log file if its priority is smaller than
    the current logging level. The name of the log file is
    mylist.log, but error messages may be sent to general.log
    or control.log in case of setup errors. Log levels:
    1 - log fatal errors
    2 - log warnings
    3 - log list command execution information and letters
	rejected by the spam filter
    4 - log incoming letters and list processing
    5 - log SMTP and NNTP sessions
    Default: 1
logging=yes/no
    Switches the logging on/off. If logging is off, error messages
    will be sent back as error letters by sendmail else they will
    be written in the log files. Default: logging yes.
list=<e-mail address>
    Address of the list. Required parameter.
from=<address>
    Address written to the From: e-mail header. Default: sender.
to=<address>
    Address written to the To: e-mail header. Default: list
replyto=<address>
    Address written to the Reply-To: e-mail header.
    Default: empty string, no reply-to.
errorsto=<address>
    Address written to the Errors-To: e-mail header.
    Default: empty string, no errors-to is generated.
title=<title string>
    Sets the title of the list. The title string is appended
    to the beginning of the subject of every list distributed
    from the list. If the title string is already in the subject
    (for example if it was reply to a letter distributed from the
    list) the string will not be appended. Default: empty string,
    no title processing
timeout=<seconds>
    Timeout before error is reported if nlist cannot
    grab lock for the config file. It means that an instance
    of nlist is in the critical region an doesn't want to
    give up the lock. Default is 60 seconds but it may be
    necessary to increase this value if the list has
    many subscribers.
smtp_server=<servername>
    Name of the SMTP server. Default: localhost
domain_name=<SMTP server domain name>
    Domain name of the SMTP server. May be necessary in
    certain sendmail 8.x configurations. Default: empty
    string, simple HELO messages
archive=<archive directory name>
    Name of the WWW-archive if archiving is enabled. WWW-archiving
    is treated by the listarchiver program that is invoked
    automatically by nlist if archiving is enabled. Default:
    empty string, no archiving.    
newsgroup=<newsgroup name>
    If given, nlist relays the traffic of the list to the
    given newsgroup. Default: empty string, no NNTP relaying.
nntp_server=<server name>
    Sets the name of the NNTP server. Default: localhost.
nntp_port=<port number>
    Sets the port on the NNTP server. Default: 119, NNTP
    standard port number.
nntp_list=<e-mail address>
    If given, nlist will consider the list address as the
    given address but only when posting to the news.
    This way anti-spam address can be specified. Default:
    the address specified at the "list" variable.
nntp_from=<address>
    If given, nlist will post to the news with this From
    specifier. Default: address specified by the "from"
    variable.
nntp_replyto=<address>
    If given, nlist will set the Reply-To header according
    to this variable. Default: use "replyto" variable. 

iii.	Enabling WWW-archiving

This distribution of Nlist comes with the listarchiver utility
that can archive list traffic. If the archive configuration
parameter is set up properly, Nlist invokes this utility
automatically to archive the messages to a Webarchive.
List managers has to designate a directory for WWW-archiving
and create an index.html file into it. This is a regular
HTML file that has one special line.
	    <!-- LISTEND -->
Listarchiver inserts the archive directory to this mark.
All other HTML-creating and modification is handled by
the archiving tool.

Web-managers has to set up a virtual directory for Nlist
icon pictures. The default name is /listicons, can be changed
in config.h. Three icons, back.gif, forward.gif and up.gif
are accessed from this directory, a default set comes with
the Nlist distribution.

Note that the archive directory must be writable by the
mailer daemon process. 

iv.	Spam filters

Unfortunately spam is the everyday reality of the Internet.
It seems that no law, netiquette, flame war can cease
the flow of unsolicited e-mail. If a spammer finds a mailing
list, it can be very annoying as he can use the list as
a free of charge spam helper. If your list is found by spammers,
you may want to take a look at nlist's spam filter feature.

The spam filter is configurable, so the user has to define
what is considered to be spam. Nlist looks for mylist.spamfilt
file, if one is found, it uses the ruleset in this file.
The ruleset describes how many occurences of certain word
combinations declared to be characteristic spam messages. It
is best described by an example.

free 4 sample 2

This rule line says that if the word "free" appears 4 times or
more AND the word "sample" occurs 2 times or more, the letter
is a spam. If the ruleset is extended by another line:

free 4 sample 2
make 1 money 1 fast 1

then the rule says that free and sample must occur 4 and 2 times
respectively OR make, money, fast words must each appear at least
once so that the spam filter be triggered. The tokenizer cuts down
punctuation marks and ignores case so the pattern "free" matches
free, FREE, FreE, <free>, FREE!!!!!!, *******FREE******* and
so on.

Empty lines or lines beginning with # in the ruleset are ignored.
Spam filter configuration errors are sent to the log if the log
level is at least 2.

Spam letters are swallowed by the list processor without warning.
If the log level is at least 3, spam letters along with the rule
that provoked their filtering will be written into the log file.

Note that nlist takes every precaution possible to avoid mail
loops and its filters try to remove every automatically
generated letter. These actions of nlist are not influenced
by the spam filter configuration.

v.	News relaying

Nlist can relay the traffic of the list to an Usenet newsgroup.
Before you take this step, obtain the agreement of the newsgroup
of question, else you will be considered spammer. You may want
to create a newsgroup of your own that you use only as an
auxiliary access to your list. Anyway, there is another danger:
spammers. Spammers adore to grep newsgroups for updating their
e-mail database so if you decide relaying to Usenet, spammers
will find you. Nlist has spam filter and Usenet anti-spam address
feature to make their work harder.

News relaying is switched on by specifying "newsgroup"
variable in the config file. For example:

newsgroup=hun.test

Other settings may be necessary. Most likely the news
server must be specified where the machine running nlist
has post permission.

nntp_server=news.foo.edu

Always think about spam if you connect your list to the
Usenet. Nlist features anti-spam address specification
so that articles sent to news be less usable for address
collectors. You can set the list, from, replyto addresses
that are only effective when nlist posts to the Usenet.

nntp_list=!spam-mylist@myhost

Always be responsible when using anti-spam address feature.
Embed a footer in the message that gives the correct address
of your list else YOU will be a spammer.

vi. 	Setting it up and using

1. edit config.h to suit your desire
2. type make;make install as root
3. In /etc/aliases put a alias for commands such as subscribe and unsubscribe

ie:
list: "|/usr/local/bin/NList/nlist"

then one for each list with the list name specified as an argument
ie:
mylist: "|/usr/local/bin/NList/nlist mylist"
then make sure that a mylist.members exists (usually empty)

Alternatively Nlist can be used with only one list address.
In this case the command address is the same as the list
address and subscribe and unsubscribe requests can be sent
as simple "subscribe" and "unsubscribe" strings in the subject.
This way Nlist can be run without supervisor privilegies from
.forward file of an ordinary user. .forward must contain the string
in the form:

|<directory name>nlist mylist

where directory name is the place the nlist binary is stored.

4. Set up mylist.config.

Take special care when specifying smtp_server and domain_name.
If you are on a properly managed Unix server, you don't have
to care much about them. (Still, you may have adventures
with domain_name, see the Help!!!! section). If your network
configuration is a bit trickier, it may need some fiddling.
Raise the loglevel to 5 and follow SMTP conversations in the
log if necessary. Nlist will not send any letter if the SMTP
connection is not functioning properly.

5. create a .deny, etc. if needed.

Users can mail list@hostname with the subject "subscribe mylist" to subscribe
"unsubscribe mylist" to unsubscribe
Users can not subscribe if they are in the .deny file
If you want to only allow say your friends in you might put "ALL" in the .deny
and then put them in the .approve to let them in and not everyone else.
after a user is in the members list they can mail mylist@hostname with whatever
they want.

vii.	Contacting the authors

Bug reports? Questions? Comments?
Send mail to erich@minn.net
Problems with version 1.1, 1.2 ?
Send mail to paller@javasite.bme.hu

viii.	Help!!!

Problem: 
I get permission denied errors back from the mailer daemon when I try to use 
the list

Fix:
Find out what user sendmail is executing nlist under. 'chown'
it to that user then 'chmod 700 nlist' also make sure that the
list files are also set appropriately. Note that the *.config
files must have write permissions for nlist.


Problem:
I get errors that the file isn't found but the members file is with nlist

Fix:
make sure PATH is defined right in config.h, set PATH to wherever your
list files are located. Also make sure it doesn't have a trailing /

if that doesn't work make sure the permissions for the list files are correct

Problem:
Nlist is properly installed but it doesn't seem to work at all.
I am desperate.

Fix:
Execute the nlist binary directly from shell with one of
test-msg files. Example:

nlist example <test-msg

This may bring up error messages that couldn't be shown
before. For example if for any reason the connection with
the SMTP server is not working, nlist simply cannot shoot
back error letters. Note that this fix will not show permission
problems. Another good places are the log files if logging is
on and nlist has the file permissions to create them. You
must be aware that if logging is on and nlist doesn't have right
to write its log files, error messages will be completely
lost. If you have a very weird problem, switch off logging
and run nlist from shell.

Problem:
Okay, now I can see that there's something with HELO and
domain names.

Fix:
You have sendmail 8.x and its ruleset prescribes obligatory
domain names. Set the domain_name configuration option
to whatever the domain name of your SMTP server is and
it should work.

Problem:
nlist still cannot communicate with the SMTP or NNTP server.

Fix:
Raise the log level to 5 and nlist will log SMTP and
NNTP sessions.

Problem:
Some strange letters arrive from the wilderness and I
want to find out what happens.

Fix:
Raise the log level to 4 and nlist will copy every incoming
letter to control.log.

Problem:
nlist doesn't create log files as I requested in the config
file.

Fix:
Make sure that nlist has right to create or write log file. Files
used are general.log, control.log and mylist.log. If nlist
running under the sendmail daemon doesn't have right
to create these files, create them by hand and give the
necessary rights (write for the daemon user). Also be sure
that you set the correct logging level in the correct config
file. If you use separate control and list addresses, your
commands going to the control address use control.config
and their log output goes to control.log.

Problem:
I have installed nlist in a one control address-one (many)
list address configuration but something is not right
with the control address. For example the help feature doesn't
work.

Fix:
You haven't created configuration file for the control
address. You must set up a file named control.config and
fill it up as any other config file.

Problem:
Time by time I get error letters that config file cannot
be locked.

Fix:
Your list is very long and it takes long time to process
all the subscribers. If another nlist request arrives
during this time, this request has to wait for the other
instance to finish its operation. Increase the timeout config
variable.

Problem:
WWW-archiving doesn't work correctly.

Fix:
Have you checked the errorlog file in the WWW-archive directory ?
The listarchiver utility sends its error messages to that file.

ix.	To-do

Among many to-dos are moderated lists and digest option.

x.	Disclaimer

This program is distributed under the GPL and comes with no warrenty what so
ever. Please consult the GNU General Public License included with this program
for more information.
