The Best of Windows 95.com 1996 September

home *** CD-ROM | disk | FTP | other *** search

/ The Best of Windows 95.com 1996 September / WIN95_09961.iso / mailsrv / LSV95.ZIP / win95.z / listmast.memo < prev next >

Wrap

Text File | 1995-05-24 | 32KB | 599 lines

LISTSERV historical documentation, release 1.5d ----------------------------------------------- Copyright Eric Thomas 1986 ***************************************** * * * Privileged commands for postmasters * * * ***************************************** This memo is a description of the commands offered by the Revised LISTSERV to postmasters. It includes a description of privileged postmas- ter commands, general information about the various data files on the LISTSERV minidisk and a (short) maintenance guide. Defining the postmasters: Apart from the LISTSERV userid, which has full postmaster privileges, it is mandatory to define at least one postmaster for the LISTSERV machi- ne. Postmaster accounts must all be BITNET userid@nodes and are defined in LSV$PROF EXEC ("postmaster" variable). The first postmaster in the list will be the "main" one and will receive files which have been rejec- ted by the server. Apart from that, "main" postmastership does not confer any additional privilege. "Weaker" postmasters can be defined by including a "cc:" keyword in the postmasters list. Those "weak" postmasters will be "cc:"-ed (instead of "To:"-ed) whenever mail is sent to the postmasters list, and they will not be able to issue any CP or CMS (qqv) command to the server. They will still have full postmaster authority over all the distribution lists, and will be able to stop the server if needs arise ("STOP"/"SHUTDOWN" com- mand). Good candidates for "cc:"-postmastership are the system operator (who must be able to stop the server and will know where to find the main postmaster in case he gets an error mail from the server), the site direc tor (in case not a system person) and remote postmasters. Additionally, it is possible to define "hidden" postmasters, who will not appear on the "Help" command output. For example, it might be desired to "hide" the OPERATOR userid so that he does not get any error-report mail from users, while still keeping his full postmaster attributes. Spe- cifying a "hide:" keyword in the postmasters list will cause any and all subsequent userid@nodes to be hidden. This implies that you cannot have both hidden full-prived postmasters and non-hidden cc:-postmasters. This is a restriction, et voila. Note that a remote cc:-postmaster to which none of the passwords has been communicated is a very weak postmaster indeed... He will not be able to create lists, nor will he be allowed to issue any privileged command; he will not be able to alter lists unless the password has been communi- cated to him (or unless there is no password). He will, however, receive notification of any severe internal error, and will be able to review all the lists (and to obtain a complete list of all the distribution lists). You should therefore feel free to give "blind-cc:-postmastership" (as we might call it) to a relatively trusted off-node person, for example, the adjacent node's system operator, who could then drain the link in the (quite improbable) case that this system error caused the server to loop on a mail-sending operation. This person should probably be "hidden" from the list, too. Remote control -- password validation Because the RSCS network is not proof against userid@node falsification it was deemed necessary to provide a means whereby any message coming from the network can be validated before being executed, thus thwarting possible hacking attempts from UREP hijackers. Lists can be protected by a "list password" which is optionally validated on all the list-maintenan ce commands. A similar scheme has been adopted to protect postmaster com- mands. In that case the passwords that have been adopted are the list- creation password ("createpw" variable in LSV$PROF EXEC) and the remote- file-storing password (see PUTC command description below). The former is used to protect all the postmaster list-maintenance commands (which are available to all classes of postmasters), while the latter is reser- ved to CP, CMS, et al. -- commands which are only available to full-priv postmasters. Since cc:-postmasters are basically list-maintenance persons they will have to know the "create" password for other reasons (eg when they have to create a new list), but should not have access to the "store" password (nor to the server's logon password). Full-prived post- masters will have access to all passwords, of course. For better convenience it was decided that whenever the "create" pass- word is required, the "store" password would be accepted as a replacement since it is a much "stronger" password. Remote full-priv postmasters will therefore not have to worry about which password is required by the com- mand they want to issue -- the "store" password is universal. Furthermore password validation is waived whenever the command has been physically entered at the server's keyboard or directly sent to the server via a "CP SMSG" or "CP MSG" command from the local node. In other words, pass- words must be supplied only when the command comes from the RSCS machine. It is furthermore possible to disable remote CP, CMS, et al. commanding by setting the "storelist" variable to '' in LSV$PROF. This will cause the "store" password not to exist and will disable any command that would have required it to be specified. Privileged postmaster commands: Apart from all the "postmaster-only" commands, postmasters have access to all the commands restricted to list-owners and have authority to act upon ANY list exactly as if they "owned" all of them. They must still use the correct list password, though. CMS command-text <PW=storepw> (requires full-postmaster privilege) Will execute the specified CMS command and display the return code. Note that there is no protection against programs which place the vir- tual console in VM READ state and can cause CP to terminate the virtual machine. I *have* a program to do that (re-ipl the machine if you get into VM READ or CMS ABEND), but thought it wasn't really necessary to use it. I could install it if really needed, though (it's been running on all the RELAYs since months without any problem, so it is safe; the only problem is to be sure it cannot cause re-ipl loops). Xedit fn ft <fm <(options>> (restricted to the LISTSERV userid) Is functionally identical to "CMS Xedit ..." It is intended to be exe- cuted from the LISTSERV console only, and has no other purpose than to make the life of the author a deal easier when he wants to update some LISTSERV exec... CP command-text <PW=storepw> (requires full-postmaster privilege) Will execute the specified CP command and display the resulting output (trapped via EXECIO), as well as the return code. This is not the same as "CMS CP command-text", which would not display the command output. DISC (restricted to the LISTSERV userid) Will disconnect the LISTSERV machine. It is functionally equivalent to "CP DISC", and it's only purpose is to avoid stressing the postmaster when he tries to disconnect the machine... SENDFile fn ft <fm> <PW=storepw> SF (requires full-postmaster privilege) Will send you the requested file from the appropriate LISTSERV mini- disk, in Netdata format. Any file can be obtained by means of this command. SHUTDOWN <REIPL> <PW=createpw or storepw> STOP REBOOT Will shut down the LISTSERV machine. All disk files will be closed, the IUCV-trap will be reset and control will be returned to CMS unless the virtual console is found to be disconnected, in which case a CP LOGOFF command is performed. When the "REBOOT" or "REIPL" option is specified, an "IPL CMS PARM AUTOCR" command will be issued to reboot the server. This allows remote postmasters to reboot the server after updating one of the LISTSERV execs, for example. PUT listname <PW=createpw> By means of this command postmasters can update any LISTSERV list or create new lists. A detailed description of the command can be found in the list-owner's guide; however, there are some different aspects about creating new lists. Since by definition a "new list" does not already exist, it will have no "PW=" keyword in it, ie no explicit password. This would imply that anybody able to fake the postmaster's userid@node could create a new list on the server for himself (by specifying him- self as owner for future store commands), or (even worse) could create a list with someone else's userid in the "Owner=" keyword, and that person would be accused of all sorts of nasty things... It has there- fore been decided that an implicit password be assigned to new lists. This password is defined in LSV$PROF EXEC ("createpw" variable) and can be changed only by modifying this EXEC and rebooting the server. This password must be specified the usual way (ie "* PW= createpw") when creating the list. Note that unless you specify a second "PW=" keyword in the list, no password will be assigned to it. Do not forget to cre- ate the dummy VM account after creating a new list -- otherwise you couldn't mail to it. Alternately, a list can be "locked" by NOLOG-ing the associated dummy account: subscriptions and list maintenance will still be possible, but no actual mailing/file sending will take place. NOTIFY userid@node ON | OFF <PW=createpw or storepw> By issuing a "NOTIFY userid@node OFF" command, you can have LISTSERV automatically suppress all notification mail sent to the specified userid@node. This command should be used whenever LISTSERVs are linked together -- refer to LISTLINK MEMO for more detailed information on list linking. NODESGEN <WTONLY> <PW=storepw> | | (requires full-postmaster privilege) | The NODESGEN command must be invoked every time a new version of the | BITEARN NODES database is made available to LISTSERV, and after the | server has been rebooted to re-access the appropriate (supposedly) R/O | disks. It will automatically rebuild all the BITEARN NODES-based data | files used by LISTSERV. The WTONLY option indicates that the only | action that should be taken is to compile the links weight file | ("LINKSWT FILE") into the "BITEARN LINKSUM" file. This process takes | only a few seconds and should be used whenever the links weight file | has been updated. Note that the full NODESGEN command also includes | compilation of the links weight file. > GENROUTS is no longer needed. HOLD listname <PW=listpw or createpw> FREE listname <PW=listpw or createpw> | | These commands are strictly identical to the list-owner commands of the | same names. However, postmasters (including cc:-postmasters) have the | ability to use them against any list without having to know the list | password: the createpw (or the storepw) is accepted on these two | commands. OFFLINE <PW=createpw or storepw> | | The OFFLINE command provides a means whereby any file or piece of mail | received by the server and determined to be destined for distribution | to a list can be placed in (spool) HOLD status with a message being | sent to its sender. This is equivalent to issuing a HOLD command (see | LISTOWNR MEMO) against all the distribution lists of the server, with | the difference that a list that has been held by means of a HOLD com- | mand will not be released when the OFFLINE command is negated (see | ONLINE command below). In other words, OFFLINE is a 'global' indicator | while HOLD is a 'local' one, and the list is held as soon as one of | those two indicators is set. ! ! OFFLINE also causes all DISTRIBUTE commands to be postponed, with a ! message being sent to the originator and the file being kept in the ! reader in HOLD status until subsequently freed by an ONLINE command. | | The OFFLINE command should be used only when the precise origin of a | mailing loop could not be determined. As soon as the list that caused | the loop has been identified, it should be placed under selective hold | status by means of a HOLD command (qqv) *before* the OFFLINE command is | negated. ONLINE <PW=createpw or storepw> | | ONLINE is the counterpart of OFFLINE and releases all the distribution | lists that have not been subjected to an individual HOLD command. All | files that had been placed in spool HOLD status are released and re- | enqueued for distribution. Lists that have been individually held by | means of a HOLD command are not released -- use the FREE command for | that purpose (described in LISTOWNR MEMO). PUTC <fn ft <fm>> <RECFM=F|V> <LRECL=nnn> <PW=storepw> |> |>This command replaces, and makes obsolete, the dummy <PUT> command of |>the earlier versions of LISTSERV. The format of this new command subsu- |>mes that of the old <PUT> command and full ascending compatibility is |>warrantied. | | The PUTC command, which can only be issued from a file, allows you to | store a file on any of the server's minidisk, under any name. The com- | mand must be placed in the first record of the file to be stored, with | the appropriate keywords being specified (they are all optional, except | "PW=storepw"). The file must then be sent to the server with a spool | form of "QU-STORE" to effect the store operation. The keywords can be | specified in any order and anywhere in the command line. The default | value for "RECFM=" is V, and the default value for "LRECL=" is not to | change the lrecl. The default filemode is A1 and the default fileid | is as indicated by the spool fileid. | | To delete a file from the server's disk, you can either use a CMS ERASE | command or send a PUTC command with no data (ie just the PUTC record). | The file will then be erased from the server's disk. | | It is strongly recommended that you use the LSVPUT program to send your | PUTC commands to LISTSERV, since it will automatically fill in the | "RECFM=" and "LRECL=" keywords to make sure that the file is properly | reformatted. |>The old <PUT> command changed all RECFM F files to RECFM V when used |>in conjunction with LSVPUT. | |>The reasons for the strange name of this command (PUTC instead of PUT) |>are twofold: compatibility with the equivalent Netserv command (PUTC), |>and possibility to reserve the name "PUT" to the list-owner command |>that will be developped in the next release as part of the planned file |>server capabilities of LISTSERV. This, again, will follow the Netserv |>conventions. The GET command will be enhanced to perform as the Netserv |>command of the same name when more than one argument is specified. | The password required for this command is obtained from the dummy dis- tribution list whose name is defined in the LSV$PROF exec ("storelist" variable). If "storelist" is set to '', no PUTC operation will be possi- ble at all, nor will remote CP/CMS commands be accepted. The "store" pass word can be changed by changing the password of the "store" list in the usual way (with a <STORE> command). Note that you do NOT need to create a dummy userid for the "store" list. PWC ADD userid@node password <PW=createpw> ! DELete userid@node <PW=createpw> ! Query userid@node <PW=createpw> ! ! This command allows you to assign, delete, or query the LISTSERV pass- ! word of any user. Notification will be sent to the target for the ADD ! and DELete options unless you have specified QUIET (eg QUIET PWC DELETE ! userid@node). "userid node" is accepted in lieu of "userid@node" for ! compatibility with the Netserv syntax. FOR userid@node any_command ! ! This command allows you to execute a command "for" another userid. The ! result is the same as if the specified user had issued the command to ! LISTSERV himself, except that you get a copy of all the messages that ! may be sent to him as a result of the command. No password is required ! on the FOR command -- people able to fake your userid@node to issue a ! FOR command can also fake the target's userid@node.... DEBUG ON | OFF <PW=storepw> ! ! (requires full-postmaster privilege) ! This command should normally not be used except by the author... Pla- ! cing LISTSERV in debug mode will cause an EXECDROP * to be executed, ! with a flag being set to avoid any subsequent EXECLOAD command from ! LSVPROF, will remove the second and subsequent postmasters from the ! in-storage POSTMASTER global variable (to avoid sending 100 junk mail ! files over 15 links to a remote postmaster as it already happened once) ! etc. DEBUG OFF will return everything back to its normal status and ! will reboot the server. Note that performances may be severely affected ! when running in debug mode. Data files on the LISTSERV disk: The LISTSERV machine has a variety of files on its 191 minidisk, some of which must be maintained/tailored by the postmaster. Here is a (short) description of the various files that can be encoutered on LISTSERV 191: - LSVaxxx EXEC and LSVaxxx XEDIT, where 'a' is an alphabetical character, are the various components of the LISTSERV program per se. They should not be modified. You will gain no benefit from EXECLOADing them if you use the VM/SP 3 EXECLOAD program since they are always invoked via the REXX "Call" statement. The startup exec (LSVPROF) will automatically issue EXECLOAD commands for the execs which are frequently used if your CMS system is release 4 or better. - LSV$xxx EXEC are user-tailorable exits/definition execs. Acceptable ! default execs are provided for most of them, but LSV$PROF *must* be ! tailored before the server is started. It defines the postmaster's ! userid, mailer's userid, default password for new lists, etc. LSV$PW is ! the installation-tailorable exit to control PW ADD commands. LSV$PUT is ! called whenever a PUT command is issued against a file which is undefi- ! ned to LISTSERV. - LSV_xxx EXEC are user-defined "control exit" execs associated with some ! of the files which are made available on LISTSERV. Some of them are ! shipped with the LISTSERV code but you can create your own ones. See ! LISTFOWN MEMO for more information. - PROFILE EXEC should be modified to change the CP SPOOL CONSOLE state- ment, userid of the person getting a message if REXX unexpectedly exits to CMS, and PFkeys settings (if desired). - NONOTIFY FILE contains the userid@nodes of all the persons which have been subjected to a NOTIFY OFF command (qqv). You can modify it manual- ly if needed, but the NOTIFY command can do it too... - SIGNUP FILE lists the userid@nodes and true names of all people known to LISTSERV. Whenever information mail is sent to someone who appears on this list, the person's true name is extracted from it and inserted in the mail header. Although you can manually modify it without problem it is automatically updated whenever a SUBSCRIBE/ADD command is recei- ved (if the user already appears in the file his name is replaced with the one that was specified in the latest command). Entries are not removed when a user signs off from a list (in case he appears on seve- ral lists), so some housekeeping might be required once a year or so. - PEERS FILE !>This file has been superseded by PEERS NAMES. The startup exec of ver- !>sion 1.5d will automatically erase this file if present on the disk. - PEERS NAMES contains information about all the known (operational) Revised LISTSERVs in the world. - BITEARN NODESUM is a summary of the information contained in the | BITEARN NODES database. It is generated by the NODESGEN command. Al- | though LISTSERV can probably still run without it, this file is now | officially MANDATORY. Problems caused by the absence of this file from | the server's disks will no longer be addressed by the author. - BITEARN LINKSUM contains information about the network topology. It is | generated from BITEARN NODES by the NODESGEN command (qqv) and is used | by the EXPLODE and SUBSCRIBE commands processor. The format of this | file is special and it must NEVER be modified using XEDIT, even with | SET HEX ON, SET IMAGE OFF, etc. This file is now considered to be man- | datory under the same conditions as BITEARN NODESUM. - LINKSWT FILE is the "links weight" file that is used to override links | weights when generating the "BITEARN LINKSUM" file. It indicates, in a | free format, pairs of nodes and the appropriate arbitrary distance that | separate them (in the 1-9 range). Note that whenever an alias node name | exists for one of the nodes, an additional entry must be provided for | that alias name, with the same distance. For example, if you specify | "EARNET BITNIC 9", you MUST also specify "IEARN BITNIC 9". Since the | relation is symmetrical you do not need to specify "BITNIC EARNET 9", | but if BITNIC had an alias you would have to file in a total of four | entries. | | *** Important note *** | This file is maintained, EXCLUSIVELY, by the Listserv coordinators. You | should not modify it without checking with the Listserv coordination | first, unless the modification you intend to make applies only to nodes | that are local to your institution. See LISTCOOR MEMO for more details | on this subject. - NODES FILE !>This file is no longer required. The startup program of version 1.5d !>will automatically erase it if found on the disk. - xxxxxxxx LIST are the LISTSERV lists definitions, as obtained by a GET or REView command (but of course the "PW=" keyword appears in the file) You should not modify these files manually, or if you do you MUST pre- serve the special format (tabulation, etc). You should always use the GET & STORE method which will automatically reformat the file and sort it by nodes. - xxxxxxxx STATS are the statistics associated with list "listname". They are automatically maintained by the LISTSERV system, and should not be altered. The statistics can be "reset" by erasing the appropriate STATS file. - xxxxxx MAILFORM are information mail templates. You can create one of these for each list, but this is not mandatory (default is "$DEFAULT MAILFORM"). The format of these files is easy to understand -- each "form" has a name and its location in the MAILFORM file is indicated by a ":formname formsubject" line (where 'formsubject' is the line to be put in the "Subject:" tag). The body of the note follows and is ended by ":END". Anything that appears between quotes is "translated" as per the REXX "Interpret" statement; note that this is exactly the opposite of a REXX statement, ie what is WITHIN quotes gets translated. Some of the variables are always available (eg 'listname'), but some of them are specified by the calling program. Note that lines in excess of 79 characters will be split, with the remainder inserted before the next line. Also, any line longer than 70 characters will be justified. | Quotes must be doubled whenever they are to appear untranslated in the | text. *** WARNING *** You should carefully review the "listname MAILFORM" files sent to you by list owners before placing them online. Since the quoted clauses are not checked before being interpreted, a carefully designed mail form could jeopardize your system's security by allowing CP commands to be executed. For example, a 'Diag(8,username)' field would allow anybody to issue any CP command to your server by just signing on to a list with the command text as "name". - xxxxxxxx MEMO and xxxxxxxx REFCARD are the documents sent by the "Info" command. You should not erase them nor rename them. - WAKEUP MODULE and CARD MODULE are required for LISTSERV to operate pro- perly. WAKEUP is (of course) the release 5 one, with IUCV support. The version shipped with the code is 5.35, and it was the safest one at the time this memo was written. Version 5.4 is a can of bugs, so to speak... All other MODULEs are utilities and can be discarded if required, but it is strongly recommended that REXXDUMP be left on the disk since it is invoked by some of the REXX programs after an abnormal condition is detected. Also, FREE is a module that will display the amount of free high-area storage and can be very useful to determine which storage size is required by the server. - WAKEPARM FILE is an optional "WAKEUP PARMS" format file which lists events that LISTSERV should execute at specific times on a regular basis. Refer to the proper IBM documentation for more information on the format of this file. The "event" is interpreted as follow: - If the first word is "CP", it is interpreted as a CP command to execute. - If it is "CMS", the command is passed to CMS via an "Address CMS". - "EXEC" is equivalent to "CMS EXEC". - "REXX" indicates that the command must be passed to REXX as per the 'Interpret' statement. - Any other parameter string is 'Interpret'-ed. - LOCALCMD FILE is an optional file which allows you to define "local" commands for your server without having to modify the standard LISTSERV execs. The format of each line of this file is: command_name min_abbrev exec_name <exec_parms> command_name is the full command name. It MUST start with a special character (anything not in the A-Z range) and be entered all uppercase. The author warranties that no standard command will ever start with a special character; you can therefore be sure that there will be no conflict between your local commands and a possible future stan- dard command. Local commands starting with A-Z are NOT allowed and are ignored by the command processor. min_abbrev is the minimum number of characters to provide for the command to be recognized. It must be an integer number. exec_name is the filename of the REXX program to receive control when the command is identified. It *must* be a REXX pro- gram and is called as per the following command: Call exec_name origin command_name parms,<exec_parms> exec_name, command_name and exec_parms are from LOCALCMD FILE origin is the "userid@node" of the command originator parms is the command parameters specified by the user on the command line The REXX command exec must return control to the LISTSERV system via a "Return <return-code>" instruction. The return-code is optional and is > ignored by the present version of LISTSERV, but should follow the con- > vention that 0 = command completed successfully, 1 = unknown command > and other = not yet defined. A future version of LISTSERV might make > these values available to command jobs for conditional command execu- > tion. LISTSERV subroutines and functions can of course be "Call"-ed by the user REXX command processor, although no documentation is available on these functions. - LOCALCMD HELPFILE should contain help information about your local com- mands, if any. This information is dumped "as is" to users issuing a "Help" command and is preceded by a message saying "The following local commands are available at this installation:". The format should be si- milar to the format of the "standard" help messages. - XMAILER NAMES and DOMAIN NAMES are not mandatory but they are strongly recommended. They are used to detect possible mailing loops and must be regularly refreshed to take new mailers into account. It is therefore suggested that a LISTSERV be LINKed to MAILER 191 in RR mode with this disk being subsequently accessed in the PROFILE EXEC to make sure that LISTSERV always has the latest version of these files. Do not forget to reboot LISTSERV when you modify the MAILER's 191 disk. > These files will become mandatory in the next release. - NETSERV CONTACTS is the list of contacts for the NETSERV machines. Any ! piece of mail sent to a Netserv machine will be automatically forwarded ! to the corresponding contacts, with a copy being sent to the author of ! Netserv (Berthold Pasch <PASCH@DHDIBM1>) ! - AFDLIST FILE and FUILIST FILE are the list of all AFD and FUI subscrip- ! tions served by your server. ! - AFDPEND FILE and FUIPEND FILE list the pending delayed AFD/FUI opera- ! tions. It is automatically reset when LSVXAFD is called from the WAKE- ! PARM FILE. ! - HARDFAC FILE is a description of the "hardcoded" FACs and is automati- ! cally included in each FILELIST sent via a GET command. ! - PWLIST FILE contains the LISTSERV passwords of all the users who were ! assigned a password on your server. ! - xxxxx FILELIST are the various filelists available via the file-server ! functions. ! - xxxxx FILEID are the "fileid definition" files for the corresponding ! filelists. The format is the following: ! ! line 1: internal counter, do not change it. Set it to "1" if you ! create a new FILEID file. ! line 2: optionally, "*DEFAULT* filemode execname execparm". Defines ! the default filemode, control exec and control exec parms to ! be used when generating new entries in the file. ! ! Other: fn ft true_fn true_ft true_fm <execname <execparm>> ! associates "true_fn true_ft true_fm" as "true fileid" for ! the file "fn ft" of the filelist, and optionally associates ! a "control exec" to it. ! - All the other files are profiles/utilities enjoyed by the author and can be discarded if needed. For more information refer to: LISTSERV MEMO, LISTOWNR MEMO, LISTLINK MEMO, LISTINST MEMO. Comments and complaints should be sent to Eric Thomas <ERIC@FRECP11>