	fml installation guide on Unix
	--- fml Mailing List Server Package ---

				Ken'ichi Fukamachi

   EXCUSE FOR MY LIMITED ENGLISH (I WELCOME FIXES). 

   For easy guideline of installation and fundamental configuration,
   See
	http://www.fml.org/fml/examples/index-e.html

   For more details of internals, advanced configurations, see
   doc/op.en		(plain text)
	http://www.fml.org/fml/op-e/index.html

   For more details on advanced settings, please see the part III of
   doc/op.en		(plain text)
	http://www.fml.org/fml/op-e/index.html#Configurations

   For installation on Windows NT4, please also see INSTALL_on_NT4.
	http://www.fml.org/fml/

[Terminology]
   The word "ML" is the abbreviation of "Mailing List" in this document.
   % is the shell prompt.

------------------------------------------------------------
1	Quick Overview

2	What is ML?

3	Installation
3.1	Introduction
3.2	What is your OS?
3.3	A few checks before installation
3.4	Installing by makefml
3.5	query from installer
3.6	If you cannot manage /usr and /var .. (e.g. on the provider)
3.7	The Location Where The Fml System Configuration File Is Saved.
3.8	call makefml via CGI

4	Overview on how to treat fml 

5	Creating A New Mailing List
5.1	Creating A New Mailing List
5.2	Remove a Mailing List
5.3	Digest Delivery
5.4	fmlserv (Listserv or majordomo like interface for fml)

6	To Add And Delete A User In The Mailing List
6.1	Attention When To Add And Delete A User
6.2	To Add A New User To The ML
6.3	To Remove The User From The ML

7	To change the configuration of a mailing list
7.1	TOP MENU
7.2	Manual/Automatic Registration and Access Control Policy
7.3	The type of Automatic Registration
7.4	Address for ML commands
7.5	Remote Administration
7.6	Header Configurations
7.7	Other Optional Settings (e.g. MIME, Automatic Html Generation)
7.8	Security

8	How to add a user by remote administration
8.1	To add the user who can manage the ML server in remote. 
8.2	To remove the user who can manage the ML server in remote. 
8.3	To set or change the password of the remote-maintenance user 

9	Configuration File
9.1	On cf and config.ph
9.2	the format of cf and config.ph
9.3	makefml config-template
9.4	Edit Template Files

10	How to test and debug

Appendix A	Typical Error Cases

Appendix B	Attention to the command address

Appendix C	ML via pop3

Appendix D	Header information to notify information

Appendix E	Moderators

Appendix F	Upgrade (from before fml 2.1)

Appendix G	Security Consideration
Appendix G.1	FML Advisories
------------------------------------------------------------


1	Quick Overview

    % ftp ftp://ftp.fml.org/pub/fml/current/
    Connected to ftp.iij.ad.jp.
    220 ftp.iij.ad.jp FTP server ready.
    ftp> get fml-3.0B-current-20000227.tar.gz
    50% |*************************                         | 818 KB 00:40 ETA
    226 Transfer complete.
    1656664 bytes received in 01:20 (20.02 KB/s)
    221 Goodbye.
    %
    
    % gunzip fml-3.0B-current-20000227.tar.gz
    % tar xf fml-3.0B-current-20000227.tar
    
    % cd fml-3.0B-current-20000227
    
    % env RECOMMEND=yes perl makefml install
    
    % /usr/local/fml/makefml newml elena

2	What is ML?

Fml, a ML server (manager) is a filtering process. It does not need to
handle delivery process. MTA receives mail, kicks off fml and
injects the mail to fml. fml checks, adjusts the mail header and body,
and distribute the ML article to ML members by passing it to MTA for
delivery.

[Figure]

<a host>                                      <ML Server Host>
mail from a member
   |
   V                    kick off fml
 MTA (e.g. sendmail)   ------------------>     
                                            fml <ML server (ML driver)>
 MTA (e.g. sendmail)   <-----------------      
 (distribution)
   | | | 
   V V V   
 members of the Mailing List 

Described above, the mailing list and delivery process works.
A mailing list driver can accept commands, too. 

Only when mail comes in, fml is kicked off. That is event driven.
The traffic is intermittent. If you are concerned with the traffic
burst, you can receive a digest e.g. once per three hours.

You should use operating system function to run digest delivery
program periodically. On UNIX, you may be able to use cron (cron(8)).
Fml assumes you can use cron of your OS. If not, you can use an
emulator bin/cron.pl in fml-source (see => 5.3).

3	Installation

	% su
	# groupadd fml
	# useradd -g fml fml

	# mkdir /usr/local/fml /var/spool/ml
	# chown fml /usr/local/fml /var/spool/ml
	# chgrp fml /usr/local/fml /var/spool/ml

3.1	Introduction

In general you should not run mailing lists as a privileged user.
Please run mailing lists as a non-privileged user.
The best way is to set up a non-privileged user (e.g. fml) for the
mailing lists. So you always use the account to configure fml.

A policy may be acceptable that fml installation by root, but usual
uses can handle fml.  Hence usual users cannot touch the executable
and libraries but can run "makefml fml" and others. It depends on your
operation policy.

3.2	What is your OS?

makefml tries to detect your OS and adjusts fml to fit it. If makefml
cannot detect your operating system, please use -O option to enforce
the os type. For example

	% makefml -O i386-unknown-OSTYPE install

Some OS's provides a memo on installation. Please check your OS.
e.g.	Debian Linux	/usr/doc/fml/

When you encounter some warning or error on SYSV (e.g. NEC EWS4800),
it may be effective to enforce

	% makefml -O unknown-unknown-sysv install

3.3	A few checks before installation

In default fml sets up only ML owner can read and write ML's HOME
directory and article spool and so on. How many accounts is used to
maintain mailing lists? Only you can run mailing lists? or a group of
people run mailing lists on this machine	? The files and directories
permissions fml should set up depend on the policy.

fml asks you on it in the first stage of installation.

   Personal Use or ML-Admin-Group-Shared or fmlserv you use? 
   Personal, Group, Fmlserv (personal/group/fmlserv) [personal] 

personal	only you use the fml system. In this case you 
		use your account or "fml" account only for ML maintenance.
		Only you can read and write the whole system.

group		Prepare a group. Members in a group can create a ML.
		but "fmlserv" is NOT USED.
		/var/spool/ml is group writable but the other permission
		is the same as in "personal" case.

fmlserv		Similar to "group" but they use fmlserv also.
		A lot of files are group writable since fmlserv should
		handle them. Only ML owner of a ML can change the ML's
		configuration file.

The write permission of the fml system changes in each type. 

If only you create and maintain mailing lists on a machine, please
select "personal". When plural people create and maintain plural
mailing lists, more loose permission is needed. Ideally speaking you
should prepare ML account e.g. "fml".

1. If only you runs mailing lists, please jump to the next section
(select "personal"). If you use "fmlserv" under "fml" account, please
select "personal".

2. There exist several mailing lists, but only you can do "newml" and
edit files directly.  In this case please select "personal", too.

3. When several people can set up and run several mailing lists, that
is the owners of mailing lists are plural, you can select "group". In
this case please create the maintainer group (e.g. fml) in /etc/group
(4.4BSD),

Attention! The current MTA does not accept group writable permission.
If you use "group" or "fmlserv" type, you may need MTA configuration
change. For example, see 

For example, see "O DontBlameSendmail=GroupWritableIncludeFileSafe" option.
	http://www.sendmail.org/tips/DontBlameSendmail.html

3.4	Installing by makefml

Unpack fml-something(usually revision).tar.gz, you can find
fml-x.y-something directory. Change to the directory, you find a set
of the fml system. In this directory, please run

	perl makefml install

to install the fml to your system.

	env MKDOC=no perl makefml install

    Note 1: To replace perl path with some special path
    (e.g. /usr/local/bin/perl5), run
    
       % env _PATH_PERL=/usr/local/bin/perl5 perl makefml install
    
    Note 2: fml locks ML's in installing. If you install under unlocking,
    run 
    
    	perl makefml -U install

3.5	query from installer

Here you see the following questions. Please answer them!

   Personal Use or ML-Admin-Group-Shared or fmlserv you use? 
   Personal, Group, Fmlserv (personal/group/fmlserv) [personal ]

   DOMAIN NAME               [fml.org] 
   FQDN                      [beth.fml.org] 
   EXEC FILES DIRECTORY      [/usr/local/fml] 
   TOP LEVEL ML DIRECTORY    [/var/spool/ml] 

   Language (Japanese or English) [Japanese] 

   TimeZone (TZ: e.g. +0900, -0300) [+0900] 

The value in [] is the default.  If you just "ENTER"(Carriage Return),
the value in the [] is used. These questions are as follows:

   Personal Use or ML-Admin-Group-Shared or fmlserv you use? 
   Personal, Group, Fmlserv (personal/group/fmlserv) [personal] 

Please see the previous section!

    Please define the group (in /etc/group) ML Operators use
    Group of Mailing List Operators (fml or GID ([\w\d]+)) [fml] 

	Please input group (e.g. fml) explained above.

   DOMAIN NAME               [fml.org] 

	Domain Name. The part after "@" of the Mailing List Address.
	If you use FQDN as e.g. the mailing list address, please input
	FQDN as "DOMAIN NAME". It is a fake :) but works well.

   FQDN                      [beth.fml.org] 

	Fully Qualified Domain Name of the machine you install in

   EXEC FILES DIRECTORY      [/usr/local/fml] 

	Where you install executable files of the fml system?  
	For example, the locations defined by values above are

		/usr/local/fml/fml.pl  (main executable file)
		/usr/local/fml/doc/    (document directory)

   TOP LEVEL ML DIRECTORY    [/var/spool/ml] 

   ML (ML's) are supposed to be created here. For example, 
	/var/spool/ml/elena	for an "Elena" Mailing List
	/var/spool/ml/mirei	for a  "Mirei" Mailing List
   are the ML's directory for each ML.
   The directory for each mailing list has configuration files and
   the spool of ML articles in each ML.

   LANGUAGE                  [Japanese] 
	When you make a new ml by "makefml newml", this setting
	determines the language of documents for the mailing list.

	By default, If the target machine to install matches "*.jp",
	"Japanese". If not, "English". If you would like to change,
	please select "Japanese" or "English".

   TimeZone (TZ: e.g. +0900, -0300) [+0900] 

	Fml tries to speculate your TIME ZONE but may be incorrect.
	If so, please input your timezone.

3.6	If you cannot manage /usr and /var .. (e.g. on the provider)

For example, 

	when you are not one of superusers but you can manage
	directories under /home on providers or universities.
	You can install fml to directories under your home. You must
	request administrators to edit /etc/aliases.

In this case, you change the input for "makefml" to the following

	/home/fukachan/fml	for the directory of executables
	/home/fukachan/ml	for the hierarchy of ML's

3.7	The Location Where The Fml System Configuration File Is Saved.

    Config Saved in [/usr/local/fml/.fml] 

The configurations you input are saved here.  After this time,
"makefml" uses this configurations to generate each mailing list
configurations (e.g. config.ph, include).

3.8	call makefml via CGI

	http://www.fml.org/fml/INSTALL_CGI/

4	Overview on how to treat fml 

It is better for the ML maintainer to log in the fml running host to
customize ML configurations and change ML member lists on the fml
running host. "makefml" command helps you to do them.

The term "remote administration" implies "to control fml by sending
administrative commands to fml". It is not default. You need to set it
explicitly. => 7.5

The ML maintainer can send the commands to fml if he/she knows the
password. The authentication is based by password or PGP, you can
select. => 8

You can use makefml to set up the fundamental configuration 
=> 7

To regist and remove a member, you can edit member list files directly
or use "makefml" command. => 6

You may not find advanced configurations in "makefml config" menu.  If
so, you should edit cf or config.ph file directly => 9

Please see "help" file for commands usual users who can use.
Please see "help-admin" file for ML maintainers commands.

Search
	http://www.fml.org/fml/search-e.html 

doc/Japanese/
	http://www.fml.org/fml/English/tutorial.html

To find information, 
1.	search keyword or variable name in the doc/op.en
2.	use http://www.fml.org/fml/search-e.html 
Check your system following doc/CHECK_LIST.en.

5	Creating A New Mailing List

By makefml, you can create a new mailing list and control the
fundamental parameters for a ML.

"makefml" command syntax is as follows:
	makefml command [parameters or options]

5.1	Creating A New Mailing List

When you create a new "elena" Mailing List, you do just

	/usr/local/fml/makefml newml elena

You can find the samples for each ML under /var/spool/ml/"listname"/
e.g. the include sample for elena ML is

	/var/spool/ml/elena

You can see a sample to add to /etc/aliases is shown in the last
action of makefml. Please cut and paste them in /etc/aliases and
"newaliases". This sample is in /var/spool/ml/etc/elena/aliases.
If you encounter some errors, see Appendix A

If /var/spool/ml/elena already exists, makefml stops to avoid
overwriting. If you want to force to overwrite elena ML, run 

	/usr/local/fml/makefml -F newml elena

where -F is 'force'.

In default examples are for sendmail. If you use qmail, please see
INSTALL_with_QMAIL and examples generated by "makefml qmail-setup ML".
Fml provides tips for each MTA such as:

    sendmail	INSTALL_with_SENDMAIL (almost dummy :-)
    postfix		INSTALL_with_POSTFIX
    qmail		INSTALL_with_QMAIL
    exim		INSTALL_with_EXIM

Don't forget to permit relay from localhost since fml uses SMTP since
latest MTA rejects mail relay in default.
Please see manuals and faq's of MTA's.

If you create another "mirei" ML, you do the same way again for mirei
in replacing "elena" with "mirei".

Created samples are the following files:

[Files]
	aliases		/etc/aliases samples
	include		include file for post address
	include-ctl	include file for command address
	include-mead	not used in default. This is for mead
			which analyzes error mails to remove obsolete address

	config.ph	the FML configuration file for each ML

	guide		guide
	help		help for ML and user commands
	help-admin	command index for remote administration
	objective	objective of ML
	welcome		when automatic subscription, we send back this file
	confirm		send back this explanation when confirmation mode
	crontab		vixie cron 's sample
	deny		deny post from not member

	fmlwrapper.c	C Wrapper
	fmlwrapper.h	fmlwrapper.c header file

5.2	Remove a Mailing List

	rm -fr /var/spool/ml/listname

and delete the entries in /etc/aliases.

5.3	Digest Delivery

Digest delivery is to send articles in one mail periodically not real
time delivery of mail when the server receives mail.

	% crontab /var/spool/ml/elena/crontab 

For each user who used "makefml newml listname", the user can find

	/var/spool/ml/etc/crontab/user-name

which entries are automatically added when you create a new ml. 
This file has all crontab entries the user administrates. 

	/var/spool/ml/etc/crontab/USERNAME

Please use crontab(1) in the following way:

	% crontab /var/spool/ml/etc/crontab/USERNAME
	   or
	% crontab /var/spool/ml/etc/crontab/USERNAME.master (see below)

cron wakes up periodically, checks articles in the mailing list spool
and deliver articles in one mail.

If your OS has not Vixie cron, please see the manual of "crontab" or
the chapter on "cron" of doc/op.en in the fml source.

=
***** When a lot of ML run in ONE MACHINE? (must be always yes on ISP
***** accounts)?

When in operational point of view, as usual to say, a lot of people
should avoid to run programs simultaneously on one machine. Plural
people run msend programs for plural ML's, each msend should run in
shifted phase, 10:00 min for A ML, 10:03 min for B ML, 10:06 for C
ML... Cron does its work as defined but not tunes itself up. System
administrator should check its system tuning.

/var/spool/ml/etc/crontab/USERNAME.master helps you to avoid
concurrent plural msend running. This crontab example follows:

   0 * * * * /usr/local/fml/bin/msend_master.sh -E /usr/local/fml -M /var/spool/ml

You should run msend in order, now elena, next mirei, ...
msend_master.sh kicks off msend.pl in order for each ML's in
/var/spool/ml (-M option).

Crontab Example to avoid concurrent msend running:

   0 * * * * /usr/local/fml/msend.pl /var/spool/ml/elena -q
   2 * * * * /usr/local/fml/msend.pl /var/spool/ml/mirei -q
   4 * * * * /usr/local/fml/msend.pl /var/spool/ml/anna  -q

5.4	fmlserv (Listserv or majordomo like interface for fml)

"fmlserv" is listserv/majordomo style emulator. If you would like to
set up it, run

	/usr/local/fml/makefml fmlserv

You can see the example setting in 

	/var/spool/ml/fmlserv

Please cut and paste the example of "aliases" which is seen in the
last of "makefml" for /etc/aliases and do "newaliases".
To check the action of "fmlserv", please send "help" to the
fmlserv@your-domain.

The command syntax of "fmlserv" is 

	command	   listname   [arguments or options]

Precisely speaking, "fmlserv" recognizes a command for each mailing
list as the syntax above. The part of "listname" is added to the
default fml command syntax. 

In fml, "config.ph" for each ML defines each command set for each ML.
fmlserv can understand each proper commands defined for each mailing
list since fmlserv can emulate each mailing list in the action.
fmlserv just offers in another "fmlserv" (listserv) syntax.

6	To Add And Delete A User In The Mailing List

6.1	Attention When To Add And Delete A User

When you send e-mail to a mailing list server on the same machine as
one running mailing list servers, your mail header may have NOT

	From: username@domain 

BUT

	From: username 

In this case the server recognizes YOU ARE NOT A MEMBER!. To avoid
this error, you can register both addresses "username" and
"username@domain" by "makefml add listname address"

6.2	To Add A New User To The ML

Add a new user "fukachan@baycity.asia" in "Elena" ML.

   /usr/local/fml/makefml adduser elena fukachan@baycity.asia
   /usr/local/fml/makefml add elena fukachan@baycity.asia

6.3	To Remove The User From The ML

Remove "fukachan@baycity.asia" in "Elena" ML.

   /usr/local/fml/makefml byeuser elena fukachan@baycity.asia
   /usr/local/fml/makefml bye elena fukachan@baycity.asia

7	To change the configuration of a mailing list

   /usr/local/fml/makefml config listname

e.g.   /usr/local/fml/makefml config elena

You can configure the "elena" mailing list interactively. You see the
following recursive menu, so please select one and answer it.
See 9 for more "config.ph".

~/.profile ~/.bash_profile (?)

  MAKEFML_LANG=euc; export MAKEFML_LANG

~/.cshrc ~/.tcshrc
  setenv MAKEFML_LANG euc

7.1	TOP MENU

   === TOP MENU ===

   Mailing List Addresses
        FOR POST          elena@baycity.asia
        FOR COMMAND       elena-ctl@baycity.asia
   _______________________

   0    END		
   1    POLICY OF ACCESS (WHO CAN POST AND USE COMMANDS)

        [POST]
          PERMIT_POST_FROM                 moderator
          WHEN POST FROM NOT MEMBER        reject

        [COMMAND]                          
          PERMIT_COMMAND_FROM              members_only
          WHEN COMMAND FROM NOT MEMBER     reject

   2    REGISTRATION METHOD TYPE

        AUTO_REGISTRATION_TYPE             confirmation
        UNSUBSCRIBE_AUTH_TYPE              address

   3    SETTINGS AROUND COMMANDS
              address for command          elena-ctl@baycity.asia

   4    ML REMOTE ADMINISTRATION              
                     PERMIT ?              NO
                     AUTH_TYPE             crypt

   5    HEADER_CONFIG
        SUBJECT_TAG_TYPE                   
        REWRITE_TO                         To: is original (pass through)

   6    OPTION                             

   7    SECURITY & FILTERING                
   ************************************************************

   Which section? (0-7) [0] 

Please input the number you choose, you see the similar menu in the
next hierarchy.  When you see "[y/n]", please input y(yes) or n(no).

   Mailing List Addresses 

   1    POLICY OF ACCESS (WHO CAN POST AND USE COMMANDS)

The list of choice is 

	post from anyone			anyone
	post from only a member			members_only
	post form only a moderator		moderator

If mail comes from not a ML member, what action should be done?
(=> Section 7.2)

	send back "deny" file to notify "reject"	reject
	automatic registration/subscription		auto_subscribe
	ignore the mail					ignore

In default, the mode of FML is 
	post from only a member			members_only
and
	send back "deny" file to notify "reject"	reject.

Automatic registration is done when mail comes to an address form not
member and the mode for the address is "auto_subscribe".

* MANUAL REGISTRATION

It is default. If fml receives subscribe request, fml sends back a
confirmation to the user. If the user replies it and fml confirms it,
fml sends "someone wants to join our ML" to ML maintainers. After
this, ML maintainers adds the user. 

How to add depends on the configuration. In default fml expects a
maintainer edit member lists by hand. If you use remote administration
commands, please enable it explicitly. 

   [COMMAND]

   3    PERMIT_COMMAND_FROM                members_only
   4    WHEN_COMMAND_FROM_NOT_MEMBER       auto_subscribe

   2    REGISTRATION METHOD TYPE

        AUTO_REGISTRATION_TYPE             confirmation
        UNSUBSCRIBE_AUTH_TYPE              address

The automatic registration type. The default is "confirm" which
requires the confirmation of subscription will.
 (=> Section 7.3)

   3    SETTINGS AROUND COMMANDS
              address for command          elena-ctl@baycity.asia

The address for command (=> Section 7.4).
You can select e.g.
	listname-ctl
	listname
	fmlserv (listserv style interface)

   4    ML REMOTE ADMINISTRATION              
                     PERMIT ?              NO
                     AUTH_TYPE             crypt

You maintain the ML in remote? or not. And the default type is
"crypt". This is "password authentication" and the password is saved
as a crypted. (=> Section 7.5)

                    AUTH_TYPE              crypt

Header configuration, e.g. Subject Tag Type (=> Section 7.6).

   5    HEADER_CONFIG
        SUBJECT_TAG_TYPE                   
        REWRITE_TO                         To: is original (pass through)

Other options (=> Section 7.7).

   6    OPTION                             

Special functions for security (=> Section 7.8 Appendix G).

   7    SECURITY & FILTERING                

7.2	Manual/Automatic Registration and Access Control Policy

  MENU => POLICY OF ACCESS (WHO CAN POST AND USE COMMANDS)

   WHO CAN POST AND COMMAND

   0    END             

   [POST]

   1    PERMIT_POST_FROM                   members_only
   2    WHEN_POST_FROM_NOT_MEMBER          reject

   [COMMAND]

   3    PERMIT_COMMAND_FROM                members_only
   4    WHEN_COMMAND_FROM_NOT_MEMBER       reject
   ************************************************************

      policy (0-4) [0] 

The permission for post address has the following choice:
	post from anyone			anyone
	post from only a member			members_only
	post form only a moderator		moderator

If mail comes from not a ML member, what action should be done?

	send back "deny" file to notify "reject"	reject
	automatic registration/subscription		auto_subscribe
	ignore the mail					ignore

Caution: you can use "auto_regist" but it is obsolete in fml 3.0.
         It works even in fml 3.0 for compatibility.
	http://www.fml.org/fml/UPGRADE-3.0-e/index.html

The example of an automatic registration setting.

   3    PERMIT_COMMAND_FROM                members_only
   4    WHEN_COMMAND_FROM_NOT_MEMBER       auto_subscribe

If you select 1, 

   ************************************************************
   ADDRESSES FOR POST                  elena@baycity.asia
   PERMIT_POST_FROM                   members_only

   0    END
   1    members_only
   2    anyone
   3    moderator
   ************************************************************

         Permit post from  (0-3) [0] 

Please select one of them. 

* Restrict persons who can post to ML, but distribution list is
automatic registered.

    $REJECT_COMMAND_HANDLER can have a value 'auto_asymmetric_regist'. If
    defined, FML uses delivery list controlled by automatic registration
    and authentication list edited by hand (or makefml).
    This configuration may be useful to make one way information delivery.
    But fml checks a poster by From:, so you may have to consider
    moderator or PGP authentication.

	elena/actives	delivery list (automatic registration)
	elena/members	authentication list (edit by hand)

    In all cases, even if "anyone" is selected, FML denies From: addresses
    which matches $REJECT_ADDR. $REJECT_ADDR is for example, "root",
    "MAILER-DAEMON". We reject these addresses since these are public and
    not personal since such an address may be a fake. If you permit anyone
    in fact, not define $REJECT_ADDR in config.ph.
    
7.3	The type of Automatic Registration

MENU => REGISTRATION METHOD TYPE => AUTO_REGISTRATION_TYPE

If you select "auto_subscribe" in either REJECT_POST_HANDLER or
REJECT_COMMAND_HANDLER, you can see the following menu

   ************************************************************
   AUTO_REGISTRATION_TYPE       confirm

   0    END
   1    confirmation
   2    body
   3    subject
   4    no-keyword
   ************************************************************

[description]
	confirmation
			RECOMMENDED AGAINST SUBSCRIBE ATTACK!
			the server asks the user (From:) the confirmation
			of subscription will.
        body
			A keyword "subscribe" in the body is required 
			to add him.
			If the keyword not exists or is not matched, 
			not added.
        subject	
			A keyword "subscribe" in the subject is required 
			to add him.
			e.g. Subject: subscribe 
			If the keyword not exists or is not matched, 
			not added.
        no-keyword	added if the mail comes from a not member.

MENU => REGISTRATION METHOD TYPE => UNSUBSCRIBE_AUTH_TYPE

enable confirmation in "unsubscribe" command?(default "NO")

MENU => REGISTRATION METHOD TYPE => CHADDR_AUTH_TYPE	        

enable confirmation in "chaddr" command?(default "NO")

7.4	Address for ML commands

   3    COMMAND ADDRESS 
              address for command          elena-ctl@baycity.asia

In default, fml sets up these addresses for elena ML

	elena		for post
	elena-ctl	for command	
	elena-admin	for maintainer. Human reads mails for this address.

We suppose several environments,
	* You can not control /etc/aliases freely.
	  You have a few limited address.

	* You DO NOT USE well-known addresses such as "listserv".
	  You set up "elena" for post, "elena-ctl" for "elena" ML's command.
	  For security and the concept "ML is a personal communication", 
	  I recommends this style

	* You use listserv-style. Your choice is "fmlserv" listserv emulation.

   ************************************************************
   0    END
   1    CONTROL_ADDRESS                 elena-ctl@baycity.asia
   2    MAIL_LIST_ACCEPT_COMMAND        NOT USE
   ************************************************************

* CONTROL_ADDRESS (gives the following menu)

   ************************************************************
   COMMAND ADDRESS                      elena-ctl@baycity.asia

   For command, which address you use?
   (here DOMAINNAME = baycity.asia);

   0    END
   1    elena-ctl@$DOMAINNAME
   2    elena@$DOMAINNAME
   3    fmlserv@$DOMAINNAME
   4    NOT USE

   In default, we use "listname-ctl" format address for command only.
   If you choice "listname" for commands, 
   your mailing list address receive both posting and commands.
   "fmlserv" is the listserv/majordomo style interface of fml.
   ************************************************************

      which type (0-4) [0] 

   COMMAND ADDRESS                      *** Command Unavailable ***

*  MAIL_LIST_ACCEPT_COMMAND (default: NO)

    This menu enables both elena and elena-ctl accepts "# command" trap
    for backward compatibility.

7.5	Remote Administration

In default we do not permit remote administration for security.  You
need to enable this function by yourself.  Please see file
"help-admin" for remote administration commands.

   ************************************************************
   REMOTE ADMINISTRATION
   Do you maintain the ML in remote?        no

   0   END
   1   REMOTE ADMINISTRATION              NO
   2   REMOTE_ADMINISTRATION_AUTH_TYPE    crypt
   3   ADMIN_ADD_SEND_WELCOME_FILE        NO
   ************************************************************

      which (0-3) [0] 

*  REMOTE_ADMINISTRATION (default: NO)

If you maintain the ML in remote, please select "yes". You can control
ML to send "# admin command" or "# approve PASSWORD command" format
commands.

*  REMOTE_ADMINISTRATION_AUTH_TYPE (default: crypt)

set up the authentication type in remote administration.

   ************************************************************
   REMOTE_ADMINISTRATION_AUTH_TYPE          crypt

   0    END
   1    pgp
   2    crypt
   3    md5
   4    address
   ************************************************************

	pgp		PGP based authentication

	crypt		password authentication 
			the password is saved in ML/etc/passwd in crypted form

	md5		password authentication 
			the password is saved in ML/etc/passed in md5 form

	address		From: field's address exists in members-admin
			* members-admin is the default of $ADMIN_MEMBER_LIST

*  ADMIN_ADD_SEND_WELCOME_FILE (default: no)

    When you do 'admin add' to add a user to your ML, do you want to send
    WELCOME_FILE to the user? In default, fml does nothing. It is your job
    to notify the registration.

7.6	Header Configurations

   ************************************************************
   0  	END

   * Subject: TAG
   1  	SUBJECT_TAG_TYPE                   
   2  	SUBJECT_TAG_FIGURE                 6

   * To:
   3  	REWRITE_TO                         To: is original (pass through)

   * Date:
   4  	DATE_TYPE                          original-date

   5  	PASS_ALL_FIELDS                    YES
   6  	PASS_RECEIVED_THROUGH              YES

   ************************************************************

*  SUBJECT TAG TYPE (default: nothing)

    You can configure the listname and the sequence number of the article
    in the subject.  e.g. You like Subject: [Elena:00010] ? (though I like
    such a syntax does not exists (I recommended)). You can select one of
    the following types.
    
          Subject: (Elena:00100)
          Subject: [Elena:00100]    (hml 1.6 compat)
          Subject: (Elena 00100)
          Subject: [Elena 00100]
          Subject: (Elena,00100)
          Subject: [Elena,00100]
          Subject: (Elena)
          Subject: [Elena]
          Subject: (00100)
          Subject: [00100]

*  SUBJECT_TAG_FIGURE (default: nothing, which implies 5)

   0 padding figures in the Subject TAG.

*  REWRITE_TO (default: 0, not rewrite and pass the original To:)

   *  To: elena@baycity.asia, NON-MAIL-LIST-ADDRESS

	We always overwrite To: to To: $MAIL_LIST but not ignore original To:.
	We rewrite To: to 

   * To: elena@baycity.asia

	always overwrite To: to To: $MAIL_LIST 

   * pass through the original To: 

	original To: (fml 2.2 default)

*  DATE_TYPE (default: original-date)

	Date: is original? Date: is the time when fml is kicked off and
	the original is in X-Posted: or X-Original-Date: ? and so on...

*  PASS_ALL_FIELDS (default: yes)

    Do you pass all fields in the header or not? If you ignore superfluous
    X-* fields, please set this. The format of the header used by FML
    default is defined as @HdrFieldsOrder. Even in "yes", fml ignores
    $SKIP_FIELDS (Received: and Return-Receipt-To) fields to avoid loops
    and hop count expiration errors. see the next menu.

*  PASS_RECEIVED_THROUGH (default: no)

FYI: The following functions are prepared to customize the mail header
more precisely.

	&ADD_FIELD
	&DELETE_FIELD 
	&COPY_FIELD 
	&MOVE_FIELD 
	&DEFINE_FIELD_FORCED 
	&DEFINE_FIELD_ORIGINAL
	&DEFINE_FIELD_OF_REPORT_MAIL 
	&DEFINE_FIELD_PAT_TO_REJECT

7.7	Other Optional Settings (e.g. MIME, Automatic Html Generation)


   ************************************************************
   0    END		
   1    HTML_GENERATION               NO
   2    SPOOLING                      YES
   3    FLOCK                         YES
   4    SMTP
   5    USE_MEMBER_NAME               NO
   6    LANGUAGE
   7    VARIABLE_OFF_ON               off/on toggle variables
   ************************************************************

*  HTML_GENERATION

   ************************************************************
   0    END		
   1    AUTO_HTML_GEN		
   2    HTML_THREAD_REF_TYPE   	prefer-in-reply-to
   3    HTML_STYLESHEET_BASENAME	
   4    HTML_INDEX_UNIT		
   5    HTML_INDENT_STYLE		
   ************************************************************

    If you set AUTO_HTML_GEN to "yes", you will have the directory for
    elena ML /var/spool/ml/elena/htdocs/ which contains the html'ed
    articles here. In default articles are collected in each day directory
    below here.  Each directory has index.html and thread.html. index.html
    is the menu for the ML sequence order, thread.html is threaded menu
    for articles.

*  SPOOLING (default: yes)

   articles is spooled in $DIR/spool or not?

*  FLOCk (default: yes)

   flock or not for lock algorithm. If no, rename() based lock is done.

*  SMTP

   USE_OUTGOING_ADDRESS (default: NO)
	fml.pl => list-outgoing => expand

   USE_VERP (default: NO)
	Variable Envelope Return-Paths

*  USE_MEMBER_NAME
   relate "address" with "real name"

*  LANGUAGE

   MESSAGE_LANGUAGE (default: Japanese or English determined in installation)
	Message Language Extension

Which language you use in error reply? Default language is the same as
$LANGUAGE asked and determined in installation.

      7    VARIABLE_OFF_ON               off/on toggle variables

7.8	Security

*  set up several parameters related with security.
   If you run "make secure", you can get the same effect.
   See Appendix G for "more secure".

   MENU => SECURITY => MORE_SECURE => "y"

*  FILTERING FOR MAIL BODY
    
    Reject empty mails or only "unsubscribe" mails.
    If MIME/Multipart mail is input, fml checks only the first block.

*  USE_DISTRIBUTE_FILTER (default: NO)
   Do you use filter? answer "yes" if you use this (recommended).

*  FILTER_ATTRIBUTE

 * FILTER_ATTR_REJECT_COMMAND (default: no)

 * FILTER_ATTR_REJECT_COMMAND (default: no)
   reject "#help" posted to a ML. ("yes" is recommended)

 * FILTER_ATTR_REJECT_2BYTES_COMMAND (default: no)

   Japanese specific

 * FILTER_ATTRIBUTE => FILTER_NOTIFY_REJECTION (default: no)

 * FILTER_ATTRIBUTE => FILTER_NOTIFY_REJECTION (default: no)
   report the rejection to the sender?

 * FILTER_ATTRIBUTE => FILTER_ATTR_REJECT_MS_GUID (default: no)

   reject files with M$ GUID, which may be a file with macro definition,
   e.g. Melissa virus.    

*  USE_MTI (Traffic Monitor; default NO)

    Inspect the ML traffic. If the traffic is over some threshold, fml
    regard it as mail bomb and rejects mails from the sender.

*  MAX_MAIL_SIZE (default: nothing, == infinite)

    The maximum size of mail (for both article and command mail). This
    size must depend on the policy that your ML accepts mail with
    appended files.

    notify the rejection that your mail size is too big to the sender.  If
    not, the sender retries to send big mails. If the mail format is
    message/partial, fml guesses the total mail size and compare it with
    $MAX_MAIL_SIZE.

send "it is rejected" to ML as a distribution.

*  ADDR_CHECK_MAX (default: 3)

    How severe fml checks the address? If 3, fml identifies addresses in 3
    level domains. beth.fml.org and jo.fml.org differs but beth.lw.fml.org
    and jo.lw.fml.org is same in 3 level comparison.

*  MAXNUM_COMMAND_INPUT (default: infinite)

   The max number of commands in on mail.

*  REJECT_ADDR (the account name list to ignore against mail loop)
   see => 7.2

*  USE_LOG_MAIL (default: NO)

    For debug (and against tricks), it may be useful to save the latest
    $USE_LOG_MAIL mails (2K bytes). The cache is stored in $DIR/var/Mail/

*  USE_ENCRYPTED_DISTRIBUTION (default: no)

PGP encrypted ML. Need pgp configuration. 

8	How to add a user by remote administration

8.1	To add the user who can manage the ML server in remote. 

   /usr/local/fml/makefml addadmin elena fukachan@baycity.asia

Add "fukachan@baycity.asia" in "Elena" mailing list. He can
manage the mailing list server in remote.

8.2	To remove the user who can manage the ML server in remote. 

   /usr/local/fml/makefml byeadmin elena fukachan@baycity.asia

Remove the user "fukachan@baycity.asia" who can manage the
"Elena" ML in remote.

8.3	To set or change the password of the remote-maintenance user 

   /usr/local/fml/makefml passwd elena 

	---Changing Passwd of Admin  in elena mailing list
	Who: 
	Password: 

Please input the "password" of "who" (Email address). 

9	Configuration File

9.1	On cf and config.ph

fml.pl is the main execution file. The configuration file "config.ph"
controls this action.

"makefml" (makefml config => Chapter 7) is the
interface to edit "cf" file.  makefml converts cf to
config.ph. makefml always re-generates config.ph from cf.

	/var/spool/ml/elena/cf -> /var/spool/ml/elena/config.ph

To configure advanced settings, 

	1. edit cf and create config.ph from cf.
	   you can re-generate config.ph by 
		(prompt)% make config.ph

	  % makefml update-config.ph ML

	2. edit config.ph by hand ALWAYS.

Pay attention! cf is the master file of config.ph. It is better to
edit config.ph by hand. makefml is easy interface for
config.ph. It always overwrites config.ph.

9.2	the format of cf and config.ph

-- config.ph
config.ph is perl statements.

-- cf file
The format of cf is "variable the value of it", UNIX traditional
style. The rest of a line after # is a comment. We use the default
value defined in cf/MANIFEST for an entry not defined in cf. The list
of user defined variables exists in
fml-installed-directory/cf/MANIFEST (e.g. /usr/local/fml/cf/MANIFEST).

Each entry in config.ph converted from cf is the following:
	$variable = "the value of it";

For Example, in cf

	MAIL_LIST                	elena@$DOMAINNAME
	PERMIT_POST_FROM         	members_only
	REJECT_POST_HANDLER      	reject

corresponds to this in config.ph.

	$MAIL_LIST                     = "elena\@$DOMAINNAME";
	$PERMIT_POST_FROM              = "members_only";
	$REJECT_POST_HANDLER           = "reject";

You can write raw perl statements after "LOCAL_CONFIG". It is appended
in the config.ph when you re-create "config.ph" from "cf" file. Here
is for localhack.

9.3	makefml config-template

In "makefml newml", makefml creates $DIR/cf from
$EXEC_DIR/etc/makefml/cf file. If you make a lot of ML's and need to
configure them, you want to change the default configuration for
yourself. e.g. the default is "automatic registration". 

	makefml config-template 

provides the "makefml config" like interface to edit the template file
$EXEC_DIR/etc/makefml/cf. Please ignore and do not touch several
keyword e.g. _ML_ used in template file.

9.4	Edit Template Files

When "makefml newml" creates a new mailing list with examples e.g. cf,
help, guide, ..., makefml uses templates. They are in
e.g. /usr/local/fml, where you installed. If you edit template files,
1.	edit them, which are under /usr/local/fml.
2.	edit them under makefml. makefml edit-template command provides
	you can edit cf file under ML's are locked. In addition
	you need not to search the template file location.

	makefml edit-template cf

Also you can edit files e.g. help, guide in the same way.

	makefml edit-template help.jp (Japanese help file template)
	makefml edit-template help.en (English help file template)

10	How to test and debug

1. See system mail log e.g. /var/log/maillog to check your MTA.
   If you find some errors in it, check MTA configurations.
2. see $DIR/log (ML's HOME log file) to check fml.
3. see $DIR/var/log/_smtplog to check SMTP from fml to MTA.
4. "makefml test ML" to test fml itself apart from MTA.

	makefml test ML

to sets in debug mode. Under this environment, makefml emulates a fml
works. When the following prompt appears, select "y" (command test) or
"n" (post test) and go ahead! 

	test of command? (y/n) [n] 

The last of input is just a period "." line.

Example:

	* Enter mailbody, end with "." on a line by itself
	help
	.

Appendix A	Typical Error Cases

Please check items e.g. logfiles referred in CHECK_LIST.en (package),
http://www.fml.org/fml/CHECK_LIST-e/.

http://www.fml.org/fml/op-e/index.html#trouble

	% grep -i unsafe doc/Japanese/*

    %perl makefml install
      Can't locate getopts.pl in @INC at makefml line 104.

The installation of perl fails. Please install perl again!

Please see error mails from your MTA. These are typical errors shown
in error mails returned from MTA's.

	error		origin
	--------------------------------------------------------
	unsafe		permission of files or directories
	loop		/etc/aliases miss-configuration
			did not newaliases
	user unknown	no such user
			/etc/aliases miss-configuration
			did not newaliases
	sh: fml.pl not available
			you use smrsh? properly configured?

*	You fails to use :include: form in /etc/aliases

The following reasons are possible:

	* "include" file exists in an insecure directory.
	  Please check the whole hierarchy permission from / to the "include".
	  check	/usr, /usr/local, /usr/local/fml, ... and chmod 755 them!

	* your mail system do not support include form.
	  You may require C-Wrapper (see below). 

If you fails to use :include: in /etc/aliases, please use the
C-wrapper program which may be required to be root-setuid.
The example of the C-wrapper is 

	/var/spool/ml/listname/fmlwrapper.c 

Please compile and set it properly. I recommend you council the
setting of the C-wrapper with the administrator of the
machine since it requires a lot of attention.

FYI: Some OS's provides a memo on installation. Please check your OS.
e.g.	Debian Linux	/usr/doc/fml/

Appendix B	Attention to the command address

When 

	$COMMAND_ADDRESS = $MAIL_LIST;

elena@baycity.asia accepts the command such as "# help" ("# command" form). 
Both X-ML-Info: and command server replies shows the pointer to
elena@baycity.asia on the use of commands.

If you configure that both elena@baycity.asia and elena-ctl@baycity.asia can
accept commands, you should set

	$MAIL_LIST_ACCEPT_COMMAND = 1;

Appendix C	ML via pop3

If sendmail do not run on your machine, you can set ML via POP3.
Please see doc/op.en for more details. 

FYI. NT Version uses this trick:)

Appendix D	Header information to notify information

Appendix E	Moderators

$PERMIT_POST_FROM              = "moderator";

   [POST]

   1    PERMIT_POST_FROM                   moderators

   [COMMAND]

   3    PERMIT_COMMAND_FROM                moderators

   Moderated $MAIL_LIST (elena@baycity.asia) receives a submit from

      fukachan@baycity.asia.

   Please check it. If you certify the following article, 
   please send to elena-ctl@baycity.asia
   the following line (only this line!)

   moderator certified 199711032027.709982

   ------- Forwarded Message

   ------- End of Forwarded Message

moderator certified 199711032027.709982

Appendix F	Upgrade (from before fml 2.1)

	makefml newml elena

Appendix G	Security Consideration

* run in the installation if you use recommended secure cf template.

   % env RECOMMEND=yes perl makefml install

	% make secure 

run "make secure" in your ML HOME to enable typical secure
options. These are a part of the following ones. Configurations to add
follow:

    $INCOMING_MAIL_SIZE_LIMIT	= 512000;
    $USE_LOG_MAIL			= 1;
    $USE_DISTRIBUTE_FILTER		= 1;
    $FILTER_ATTR_REJECT_COMMAND	= 1;
    $USE_MTI			= 1;
    
    &DENY_PROCEDURE('member');  # _this_line_is_added_by_makefml_
    &DENY_PROCEDURE('active');  # _this_line_is_added_by_makefml_
    &DENY_PROCEDURE('members'); # _this_line_is_added_by_makefml_
    &DENY_PROCEDURE('actives'); # _this_line_is_added_by_makefml_
    &DENY_PROCEDURE('status');  # _this_line_is_added_by_makefml_
    &DENY_PROCEDURE('stat');    # _this_line_is_added_by_makefml_

* Disable members/actives command 

Append in config.ph (before the last "1;")

&DENY_PROCEDURE('member');  # _this_line_is_added_by_makefml_
&DENY_PROCEDURE('active');  # _this_line_is_added_by_makefml_
&DENY_PROCEDURE('members'); # _this_line_is_added_by_makefml_
&DENY_PROCEDURE('actives'); # _this_line_is_added_by_makefml_
&DENY_PROCEDURE('status');  # _this_line_is_added_by_makefml_
&DENY_PROCEDURE('stat');    # _this_line_is_added_by_makefml_

 @DenyProcedure = ('member', 'active', 'members', 'actives', 'status', 'stat');

* enable security related options 

	$INCOMING_MAIL_SIZE_LIMIT The upper limit of mail size
	$USE_DISTRIBUTE_FILTER    Filtering
	$USE_MTI                  Traffic Monitor against e.g. mail bomb
	$UNSUBSCRIBE_AUTH_TYPE    confirmation of un-subscription
	$USE_LOG_MAIL             logging all mails fml received

* PGP Encrypted ML: encrypted article is distributed. 

* Disable attachments

$DISTRIBUTE_FILTER_HOOK = q#
    if ($e{'Body'} =~ /Content-Disposition:\s*attachment/i) {
	return 'THIS ML NOT PERMIT ATTACHMENT';
    }
#;

Appendix G.1	FML Advisories

FML Advisories are a series of documents to advice some kinds of
current topics, for example, happy99, Melissa ...

	http://www.fml.org/fml/advisories/

$Id: INSTALL.wix,v 1.119.2.2 2001/07/01 03:37:32 fukachan Exp $
