BeroList v2.5.5
===============
(c) 1996-97 by Bernhard Rosenkraenzer <bero@bero-online.ml.org>

CONTENT                                (last changed in version)
================================================================

1. WHAT IS BEROLIST                                        2.5.0
2. INSTALLATION                                            2.5.5
2.1. FILE PERMISSIONS / SYSTEM SECURITY                    2.5.0
2.2. KILLFILE                                              2.5.3
3. CREATING A MAILING LIST
3.1. USING THE new-list PROGRAM                            2.5.0
3.2. USING THE WWW-BASED LIST ADMINISTRATION TOOL          2.5.0
3.3. DOING THINGS BY HAND                                  2.5.0
3.3.1. ASSIGNING THE ADDRESS                               2.2.0
3.3.2. CONFIG FILE                                         2.5.4
3.4. MEMBERS FILE                                          0.1.0
3.5. OPERATORS FILE                                        0.1.0
3.6. FOOTER FILE                                           0.1.0
3.7. WELCOME FILE                                          0.1.0
4. UPGRADING FROM 0.x.x AND 1.x.x VERSIONS TO 2.x.x        2.0.0
5. ACCESSING THE GDBM ARCHIVES VIA WWW                     2.3.0
6. PROBLEMS                                                2.3.5
7. UPDATES                                                 2.5.0
8. CHANGING THE CODE                                       0.1.0
9. THE BEROLIST MAILING LIST                               0.1.0
10. COPYING                                                2.5.1
 

====================
1. WHAT IS BEROLIST?
====================

BeroList is an easy-to-use, easy-to-install mailing list server. Unlike many
other mailing list servers, BeroList does not require perl to be installed
on your system.
Since it does not require any interpreters, it is faster than perl-based
servers, and uses up less system resources.


===============
2. INSTALLATION
===============
IF YOU ARE UPGRADING FROM A VERSION < 2.5.0, YOU WILL PROBABLY NEED TO
CHANGE YOUR LIST CONFIG FILES. ALSO, YOU CANNOT USE OLD LIST.H FILES.
IF YOU ARE UPGRADING FROM A VERSION < 2.2.0, IT IS RECOMMENDED TO CHANGE THE
ALIASES FILE TO THE NEW FORMAT. PLEASE READ ON, AND DON'T FORGET TO RUN
newaliases AFTER MAKING THE CHANGES.

Quick and easy way:
-------------------
configure; make user

If you need to adjust settings:
-------------------------------
To install BeroList, run configure, then run make.
configure accepts several parameters:
--enable-debug
	Compiles the program with debug information
--enable-debugonly
	Generate a version for debugging only. This version will send a
	detailed error message for each and any message sent to the list.
--disable-log
	Disallow generation of log files for all lists.
--disable-archive
	Disallow generation of archives for all lists.
--disable-unsub
	Disallow auto-unsubscription (see 3.3.2; errors-action=) 
--disable-postmaster
	Treat messages from postmaster@* as error messages - some ISPs don't
	seem to know about RFCs.
	This option is obsolete, and remains only for compatibility.
	Check 2.2 for more comments.
--enable-ntsmtp
	Use \r\n as newline in SMTP commands - some NT-based SMTP servers
	apparently require this, while a few others complain about it.
	Generally, if your SMTP server is running NT, you'll probably need
	this, if it's running something reasonable, you probably won't.
--with-bindir=x
	Specify alternate location for the list binaries (except for the
	CGI scripts) (default: /usr/sbin)
--with-killfile=x
	Specify alternate location for the killfile (see 2.2).
	Default is LISTDIR/killfile.
--with-logdir=x
	Specify alternate location for the log files.
	Default is LISTDIR/logs.
--with-hostname=x.y
	If your computer does not have the gethostbyname() function, you
	have to specify your full hostname (including the domainname)
	here.
	Also, if you want to use a CNAME rather than your primary hostname,
	you can specify it here.
--with-cgi=x
	Specify the path to your WWW server's cgi-bin directory
	By using --without-cgi, you can prevent BeroList from compiling the
	CGI scripts even if it detects your WWW server.
--with-listdir=x
	Specify the path for all list-related files. Defaults to /var/lists.

If you wish to change other settings, you'll need to edit the list.h file to
suit your needs. The options are documented in that file.

Since some servers are (still) sending error messages from a user different
from MAILER-DAEMON, it has become necessary to add the possibility to
prevent certain users from posting to lists. If you need this, #define
KILLFILE in list.h as the name of a file containing a list of addresses that
may not post to any list.
Each version of the program is tested on a 486 running the latest stable
Linux kernel and the latest 5.4.x libc, a Pentium 133MMX running the latest
beta Linux kernel and the latest 5.4.x libc, and an AMD K6/266 running the
latest stable kernel and glibc 2 (libc-6). It should work on other systems, as
well.
Minor changes may be necessary, especially for non-Linux Unix derivates (or
even non-Unix operating systems).

If you wish to use send sendmail for mail transmission (USE_SENDMAIL in
list.h), it is recommended to add the line 'Tbin' to your sendmail.cf file,
which makes 'bin' (which is normally used as the sender of mails) a 'trusted'
user, who may send messages with other user names in the From: field.

=======================================
2.1. FILE PERMISSIONS / SYSTEM SECURITY
=======================================
The list program needs read/write access to all list related files.
If you wish to use the WWW based list administration tools, so will they.
As the WWW server is (usually) run as a user and group different from
the user/group of programs called by sendmail (usually bin.bin), if you
don't want to grant everyone access to your list files, the program or the
CGI scripts will have to run setuid and/or setgid.

The (probably) safest way is to create a new user only for the list program,
and let all BeroList programs run as that user.
If your system has the useradd and groupadd commands, type "make user" (as
root) in the BeroList source directory. This will create a user and group
"lists" and install all programs accordingly. Also, it will make
/etc/aliases read-writable by the group lists - that way, the WWW list
administration tool can create and delete lists.
(NOTE: If you're using this with USE_SENDMAIL, replace "Tbin" in the
sendmail.cf file with "Tlists".)
To prevent wannabe-hackers from crashing the system by filling the harddisk
by sending tons of mail to an account that will never be checked (lists),
it's probably a good idea to make an entry like "lists:your.address", or even
"lists:"|/bin/cat >/dev/null"" to your /etc/aliases file.

"make install" will install the list program without setuid/setgid bits
(probably the best way if you don't want to use the CGI scripts). If you're
installing the CGI scripts, they will be setuid/setgid bin.bin. If sendmail
is running list as anything other than bin.bin, you'll need to change the
file owners.

=============
2.2. KILLFILE
=============
As SPAM mail is getting more and more wide-spread (and some ISPs won't send
error messages as MAILER-DAEMON as required by RFC), you might want to prevent
certain users from posting to your lists.
To do this, you can create a so-called killfile (Location is
/var/lists/killfile, unless specified otherwise with
--with-killfile=/somewhere). Anyone listed in the killfile will be
completely ignored by BeroList.
The format of the killfile is simple:
user1
user2
user3
Where userx is either a full e-mail address (such as
spamsender@spamforever.com), a username followed by '@' to prevent all
people with that username from posting (postmaster@ ignores all
postmasters), or @ followed by a hostname (@spamsenders.net will block all
messages coming from anyone@spamsenders.net).

==========================
3. CREATING A MAILING LIST
==========================

3.1. USING THE new-list PROGRAM
-------------------------------

As the configuration files are getting bigger, BeroList >=2.5.0 comes with a
program that will automatically set up the list config files.
Simply type new-list (after compiling BeroList) and answer the program's
questions.
If you're running a mailer that doesn't use /etc/aliases to look up
pseudo-addresses, or if you don't have root access, you'll need to add the
list address manually. If you don't know how to do this, check your mailer's
documentation/man-pages.
If new-list works for you, you can move on to 3.4.

3.2. USING THE WWW BASED LIST ADMINISTRATION TOOL
-------------------------------------------------

If you've installed the WWW based list administration tool correctly, you
can create new lists (and edit existing lists) by going to
http://your.machine/cgi-bin/listadm - after that, follow the instructions in
your browser. (And don't forget the password you (should) have defined in
list.h...)

3.3. DOING THINGS BY HAND
-------------------------

3.3.1. ASSIGNING THE ADDRESS
----------------------------
3.3.1.1. If you have root access
--------------------------------
  ENTRY IN /etc/aliases
  ------------------------------

  To create a mailing list, add the list to your /etc/aliases file. Create a
  pipe to BeroList's 'list' program. The list program will need to know the
  name of the list - it is strongly recommended to pass the list name as
  parameter to the program. If you don't, it will try to determine the name
  for itself, which causes problems if a message is sent to multiple
  recipients, or just Cc:'ed to the list.
  An entry for the mailing list test-list with BeroList installed in
  /var/lists should, for example, look like this:

  test-list:"|list test-list"

  If you want BeroList to be more compatible with other mailing list
  servers, duplicate the entry to

  test-list-request:"|list test-list"

  BeroList will handle subscribe and unsubscribe orders to that address just
  like ones directed to test-list.

  If you want BeroList to behave even more like these programs, you can
  make it accept control messages only on one address, list messages only
  on the other one:

  test-list:"|/usr/inet/lists/list -nocontrol test-list"
  test-list-request:"|/usr/inet/lists/list -control test-list"

  Run newaliases after making the change.

  Since BeroList determines by the message header's To: field which list is
  addressed, you can run several mailing lists using the same copy of
  BeroList. An alias entry like

  test-list:"|list test-list"
  startrek:"|list startrek"
  linux:"|list linux"

  would be exactly what the program is meant for. (If the lists are configured
  accordingly, of course. :) )
  
  It's also possible to have several entries for the same list, like

  test:"|list test-list"
  test-list:"|list test-list"

  though I don't see any real sense in that.


3.3.1.2. If you don't have root access
--------------------------------------

  Get a second e-mail account from your system administration.

  In the new user's home directory, create a file called
  .forward, which forwards incoming mails to the program.
  If you want to run the list "testlist" with the "list" program in
  /home/user1/, the .forward file would have to say

  "|/home/user1/list testlist"

  The mail address for the list is, in that case, user1@your.server, not
  testlist@your.server.


3.3.2. CONFIG FILE
------------------

Next, create a file in your mailing list (/var/lists) directory, called
listname.config (in our example: test-list.config).
All list-related filenames have to be lowercase, to prevent the program from
trying to use case-sensitive e-mail addresses.
You can define the following options in the config file (choices in brackets
are the default setting):

newusers=[yes]/no
		If set to yes, new users can subscribe to the list by
		sending a message with subject 'subscribe' to the list
		address. If no, new users must be subscribed by a list
		operator. (see 3.4)
closed=yes/[no]/operators
		If yes, only members of the list may send messages to the
		list. If operators, only list operators may send messages
		to the list (i.e. announcement lists).
		If no, everyone may send messages.
contact=address	Address of a list operator (for newusers=no lists only).
		Users trying to subscribe will get a message like
		"You may not subscribe to the list by yourself. Contact
		the list operator, (address specified here)."
		(defaults to root@(Host specified in list.h))
limit=size[,msgfile]
		Limits the size of messages sent to the list to size bytes.
		if message is specified, anyone sending a longer message
		will get the content of the file msgfile as error message.
sender=address/[original]/list
		Specifies the sender of messages generated by the list.
		If set to original, the sender will be copied from the
		incoming message's header.
		If an address is specified, all list messages have
		From: (specified address)
		in the header.
		If set to list, BeroList will determine the list address
		and use it. (Enables replies to the entire list.)
replyto=address/sender/list [default: none]
		Sents a Reply-To value in the list header - that way, you
		can direct replies to a sender=original list to the list
		rather than just the person posting the message,
		(sender=original, replyto=sender) or you can direct replies
		to an announcement list (closed=operators, sender=list,
		replyto=sender) to the sender, or even to another mailing
		list (replyto=other.list@whereever.org)
		If replyto is not specified, there will be no Reply-To field
		in message headers; replies will go to the address specified
		in sender=.
errors=forward/[unsubscribe]/both
		Determines how to handle a MAILER-DAEMON message.
		forward: Forwards the error message to the e-mail address
		specified in errors-to (see below).
		unsubscribe: The error message is analyzed to see if there
		were any fatal errors (invalid e-mail addresses, or
		something similar). If so, the address causing the problem
		is removed from the list.
		both: The message is analyzed, processed, and forwarded to
		the address specified in errors-to.
errors-to=address
		If a message from mailer-daemon@somewhere arrives to the
		list (normally an error message; caused mail loops if
		sender was = listname@listhost in early versions),
		it is sent to this address instead.
		If not specified, the error message is sent to the
		address specified as contact.
prefix=something
		If specified, [something] will be added to the beginning of
		each subject line.
log=file [default: none]
		If defined, a log for the list will be kept in the file
		specified.
		It is possible to specify the same filename for several
		lists.
newsgroup=group.name
		If defined, a copy of every message will be posted to
		the newsgroup group.name. This is primarily meant for
		keeping messages in local newsgroups.
		It will only work if you have defined HAS_NNTP in the
		list.h file.
nntp-server=address
		If you're copying list messages to a newsgroup, you can
		specify the nntp server here. By default, the one defined
		in list.h will be used.
		As the feature is meant primarily for local newsgroups,
		I think it makes sense to be able to specify different
		news servers for every list.
distribution=local/world
		Distribution header for NNTP messages. By default, the
		one defined in list.h will be used.
archive=filename/none
		If ARCHIVE is defined in list.h, the archive=filename
		parameter tells BeroList where to store message archives.
		archive=none tells BeroList not to archive messages for
		this list.
www-subscribe=cgi/mailto/no
		If you're using the WWW gateway, you can permit users
		to subscribe to the list using this flag.
		cgi = Users will be subscribed using a CGI script - the
		problem with this is that the user can enter any e-mail
		address (s)he likes, thereby subscribe whatever persons
		who _don't_ want to be subscribed.
		mailto = When clicking on "subscribe", the user can send
		a message to the list with the subject set to "subscribe" -
		the problem with this is that it might be a bit confusing
		for beginners.
www-unsubscribe=cgi/mailto/no
		Basically the same as www-subscribe - with the difference
		that this is for unsubscribing. (You wouldn't have guessed
		this, would you?)		
www-password=password
		If you're using the WWW-based list administration scripts,
		use www-password to set the operator password.

Example:
Our test-list.config might look like this:

newusers=no
closed=no
contact=roomcleaner@whitehouse.gov
sender=test-list@windows-sucks.linux.org
errors-to=damned.exploiters@dtag.de
newsgroup=local.test-messages
nntp-server=news.here.com
distribution=local
archive=none

It would result in a list that does not accept new users. Users trying to
subscribe would be told to contact roomcleaner@whitehouse.gov.
It would accept messages from people not in the list. All outgoing messages
would be sent from test-list@windows-sucks.linux.org
Errors would be sent to damned.exploiters@dtag.de.
Copies of all messages would go to the local.test-messages newsgroup on the
news.here.com server, there would be no message archives.

The config file must be readable by the user as which BeroList is running -
if you're running it from the aliases file, that's 'bin' (unless defined
otherwise in the sendmail configuration), if you're running it from the
.forward file, it's the user who owns the list.


3.4. MEMBERS FILE (optional)
----------------------------
Next, create a file called listname.members.
Its format is:

User1@Host1
User2@Host2
...

or

Realname 1 <User1@Host1>
Realname 2 <User2@Host2>
...

or any other valid format of e-mail addresses.

All people listed in the listname.members file are subscribed to the list.
If you do not create the listname.members file, it will be automatically
created when a user sends a 'subscribe' message to the list.

The file must be read-writeable by user 'bin' (or whatever user the list
program is running as). (Do 'chown bin.bin listname.members')


3.5. OPERATORS FILE (optional)
------------------------------
Next, create a file called listname.operators. (And again, it is probably ;)
a good idea to replace 'listname' with the name of your mailing list.)

Its format is exactly like the MEMBERS FILE (see 3.3.)

All people listed here are list operators, meaning they can subscribe and
unsubscribe users by sending messages with subjects like 'subscribe
root@bero-online.ml.org' or 'unsubscribe billg@microsoft.com' to the list.

The file must be readable by the user as which list is running.


3.6. FOOTER FILE (optional)
---------------------------
Next, create a file called listname.footer. (optional)
If the file exists, it will be appended to every message that passes the
list.

The file must be readable by the user as which list is running.


3.7. WELCOME FILE (optional)
----------------------------
Last, create a file called listname.welcome. (optional)
If the file exists, it will be sent to new subscribers.
If the first line starts with 'Subject: ', it will be used as subject of the
message.

The file must be readable by the user as which list is running.


===================================================
4. UPGRADING FROM 0.x.x AND 1.x.x VERSIONS TO 2.x.x
===================================================
Version 2.0.0 implements a completely new way of sending messages by
connecting to a SMTP server without using an external program.
The advantage is that mail to lists is processed significantly faster
(especially for large lists), and it uses less system resources.
If you insist on using the old way (it might be more reliable on some
systems), #define USE_SENDMAIL in the list.h file.


======================================
5. ACCESSING THE GDBM ARCHIVES VIA WWW
======================================
BeroList comes with two CGI programs to make message archives accessible
over the world wide web: messages and display.
messages displays a list of all messages posted to the list, display
displays a single message. As the scripts provide links to each other,
they will need to know where they reside. Check the file cgipath.h.

You must pass one parameter to the messages script: list=listname

For example, if you want to make the list test-list accessible over the www,
put a link on your www page pointing to
<A HREF=/cgi-bin/messages?list=test-list>test list</A>.
The messages script will take care of the rest.
You can also use forms to have users select the mailing list they want to
read.
A sample .html page for this is provided in the BeroList distribution as
examples/www/list.html.

If you wish to use the display script directly (it's primarily intended to
be called from the messages script), you need to pass two parameters to it:
list=listname and msg=number of message, beginning with 0.

For example, to link directly to the first message in the archive for
test-list, use <A HREF=/cgi-bin/display?list=test-list&msg=0>message</A>.


===========
6. PROBLEMS
===========
If you have problems with the program, read the PROBLEMS file. It describes
the most common mistakes people make in installing, and the solutions.
If nothing seems to help, drop a message to the mailing list
(berolist@bero-online.ml.org), or contact me directly
(bero@bero-online.ml.org).
If you're receiving MAILER-DAEMON messages from the list program, please
include them.


==========
7. UPDATES
==========
Whenever I make changes to the program, a new version can be found in the
ftp://ftp.croftj.net/usr/bero/BeroList
directory.
If you wish to be notified of updates, subscribe to the list
berolist@bero-online.ml.org.
You can also get the patch files as soon as they're out by subscribing to
the list berolist-patches@bero-online.ml.org.

====================
8. CHANGING THE CODE
====================
You are permitted to change the program code. If you make any improvements,
please help improving the product, and send me a copy of your version.
You can contact my by e-mail at root@bero-online.ml.org, or upload the
file to ftp://ftp.bero-online.ml.org/incoming/progs/unix
Or, drop a message to the BeroList mailing list,
berolist@bero-online.ml.org

Ok, ok... The code is mostly uncommented...
I want it to be a challenge for hackers... (err...) ;)


============================
9. THE BEROLIST MAILING LIST
============================
I have created a mailing list for discussion of BeroList which is running on
berolist@bero-online.ml.org (guess which program I used... ;) ). If you're
interested in improving the program, subscribe.


===========
10. COPYING
===========
The program may be freely distributed and used in any way as long as the
copyright notice is not removed.
Programs based on this program MUST have a reference to BeroList in
the documentation and (if possible) the program itself.
Anyone (ab)using the program for creating mailing lists with fascist, racist or
nationalist content, or for sending spam mail, is not entitled for support.



BBBBB   EEEEE  RRRRR     OOO       Bernhard Rosenkraenzer
B    B E       R    R   O   O      Auf der Hard 3
B    B E       R    R  O     O     54456 Tawern, Germany
BBBBB  EEEEEE  RRRRR   O     O     e-mail:  bero@bero-online.ml.org
B    B E       R  R    O     O              bero@startrek.in-trier.de
B    B E       R   R    O   O      Phone +49-6501-99609
BBBBB   EEEEE  R    R    OOO       Fax +49-6581-919191