    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=]

           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[=]

           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

           where  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[=]

           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, [=]

              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

              where  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

              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 */
                   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 ,

Go Back