
		customize fml commands

------------------------------------------------------------I	overview

1	Overview
1.1	Available command index
1.5	members 

2	Examples
2.1	Send back $DIR/uja for anyone
2.2	Automatic Replay Server
2.3	make a new command what send back a file
2.4	get some files by not "get" commands 
2.5	you gets back article 100 in MIME/multipart format by "get 100" command

3	how fml command works
3.1	Maximum Number Of Commands In On Mail
3.2	Warning for Invalid Commands
3.3	If an empty effective command mail comes in ?
3.4	End of Command Sets Against Signature

II	Internals
4.1	How to Add or Remove Available Commands
4.2	Special keys available in %Procedure
4.3	'# syntax' is required?

III	Several commands

5	library commands
5.1	Library Commands for Special Purposes
5.2	Extension of member list (libmember_name.pl)
5.3	Traffic Command to Examine The ML Traffic
5.4	traffic; how to identify one person who has plural Email addresses

6	whois (local whois-like database)

6	Whois Database
6.1	Introduction
6.2	Whois command
6.3	Whois Variables
6.4	Whois And Japanese Code Translation

7	other topics
7.1	index command
7.2	listname-command (qmail case; a trick) 
------------------------------------------------------------


I	overview
1	Overview

1.1	Available command index

Please see "help" file for standard commands list.
doc/help.jp (Japanese) and doc/help.en (English) are available.

	makefml newml elena 

	@PermitProcedure = ('guide', 'summary');

	@DenyProcedure = ('get', 'send', 'mget', 'msend');

	%LocalProcedure = ('hack', 'myProcHack');

1.5	members 

2	Examples

2.1	Send back $DIR/uja for anyone

1	requests from anyone are O.K.
2	keyword "uja" in the mail body to send back the file "uja".

$START_HOOK = q#
    $UJA_FILE = "$DIR/uja";

    if ($Envelope{'Body'} =~ /^[\n\s]*\#\s*uja/) {
	&SendFile($Envelope{'Addr2Reply:'}, "UJA $ML_FN", $UJA_FILE);
	&Log("UJA");
	$DO_NOTHING = 1;
    }
#;

2.2	Automatic Replay Server

Please set a file to $GUIDE_FILE in config.ph and set up $START_HOOK
in the following hook:

	$START_HOOK = q#
		&SendFile($From_address, "Guide $ML_FN", $GUIDE_FILE);
		&Log("Guide request from $From_address");
		$DO_NOTHING = 1;
	#;

2.3	make a new command what send back a file

E.g. "news" command is to send back $DIR/news file.

In config.ph

%LocalProcedure = (
		    # help for usage of commands
		    'news',	'ProcFileSendBack',
		    '#news',	"$DIR/news",

		);

2.4	get some files by not "get" commands 

get-SOMETHING gets file in SOMETHING directory.

%LocalProcedure = (
		   'get-spool',   'mySendFile',  # $DIR/spool
		   'get-archive', 'mySendFile',  # $DIR/archive
		   'get-etc',     'mySendFile',  # $DIR/etc
		   );

sub mySendFile
{
    local($proc, *Fld, *e, *misc) = @_;

    if ($proc =~ /^get-([a-z]+)$/io) {
	local($dir) = $1;
	if (-f "$dir/$Fld[2]") {
	    &SendFile($to, "Get $dir/$Fld[2] $ML_FN", "$dir/$Fld[2]");
	}
    }
}

2.5	you gets back article 100 in MIME/multipart format by "get 100" command

A: always identify "get" and "mget" commands internally.

append it to config.ph.

   $MGET_MODE_DEFAULT = "mp";
   %LocalProcedure = ('get', 'ProcMgetMakeList');

(fml-support: 06997)

3	how fml command works

3.1	Maximum Number Of Commands In On Mail

If $MAXNUM_COMMAND_INPUT is defined, the maximum number of commands in
on mail is $MAXNUM_COMMAND_INPUT. If not defined, the number is
infinite:). In default INFINITE!

3.2	Warning for Invalid Commands

In default, FML does not warn against invalid commands and ignore
them. If you want to warn it, set

	$USE_INVALID_COMMAND_WARNING = 1; (default 0)

3.3	If an empty effective command mail comes in ?

FML sends back help file.

3.4	End of Command Sets Against Signature

Please use one of them to show the end of commands sequence. 

	exit 
	end
	quit

II	Internals

4.1	How to Add or Remove Available Commands

You can set up what commands you add or remove in config.ph.
FML interprets it as follows:

   1 	If @PermitProcedure is defined, FML disables all commands 
	and permits commands defined in it. 
	If not defined, %Procedure (default) is used which is 
	automatically set in the first phase of FML command routine

   2	%LocalProcedure overwrites %Procedure.

   3 	If @DenyProcedure is defined, remove commands defined in
	@DenyProcedure from %Procedure.

Example:

	permit only "guide" and "summary", but disables other commands.

	@PermitProcedure = ('guide', 'summary');

	add my "hack" command. You need to write subroutine "ProcHack".

	%LocalProcedure = ('hack', 'ProcHack');

	Disable "get" commands but others are available.

	@DenyProcedure = ('get', 'send', 'mget', 'msend');

	Disable commands to retrieve member lists

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

4.2	Special keys available in %Procedure

%Procedure has a special format. Usually the key and value of the hash
is as follows:

	----------------------------------------

	hash key	the corresponding value
	----------------------------------------
	command name	the corresponding Function name (e.g. ProcHoeHoe)

FML defines and uses the following special syntaxes.

	----------------------------------------

	hash key	the corresponding value
	----------------------------------------

	key		Function Name (e.g. ProcHoeHoe)
	#key		file name
	r#key		1 or 0
	r2a#key		1 or 0
	l#key		the maximum request for key in one mail

'#key' is a file name to send back since the function to send back a
file is common and the file to send differs. You can use this to
define a new command to a special file.

Example: "help" command definition. 

		    # help for usage of commands
		    'help',	'ProcFileSendBack',
		    '#help',	$HELP_FILE,

Example: add your new command "news" to send back "$DIR/news" file.

%LocalProcedure = ('news',	'ProcFileSendBack',
		   '#news',	"$DIR/news");

* If "r#key" is defined, FML sends the trace log of the command to the
user who submits the command mail.

Example: "off" command definition

		    'off',    'ProcSetDeliveryMode',
		    'r#off', 1,

* If "r2a#key" is defined, FML sends the trace log of the command to
$MAINTAINER. 

Example: "bye" and "unsubscribe" to notify the log to maintainers.

		    'bye',             'ProcSetMemberList',
		    'r#bye',           1,
		    'r2a#bye',         1,
		    'unsubscribe',     'ProcSetMemberList',
		    'r#unsubscribe',   1,
		    'r2a#unsubscribe', 1,

Ex 2: "chaddr" case.
		    'chaddr',         'ProcSetMemberList',
		    'r#chaddr', 1,

Restrict 'command' requests in one mail up to $Procedure{"l#command"}
$MAXNUM_COMMAND_INPUT is another issue which restrict the
total number of commands in on email.

Example: "get" command requets is up to 10 in one mail.

	             'l#get',      10,

4.3	'# syntax' is required?

Usually, '# ' part is NOT needed. In default FML sets up
"listname@FQDN" for post and "listname-ctl@FQDN" for command.

If both posting and command addresses are the same, a keyword for the
switching between post function and command function is required. '#
syntax' is the key of switching.

To configure that "# command" is the same as "#command", set 

	$COMMAND_SYNTAX_EXTENSION = 1; (default 1)

III	Several commands
5	library commands

5.1	Library Commands for Special Purposes

FML does not accept "put" style commands in default for security.
So "library" commands are defined in @DenyProcedure (see config.ph).
If you use "put" style commands, you can use "library" commands series.
"library" commands are a sub-mailing list. This command has its own
summary file and archive directories. "put" file is stored in
$LIBRARY_ARCHIVE_DIR ($SPOOL_DIR for ML) and summary file is
$LIBRARY_DIR/summary. The system is closed under $LIBRARY_DIR.
This system uses the same routines as the usual ML. Hence the file
name is number. Also FML does not permit the freedom of file names to
put for security.

Removing needs the authentication that From: address is the same
person which submitted the file in the past.

Please rename a number file name to arbitrary file name by hand if you
like it.

	$LIBRARY_DIR		library HOME  (<=> $DIR)
	$LIBRARY_ARCHIVE_DIR	library SPOOL (<=> $SPOOL_DIR)

To disable one of library commands, set @DenyLibraryProcedure.
How to use this array is the same as @DenyProcedure. 

e.g. disable 'library put' command.

	@DenyLibraryProcedure = ('put');

5.2	Extension of member list (libmember_name.pl)

1998/01/09 AUTHOR: <fukui@sonic.nm.fujitsu.co.jp>

libmember_name.pl provides a member list with member names.

Enable this function, please write 

      $USE_MEMBER_NAME = 1;

in config.ph. You can use the menu style by "makefml config" to set
this.

DESCRIPTION:

Fml command "members" sends a list back but the list contains only
E-mail addresses. So you cannot identify who is an address? 
libmember_name.pl module provides a function that "members" command
sends back a list with full names where the name is extracted from
"From:" field e.g. in automatic registration.

When you enable this function, fml changes like this.

* When automatic registration works

When fml registered a user in automatic registration mode, fml
extracts GECOS field in From: and caches it to a file
$MEMBER_NAME_FILE.

members / member command

members / member command sends back a list with full names.

	sakura@card.captor (Sakura Kinomoto)
	kerochan@fml.org   (Kerberos)
	tomoyo@fml.org     (Tomoyo Daidouji)

"name" command

SYNOPSIS: name new-name

Replace the full name in the cache file for "From:" address with
"new-name". If no argument is given, fml removes the full name entry
in the cache file.

"admin name" command

SYNOPSIS: admin name address new-name

In administration mode, overwrite the name for the address. The usage
is the same way as "name" command. Administrators can use this
command. This function is useful to overwrite the name cache file not
only in automatic registration but also in manual registration. Also
this command overwrite the name to arbitrary ones e.g. nick names,
handles ...

5.3	Traffic Command to Examine The ML Traffic

AUTHOR: yuao@infonia.or.jp (Yuao Tanigawa)

    The usage of libtraffic.pl is 
    
    % libtraffic.pl [-n <best?>] [-m <mails>] [-d] [where is summary?]
    
    % libtraffic.pl
    
    1. article traffic per a month
    2. days 
    3. articles per an hour zone
    4. days over  a traffic limit (25 mails)
    5. best 10 of heavy posters
    6. average and maximum traffic
    
5.4	traffic; how to identify one person who has plural Email addresses

	Author: Yuao Tanigawa <yuao@infonia.or.jp>
	fml-support: 00736
	fml-support: 02578
    > $TRF_NAME_HOOK = q#
    >     $name =~ s/umura@solan\.chu/umura@nn.solan./oi;
    > #;
    > 
    > 
    >    umura@solan.chu -> umura@nn.solan.
    > 
    
    You can customize $TRF_NAME_HOOK to set aliases e.g.
    
    if ( $name eq 'yuao@drei.mech.' || $name eq 'XN9Y-TNGW@j.asa' ) {
    	$name = 'tanigawa@tribo.';
    }
    
6	whois (local whois-like database)
6	Whois Database

"whois" is FMl local database access method. It is a series of
commands e.g. "whois", "iam", "who". Please see help file for the
usage.

6.1	Introduction

"whois" command of FML provides both local data access
(var/db/whoisdb) and tcp/ip based relay to whois servers at other
hosts. The data format of local database is plain text not usual DB
such as Berkeley DB. "-h host" option makes FML relay the query to the
host whois. If without -h option, FML uses the local database.

6.2	Whois command

	$USE_WHOIS = 0;	(default 0)

If 0 (default), FML does not use whois database. If you use it, set 1.
This is based on the FML design policy that you can use additional
functions if you explicitly permit it.

Example 1: search the local database for fukachan

   % echo  "whois fukachan" | Mail Elena-ctl@phys.titech.ac.jp

Example 2: query fukachan to whois of the host 

   % echo "whois -h host fukachan" | Mail Elena-ctl@phys.titech.ac.jp

6.3	Whois Variables

	$DEFAULT_WHOIS_SERVER (default "localhost")

This variable is the default whois sever. However without -h option is
local database search, so the default of whois server is of no mean.

	$WHOIS_DB (default "$FP_VARLOG_DIR/whoisdb")

local database file (default $FP_VARLOG_DIR/whoisdb).

6.4	Whois And Japanese Code Translation

	$WHOIS_JCODE_P	(default 0)

using jcode to translate the result to JIS. Default is 0 (do not translate).

7	other topics

7.1	index command

If $INDEX_FILE ($DIR/index) exists, FML sends back it as an index of
archives FML has. If not exists, FML scans $SPOOL_DIR and @ARCHIVE_DIR
not recursively and reports the result.

If $INDEX_SHOW_DIRNAME is set, FML scan	is recursive.

7.2	listname-command (qmail case; a trick) 

makefml craetes a sample .listname-default. If you copy it to
/var/qmail/alias/ and set 

	$USE_DOT_QMAIL_EXT = 1;

in config.ph, you can use listname-command-argument for "command
argument" to listname-ctl. For example, 

	send "get 100 " to elena-ctl@baycity.asia

is the same as

	send "" to elena-get-100@baycity.asia

"-" is not used, so fml recognizes

	elena-mget--1-3-mp@DOMAIN 

as a command

	"mget 1-3 mp" 


		INDEX

$COMMAND_SYNTAX_EXTENSION                  ...   4.3 
$DEFAULT_WHOIS_SERVER                      ...   6.3 
$INDEX_FILE                                ...   7.1 
$INDEX_SHOW_DIRNAME                        ...   7.1 
$LIBRARY_ARCHIVE_DIR                       ...   5.1 
$LIBRARY_DIR                               ...   5.1 
$MAXNUM_COMMAND_INPUT                      ...   3.1 
$MEMBER_NAME_FILE                          ...   5.2 
$USE_INVALID_COMMAND_WARNING               ...   3.2 
$USE_MEMBER_NAME                           ...   5.2 
USE_WARNING                                ...   3.2 
$USE_WHOIS                                 ...   6.2 
whois                                      ...   6 
$WHOIS_DB                                  ...   6.3 
$WHOIS_JCODE_P                             ...   6.4 
