Document: FSC-0057
Version: 003
Date: 07-Dec-92
Conference Managers - Specifications for Requests
December 7, 1992
Fabiano Fabris Joaquim H. Homrighausen
2:285/304.100@fidonet 2:270/17@fidonet
Status of this document:
This FSC suggests a proposed protocol for the FidoNet(r) community, and
requests discussion and suggestions for improvements. Revision 3
presents several additions and enhancements over the previous revision.
Distribution of this document is unlimited.
Fido and FidoNet are registered marks of Tom Jennings and Fido
Software.
1 Purpose
This document will explore the methods implemented by various
conference managers which process requests (in net mail form)
for changes to the conference mail links on the system on which
they are in use.
Until now, it would appear that no real standard exists, so most
software authors have either tried to emulate another program, or
to create a new method of their own, or both.
Here, an attempt will be made to define a standard, one which tries
to maintain compatibility with methods already in use, while also
extending them to provide new functions.
2 Conventions
The names of the commands described in the following paragraphs are
given in upper case, for legibility. However, a conference manager
should be able to interpret them even if they are given in lower
or mixed case.
Similarly, conference names, or tags, are given in upper case, but
the conference manager should be able to handle them even if typed
in lower or mixed case.
Optional information is enclosed with square brackets, while
variable information is enclosed with angle brackets. For example:
+CONF [,R=<n>]
indicates that the section within square brackets is optional, and
if supplied, requires a parameter after the equals sign.
Some conference managers may allow commands to be abbreviated to the
shortest non-ambiguous string. For example, %LIST might be reduced
to %L.
3 Format of the request
A request to a conference manager is generally made in a net mail
message containing specific information in some of the fields. In
particular, the addressee is the name of the conference manager
itself, and the subject of the message is a password assigned by
the sysop of the system running the program.
For example:
From: John Doe, on 2:123/56
To: Program, on 2:234/0
Subject: password
Here the first problem is encountered. Each of the existing programs
recognizes a different addressee. For this reason it is proposed
that all such programs recognize requests made to a single,
"standard" addressee, besides any other they may wish to implement.
The term "ConfMgr" has been arbitrarily chosen, and should be used
by those programs which adhere fully to all the standards proposed
in this document.
The text of the message itself contains the request proper, and is
the subject of the following paragraphs.
4 Linking and Unlinking of conferences.
The current methods for requesting that a conference be linked are
basically two:
+CONFNAME
CONFNAME
For reasons of uniformity, it is proposed that all conference
manager programs recognize the first method.
Requests that a conference be unlinked are given by:
-CONFNAME
It might be interesting to implement some form of pattern matching,
similar to the unix shell. The following basic wildcards should be
considered:
* matches zero or more characters
? matches any one (not zero) character
Since the requests are processed top-down, a request of the form
+CONFNAME
-*
would be redundant, since the ConfMgr would link CONFNAME from the
first line, and then immediately unlink it again because of the
second line, which requests that all linked conferenecs be unlinked.
It should also be possible to specify more than one conference tag
on the same line. For example:
+CONF1 CONF2 CONF3
would link the three conferences CONF1, CONF2 and CONF3.
5 Rescanning Conference Mail
Many conference managers currently allow a system to request that an
area be "rescanned". In other words, the system receiving the
request will export all mail in one or more areas to the requesting
system.
This may be accomplished by specifying the %RESCAN command in the
body of the request. This will force the ConfMgr to generate a scan
request for those areas which the remote system requested with the
message containing the %RESCAN command.
Rescans of a single area, newly linked, could be requested as
follows:
+CONFNAME, R[=<n>]
where 'n' is the number of messages in that area to be rescanned.
(The space following the comma is optional, but allowed.)
Rescanning has one serious drawback: dupes! It is very possible for
the requesting system to have already set up the area with several
downlinks. Thus, when the rescanned mail is received, it could be
exported to other systems. In a tree-based topology, this is
harmless, but in circular topologies this would create dupes.
Thus, it is proposed that system receiving the rescan request add a
kludge to the messages, so that they can be recognized by the
requesting system and not re-exported.
The proposed kludge is:
^ARESCANNED <addr>
where <addr> is the network address, including domain, of the
system from which the mail was rescanned.
In alternative to a rescan, a sysop might request a "sample",
consisting of a series of messages contained in a text file. The
ConfMgr would export some or all messages from an area to a plain
ASCII text file, and send it along with the reply, to the requesting
system. A "sample" request would be made as follows:
+CONFNAME, S[=<n>]
where 'n' indicates how many messages should be sampled.
a) Updating Conferences
Update requests allow a sysop to rescan or "sample" an area
without having to first unlink from it, and then relink with the
rescan or "sample" parameter.
The format of this command is:
=CONFNAME, <param>[=<n>]
Thus a rescan request for the most recent 50 messages would be
specified as:
=CONFNAME, R=50
6 Information Requests
Requests for information have until now taken two forms. In one
case, they are given as switches after the password on the subject
line, while in the second they are given as "commands" within the
body of the message text. It is proposed that the second method be
chosen as standard, since it is considerably more flexible.
Below are listed the proposed commands:
%HELP Sends a (pre-defined) help text to the
requesting system, explaining how the
ConfMgr is to be used.
%LIST[,B] Lists the conferences currently available
to the requesting system, on the basis
of a method internal to the conference
manager itself. This list would flag the
areas which are already linked. The 'B'
modifier would generate the list in
binary format (see section 8e).
%BLIST Equivalent to %LIST,B above.
%QUERY Lists the conferences currently linked to
the requesting system.
%UNLINKED Lists the conferences which are available
to the requesting system, but not
currently linked. This is the logical
difference between a %LIST and a %QUERY.
7 Remote Maintenance
Besides these simple functions, it is becoming more and more
interesting to make handling of the conference mail flow even more
automatic. For this reason, for example, it might be useful to
allow another sysop control over your own system, adding and
removing conferences as need requires. Thus a hub or coordinator
could automatically have a new area added to their conference
lists, or discontinued ones removed.
Naturally, the ConfMgr must be able to distinguish which system has
the ability to make such changes, but that is beyond the scope of
this document.
It is proposed that a conference manager be able to automatically
add a new conference to the system's list if/when it is detected.
Thus no special commands would be required. The manager should be
able to determine a default list of down-links for the new area,
and also the "group" of systems which could then request it.
However, should it be desired to explicitly create a new conference
via remote, this could be done by including a line such as the
following in the message text:
&CONFNAME
In order to remote delete an area, the requesting sysop should
include a line like this in the body of the message text:
~CONFNAME
Thus, if the system has remote privileges, the conference would be
deleted (and optionally, all systems linked to the conference could
be informed of this fact).
Similarly, it would also be possible to allow a system to change the
tag of a conference. This would be accomplished by a line such as:
# OLD_NAME NEW_NAME
The ConfMgr should inform all downlinks of the change by sending a
net mail message.
It might also be desirable to allow a sysop to make changes on
behalf of another system. This could be done by inserting a special
command at the beginning of the request itself. For example:
From: John Doe, on 2:123/1
To: Program, on 2:987/65
Subject: password
Text:
%FROM: 2:234/56
+CONFNAME
The %FROM command would make the ConfMgr carry out the changes as if
the system 2:234/56 had requested them. The password should
nonetheless be the one assigned to 2:123/1.
8 Further Automation
In order to make the system more powerful, and to reduce the
necessity for human intervention, several extensions are feasible.
a) ARCmail Compression Method
One interesting application is the possibility of allowing a
remote system to change the compression program used to "pack"
mail bound for his system. This could be done with the following
command in the message to a ConfMgr:
%COMPRESS <method>
where <method> is one of the compression programs supported by
the system. Of course, the remote system should also be able to
determine which compression methods are available; this could be
done with
%COMPRESS ?
Requests for an unsupported compression method should also be
responded to with a list of those available.
From the practical point of view, only systems which pick up
their mail (as opposed to those to whom mail is sent) should be
allowed to change the compression method used. How this
distinction is achieved is beyond the scope of this document.
b) Passwords
A sysop should be able to change the password used to make
requests to a ConfMgr without requiring the intervention of the
other system's sysop. This could easily be done if the
conference manager implemented the following command:
%PWD <new_password>
The new password (case insensitive) would replace the current
one as of the next request.
c) Temporary Unlink
Should a system's sysop be absent for a prolonged period of time,
he might want to temporarily cut all conferences from his
uplink. This could be accomplished with the
%PAUSE
command. This would tell the ConfMgr to temporarily stop sending
conferences to that system. On his return, the sysop could
reactivate them all with the
%RESUME
command.
d) Forwarding Remote Requests
If a conference manager receives a remote request to delete an
area, it could very easily "forward" that request to all its
downlinks by producing a similar request. In that way, a single
request originating from, for example, a Region Coordinator,
would result in the conference being deleted from all systems
"below" him.
Similarly, remote requests for conference name changes could
also be passed on to downlinks.
e) Automatic Requests for Conferences
A conference manager should also be able to automatically request
an area from an uplink. This would become necessary if, for
example, it processed a request for an area not currently
available on the system. In this case, it would scan a series of
conference lists for the requested area, and if found, would
send a request for that area.
In order to be able to do this, the ConfMgr would need to have
one or more lists of conferences from the uplinks. These lists
could be produced on request by the ConfMgr itself. In order to
simplify matters, a binary format is proposed. (Note that these
are C-style structures, with everything which that implies.)
This binary file is called a Binary Conference List (BCL).
The file starts with a header, containing some basic system
information:
struct bcl_header {
char FingerPrint[4]; /* BCL<NUL> */
char ConfMgrName[31]; /* Name of "ConfMgr" */
char Origin[51]; /* Originating network addr */
long CreationTime; /* UNIX-timestamp when created */
long flags; /* Options, see below */
char Reserved[256]; /* Reserved data */
}
The currently defined flags for the header are:
BCLH_ISLIST 0x00000001L
File is complete list
BCLH_ISUPDATE 0x00000002L
File contains update/diff information
The BCL would then contain a series of entries having the
following format:
struct bcl {
int EntryLength; /* Length of entry data */
long flags1, flags2; /* Conference flags */
char *AreaTag; /* Area tag [51] */
char *Description; /* Description [51] */
char *Administrator; /* Administrator or contact [51] */
}
The flags currently defined are:
FLG1_READONLY 0x00000001L
Read only, software must not allow users to enter mail.
FLG1_PRIVATE 0x00000002L
Private attribute of messages is honored.
FLG1_FILECONF 0x00000004L
File conference.
FLG1_MAILCONF 0x00000008L
Mail conference.
FLG1_REMOVE 0x00000010L
Remove specified conference from list (otherwise add/upd).
Thus, instead of scanning an AREAS.BBS style list, the ConfMgr
would parse and use lists in the above format. Naturally, each
list would be in some way "attached" to a node number, and a
corresponding ConfMgr password.
Each system may only have one master file, called anything they
want. But when transmitted to other systems, this file must
always be named ????????.BCL.
The list would be generated in response to a
%LIST, B
command in the message text.
f) Receipts
It might be useful to have the ConfMgr generate a receipt to be
sent to another system, perhaps a co-sysop or a sysop point
node. This could be done with the command:
%RECEIPT <name>,<address>
embedded in the request message. For example:
%RECEIPT JoHo,2:270/17
9 Comments in the request
It should be possible for a sysop to insert a comment in the request
made to a conference manager. These comments, naturally, would be
destined to the sysop of the system, and not to the conference
manager itself. Such comments should be placed at the end of the
message, following a %NOTE command.
In all cases except the above, the request can be deleted by the
ConfMgr once processed, but messages containing comments should be
retained.
Note: the current method used is to supply comments after a tear-
line. This practice is somewhat "messy", but it might be wise to
support it until such time as all conference managers have
implemented the %NOTE command.
10 Summary
+CONFNAME[,R|S] Request to link to CONFNAME
-CONFNAME Request to unlink from CONFNAME
=CONFNAME,R|S Rescan or "sample" linked conference
&CONFNAME Request to create CONFNAME
~CONFNAME Request to delete CONFNAME
#OLD NEW Name change request
%LIST[,B] List available areas, flag linked
%QUERY Only list linked areas
%UNLINKED List available but unlinked areas
%HELP Send help text
%FROM <addr> Simulate request from another system
%RESCAN Rescan conferences linked in current request
%COMPRESS <method> Change compression method
%PWD <new_pwd> Change ConfMgr password
%PAUSE Suspend link
%RESUME Resume link
%RECEIPT <name>,<addr> Send copy of receipt to another system
%NOTE Introduces comment to the sysop
11 Final Note
This document is to be considered as a suggestion for software
developers to make their programs compatible with one another, so as
to make life easier for the average sysop when dealing with
conference managers.
Feedback would be appreciated and can be sent to us at the addresses
specified on the title page. Please send feedback via netmail only.
