MULTICS TECHNICAL BULLETIN MTB-669 To: MTB Distribution From: Karen MacKenzie Date: 07/23/84 Subject: Summary of Discussion on MTB-656 (Reorganizing/Rewriting Administration and Maintenance Documentation) This MTB summarizes the discussion of MTB-656 which was held in the SysAdmin_doc forum (>udd>Pubs>km>mtgs>sad on System M). It describes the major changes to the proposed reorganization of the manuals on which agreements were reached. It does not describe the detailed changes to the proposed outlines for the new manuals on which agreements were reached. These will be described in a revision of MTB-656, which will be published at a later date. Comments on this MTB should be sent to the author: via Multics mail: KMacKenzie.Pubs on System M or via telephone: (HVN) 492-9308 or (617) 492-9308 _________________________________________________________________ Multics Project internal working documentation. Not to be reproduced or distributed outside the Multics Project. MTB-669 AGREEMENTS Agreements were reached on the following changes to the proposed reorganization of the manuals: 1. Privileged subroutines will NOT be documented in the same manual as privileged commands. Instead, some of them will be documented in the existing Subroutines and I/O Modules manual (AG93), and some of them will be documented in a separate, new manual. The decision as to which subroutines belong in AG93 and which subroutines belong in this new manual, as well as the decision as to whether or not the new manual should be a PLM, will be driven by B2 security requirements. A discussion of these requirements is beyond the scope of this MTB. For the time being, a separate section will be created in AG93 for privileged subroutines, and a discussion of privilege/access will be added to AG93 to avoid user confusion as to which subroutines s/he may use. 2. The new commands manual will NOT be called the Privileged Commands manual. Instead, it will be called the Administration, Maintenance and Operations (AMO) Commands manual. This title makes it as clear as possible exactly which commands this manual contains. 3. There will be two criteria for including a command in the AMO Commands manual: it requires privileged access; it is rarely used by ordinary users. Where there is a question about the second criterion, the command will be documented in both the AMO Commands manual and the existing Commands and Active Functions manual (AG92). 4. The AMO Commands manual will have the following structure: Introduction: Command Environments Section 1: Privileged Multics Commands Section 2: Accounting Commands Section 3: Initializer Commands Section 4: Exec Commands _________________________________________________________________ Multics Project internal working documentation. Not to be reproduced or distributed outside the Multics Project. MTB-669 Section 5: I/O Daemon Commands Section 6: BCE Commands Section 7: BOS Commands The introduction will describe the various command environments, and how to use them from the Multics environment with admin mode, send_admin_command (sac), ec admin, and sc_command. The exec commands will be in a separate section from the rest of the initializer commands to make it easier for sites to replace them with their own versions. The accounting commands will be in a separate section from the rest of the privileged Multics commands because they are used in a special environment. The exec_coms admin.ec and master.ec will be described with the privileged Multics commands, with pointers to the exec and accounting commands, respectively. Commands will be arranged alphabetically within each section. Care will be taken to ensure that the index is complete, so a user who doesn't know which section a command is in can easily find out. 5. Project administration commands will be documented in the Project Administration Procedures manual as well as in the AMO Commands manual. 6. Care will be taken to ensure a one-to-one mapping between policy setting as described in the Owner's Manual and policy implementation as described in the System Administration and System Maintenance Procedures manuals. 7. Software overviews will be arranged by function, not alphabetically. Care will be taken to ensure that the glossary is complete, so a user who wants a quick definition of a term in isolation can easily get it. 8. A MTB needs to be written which outlines our philosophy on documenting PSPs. Documenting communications PSPs (e.g., HASP) is especially problematic. 9. There is a lot of overlap between the System Administration and System Maintenance Procedures manuals, because there is both an administrative and a maintenance aspect to many parts of the system. Care will be taken to give a different emphasis to discussions of the same topic in different books, to _________________________________________________________________ Multics Project internal working documentation. Not to be reproduced or distributed outside the Multics Project. MTB-669 provide cross references, and to point out that neither discussion is complete. 10. The outlines for the System Administration and System Maintenance Procedures manuals do not follow logically from the definitions of system administrators and system maintainers in the MTB. But the split of information/responsiblities exemplified by the outlines will make sense to users. Thus, what needs to change are the two definitions -- more specifically, the definition of system administration needs to be broadened. There are no absolute, correct definitions of the terms "system administration" and "system maintenance." And users (as a group) have hundreds of definitions and distinctions. Thus, we must pick our own definitions, explain them to our users carefully, and build our books around them. Trying to organize our books according to the way sites currently do things is not a good idea in this case. Sites have never had adequate documentation to learn from, so their ways of accomplishing administration and maintenance tasks often aren't the best. By splitting up administrative and maintenance documentation the way the MTB suggests, we're presenting sites with a new model of how to do things. This model corresponds to a design goal for the code which is driven in part by B2 security requirements. Hopefully, it will present sites with information in a way which is instructive, rather than a way which mirrors their current mistakes. Sites which choose not to do things the way we suggest shouldn't have any trouble finding the information they need, because so much of it is repeated (with different slants) in the two procedural books. _________________________________________________________________ Multics Project internal working documentation. Not to be reproduced or distributed outside the Multics Project.