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.