MULTICS DESIGN DOCUMENT MDD-008 To: MDD Distribution From: Ed Sharpe Date: July 1, 1985 Subject: Online Storage Volume Management Abstract: This MDD describes the management of Online Storage Volumes. Revisions: REVISION DATE AUTHOR initial 85-07-01 Ed Sharpe _________________________________________________________________ Multics Design Documents are the official design descriptions of the Multics Trusted Computing Base. They are internal documents, which may be released outside of Multics System Development only with the approval of the Director. i MDD-008 Online Storage Volume Management CONTENTS Page Section 1 Introduction . . . . . . . . . . . . . . 1-1 1.1 Organization of this Multics Design Document . . . . . . . . . . . 1-1 1.2 Goals of Volume Management . . . . 1-2 1.3 General Overview . . . . . . . . . 1-2 Section 2 Volume Registration . . . . . . . . . . . 2-1 2.1 Overview . . . . . . . . . . . . . 2-1 2.1.1 Logical/Physical Volumes . . 2-1 2.1.2 Public/Private Volumes . . . 2-2 2.1.3 Commands . . . . . . . . . . 2-2 2.2 Implementation Details . . . . . . 2-4 2.2.1 Databases . . . . . . . . . . 2-4 2.2.2 Database Operations . . . . . 2-7 2.2.3 Programs . . . . . . . . . . 2-7 Section 3 Volume Access Mounting/Demounting . . . . 3-1 3.1 Overview . . . . . . . . . . . . . 3-1 3.1.1 Mounting Public Volumes . . . 3-1 3.1.2 Mounting Private Volumes . . 3-1 3.1.3 Mounting Root Volume (RLV) . 3-2 3.1.4 Commands . . . . . . . . . . 3-2 3.2 Implementation Details . . . . . . 3-2 3.2.1 Databases . . . . . . . . . . 3-2 3.2.2 Database Operations . . . . . 3-2 3.2.3 Programs . . . . . . . . . . 3-2 Section 4 Volume Quota Management (Master Directory Control) . . . . . . . . . . . . . . . . 4-1 4.1 Overview . . . . . . . . . . . . . 4-1 4.1.1 Quota Accounts . . . . . . . 4-1 4.1.2 Master Directories . . . . . 4-2 4.1.3 User (Quota Administrator) Commands . . . . . . . . . . . . . 4-2 4.1.4 User (Volume Administrator) Commands . . . . . . . . . . . . . 4-3 4.1.5 System Administrator Commands 4-4 4.2 Implementation Details . . . . . . 4-5 4.2.1 Databases . . . . . . . . . . 4-5 4.2.2 Database Operations . . . . . 4-10 ii Online Storage Volume Management MDD-008 CONTENTS (cont) Page 4.2.3 Programs . . . . . . . . . . 4-10 Section 5 Security . . . . . . . . . . . . . . . . 5-1 5.1 Security - Volume Registration . . 5-1 5.2 Security - Volume Access . . . . . 5-2 5.3 Security - Volume Quota Management (Master Directory Control) . . . . . 5-2 Section 6 Scenarios . . . . . . . . . . . . . . . . 6-1 Section 7 Glossary . . . . . . . . . . . . . . . . 7-1 iii Online Storage Volume Management MDD-008 SECTION 1 INTRODUCTION This Multics Design Document describes the construction, modularization, operation, and interaction of those subsystems of the Multics supervisor which implement the management of online storage (disk) volumes. These subsystems are: Volume Registration This is the subsystem responsible for tracking all physical and logical volumes known to the system. Volume Access (Mounting/Demounting) This subsystem is responsible for mounting and demounting all pieces of a logical volume upon operator or user request. It interfaces with Volume Registration to determine the physical volumes involved and the user's access if necessary. Volume Quota Management (Master Directory Control) This subsystem called (Master Directory Control) is responsible for the allocation of logical volume storage space. The following subsystems are not described in this Multics Design Document: Disk IO Page Control Segment Control Directory Control Process Directory Volume Management Storage System Salvaging _1_._1 _O_R_G_A_N_I_Z_A_T_I_O_N _O_F _T_H_I_S _M_U_L_T_I_C_S _D_E_S_I_G_N _D_O_C_U_M_E_N_T This Multics Design Document has three major sections (2, 3, and 4) corresponding to the three subsystems summarized in the preceeding section. Each has two subsections: 1-1 MDD-008 Online Storage Volume Management Overview Implementation Details The Overview is intended to provide the reader with the functional requirements of the particular software subsystem. Implementation Details provides actual database organization, the operations performed on the databases, and the names and specific functions of each system program which supports the databases. Three other sections of this manual are: "5 - Security" which deals specifically with the security provisions of volume management; "6 - Scenarios" which gives 3 detailed code "walk-throughs"; and "7 - Glossary" which defines terms and names used in this manual and the related supervisor routines. _1_._2 _G_O_A_L_S _O_F _V_O_L_U_M_E _M_A_N_A_G_E_M_E_N_T A problem in any general purpose computing system is the management of storage medium. In the case of online storage, the more specific problem is in dealing with disk devices. In a minimal system, the solution may be to require the end-user to explicitly specify a symbolic identifier for the device as well as the name of the file on that device. The Multics solution, however, requires that the user need only provide a directory pathname of a desired file. The end user is not concerned with which device a particular file resides upon. Also, considering the number of users and size of online storage, system administrators need to modify the device configuration in a manner transparent to the users. Those functions are provided by the Volume Registration and Volume Access subsystems. Another problem is that of storage space administration. The fixed amount of space on disk medium must be monitored so that system administrators can keep the disk storage configuration consistant with the needs of the user community. Also, the space must be controlled to ensure fair allocation. Multics provides the Master Directory Control subsystem as a solution. _1_._3 _G_E_N_E_R_A_L _O_V_E_R_V_I_E_W Multics defines a _L_o_g_i_c_a_l _V_o_l_u_m_e (LV) as a collection of one or more _P_h_y_s_i_c_a_l _V_o_l_u_m_e_s (PVs). A PV is simply a disk medium device as defined by the interfacing hardware (e.g. a model 451 disk drive defines a disk pack as a single device or PV, a model 501 disk drive defines a spindle as two devices or PVs). PVs cannot be used individually, all PVs of an LV must be mounted to be accessible. The grouping of PVs into LVs allows higher level 1-2 Online Storage Volume Management MDD-008 mechanisms (e.g. Directory Control) to access the LV as one huge storage device. PVs may be added to an existing LV at any time without disruption of service. Also, PVs may be removed from an LV as long as they contain no data (PVs may be emptied during system service, the data is moved onto other PVs in the same LV). Each directory in the system is assigned an LV onto which all its segments will be stored. (The segment creation primitives will handle online storage allocation on the proper LV without user intervention.) In most cases the LV assignment of a directory is the same as that directory's parent directory. Thus, directory sub-hierarchies will store all their descendant segments on the same LV. This simplifies the administrative task of mapping hierarchy pieces onto the LV configuration. One special LV is the _R_o_o_t _L_o_g_i_c_a_l _V_o_l_u_m_e (RLV). It is always named "root". It contains at least one PV called the Root Physical Volume (PRV). The RLV has some special attributes. It is mounted during the early stages of system manipulation and cannot be demounted. It is the LV on which the actual directory segments reside. It contains all that is necessary to boot the system to ring-1 initializer command level. When a directory is assigned a logical volume different from that of its own parent directory, that directory is called a _m_a_s_t_e_r _d_i_r_e_c_t_o_r_y. Descendant directories of a master directory will have the same LV assigment as that master directory unless, they too, are master directories. The LV assigned any directory is called the directory's _s_o_n_s__l_v. In the hierarchy diagram below each directory is labeled with its sons_lv. The directories >udd, >udd>SysDaemon, and >ldd are master directories. 1-3 MDD-008 Online Storage Volume Management ________ | | sons_lv | root | = "root" |______| / | \_________________________ / \________ \ ________ \________ ________ | | sons_lv | | sons_lv | | sons_lv | >udd | = "public" | >sss | = "root" | >ldd | = "libs" |______| |______| |______| / \___________________ / \ _________________ \ | | sons_lv __________________ | >udd>UserProj | = "public" | | sons_lv |_______________| | >udd>SysDaemon | = "root" |________________| A typical site will maintain a "root" logical volume and a "public" logical volume (where "root" and "public" are names in this case. The "root" LV is used for system hierarchies such as >ldd, >sss, >tools, etc. The "public" LV is used for the hierarchy rooted at >user_dir_dir. (Two exceptions are >udd>SysDaemon and >udd>SysAdmin, which will be assigned to the "root" LV). Thus, every segment needed to run the system will reside on the "root" LV. All user created segments will reside on the "public" LV. The "root" LV is usually much smaller than the "public" LV. The site may use the system with "public" demounted (thus safe from accidental corruption) for "special sessions", etc. Each logical volume is assigned a _v_o_l_u_m_e _q_u_o_t_a value which reflects the amount of space available on that volume. This amount is dispersed among one or more _q_u_o_t_a _a_c_c_o_u_n_t_s managed by system or volume administrators. Quota accounts are used to assign storage space to master directories. The quota assigned to a master directory may be dispersed (once again) to its descendant directories. Thus, each directory on the system may be assigned a specific amount of space on an LV. (Note that this space is NOT reserved, it simply specifies an assigned space limit.) The databases used in volume management are: >lv>lv. (Ring 1 -- one per logical volume) >disk_table (Ring 1) logical volume table (lvt) (Ring 0) physical volume table (pvt) (Ring 0) >lv>lv_attach_table per-process lv_list (Ring 1 static in rcp_lv_) >lv>.modes (one per logical volume) 1-4 Online Storage Volume Management MDD-008 SECTION 2 VOLUME REGISTRATION This section describes the function and implementation of the subsystem contracted to handle the registration of logical volumes. _2_._1 _O_V_E_R_V_I_E_W The volume registration subsystem is responsible for the system's physical and logical volume configuration. It maintains a database which lists all the LVs and the PVs belonging to those LVs. It ensures integrity of the configuration and volume security. _2_._1_._1 _L_o_g_i_c_a_l_/_P_h_y_s_i_c_a_l _V_o_l_u_m_e_s When a _l_o_g_i_c_a_l _v_o_l_u_m_e is registered, it is assigned a set of attributes. These are: LV name LV unique identifier access class range volume owner ACS path When a _p_h_y_s_i_c_a_l _v_o_l_u_m_e is registered, it also is assigned a set of attributes. These are: PV name PV unique identifier device model device location medium serial number date registered A logical volume is registered with at least one physical volume. More PVs can be added to an LV as needed. Also, PVs may be deleted from an LV if all data has been vacated. If an LV has 2-1 MDD-008 Online Storage Volume Management a single PV that PV may not be deleted, the LV itself must be deleted. _2_._1_._2 _P_u_b_l_i_c_/_P_r_i_v_a_t_e _V_o_l_u_m_e_s A _p_u_b_l_i_c _l_o_g_i_c_a_l _v_o_l_u_m_e is one upon which any user may read/write segments as long as the proper access (ACL, AIM, rings) is set. The RLV is a public LV. Also, the typical site has an LV named "public" which is also a public LV. Public LVs are usually mounted during system service. The "owner" and "acs_path" attributes are not used for determining user access to public LVs. A _p_r_i_v_a_t_e _l_o_g_i_c_a_l _v_o_l_u_m_e is one which, in addition to the required ACL, AIM, and ring bracket settings, the user needs access to the volume itself. Also, a private LV is not usually mounted. It is mounted only when use of its contents is required. Any user who wishes to use a particular private LV must issue the "attach_lv" command. The ring-1 supervisor will check the user's access to the volume. If the user does not have the proper access the attachment will be aborted, and segments on the LV will remain inaccessible to that user's process. If it is determined that the user is authorized for the LV, attachment proceeds. If the LV is already mounted, the attachment occurs immediately and segment usage may proceed. If the LV is not mounted the ring-1 supervisor will make an operator request to mount all PVs in that LV. When operator intervention is complete user attachment to the LV may proceed. Private logical volumes are useful for several purposes. It allows further isolation of data from the general user community. Removable medium devices may be used for several LVs (at different times). Responsibility for space management on a private LV is removed from the system administrator and placed upon the private LV owner. In a private or public LV, the "owner" attribute specifies that user who controls the LV space and access. The "acs_path" field specifies the location of an access control segment. The ACL of this segment specifies the user access to the volume. The acs_path is usually located in the owners home directory. _2_._1_._3 _C_o_m_m_a_n_d_s This section describes the commands used in volume registration. The user must have access to the mdc_priv_ gate to use the non-operator commands described here. An incomplete syntax is supplied in some descriptions to add clarity. For detailed information see the Multics _A_d_m_i_n_i_s_t_r_a_t_i_v_e_, _M_a_i_n_t_e_n_a_n_c_e_, _a_n_d _O_p_e_r_a_t_i_o_n_s _C_o_m_m_a_n_d_s manual order number GB64. 2-2 Online Storage Volume Management MDD-008 add_volume_registration (avr) This is an administrative command used to register logical or physical volumes. It accepts arguments which specify attributes of the volume being registered. Its syntax is: avr -pv NAME {PV ATTRIBUTE ARGS}... ... -lv NAME {LV ATTRIBUTE ARGS} The "PV ATTRIBUTE ARGS" must include at least the device model. The "LV ATTRIBUTE ARGS" are specified only when registering a new LV. list_volume_registration (lvr) This is an administrative command which lists the attributes of the specified logical or physical volume. Its syntax is: lvr [-pv | -lv] NAME {-brief} When listing a logical volume, all physical volumes in that logical volume will be listed unless "-brief" is given. change_volume_registration (cvr) This is an administrative command which facilitates the adjustment of volume attributes. Its syntax is: cvr [-pv | -lv] NAME {PV or LV ATTRIBUTE ARGS} Some volume attributes should not be changed when the physical disk medium has already been initialized. This is because some attributes (e.g. access class, name, and unique identifier) are written onto the medium label at initialization and cannot be altered without re-initialization of the medium. delete_volume_registration (dvr) This is an administrative command used to remove the registration of a logical or physical volume. Its syntax is: dvr [-lv | -pv] NAME Physical volumes should only be deregistered when their contents have been moved onto other physical volumes (within the same logical volume). Logical volumes should only be deregistered when their corresponding directory hierearchies have been removed from the system (thus leaving the whole LV empty). Since a logical volume must always have at least one physical volume, the last PV in an LV may not be deleted from the LV, the LV itself must be deleted. init_vol This is an operator command used to initialize a physical volume. As well as setting up the volume table of contents 2-3 MDD-008 Online Storage Volume Management (VTOC), etc, it also sets up the volume label which contains from the volume registration data: the access class, the PV name, the LV name, a unique PV identifier (PVID), and a unique LV identifier (LVID). Once these fields are written to the volume, they cannot be changed except through re-initialization. reregister This is an operator command used to recreate the online registration data for a physical volume. It is useful in cases where the registration database has been damaged due to system failure. It reads the PV/LV name and unique identifiers from the volume label and attempts to recreate the proper database entries. _2_._2 _I_M_P_L_E_M_E_N_T_A_T_I_O_N _D_E_T_A_I_L_S This section describes the specifics of the supervisor programs and databases that constitute the Volume Registration Management subsystem. It is broken into three pieces: 1) Databases - which describes the data maintained by the subsystem and presents the data declaration include files; 2) Database Operations - which describes what primitive operations are performed on the data and at what times they're performed; and 3) Programs - which describes the actual supervisor modules and their entrypoints. _2_._2_._1 _D_a_t_a_b_a_s_e_s The volume registration database is maintained in the directory ">lv". A separate ring-1 segment of data is used for each logical volume. The primary name of the segment is "lv.LVNAME". The structure of the data in the segment is described by the include file "volume_registration.incl.pl1" which is similar to: /* BEGIN INCLUDE FILE ... volume_registration.incl.pl1 */ dcl 1 volume_registration aligned based (vrp), 2 version fixed bin init (2), /* Version number of this dcl */ 2 lvid bit (36), /* Logical volume unique ID */ 2 lvname char (32), /* Logical volume name */ 2 access_class (2) bit (72), /* Minimum/Maximum AIM class */ 2 volume_owner char (32), /* Person.Project */ 2 acs_path char (168), 2-4 Online Storage Volume Management MDD-008 /* Path name of ACS */ 2 flags, 3 public bit (1) unal, /* TRUE if public volume */ 3 pad bit (35) unal, /* unused flags... */ 2 npv fixed bin, /* Number of physical volumes */ 2 pv (volume_registration.npv /* PV registration array */ refer (volume_registration.npv)) like pv_registration; dcl 1 pv_registration aligned based (pvrp), 2 pvid bit (36), /* Physical volume unique ID */ 2 model fixed bin, /* Model number */ 2 pvname char (32), /* Physical volume name */ 2 location char (32), /* Where to find volume */ 2 mfg_serial char (32), /* Manufacturer's serial no. */ 2 date_registered fixed bin (71), /* Date and time registered */ 2 password bit (2); /* not used */ /* END INCLUDE FILE ... volume_registration.incl.pl1 */ Explanation of structure components: version is simply a fixed number representing the version of the database structure. lvid is a bit string identifier for the logical volume. It is unique from all other volume identifiers in a particular system. It is used in internal references to an LV. lvname is a character string name of the logical volume assigned by the system administrators. All command arguments use this to identify the LV. access_class specifies an access class range for private logical volumes. Users outside this range cannot attach the volume regardless of whether the user is the owner or has full access to the ACS 2-5 MDD-008 Online Storage Volume Management volume_owner is the Person_ID.Project_ID of the volume owner. This user has access to change volume quota, create master directories, give other users access (in the case of private volumes), etc. acs_path specifies the pathname of an access control segment for private logical volumes. Typically the ACS is in >lv or the owner's home directory. flags.public specifies that the volume is public and need not be explicitly attached for access. npv specifies the number of physical volumes that belong to the LV. This number will always be 1 or greater. pv is an array of pv_registration structures. There is one active entry for each PV belonging to the LV. The entries are contiguous, that is, there are no "inactive" entries between entries 1 and npv. pvid like lvid is a unique bit string which identifies the PV to internal supervisor modules. The pvid is written into the label of the corresponding physical disk device. model is the model number (index) of the physical disk device corresponding to the PV. location is the location of the physical disk device corresponding to the PV. It is of the form "DISK-SUBSYSTEM_DEVICE-NO" (e.g. dska_10). This field is not actually used by the supervisor modules but may be set by the system administrators to track PV location. mfg_serial is a field used by the system administrators to note the serial number of the physical device. It is not used by the system supervisor modules. date_registered is a binary date-time value specifying when the PV was registered. password is not used. 2-6 Online Storage Volume Management MDD-008 There are a number of addnames on each volume registration data segment. The first addname corresponds to the logical volume unique identifier (LVID). It is of the form: "lvid.[unique]" where "[unique]" is a string of letters derived from the LVID bit string. The rest of the addnames correspond to each physical volume name and unique identifier (PVID) which belong to that LV. The addnames are of the form: "pv.PVNAME" and "pvid.[unique]". These addnames allow an entry to be quickly located by PV or LV name or unique identifier (no need to search every registration data segment). _2_._2_._2 _D_a_t_a_b_a_s_e _O_p_e_r_a_t_i_o_n_s The operations that may be performed upon the volume registration database are: ox Add registration data for a new LV and its single PV. ox Add registration data for a new PV into an existing LV. ox Extract the registration data for an LV and all its PVs. ox Extract the registration data for a single PV. ox Modify registered attributes of an LV. ox Modify registered attributes of a PV. ox Remove the registration for an LV and all its PVs. ox Remove the registration for a PV. ox Find the name of an LV given the LVID. ox Find the name of a PV given the PVID. ox Determine the access of a given private LV. ox Reregister a LV or PV based on information from the disk_table. _2_._2_._3 _P_r_o_g_r_a_m_s The two modules which support the volume registration database are: volume_registration_cmds_ implements the ring-4 administrative commands avr, lvr, cvr, and dvr. volume_registration_mgr_ implements the ring-1 primitives for database manipulation. Its main caller is volume_registration_cmds_ via the mdc_priv_ gate. It is also called by mdx, mdc_repair_, mdcs_util_, rcp_attach_lv_, and countervalidate_label_ for information retrieval. The entrypoints to volume_registration_cmds_ simply correspond to the four administrative commands. They build registration data 2-7 MDD-008 Online Storage Volume Management structures according to control arguments supplied on the command line. The structures are then passed to volume_registration_mgr_ for final validation and inclusion in the database. The entrypoints of volume_registration_mgr_ are described separately in the following paragraphs: init This entry is called at system initialization time by mdx$init (which is invoked by disk_table_$init just prior to ring-1 initializer command level). This "init" entry simply sets up its lock segment ">sl1>vrm_data", and calls mdc_init_ (which simply sets up the lock segment for Master Directory Control). read_lvr Reads the LV registration data, including the data for all PVs belonging to that LV, into a place provided by the caller. The caller supplies the PV name. read_pvr Reads the PV registration data for a single PV into a place provided by the caller. The caller supplies the PV name. add_lvr Adds a new registration data segment to the volume registration database. The caller provides a volume_registration structure containing the LV attributes and the attributes for a single PV. The structure is the same as that used for the ring-1 data segment. If all validation passes, the caller's structure is copied into a new segment named "lv.LVNAME". Three addnames are added to the segment corresponding to the LVID, PVNAME, and PVID. The Master Directory Control entry "create_mdcs" is called to create its data segment which corresponds to the LV registratoin data segment. add_pvr This entry adds the registration data for a single PV to an existing LV registration data segment. If all attributes in the given pv_registration structure are valid, it is added to the end of the "pv" array in the LV data segment. Two addnames are appended to the LV registration data segment entry corresponding to the PV name and PVID. delete_lvr This entry deletes the registration data segment for the given LV. The Master Directory Control entry "delete_mdcs" is called to delete its data segment which corresponds to the deleted LV registration data segment. delete_pvr This entry deletes the registration data for a single PV. The 2-8 Online Storage Volume Management MDD-008 two addnames corresponding to the PV are removed from the LV registration data segment. The "pv" array is compressed so that the remaining active entries are contiguous. change_lvr This entry changes selected attributes of an LV. The caller supplies a volume_registration structure with no "pv" array entries. All attributes are validated before any changes are made. Changes to the LV name or LVID are propagated to Master Directory Control through a call to its entries "update_hvid" and "rename_mdcs". Also, changes to the LV name or LVID make it necessary to change the LV registration data segment names. change_pvr This entry changes selected attributes of a PV. The caller supplies a pv_registration structure with all members initialized. All attributes are validated before any changes are made. If the LV name or LVID changes it is necessary to also change the corresponding names on the LV registration data segment. pvname_info This entry returns the PVID, LV name, LVID, and device type (model index) for a given PV name. find_lvid This entry returns the LVID for a given LV name. find_volname This entry returns the PV name and LV name for a given PVID. find_lvname This entry returns the LV name for a given LVID. get_access This entry computes the callers access mode to a given LV. The code first checks the AIM access range and RCP_PRIVILEGE. If neither of these are acceptable, the mode returned is "null". Otherwise, the access will be computed from the ACS. If no acs_path is registered, or if the ACS itself is missing, the access returned is "REW" for the owner, "null" for all others. lvname_info This entry returns a specialized structure of information on all PVs belonging to a given LV name. get_lv_pvinfo This entry has the same function as "lvname_info". In addition it will return the index of the corresponding LV disk_table entry. If there is no corresponding disk table LV entry, it will be created. 2-9 MDD-008 Online Storage Volume Management find This entry will create an LV disk table entry given an index to a disk table PV entry. The LV entry will correspond to the LV of the given PV. check_volume_registration This entry is called during system initialization to validate/re-create the volume registration database. "mdx$init" (which had previously called our "init" entry) scans the old disk table and calls here for each entry that had a valid drive mounted in the previous session. This is evidence that the PV should have a valid registration. On the first call this entry will create ">lv" if necessary (i.e. if its a new system or was booted with NOLV). The disk table PV entry is checked to determine that it points to a valid disk table LV entry. If not, the disk table LV entry is recreated from the PV's LV registration data. If the LV registration can't be determined, nothing more can be done but issue a console message. If the disk table does contain a valid LV entry for the PV in question it is compared to the LV registration data. If the LV registration disagrees with the disk table entry, or can't be found, it is recreated. (Thus, the disk table is the more trusted database.) Calls will be made to mdc_repair_$recreate_mdcs to check the Master Directory Control database for each LV, and create it if necessary. If the PV registration data disagrees with the disk table PV entry, the registration data is "fixed" to be the same. If the PV registration doesn't exist in the LV registration data segment, it is recreated there. Note that registration of the root logical volume (RLV) is created by this entrypoint upon a cold boot of the hierarchy. The volumes registered will be those specified on the "ROOT" configuration card (which are accepted by the Volume Access subsystem regardless of the registration). This entry also ensures that all proper addnames are in place. 2-10 Online Storage Volume Management MDD-008 SECTION 3 VOLUME ACCESS MOUNTING/DEMOUNTING This section is not yet written because the code needs rewriting. The modules involved are: mdx, wdx, lv_request_, lv_request_communicator_, pvt_init, disk_table_, logical_volume_manager, private_logical_volume, mountedp, rcp_lv_, rcp_attach_lv_, rcp_detach_lv_, attach_lv, detach_lv, rcp_check_attach_lv_, lv_attached, init_disk_pack_, countervalidate_label_ etc. This section describes the function and implementation of the subsystem contracted to handling the mounting and demounting of logical volumes. _3_._1 _O_V_E_R_V_I_E_W This section will provide an overview of what's need to mount a volume. i.e. - all PVs mounted, everything registered consistantly, etc. _3_._1_._1 _M_o_u_n_t_i_n_g _P_u_b_l_i_c _V_o_l_u_m_e_s This section will be an overview of the steps taken in getting a public volume mounted and accessible. This is assumed to be the "normal" case. The operator has full control over what public volumes are mounted. _3_._1_._2 _M_o_u_n_t_i_n_g _P_r_i_v_a_t_e _V_o_l_u_m_e_s This section will be an overview of the steps taken in getting a private volume mounted and accessible. The operator may mount a private volume in response to user request. The user's access to the volume is checked before the request is made by rcp_attach_lv_ (via the attach_lv command). 3-1 MDD-008 Online Storage Volume Management _3_._1_._3 _M_o_u_n_t_i_n_g _R_o_o_t _V_o_l_u_m_e _(_R_L_V_) This section will overview the special case of mounting the RLV. It is done during system initialization under control of the "ROOT" configuration card. _3_._1_._4 _C_o_m_m_a_n_d_s This section will briefly describe each user/operator/administrator command used in or related to mounting volumes . _3_._2 _I_M_P_L_E_M_E_N_T_A_T_I_O_N _D_E_T_A_I_L_S This section describes the specifics of the supervisor programs and databases that constitute the volume mounting subsystem. It is broken into three pieces: 1. Databases - which describes the data maintained by the subsystem and presents the data declaration include files. 2. Database Operations - which describes what primitive operations are performed on the data and at what times they're performed. 3. Programs - which describes the actual supervisor modules and their entrypoints. _3_._2_._1 _D_a_t_a_b_a_s_e_s Will describe the disk_table, LVT, PVT, lv_attach_table, per-process lv_list, etc. _3_._2_._2 _D_a_t_a_b_a_s_e _O_p_e_r_a_t_i_o_n_s Will describe the primitive operations performed on the databases. _3_._2_._3 _P_r_o_g_r_a_m_s Will describe the actual entrypoints in mdx, wdx, lv_attach, disk_table_, lv_request_, etc. 3-2 Online Storage Volume Management MDD-008 SECTION 4 VOLUME QUOTA MANAGEMENT (MASTER DIRECTORY CONTROL) This section describes the function and implementation of the subsystem contracted to handle the management of logical volume space (Master Directory Control). It describes the databases and programs which deal with "volume quota". It does not describe segment or directory quota. These are described in the Multics Programmer's Reference Guide. _4_._1 _O_V_E_R_V_I_E_W Each logical volume registrated on a system is assigned a _v_o_l_u_m_e _q_u_o_t_a which sets an upper limit on the number of records (1 record = 1024 36 bit words) which may be allocated on that volume. This quota limit is dispersed among one or more _q_u_o_t_a _a_c_c_o_u_n_t_s by the _v_o_l_u_m_e _a_d_m_i_n_i_s_t_r_a_t_o_r (volume owner). In order to make the quota in an account useable, it must be dispersed into _m_a_s_t_e_r _d_i_r_e_c_t_o_r_i_e_s of the logical volume. Quota accounts, master directories, and related commands are described in the next sections. _4_._1_._1 _Q_u_o_t_a _A_c_c_o_u_n_t_s As already stated, each logical volume registered on the system is assigned volume quota (in one or more quota accounts). This is simply the total number of records (1024 X 36-bits) available for paging on the physical volumes contained in that LV. The value is calculated manually and set by the volume administrator via the command "set_volume_quota". The total volume quota assigned to the quota accounts should be adjusted as PVs are added or deleted from the LV. (The logical volume space may be displayed using the command "list_vols {LV_NAME} -tt" for mounted volumes). The task of assigning quota to master directories may be delegated to other system users via the quota accounts. A _q_u_o_t_a _a_d_m_i_n_i_s_t_r_a_t_o_r is a user who is given this privilege (REW access to volume ACS). The volume administrator will set up a separate 4-1 MDD-008 Online Storage Volume Management quota account for each quota administrator. The quota administrator may create master directories on the LV and assign a specified portion of the quota in his/her account. Quota in a master directory may by changed using the "set_mdir_quota" command. Note: Volume quota is meant to represent the actual available space on the logical volume. However, due to the dynamics of user storage, volume administrators sometimes will over-represent the space with a high quota value to attain better disk utilization. (Example: If users tend to use 50% of their allocated space, and volume quota correctly reflects the actual disk capacity, the disks are 50% utilized. If however, the volume administrator over-represents the capacity by 50%, the utilization is then 75%). The volume administrator must ensure that proper controls and monitoring procedures are in place to avoid logical volume overflow. Thus, site system administrators should delegate volume administration to only trusted personnel. A possible use of quota accounts at a site is to allocate a quota account for each department head. The department head would then allocate quota among the department's projects as necessary. The individual project administrators would not have to contact the system administrator. _4_._1_._2 _M_a_s_t_e_r _D_i_r_e_c_t_o_r_i_e_s A _m_a_s_t_e_r _d_i_r_e_c_t_o_r_y is a directory where the _s_o_n_s _l_o_g_i_c_a_l _v_o_l_u_m_e is specified at creation time. A normal directory gets this attribute from its parent. The "sons logical volume" specifies where descendant segments of the directory will reside. Another difference is that segment quota for a master directory is drawn from a volume quota account rather than from its parent. (Note that a master directory may have the same sons logical volume as its parent.) Quota from a master directory can be moved to descendant directories. This allows the space to be allocated in small useful amounts. A possible use of master directories at a site is to make each project directory a master directory. The segments under that project will reside on the given logical volume and the quota drawn from one of the associated quota accounts. If one logical volume is out of service, only those projects whose segments reside on that volume will be affected. 4-2 Online Storage Volume Management MDD-008 _4_._1_._3 _U_s_e_r _(_Q_u_o_t_a _A_d_m_i_n_i_s_t_r_a_t_o_r_) _C_o_m_m_a_n_d_s This section describes those commands which may be used by a user who has access to a quota account. That is, a quota account whose name is the same as the user's PersonID.ProjectID. An asterisk ("*") may appear in either component of an account name to match any PersonID or ProjectID. An incomplete syntax is given for some commands to simplify the description. create_dir PATH -logical_volume LVNAME -quota N This is a normal Multics user command except when used with the "-logical_volume" control argument. The use of that argument causes the created directory to be a master directory where the sons logical volume is set to LVNAME. Also, the initial quota (which must be specified with "-logical_volume") is drawn from the user's quota account rather than from the parent directory. (The user MUST have a quota account on the specified LV). The user is said to be the "owner" of the master directory. list_mdir This command lists all master directories which the user created on the specified LV. set_mdir_quota This command allows the owner of a master directory to move quota between a specified master directory and his/her quota account. _4_._1_._4 _U_s_e_r _(_V_o_l_u_m_e _A_d_m_i_n_i_s_t_r_a_t_o_r_) _C_o_m_m_a_n_d_s This section describes the commands available to a volume administrator (any user with executive (E) access to the LV ACS or the owner). The quota administrator commands are also available (the list_mdir command is described in this section again because it gives more information to the volume administrator). An incomplete syntax is given for some commands to simplify the description. create_dir PATH -lv LVNAME -quota N -acct ACCT_ID -ow USER_ID This is a normal Multics user command except when used with the "-logical_volume" control argument. The use of that argument causes the created directory to be a master directory where the sons logical volume is set to LVNAME. Also, the initial quota (which must be specified with "-logical_volume") is drawn from the given quota account rather than from the parent directory. Volume administrators may also specify the owner of the master directory (must be supplied if the specified account has a star component). 4-3 MDD-008 Online Storage Volume Management set_volume_quota LVNAME (+-)N ACCOUNT This command is used to setup or change a quota account. The ACCOUNT is the Person_ID.Project_ID of the desired quota administrator. (The Person_ID or Project_ID may be specified as "*" to indicate matching as in access control lists. This specifies that the account belongs to a group of users.) delete_volume_quota LVNAME ACCOUNT This command is used to remove the specified quota account. All master directories where the quota is drawn from the account must have been deleted or transferred to another account. set_mdir_account PATH ACCOUNT Changes the account from which quota for the specified master directory is drawn. The quota consumed by that directory is moved between the accounts. set_mdir_owner PATH USER_ID Changes the owner of the specified master directory. list_mdir Lists master directory and quota information. The information can be retrieved for specified accounts, master directory owners, or both. _4_._1_._5 _S_y_s_t_e_m _A_d_m_i_n_i_s_t_r_a_t_o_r _C_o_m_m_a_n_d_s This section describes the commands available to the system administrator (who has access to the mdc_priv_ gate). Of course, the commands listed for the quota and volume administrators are also available to the system administrator (if proper access is set). An incomplete syntax is given for some commands to simplify the description. change_volume_registration -lv LVNAME ... ... -owner USER_ID -acs_path PATH This command was described in section 2 "Volume Registration". However, the example above illustrates those registration fields which determine who can manipulate the volume quota. By default, the owner of a new logical volume is the administrator who registered it. The ACS path is null. The system administrator may change the volume owner at any time. The volume owner is the primary volume administrator. Additional administrators are specified by the ACS (those who have at least "e" access to the ACS). Any volume administrator may alter the volume quota accounts. The ACS should be kept under the system administrator's or volume owner's control to prevent unauthorized access to the volume space. 4-4 Online Storage Volume Management MDD-008 register_mdir This command is used for repair of the MDC databases when master directory information has been lost due to a system failure or boot with "NOLV". A specified master directory, or all the master directories in a subtree are registered in the database corresponding to the proper logical volume. However, they're registered into the quota account for Initializer.SysDaemon. (Volume administrators must use "set_mdir_owner" and "set_mdir_account" to adjust back to the desired values.) check_mdcs This command runs a salvager over the MDC database for the specified logical volume. It ensures consistancy of that database, correcting quotas, etc. set_quota This command is used to fix quota values in directories. Although not directly related to volume quota, it is listed here because its use can make quota accounts inconsistant. _4_._2 _I_M_P_L_E_M_E_N_T_A_T_I_O_N _D_E_T_A_I_L_S The following sections describe the supervisor programs which implement _M_a_s_t_e_r _D_i_r_e_c_t_o_r_y _C_o_n_t_r_o_l (MDC) which also maintains the volume quota facilities. It is broken into three pieces (Databases, Database Operations, and Programs) as in Section 2. _4_._2_._1 _D_a_t_a_b_a_s_e_s The MDC database is maintained in the directory ">lv". A separate ring-1 segment of data is used for each logical volume. the name of each segment is "LVNAME.mdcs. The structure of the data in each segment is described in "mdcs.incl.pl1" which is similar to: /* Begin include file ..... mdcs.incl.pl1 */ dcl 1 mdcs aligned based (mdcsp), /* A master directory control segment */ 2 head like mdcs_head, /* First the header */ 2 area area (0 refer (mdcs.area_size)); /* Followed by an area for allocating data */ dcl 1 mdcs_head aligned based, /* The header portion of the mdcs */ 2 version fixed bin, /* Version of structure */ 4-5 MDD-008 Online Storage Volume Management 2 init bit (1) unal, /* Set when mdcs created */ 2 free_bits bit (35) unal, /* unused space */ 2 time_checked fixed bin (71), /* Time last checked for consistency */ 2 volume char (32), /* Name of volume */ 2 uid bit (36), /* Unique id of volume (LVID) */ 2 acct_offset bit (18), /* Offset to first account entry */ 2 dir_offset bit (18), /* Pointer to first directory entry */ 2 backup (3) fixed bin (35), /* Statistics for backup */ 2 area_size fixed bin (18), /* Size of the area (rest of segment) */ 2 restrict_path bit (18), /* List of paths in volume restict list */ 2 default_path bit (18), /* List of paths in volume default list */ 2 fill (43) bit (36) aligned; /* Pad to octal 100 */ dcl 1 mdirent aligned based (mdirp), /* Master directory registration entry */ 2 next bit (18) unal, /* Pointer to next entry */ 2 fill bit (18) unal, /* unused space */ 2 uidpath (0:15) bit (36), /* Uid pathname of master dir */ 2 owner, /* Owner of directory */ 3 person char (22) unal, 3 project char (9) unal, 2 quota_offset bit (18), /* Rel pointer to quota account */ 2 quota fixed bin (18), /* The quota */ 2 backup (3) fixed bin (35), /* Statistics for backup */ 2 fill2 (10) bit (36) aligned; /* unused space */ dcl 1 acctent aligned based (acctp), /* Quota Account registration data */ 2 next bit (18) unal, /* Relative pointer to next entry */ 2 fill bit (18) unal, 4-6 Online Storage Volume Management MDD-008 /* unused space */ 2 name, /* Name of quota account (User_ID) */ 3 person char (22) unal, 3 project char (9) unal, 2 quota fixed bin (35), /* Total quota for account */ 2 quota_used fixed bin (35), /* quota assigned to master dirs */ 2 trp fixed bin (71) unal, /* Time record product for deleted dirs */ 2 backup (3) fixed bin (35), /* Backup accounting data */ 2 restrict_path bit (18), /* List of restricting paths for account */ 2 fill2 (7) bit (36) aligned; /* unused space */ dcl 1 pathent aligned based (pathp), /* Entry in a list of pathnames */ 2 next bit (18) unal, 2 fill bit (18) unal, 2 uidpath (0:15) bit (36); /* End include file ..... mdcs.incl.pl1 */ Explanation of structure components: The database segment is arranged as a header structure located at offset 0, and an area which contains chains of "acctent", "mdirent", and "pathent" structures. MDCS_HEAD occurs once in each MDC database segment and contains global information. version is simply a fixed number representing the version of the database structure. init Specifies whether the database is ready to use. (not sure why it's needed since there's a global MDC lock...) time_checked Is the time last checked for consistancy. If it's less than the last bootload, an automatic check will be performed. volume Is the name of the volume with which this MDC database segment is associated. It is the sons logical volume for all master directories registered in this particular segment. 4-7 MDD-008 Online Storage Volume Management uid Is the unique ID (LVID) of the logical volume. It is used for consistancy checks. acct_offset Anchors the chain of "acctent" entries (i.e. the quota accounts). dir_offset Anchors the chain of "dirent" entries (i.e. the list of master directories). backup This field is not currently used. It apparently was meant to keep arbitrary statistics for one of the system dumpers. area_size Is simply the size of the segment minus the size of this header. restrict_path Anchors a chain of "pathent" entries. In light of the "default_path" field described just below, there is no apparent use for this field. There is inner-ring code to set it, but none pays it any attention (except check_mdcs_). There is no command interface to set this field. default_path Anchors a chain of "pathent" entries which force any master directory created (for this volume) to match the first "n" entries in its pathname. (e.g. the volume administrator could force quota administrators to keep all master directory creations under >udd>Proj>pool). This chain is used if no "restrict_path" chain exists in the specific "acctent" entry. MDIRENT contains data describing one master directory. There is one chain of these entries in each MDC database segment. Specifies the next entry in the chain. uidpath Is the UID pathname of the master directory. Text pathnames are not maintained. owner Is the user who created the master directory or to who it is assigned by the volume administrator. The user must have access to one of the quota accounts. The quota is drawn from that account. 4-8 Online Storage Volume Management MDD-008 quota_offset Is a relative pointer to the "acctent" entry from which quota for this master directory is drawn. quota Is the quota assigned to this master directory. backup This field is not currently used. It apparently was meant to keep arbitrary statistics for one of the system dumpers. ACCTENT contains data describing one quota account for the volume. There is one chain of these entries in each MDC database segment. next Specifies the next entry in the "acctent" chain. name Is the group id which has access to this quota account. If may be of the form Person.Project, or Person.* or *.Project where "*" matches user ids as in an ACL. quota Is the total quota assigned to the account. quota_used Is the quota which has been assigned to existing master directories. trp Is the Time-Record-Product from deleted master directories to be used in the next billing cycle. backup This field is not currently used. It apparently was meant to keep arbitrary statistics for one of the system dumpers. restrict_path Anchors a chain of "pathent" entries. These paths specify the subtree which is the only place that users (with access to the account) may create master directories. The allows the volume administrator to keep master directories within a managable portion of the hierarchy (where he/she has access, for instance). If the restrict_path does not exist in the acctent entry, the "default_path" chain anchored in the mdcs_head serves the same purpose. Unfortunately there is currently no command interface to set these path chains. PATHENT contains the UID pathname of a default or restricted path. These entries are chained together in multiple lists anchored in the ACCTENT or the MDCS_HEAD. 4-9 MDD-008 Online Storage Volume Management next Specifies the next entry in this chain. uidpath Is the UID path of directory entries. Text pathnames are not maintained. Chains of these entries are anchored at "mdcs_head.restrict_path", "mdcs_head.default_path", and "acctent.restrict_path". _4_._2_._2 _D_a_t_a_b_a_s_e _O_p_e_r_a_t_i_o_n_s The operations that may be performed upon the MDC database are: ox Add database segment corresponding to an LV. ox Remove database segment. ox Add a quota account. ox Remove a quota account. ox Add a master directory entry. ox Remove a master directory entry. ox Extract header/ account/ directory information. ox Adjust fields in the MDCS header, quota account, or master directory entries. ox Set restrict path lists ox Validate MDCS database segments _4_._2_._3 _P_r_o_g_r_a_m_s There are two main bound units related to MDC. "bound_mdir_commands_" implements the command routines and is basically uninteresting (they parse arguments and call the inner ring). "bound_mdir_control" implements the inner ring functions and contains the following modules: mdc_init_ This routine is called by volume_registration_$init (which itself was called by mdx$init) during system initialization. mdc_init_ simply calls mdc_lock_$mdc_data_init to set up the global database lock segment ">sl1>mdc_data". mdc_create_$(dir dirx dirx_acct) This routine creates a master directory and registers it in the MDC database segment. It has an entry which supplies branch creation information in the arguments (mdc_create_$dir), one that supplies the information in a structure (mdc_create_$dirx), and one that supplies, in addition to the structure, account and owner information (mdc_create_$dirx_acct). The "dirx_acct" entry is called from the "create_dir" user command and the "new_proj" administrative command. The "dir" and "dirx" entries are used 4-10 Online Storage Volume Management MDD-008 by no system routine, they are retained for compatability purposes. Its general control flow is: entry copy args set up create_branch_info structure lock database locate proper database segment find quota account for this user verify new mdir path against one of: account restrict path list volume default path list check for sufficient quota in account set up mdir registration entry (mdirent) create the directory thread mdirent into database segment cleanup exit mdc_create_$delete This routine removes a master directory from the storage system along with its registration. It is called from the "delete_" system subroutine (called by the "delete" user command). Its general flow is: entry copy args get directory status info lock MDC database locate proper database segment if database missing then delete the master directory else find the registration entry move directory's quota back to account delete the master directory remove the mdir registration entry update the Time-Record-Product in the account cleanup exit mdc_set_ This module is used to set various fields in the mdirent and acctent entries. It has the following entrypoints: mdc_set_$volume_quota Sets/changes the quota available in a quota account. If the account doesn't exist, it will be created (depending upon a switch given as an argument). This entry is called from the "set_volume_quota" command. The user must be a volume administrator (i.e. have at least "e" access to the volume). 4-11 MDD-008 Online Storage Volume Management mdc_set_$delete_volume_quota Removes a quota account after verifying that no master directories exist which draw their quota from it. This entry is called from the "delete_volume_quota" command. The user must be a volume administrator. mdc_set_$mdir_owner Sets the registered owner of a master directory (in the mdirent). This entry is called from the "set_mdir_owner" command. The calling user must be a volume administrator. mdc_set_$mdir_quota Changes the registered master directory quota (in the mdirent) and the account from which it draws the quota. This entry is called from the "set_mdir_quota" command. The calling user must be a volume administrator or a quota administrator for the account from which the master directory draws quota. mdc_set_$mdir_account Changes the quota account from which a master directory draws quota. The current quota value for the directory is moved from the new account to the old account. This entry is called from the "set_mdir_account" command. The calling user must be a volume administrator. mdc_set_$dmpr_usage Updates the backup statistics for a given master directory with a given increment. The values in the mdcs_head, mdirent, and acctent are all updated. This entry is currently not used by any system routines. This entry may be called only by privileged processes. mdc_set_path_$volume_default mdc_set_path_$volume_restrict mdc_set_path_$account_restrict These three routines setup entries to the "pathent" chains anchored at mdcs_head.default_path, mdcs_head.restrict_path, and acctent.restrict_path respectively. Most of the work is done by the internal procedure "path_adjust". The calling user must be a volume administrator. mdc_status_ mdc_status_$list This module returns account and master directory information to the caller. Volume administrators are given more information than quota administrators who are given more information that miscellaneous users. This entry is called from the "list_mdir" command. Although the module is structured in a number of internal procedures, its general control flow is: 4-12 Online Storage Volume Management MDD-008 entry copy args locate database segment and check if this is a volume administrator setup information return structure if caller is not a volume administrator then if caller is a quota administrator then setup account info in return struct if account has restrict paths then setup account restrict path info in return struct else setup volume restrict path info in return struct /* following for misc users & quota admins */ setup owner info in return struct for every registered master directory if mdir owner userid = caller userid setup mdir info in return struct else /* caller IS a volume administrator */ if caller wants data by account then for all accounts set up account info in return struct for all mdirs drawing from that accnt setup info in return struct else /* caller wants data for mdir owners */ for all mdirs if caller wants mdir owner's data setup info in return struct thread into list of mdirs /* now for both account and mdir info */ setup restrict and default path chains cleanup exit mdc_repair_ This module implements the management of the MDC database segments. It is mostly called by volume_registration_mgr_ to keep the MDC database consistant with current volume registration. The following paragraphs describe its entries. mdc_repair_$make_mdcs Creates an MDC database segment for a specified logical volume. It is called by volume_registration_mgr_$add_lvr when a new volume is registered. The real work is done by mdcs_util_$create_mdcs. If the segment already exists, it is validated and error_table_$namedup is returned. If the data is invalid, the segment is initialized with a new header. 4-13 MDD-008 Online Storage Volume Management mdc_repair_$recreate_mdcs Performs the same function as mdc_repair_$create_mdcs except that no locks are set. It is called by volume_registration_mgr_$check_volume_registration during system initialization. mdc_repair_$copy_mdcs Makes a copy of an MDC database segment in caller supplied storage. It currently has no caller in the system. mdc_repair_$rename_mdcs Calls mdcs_util_$rename_mdcs to change the database segment entryname and the name in the header field "mdcs_head.volume" for an MDC database segment. It is called by volume_registration_mgr_$change_lvr when the name of the associated volume changes. mdc_repair_$update_lvid Calls mdcs_util_$update_lvid to change the mdcs_head.uid field in the MDC database segment. It is called by volume_registration_mgr_$change_lvr when the LVID of the associated volume changes. mdc_repair_$delete_mdcs Calls mdcs_util_$delete_mdcs to remove the specified MDC database segment. All master directories for the associated volume must have been previously deleted. It is called by volume_registration_mgr_$delete_lvr when removing the logical volume. mdc_repair_$register_mdir Registers a given master directory. It is called by the privileged command "register_mdir". Its control flow is: entry copy args obtain master directory status information lock the MDC database if mdirent already exists if quota bad call mdc_check_mdcs_ /*salvage quota*/ cleanup exit setup new mdirent for default account (initializer) if account doesn't exist create it call mdc_check_mdcs_ /*salvage quota*/ cleanup exit mdc_repair_$validate_uidpaths Salvages the MDC database segment. This entry is invoked by the privileged command "check_mdcs". Its flow of control is: 4-14 Online Storage Volume Management MDD-008 entry copy args lock MDC database locate database segment and validate header check volume restrict path chain check volume default path chain for all mdirent entries check uid path if bad path remove mdirent for all acctent entries check account restrict path chain call mdc_check_mdcs_ /*salvage quota*/ setup return code cleanup exit mdc_check_mdcs_ This routine is called by mdc_repair_$validate_uidpaths and mdc_repair_$register_mdir to perform volume quota validation/salvage. It goes something like this: entry check the following threads for being within the segment and non-circular: account entry thread master directory entry thread volume restricted path thread volume default path thread check that header "pad" is zero check that each mdirent points to a valid accent for each acctent check account restrict path thread as above check that account name is valid ASCII check that entry is in proper sequence for starname matching check quotas of all mdirent entries which draw their quota from this account if all was ok then update header "time checked" exit mdc_parse_acct_$star mdc_parse_acct_$default This is a utility module which parses an account name (or user's group ID) into the Person_ID and Project_ID. Validity checks are carried out. The "star" entry allows null components to be returned as "*". The "default" entry returns "Initializer" and "SysDaemon". 4-15 MDD-008 Online Storage Volume Management mdc_lock_$set mdc_lock_$reset mdc_lock_$cleanup This module handles the global database lock for MDC. The "set" entry locks the database. The "reset" entry unlocks the database. The "cleanup" entry unlocks the database only if locked by the calling process. mdc_util_ This module is used to handle the internal structure of an MDC database segment. It maintains the linked lists of master directory, account, and path entries (mdirent, acctent, and pathent structures respectively). The following paragraphs describe these entries in groups of common purpose. mdc_util_$get_XXXXent Allocates storage for the particular type of entry. A pointer to that storage is returned to the caller. mdc_util_$thread_XXXXent Threads a particular type of structure onto the appropriate list. There is only one list for mdirent and acctent structures. For pathent structures, the caller must specify which thread onto which it should be added (volume restrict, volume default, or account restrict) by passing a pointer to the head of the desired list. mdc_util_$find_XXXXent Locates an entry in a list. For master directory data, the key is the UID path. For path data, the key is the UID path (and the head of the list must be given). For account data, the key is the Person_ID and Project_ID. mdc_util_$check_pathent Is similar to "find_pathent". However, it doesn't perform a comparison of the whole UID path. Null entries in the stored paths are ignored allowing a successful match on the first non-null entries. (e.g. >udd>Proj33>Ted>x would match >udd>Proj33 stored in the thread) mdc_util_$find_matching_acctent Is similar to "find_acctent". However, it performs starname type matching on account names. mdc_util_$free_XXXXent Unthreads the data structure from its list and frees the storage it used. mdcs_util_ This module maintains the structure of the database above the segment level. That is, it is used to create, rename, and 4-16 Online Storage Volume Management MDD-008 delete segments in the database. Each entry is described in the succeeding paragraphs. mdcs_util_$create_mdcs Creates a new MDC database segment. If the segment already exists the header is validated. If the header is OK, it goes ahead and validates the rest of the segment. If the header is bad, it is re-initialized. This is called by volume_registration_mgr_$add_lvr via mdc_repair_$create_mdcs when a new logical volume is registered. It is also called by volume_registration_mgr_$check_volume_registration via mdc_repair_$recreate_mdcs during the database check/recreation done at system initialization. mdcs_util_$find_mdcs Locates the MDC database segment for the specified logical volume. The header is validated. If the rest of the contents have not been validated since the system was booted, or in the previous 12 hours, they too are vaildated. The caller's access to the volume is also returned. This routine is called whenever an operation is to be performed on the database (e.g. setting volume quota, setting restrict paths, etc). mdcs_util_$find_mdcs_and_check Is the same as "find_mdcs" except that database segment contents validation is forced (i.e. regardless of time last validated). mdcs_util_$find_mdcs_uid Is also the same as "find_mdcs" except that the caller has supplied the logical volume unique ID (LVID). Thus, the logical volume name must be obtained from volume_registration_mgr_ before the MDC database segment can be located. mdcs_util_$term_mdcs Terminates the reference to a database segment. It should be called by all callers of the "find_mdcs*" entrypoints in their respective cleanup procedures. mdcs_util_$delete_mdcs Deletes the specified MDC database segment. This is called by volume_registration_mgr_$delete_lvr via mdc_repair_$delete_mdcs at logical volume deregistration time. mdcs_util_$delete_mdcsp Deletes the MDC database given a pointer rather than logical volume name. It is currently not used. mdcs_util_$rename_mdcs Changes the name of an MDC database segment (and the internally stored name). It is called by 4-17 MDD-008 Online Storage Volume Management volume_registration_mgr_$change_lvr via mdc_repair_$rename_mdcs when the volume name is changed. (This is not to be done for initialized volumes.) mdcs_util_$update_lvid Changes the logical volume unique ID (LVID) stored internally in the MDC database segment. It is called by volume_registration_mgr_$change_lvr via mdc_repair_$update_lvid when the LVID is changed there. (This is not to be done for initialized volumes.) Entry into the inner ring modules is controlled by the gates: "mdc_" for user operations; and "mdc_priv_" for system administrator operations. DRAFT: MAY BE CHANGED 4-18 02/06/86 SECTION 5 SECURITY This section reviews the security specific features of the subsystems covered in this Multics Design Document. The following sections describe the security features of the three subsystems individually. _5_._1 _S_E_C_U_R_I_T_Y _- _V_O_L_U_M_E _R_E_G_I_S_T_R_A_T_I_O_N The ability to add, delete, or change attributes of logical or physical volumes lies with the system administration and operation personnel. Commands which perform registration functions require access to the mdc_priv_ gate. All operations on the volume registration database are logged in the syserr log. The registration attributes which have direct security implications are the access_class (which may not be changed for initialized volumes), the volume owner (primary administrator), and the volume ACS path (which defines other volume administrators and the eligible users of the volume). Note that the access control list of the ACS may limit the access of the volume owner. The subsystem has no control over access to a logical volume when an ACS path is defined. Anyone with sufficient access to that segment's parent directory may change access to the volume. Therefore, it is recommended that any public volume ACS be kept in the directory >lv. Private logical volume owners should be made aware of the pitfalls of this security mechanism. It is best that they maintain any ACS for a private volume in their home directories (or the system administration may keep it in >lv, but no extra access should be set on >lv). System operators have only the following abilities in respect to volume registration: ox initialize a PV according to its registered attributes ox reregister an already initialized volume ox remove root PVs (alter ROOT card and reboot) DRAFT: MAY BE CHANGED 5-1 02/06/86 These functions cannot change the access attributes of a volume. _5_._2 _S_E_C_U_R_I_T_Y _- _V_O_L_U_M_E _A_C_C_E_S_S An operator may mount or demount any logical volume at any time (except the RLV). This section is concened with user access to data on the volume. Any user may access any public volume data regardless of the volume's ACS access list. Of course, access to specific segments is limited by the other Multics security features (Rings, ACL, and AIM). Private volume access is controlled by the volume's ACS access list. To attach a private volume the user must have at least read/write (RW) access to the ACS and be logged in at an authorization within the access class range specified in the volume registration. (If the volume is not already mounted, a message requesting the operator to mount the volume will appear on the console. The user process will wait until the mount is complete or aborted.) Again, access to specific data on the private LV is limited by the other Multics security features. Another limiting factor imposed by volume management is that data created on the LV must be within the access class range specified in the registration. This restriction is enforced by create_vtoce. Access to a private logical volume is checked by rcp_attach_lv_ in ring one in response to the "attach_lv" user command. The actual ACS access list check is performed by volume_registration_mgr_$get_access. A value representing null access is returned unless the user's authorization is within the access range set on the volume, or the user has RCP AIM privilege turned on. rcp_attach_lv_ ensures the returned value has at least RW access present before proceeding with the attachment. Note that changes to the access list of the volume's ACS are not instantaneous with respect to users who already have the volume attached. Although the access change may revoke their ability to attach the volume, they continue to retain the present attachment until logout or until they invoke the "detach_lv" command. Attempted re-attachment will fail if there is insufficient access to the ACS. All mounts and demounts of logical volumes are logged in the syserr log. In addition, access to data contained on any LV is audited by the file system primitives (dc_find). Auditing is controlled by the state of the system and process audit flags. _5_._3 _S_E_C_U_R_I_T_Y _- _V_O_L_U_M_E _Q_U_O_T_A _M_A_N_A_G_E_M_E_N_T _(_M_A_S_T_E_R _D_I_R_E_C_T_O_R_Y _C_O_N_T_R_O_L_) Manipulation of quota accounts can be performed only by those having at least executive (E) access to the volume's ACS. If the ACS does not exist only the owner may manipulate quota DRAFT: MAY BE CHANGED 5-2 02/06/86 accounts. In addition, the user's authorization must be within the access class range specified in the volume registration. Quota accounts are handled by the inner ring routines mdc_set_, mdc_set_path_, and mdc_status_. They all call volume_registration_mgre_$get_access (via mdcs_util_$find_mdcs) which returns the user's access to the volume. A value representing null access is returned unless the user's authorization is within the access range set on the volume, or the user has RCP AIM privilege turned on. The mdc_* routines then ensure that at least executive (E) access is present before continuing with their respective tasks. Manipulation of quota accounts is not currently audited by the system. Trusted sites are advised to limit volume and quota administration to only trusted administrators (see Multics _S_y_s_t_e_m _A_d_m_i_n_i_s_t_r_a_t_i_o_n _P_r_o_c_e_d_u_r_e_s order number AK50). Creation of master directories is controlled by the existance of an appropriate quota account for the user. An account which has a name equal to the user's PersonID.ProjectID, or which has an asterisk for either or both of the non-matching components, may be used. Volume administrators may use any account. In a future Multics release, the user will also need at least read/write (RW) access to the volume in question and the quota account will have to match the user's authorization. Master directory creation is handled by the inner ring procedure mdc_create_. It ensures that a valid quota account exists via the routine mdc_util_$find_matching_account. This routine allows starname matches on the supplied userid. If the user supplied an account name, mdc_create_ will verify that the user is a volume administrator (calls volume_registration_mgr_$get_access via mdcs_util_$find_mdcs). If so, mdc_util_$find_account is called to find that specific account. If an account is found, and it has sufficient quota for the new directory requirements, mdc_create_ will continue its task. Auditing of master directory manipulation is audited by the file system primitives (dc_find). DRAFT: MAY BE CHANGED 5-3 02/06/86 SECTION 6 SCENARIOS This section will present 4 or more scenarios of using the subsystems presented in this manual. In particular, the scenarios will include: registering an LV and creating quota accounts mounting a public volume mounting a private volume system startup (NOLV) DRAFT: MAY BE CHANGED 6-1 02/06/86 SECTION 7 GLOSSARY This section will be a simply reference of terms. ----------------------------------------------------------- Historical Background This edition of the Multics software materials and documentation is provided and donated to Massachusetts Institute of Technology by Group BULL including BULL HN Information Systems Inc. as a contribution to computer science knowledge. This donation is made also to give evidence of the common contributions of Massachusetts Institute of Technology, Bell Laboratories, General Electric, Honeywell Information Systems Inc., Honeywell BULL Inc., Groupe BULL and BULL HN Information Systems Inc. to the development of this operating system. Multics development was initiated by Massachusetts Institute of Technology Project MAC (1963-1970), renamed the MIT Laboratory for Computer Science and Artificial Intelligence in the mid 1970s, under the leadership of Professor Fernando Jose Corbato. Users consider that Multics provided the best software architecture for managing computer hardware properly and for executing programs. Many subsequent operating systems incorporated Multics principles. Multics was distributed in 1975 to 2000 by Group Bull in Europe , and in the U.S. by Bull HN Information Systems Inc., as successor in interest by change in name only to Honeywell Bull Inc. and Honeywell Information Systems Inc. . ----------------------------------------------------------- Permission to use, copy, modify, and distribute these programs and their documentation for any purpose and without fee is hereby granted,provided that the below copyright notice and historical background appear in all copies and that both the copyright notice and historical background and this permission notice appear in supporting documentation, and that the names of MIT, HIS, BULL or BULL HN not be used in advertising or publicity pertaining to distribution of the programs without specific prior written permission. Copyright 1972 by Massachusetts Institute of Technology and Honeywell Information Systems Inc. Copyright 2006 by BULL HN Information Systems Inc. Copyright 2006 by Bull SAS All Rights Reserved