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 ,
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 Simulate request from another system %RESCAN Rescan conferences linked in current request %COMPRESS Change compression method %PWD Change ConfMgr password %PAUSE Suspend link %RESUME Resume link %RECEIPT , 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.