MULTICS ADMINISTRATIVE BULLETIN MAB-056-03 To: MAB Distribution From: F. W. Martinson G. E. Johnson Date: March 26, 1986 Subject: Multics Configuration Management: Installing Planned Changes in System Libraries Abstract: This bulletin defines procedures for submitting planned software changes for installation into the Multics System Libraries. This bulletin derives its authority from, and is published under, Multics Configuration Management: Policy Statement, MAB-070. Revisions: | Rev2) 08/85, FWMartinson and GJohnson Revises the | procedure for normal installations to conform with | requirements of Configuration Management. | Rev3) 02/86, GJohnson Revises the MSCR Checklist used in | preparing a submission. Provide increased detail as to | directories requiring separate MSCR Detail Sheets. | Modifies MSCR Detail Sheet to include pathnames of both | the developer's software directory and auditor's | installation directory. | _________________________________________________________________ Multics Project internal working documentation. Not to be reproduced or distributed outside the Multics Project. - i - MAB-056-03 Installing Planned Changes CONTENTS Page Introduction . . . . . . . . . . . . . . . . . . . 1 Purpose of Installing Planned Changes . . . . . . . 1 Preparation for Installing Planned Changes . . . . 1 Approval of Planned Installations . . . . . . . . . 3 Auditor Approval . . . . . . . . . . . . . . . . 3 Security Coordinator Approval . . . . . . . . . 4 Documentation Unit Approval . . . . . . . . . . 4 Manager Approval . . . . . . . . . . . . . . . . 5 Processing the Planned Installation . . . . . . . . 5 Post-Submission Bug Fixes . . . . . . . . . . . . . 5 Emergency Changes to System Libraries . . . . . . . 6 Preparing the MSCR Form . . . . . . . . . . . . . . 6 SRB Notices . . . . . . . . . . . . . . . . . . . . 8 MSCR Detail Sheet . . . . . . . . . . . . . . . . . 9 - ii - Installing Planned Changes MAB-056-03 INTRODUCTION This is one of a series of MABs on Multics Configuration Management. MAB-070 gives an overview of the entire configuration management process. In particular, MAB-070 outlines policies for three types of software changes which are controlled by configuration management: o Planned changes to pre-release software and documentation, described in MAB-056. o Emergency changes to pre-release software and documentation, described in MAB-057. o Critical fix changes to released software and documentation, described in MAB-063. This MAB describes policies and procedures for the first of these three software change types. This document describes policies and procedures for installing planned software changes to the Multics System Libraries on System M located in Phoenix, Arizona. Planned software modifications must be in conformance with Software Development Procedures as described in MAB-066. Definitions and descriptions may refer the reader to additional documentation for greater levels of detail on specific topics. For management authority describing enforcement and exceptions see Policy Statement, MAB-070. This MAB replaces MABs 004, 012, 013, 014, 015, 033, 034, and previous versions of this document. PURPOSE OF INSTALLING PLANNED CHANGES Planned installations are used to place new or modified code into system libraries. They include non-emergency and non-critical bug fixes, new features, and enhancements to existing, or new, libraries. The ultimate goal of an installation is inclusion of the modified software in a Multics Release shipped to customer sites. A Multics Release is a hierarchical dump of the installed System M libraries in a stable condition. The dump of the contents may occur only when authorized for general distribution by the Director of the Multics Development Center, or designee. - 1 - MAB-056-03 Installing Planned Changes PREPARATION FOR INSTALLING PLANNED CHANGES Code modified for planned changes must have been developed in conformance with Software Development Procedures, MAB-066. Large installations are strongly discouraged. Coding, testing, and auditing must conform to published Multics standards in effect at the time modified code is submitted for installation. When the procedures described in that MAB have been satisfied the developer performs the following steps to install the change in the System Libraries. 1. PREPARE INSTALLATION: All modified segments (e.g., source, bind file, info, etc.) should be placed in one directory. Access to the modules being submitted should be set as follows: Change Directories Change Segments -------------------------- -------------------------- sma DEVELOPER.PROJECT.* re DEVELOPER.PROJECT.* s AUDITOR.PROJECT.* re AUDITOR.PROJECT.* sma *.SysDaemon.* re *.SysDaemon.* null *.*.* null *.*.* All new and modified source modules must contain appropriate history comments. The developer must add the history comments by using the history_comment (hcom) command described in Multics Configuration Management: Tracking Software Changes for MR12.0, MTB-716. A history comment may be added by typing: hcom add path {-control_args} The developer is responsible for adding software protection notices. Refer to MAB-052 for information on pnotices. Online, type "help add_pnotice". 2. PREPARE DOCUMENTATION: Collect a copy of all relevant approved MCRs, dprints of new or changed info segments, SRB notices when appropriate, and manual writeups (if available). If the submission is an incompatible change, prepare a segment containing a notice to be placed in message_of_the_day.info or in pending_changes.info. The presence of such a segment must be specifically noted on the MSCR form, described below, under Section E, Special Instructions. 3. PREPARE MSCR: Prepare a Multics System Change Request (MSCR) as described below. Attach all documentation collected in step 2. If the proposed change includes software previously installed as an Emergency Change the - 2 - Installing Planned Changes MAB-056-03 Emergency ID number must appear as the first item under Section C, Summary of Change. Refer to MAB-057 for a discussion of emergency fixes. * 4. SUBMITTER'S APPROVAL: The submitter's signature verifies that the code completely implements changes described by the MCR(s) and that all coding and testing has been in compliance with project plans and published standards. Reference Multics Programming Standards, MAB-068. 5. SUBMIT FOR AUDIT: The developer submits the MSCR, documentation and pathname of the installation directory to the auditor for auditing, as defined in MAB-069. After the audit, the developer and auditor decide if the software is ready to install or if it must be changed to correct audit failures. When the software is ready to install, the developer's responsibility in the installation procedure ends. APPROVAL OF PLANNED INSTALLATIONS Auditor Approval When auditing begins the auditor has control over the code being installed. Access to the modules being submitted should be set as follows: Change Directories Change Segments ----------------------------- ----------------------------- s DEVELOPER.PROJECT.* re DEVELOPER.PROJECT.* sma AUDITOR.PROJECT.* re AUDITOR.PROJECT.* s SEC_COORD.PROJECT.* re SEC_COORD.PROJECT.* s MANAGER.PROJECT.* re MANAGER.PROJECT.* s *.SysMaint.* re *.SysMaint.* sma *.SysDaemon.* re *.SysDaemon.* null *.*.* null *.*.* The pathname of the auditor's installation directory must be placed on the Detail Sheets of the MSCR. The Auditor's signature implies compliance with Guidelines for Auditing Software, MAB-069. The signature also signifies the MSCR form is complete and accurate and that appropriate pathnames to modified segments appear on the MSCR. The Auditor adds all auditing checklists associated with the software to the MSCR package (MSCR, documentation, SRB notice(s), pending_changes.info segment, etc.). - 3 - MAB-056-03 Installing Planned Changes Security Coordinator Approval When a proposed submission involves modules identified as part of the Trusted Computing Base (TCB) the auditor gives the MSCR package to the Security Coordinator for approval. The role, and responsibilities, of the Security Coordinator are variously described in MAB-070, and MAB-071. Installation policy and procedure specifically charters the Security Coordinator to audit the security aspects of modified modules and include files which are a part of, or used by, the TCB. The signature of the Security Coordinator provides reasonable assurance that the modifications to be installed have no negative impact on the TCB or the security of the Operating System. Documentation Unit Approval The Auditor or Security Coordinator gives the MSCR package to the Documentation Unit for approval. For large changes, the MSCR must reference an approved MTB. For small changes, the installation form must be accompanied by an English-language description of the new functionality. The documentation should provide: (1) a narrative description of the enhancement, including a description of how it will aid the user (the "why"), (2) examples, (3) figures, where appropriate, (4) explanation of what effect the software has on other parts of the system (e.g., what software is made obsolete), and (5) an appropriate notice to be included in the SRB. See "SRB Notices" below for further details. Documentation providing a description of a command, subroutine, or I/O module should include: (1) cross references to related commands/subroutines/IO Modules, (2) output messages/system responses, (3) error messages and corrective action, (4) an explanation of when, and why, users should NOT use the command/subroutine/IO module, (5) access rights, (6) limitations on the use of control arguments, (7) how to use the command/subroutine/IO module to best advantage. Installations may require additional, special, documentation such as notices for message_of_the_day (MOTD), pending_changes.info, and the Software Installation Bulletin (SIB) write-up. Although certain installations will not require documentation changes Documentation Unit sign-off is required to acknowledge both agreement and approval. The signature of the Documentation Unit Manager, or designee, may indicate satisfaction with presented documentation changes, authorization to install modified info segments submitted as part of the installation, or - 4 - Installing Planned Changes MAB-056-03 acknowledgement that an installation does not require document modification. Documentation approval acknowledges that the documentation unit accepts complete responsibility for the generation of all final user documentation. The Documentation Unit gives the MSCR package to the Unit Manager responsible for the software area being changed. Manager Approval The Manager's signature provides final authorization that the change is ready and appropriate for installation. The Manager forwards the MSCR package to the Project Leader, Software Integration Project, Phoenix, Arizona. PROCESSING THE PLANNED INSTALLATION The System Integration Project installs the changes indicated on the approved MSCR form on System M in Phoenix, Arizona. If the change is formally installing an earlier Emergency Change, the MSCR must note under C, Summary of Change, the associated Emergency ID number. After successful installation of an MSCR which closes an Emergency Change, the associated Emergency ID entry in the emergency installation tracking database is marked closed, and modified to reference the closing MSCR's MCR/Installation_id number. POST-SUBMISSION BUG FIXES Errors introduced by the recent installation of an approved MSCR may be corrected without getting a new MCR. Such corrections are called post-submission bug fixes (PBFs). PBFs are prepared by the original submitter and require use of MSCR forms. The following conditions MUST be met to to allow the Integration Unit to honor a PBF change request: - the PBF change request MUST be submitted to the Project Leader, Phoenix System Integration Project, within two (2) calendar weeks of the original MSCR installation which introduced the error(s). - the PBF submission must be made by the appropriate Unit Manager. - the MSCR must have undergone all levels of review and approval identified above under, Approval of Planned Installations, with all appropriate signatures. - 5 - MAB-056-03 Installing Planned Changes - the PBF must be submitted using a new MSCR and identify the original MCR/Installation_id number. - the PBF may not introduce new, or changed, functionality. The PBF may only correct the identified error(s) introduced by the original installation. EMERGENCY CHANGES TO SYSTEM LIBRARIES A description of what constitutes an emergency installation and the policies and procedures associated with installation are provided in MAB-057. PREPARING THE MSCR FORM At the same time this MAB is published, a revised Multics System Change Request (MSCR) will be made available. A sample of the revised form appears at the end of this MAB. The front of the MSCR form will have four lines located at the upper right corner. The top line, Installation #, indicates the Installation_id number associated with MSCR installation. The second line, Emergency ID #, indicates an Emergency Change and is used for tracking purposes. The third line, System ID #, references the system hardcore version in use at the time of installation. The fourth line, MR #, indicates the Multics Release for which the installation is targeted. The values associated with these fields will be filled in by the System Integration Project. The top left portion, lines two and three, require that the submitter indicate whether the installation is PLANNED or an EMERGENCY. The next line allows space to list approved MCRs associated with the submission. The remainder of the first page deals with general circumstances of the MSCR and its approval for submission. Section A identifies the Review Procedures associated with the installation (e.g., TCB, nonTCB, 3rd Party (No Audit), and the Installation Type (e.g., hardcore or online). At least one Review Procedure and one Installation Type must be indicated. It is possible that more than one Installation Type may be indicated. Review Procedures identifies the level of review and approval required to authorize an installation. A change to the TCB - 6 - Installing Planned Changes MAB-056-03 requires review and approval by the Security Coordinator while nonTCB does not. Some 3rd Party changes do not require Multics Development Center audit. Installation type indicates whether a new Multics System Tape (MST) is required. Therefore, changes to >sl1 or BOS would be hardcore because a new BOS tape or MST must be generated. Other changes, including MCS, would be online. Section B requires the developer to indicate whether the installation will provide a new feature, bug fix, post bug fix, or other such as a change in performance. Section C requires the developer to provide a summary of the change. This summary is used to generate text for online.changes.info or hardcore.changes.info. If the proposed installation resolves an outstanding Emergency Change, as described in MAB-057, the Emergency ID number of the earlier MSCR is provided as the first information in this section. If the installation is a PBF the original MSCR's MCR/Installation_id number must be the first item of information in this section. Section D indicates whether the attached installation involves changes to the header, bind files, error table, or gates. The developer supplies this information. Section E is to be used for special installation, or de-installation, instructions. An example would be when the proposed installation requires co-ordination between hardcore and online installation or installation during a special session. The developer supplies this information. Section F, Documentation, must be used to indicate whether the installation will require changes to Multics manuals, info segments, message-of-the-day (MOTD), pending_changes.info, or the Software Release Bulletin (SRB). A comprehensive discussion of SRB notices appears above. The developer supplies this information. Sections G through K require various approval signatures as described above. Signatures of the Submitter, Auditor, Documentation group, and Unit Manager must be obtained prior to submitting the MSCR to the Project Leader, Phoenix System Integration Project. Section L carries the signature of the installer and verifies that the installation of the associated changes have been completed in full compliance with procedures described in Multics Configuration Management: Procedures for Software Installation and Integration, MAB-067. - 7 - MAB-056-03 Installing Planned Changes SRB NOTICES Software Release Bulletin (SRB) notices are required for changes which: o Affect the Trusted Computer Base (TCB), o Introduce incompatible changes in new or modified segments, o Provide new user-visible commands or active functions, o Provide new subroutines or subroutine entry points, o Provide new control arguments and/or keywords for existing user-visible commands and/or active functions, o Provide new subsystem requests or features, o Provide new language features, o Provide support for new hardware, o Significantly change performance, o Significantly change reliability, or o Obsolete current user-visible software. MSCRs which provide for one or more changes identified in the above list must provide an SRB notice. Short notices may be provided in Section C, Summary of Changes or Emergency ID Number, on the MSCR face sheet. More extensive notices must be referenced by absolute pathname on Page 1 of the MSCR under Section F, Documentation. A hardcopy of the SRB notice must be attached to the MSCR. The SRB, as a release document, is not meant to replace standard manuals, the Software Installation Bulletin, or on-line documentation. Therefore, SRB notices should be concise and provide enough detail to reflect the significance of the change and, when appropriate, reference other sources, such as manuals or online info, for details. The SRB notice should be a concise action statement which identifies what specific portion of the system was affected, how it was affected (e.g., installed, changed, deleted, etc.), and why the action was taken. An example of such a notice would be: o Installed the describe_psp command to return information about products based on the marketing identifier. - 8 - Installing Planned Changes MAB-056-03 MSCR DETAIL SHEET Page 2 of the MSCR provides a detail sheet for the submission. Additional detail sheets are required for each bound segment involved. The first line of the detail sheet indicates the Library where the referenced bound, unbound, info segments, or include files are to be installed. A separate detail sheet is required for all free standing modules or for each bound unit | being installed in each system library (i.e., tools, standard, | sl1, sc1, unbundled, sl3p). A separate detail sheet is required | for each info directory (e.g., >doc>info, >doc>ss>operator, | >doc>ss>forum, >doc>privileged etc.) into which listed info | segments are to be placed. Include files associated with an | installation must appear on a separate detail sheet referencing | >ldd>include. | Three options exist where include files have been modified and the modules using them remain unchanged. The options are: - modules may appear on detail sheets with the recompile only (*) option described in the next paragraph. - a statement may appear on page 1 of the MSCR form which essentially states: "all source modules using modified include files associated with this installation may be safely recompiled". - a statement may appear on page 1 of the MSCR form which essentially states: "only the source modules identified on the attached detail sheets should be recompiled. The reason(s) other source modules which use the modified include file cannot be safely recompiled are [STATE REASON(S)]". Multiple free standing segments being installed in the same library may be written up on one detail sheet. Sections A through D provide detailed information needed to properly install the submitted changes. Section A requires that the developer indicate whether the referenced segment is bound or unbound and whether there has been a bind file change. Line two of this section provides space for the submitter to provide the bound/unbound segments executable name (e.g., bound_fscom2_) and indicate whether the segment is to be added (A), replaced (R), deleted (D), or recompile only (*) using a changed include file. Section B provides the absolute pathname of the developer's | software directory (see minimum access requirements above) and | the auditor's installation directory (see minimum access | requirements above) which contains all audited software listed in | Section C. | - 9 - MAB-056-03 Installing Planned Changes The absolute pathname provided should be the shortest possible (e.g., >t rather than >system_library_tools). All segments must be free standing. Use of archives is not permitted. Section C indicates source, bind file, include file, and info segment names for all segments associated with the particular detail sheet and the action to be taken on those segments. Acceptable actions and the associated symbols are: add the segment to the referenced bound segment (A); replace the segment in the referenced bound segment (R); delete the segment from the referenced bound segment (D); and re-compile the referenced segment using changed include files provided with the proposed installation (*). This section may also be used to identify source for unbound, exec_com, or ascii segments (e.g., free standing segments). The developer supplies this information. Section D is to be used for comments pertaining to that single detail sheet. Examples would be where supplied info segments need to be installed in the subsystem utility hierarchy, supplied source must be compiled using an include file listed on another detail sheet, or provide specific control arguments to be used in re-compiling a 'pmac' module. - 10 - MSCR CHECKLIST | The following checklist identifies frequently encountered problems and should be | used to determine the integrity and completeness of proposed submissions. Each | problem refers to an action which may be taken by the System Integration Project | when the problem is encountered. | Prepare Installation Checklist: | ____ Supplied segments must contain proper pnotices. (See 5 below.) | ____ Changed segments must contain history comments which have been created by | use of the history_comment command documented in MTB-716. (See 1 below.) | ____ Include for recompiling all segments which use changed include files. All | segments must re-compile and execute error free. The peruse_crossref | (pcref) command must be used to guarantee that all segments are referenced | on the MSCR. (See 3 below.) | ____ Provide tested bind file changes. (See 1 and 5 below.) | ____ Newly introduced free-standing segments have specific MCR Board approval. | (See 1 below.) | ____ All entry names must be placed on info and unbound segments. (See 4 | below.) | ____ Verify that the proposed installation will not introduce name duplications | in the libraries. (See 1 below.) | ____ Standard library software (e.g., >sss or >t) may not reference Priced | Software Products (PSPs). (See 1 below.) | ____ PSP software may not reference other PSP software except where authorized. | (See 1 below.) | ____ No archives may be used. Segments must be free-standing. (See 1 below.) | ____ All compiler installations must be capable of re-generating themselves | using the newly installed compiler version. (See 1 below.) | ____ Hardcore segments must contain proper system error message documentation as | described in MTB-335. (See 5 below.) | ____ Provide tested hardcore header changes and cpa when required. (See 5 | below.) | ____ Verify that check_mst runs without warning or error with proposed hardcore | changes. (See 1 below.) | Prepare Documentation Checklist: | ____ Attach the approved MCR with any associated amendments. (See 5 below.) | ____ Verify that all appropriate documentation, manual writeups, and info | segments, are attached to the MSCR. (See 5 below.) | ____ SRB notices must be provided when required as described above. (See 5 | below.) | ____ MOTD and pending_changes.info messages must be provided for incompatible | changes. (See 5 below.) | Developer Prepares MSCR: | ____ MSCR form must be legible. (See 1 below.) | ____ Developer must set appropriate access of s to directories r to segments for | the auditor. You can use dev_dir_acl.ec. (See 2 below.) | | ____ Developer must include path of his installation directory with the MSCR | package for the auditor (but NOT on the MSCR Detail Sheets!). (See 2 | below.) | ____ Document under "special instructions" any pending prerequisite or | co-requisite installations. If none exist write "NONE". (See 5 below.) | ____ Verify that all special comments and instructions are complete. (See 5 | below.) | Auditor Prepares MSCR: | ____ Auditor must assure all segments are free-standing. No archives may appear | in the audit installation directory. (See 1 below.) | ____ Auditor must assure that only modules listed on detail sheets remain in the | audit installation directory. | ____ Auditor copied all names on free-standing segments when creating the audit | installation directory. (See 4 below) | ____ All segments referenced by the MSCR must be available on System M. (See 1 | below.) | ____ Auditor must set appropriate access of s to directories and r to segments | for *.SysMaint. You can use aud_dir_acl.ec. (See 2 below.) | ____ Auditor must specify pathname on each MSCR Detail Sheet for all segments | being installed. Pathnames must be legible. (See 1 below.) | ____ Auditor must attach auditing checklists to MSCR package. (See 1 below.) | ____ Auditor must add audit history comment to new or modified bind files, | include files, and source modules. (See 1 below.) The System Integration Project is essentially a service organization but lacks resources to assume individual contributor responsibilities. The following actions are available to the System Integration Project as referenced in the above checklist. 1. The Installer will contact the developer; installation forms may be returned to the submitter. 2. Neither Auditor nor Installer will force access. Forgetting to provide the pathname and appropriate access delays the audit and installation. 3. All known segments will be checked and recompiled to the best ability of the Installer. In the event referenced segments fail to compile error free the installation will be returned to the submitter. 4. The Installer will add names where it is evident such names are required, otherwise the segment(s) will be installed without the add names. 5. The Installer will contact the developer when it is felt such required documentation has not been given. This may substantially delay the installation. Multics System Change Request Installation ID #________ [ ] PLANNED Change (See MAB-056) Emergency ID #________ [ ] EMERGENCY Change (See MAB-057) System ID #________ (Items marked * are optional for EMERGENCY Change) MR #________ MCR(s) #___________________________________________________________________ A. Review Procedure: [ ] TCB [ ] nonTCB [ ] 3rd Party (No Audit) Installation Type: [ ] Hardcore [ ] Online --At least one box per line must be checked-- B. [ ] New Feature [ ] Bug Fix [ ] Post Bug Fix (PBF) [ ] Other C. Summary of Change or Emergency ID number: ________________________________ _____________________________________________________________________________ _____________________________________________________________________________ _____________________________________________________________________________ _____________________________________________________________________________ D. Changes: [ ] Header [ ] Bind File [ ] Error Table [ ] Gate E. Special Installation/De-installation Instructions:________________________ _____________________________________________________________________________ _____________________________________________________________________________ * F. Documentation: [ ] Multics Manual [ ] Info Segment [ ] MOTD [ ] SRB [ ] pending_changes.info [ ] Other (specify): __________________________ __________________________________________________________________________ APPROVALS: G. Submittor: _________________________________________ Date: ____/____/____ H. Auditor: ___________________________________________ Date: ____/____/____ I. Security Coordinator: ______________________________ Date: ____/____/____ * J. Documentation: ___________________________________ Date: ____/____/____ K. Unit Manager: ______________________________________ Date: ____/____/____ L. Installed By: ______________________________________ Date: ____/____/____ See MAB-056 and MAB-057 for detailed instructions. Send Completed Forms to: Project Leader, Systems Integration, AZ05-T70 Library ________ Multics System Change Request Page ____ of ____ Detail Sheet A. [ ] Unbound segments, or A/R/D/* [ ] Bound segment, name: _______________________________________|______| [ ] Bindfile has changed (list under C below) | B. Developer/Auditor Directory Pathnames (all modified source, include | files, bind files, info segments, etc. must be free standing). | NO archives, bound archives, object modules, or extraneous segments. | Developer Dir:__________________________________________________________ | Auditor Dir:____________________________________________________________ C. System Segment Changes: Segment_name.suffix A/R/D/* Segment_name.suffix A/R/D/* ________________________________|___|_________________________________|___| ________________________________|___|_________________________________|___| ________________________________|___|_________________________________|___| ________________________________|___|_________________________________|___| ________________________________|___|_________________________________|___| ________________________________|___|_________________________________|___| ________________________________|___|_________________________________|___| ________________________________|___|_________________________________|___| ________________________________|___|_________________________________|___| ________________________________|___|_________________________________|___| ________________________________|___|_________________________________|___| ________________________________|___|_________________________________|___| ________________________________|___|_________________________________|___| D. Comments:_______________________________________________________________ ___________________________________________________________________________ ___________________________________________________________________________ ___________________________________________________________________________ ___________________________________________________________________________ * Indicates segments to be re-compiled only. See MAB-056 and MAB-057 for detailed instructions.