SSSoooffftttwwwaaarrreee TTToooooolllsss SSSuuubbbsssyyysssttteeemmm MMMaaannnaaagggeeerrr'''sss GGGuuuiiidddeee T. Allen Akin Terrell L. Countryman Daniel H. Forsyth, Jr. | Jefferey S. Lee Jeanette T. Myers | Arnold D. Robbins Peter N. Wan | School of Information and Computer Science | Georgia Institute of Technology | Atlanta, Georgia 30332 | September, 1984 Subsystem Manager's Guide | OOOvvveeerrrvvviiieeewww You are reading the SSSoooffftttwwwaaarrreee TTToooooolllsss SSSuuubbbsssyyysssttteeemmm MMMaaannnaaagggeeerrr'''sss GGGuuuiiidddeee. The machine-readable text of this Guide is supplied with the Subsystem in the file "=doc=/fguide/mgr" (already formatted) and in the directory "=doc=/guide/mgr" (unformatted). PPPuuurrrpppooossseee This Guide addresses the needs of the Subsystem Manager: that individual or small group of individuals that is responsible for the installation, maintenance and daily operation of the Sub- system. Bringing up a large software system is a complicated process that involves several bootstrapping steps. In this case, the Subsystem Manager will be responsible for at least three: the installation of the Subsystem, initial distribution of documentation, and creation of user accounts. Once the system is running and a sizable user community develops, the responsibilities of the Manager will change. In particular, he will control the generation and distribution of new copies of documentation, maintain lists of active users, update the description of the local hardware configuration, and possibly modify the Subsystem itself by changing either the system code or documentation. It is the intent of this Guide to provide the Manager with the information necessary to carry out these duties and with procedures for their performance that are recommended by the Sub- system's designers. For further information on the philosophy and use of the Subsystem, the reader is referred to the _S_o_f_t_w_a_r_e _T_o_o_l_s _S_u_b_s_y_s_t_e_m _R_e_f_e_r_e_n_c_e _M_a_n_u_a_l, the _S_o_f_t_w_a_r_e _T_o_o_l_s _S_u_b_s_y_s_t_e_m _U_s_e_r_'_s _G_u_i_d_e, and, of course, to Kernighan and Plauger's _S_o_f_t_w_a_r_e _T_o_o_l_s. SSSuuummmmmmaaarrryyy ooofff CCCooonnnttteeennntttsss This Guide is divided into five sections as outlined in the following five paragraphs. The SSSuuubbbsssyyysssttteeemmm CCCooonnnfffiiiggguuurrraaatttiiiooonnn section deals with the directory structure of the Subsystem. It describes the standard configura- tion supplied on the Release Tape as well as options for changing directory names, locating directories on specific logical disks, and storing certain portions of the Subsystem off-line. The IIInnnssstttaaallllllaaatttiiiooonnn PPPrrroooccceeeddduuurrreee covers the initial installation of the Subsystem. It catalogs the contents of the Subsystem Installation Package and Release Tape, provides instructions for loading the tape, and details the steps the Manager must take in - 1 - Subsystem Manager's Guide order to make the Subsystem operational. The CCCooonnnvvveeerrrsssiiiooonnn PPPrrroooccceeeddduuurrreee section describes the steps neces- sary to update your current Subsystem to this release. If you are a new customer, then you need only peruse this section for various caveats, but not necessarily act upon the information contained therein. The section on DDDooocccuuummmeeennntttaaatttiiiooonnn SSStttrrruuuccctttuuurrreee describes the nature, coverage and physical location of all Subsystem documentation. Its two sub-sections correspond to the two major Subsystem documents: the _S_o_f_t_w_a_r_e _T_o_o_l_s _S_u_b_s_y_s_t_e_m _R_e_f_e_r_e_n_c_e _M_a_n_u_a_l and the _S_o_f_t_w_a_r_e _T_o_o_l_s _S_u_b_s_y_s_t_e_m _U_s_e_r_'_s _G_u_i_d_e. The day-to-day activities of the Subsystem Manager are covered in SSSuuubbbsssyyysssttteeemmm MMMaaannnaaagggeeemmmeeennnttt. Such concerns as maintaining user accounts and hardware configuration files, adding local software tools and documentation, and operating Subsystem user services are treated. SSSuuubbbsssyyysssttteeemmm CCCooonnnfffiiiggguuurrraaatttiiiooonnn The Subsystem is a complex piece of software that resides in several disk directories. This section discusses the standard directory structure and the means provided for changing it, some alternative directory structures, and naming and structural con- ventions that must be followed if changes are made. SSStttaaannndddaaarrrddd DDDiiirrreeeccctttooorrryyy SSStttrrruuuccctttuuurrreee The following chart outlines the structure of the major Sub- system directories as supplied on the Release Tape: aaauuuxxx ppprrriiimmmeeesss (file of prime numbers less than 1,000,000) ssspppeeelllllliiinnnggg {{{dddiiiccctttiiiooonnnaaarrriiieeesss ooofff EEEnnngggllliiissshhh wwwooorrrdddsss,,, ppplllaaaccceee nnnaaammmeeesss,,, eeetttccc...}}} bbbiiinnn {{{ssstttaaannndddaaarrrddd SSSuuubbbsssyyysssttteeemmm cccooommmmmmaaannndddsss,,, sssuuuppppppooorrrttteeeddd bbbyyy GGGTTT}}} lllbbbiiinnn {{{lllooocccaaallllllyyy---sssuuuppppppooorrrttteeeddd cccooommmmmmaaannndddsss}}} ttteeemmmppp {{{ssscccrrraaatttccchhh fffiiillleeesss cccrrreeeaaattteeeddd bbbyyy SSSuuubbbsssyyysssttteeemmm ppprrrooogggrrraaammmsss}}} - 2 - Subsystem Manager's Guide | vvvaaarrrsss {{{sssuuubbbdddiiirrreeeccctttooorrryyy fffooorrr eeeaaaccchhh uuussseeerrr}}} ...mmmaaaiiilll (old mail storage) ...vvvaaarrrsss (shell variable storage) ...ttteeemmmppplllaaattteee (user template definitions) | ...hhhiiisssttt (user shell session storage) eeexxxtttrrraaa bbbiiinnn {{{ppprrrooogggrrraaammmsss cccaaalllllleeeddd bbbyyy ssshhheeellllll fffiiillleeesss iiinnn '''bbbiiinnn'''}}} bbbuuuggg {{{bbbuuuggg rrreeepppooorrrtttsss gggaaattthhheeerrreeeddd bbbyyy '''bbbuuuggg'''}}} | cccrrrooonnn | {{{eeexxxaaammmpppllleee fffiiillleeesss fffooorrr uuussseee bbbyyy ttthhheee '''cccrrrooonnn''' ppprrrooogggrrraaammm}}} | cccllliiisssttt (list of command names used by 'guess') gggooossssssiiippp {{{fffiiillleee fffooorrr eeeaaaccchhh uuussseeerrr,,, fffooorrr mmmeeessssssaaagggeeesss ssseeennnttt bbbyyy '''tttooo'''}}} * iiinnnssstttaaallllllaaatttiiiooonnn (installation name) mmmaaaiiilll {{{fffiiillleee fffooorrr eeeaaaccchhh uuussseeerrr,,, fffooorrr mmmeeessssssaaagggeeesss ssseeennnttt bbbyyy '''mmmaaaiiilll'''}}} mmmeeemmmooo {{{fffiiillleee fffooorrr eeeaaaccchhh uuussseeerrr,,, fffooorrr mmmeeemmmooorrraaannndddaaa fffrrrooommm '''mmmeeemmmooo'''}}} mmmoooooottt...uuu {{{fffiiillleeesss uuussseeeddd bbbyyy '''mmmoooooottt'''}}} nnneeewwwsss * aaarrrtttiiicccllleeesss {{{fffiiillleeesss cccooonnntttaaaiiinnniiinnnggg ooonnneee nnneeewwwsss aaarrrtttiiicccllleee eeeaaaccchhh}}} iiinnndddeeexxx (index to all past news articles) sssuuubbbssscccrrriiibbbeeerrrsss (list of news service subscribers) dddeeellliiivvveeerrryyy {{{fffiiillleee fffooorrr eeeaaaccchhh uuussseeerrr,,, fffooorrr uuunnndddeeellliiivvveeerrreeeddd nnneeewwwsss}}} ppphhhooonnneeesss (list of phone numbers used by 'phone') ttteeerrrmmmsss (list of terminals attached to the system) uuussseeerrrsss (list of authorized Subsystem users) fffmmmaaacccrrrooo {{{mmmiiisssccceeellllllaaannneeeooouuusss ttteeexxxttt fffooorrrmmmaaatttttteeerrr mmmaaacccrrrooo fffiiillleeesss}}} iiinnnccclll | {{{mmmaaacccrrrooo dddeeefffiiinnniiitttiiiooonnnsss fffooorrr RRRaaatttfffooorrr,,, CCC,,, aaannnddd PPPMMMAAA}}} nnnuuummmsssggg (propaganda message sent to new users) - 3 - Subsystem Manager's Guide ttteeemmmppplllaaattteee (pathname template definition file) vvvttthhh {{{fffiiillleeesss dddeeessscccrrriiibbbiiinnnggg ttteeerrrmmmiiinnnaaalll hhhaaarrrdddwwwaaarrreee ccchhhaaarrraaacccttteeerrriiissstttiiicccsss}}} ttttttyyypppeeesss (list of Subsystem-supported terminals and their characteristics) sssrrrccc lllccclll llliiibbb {{{sssuuubbbdddiiirrreeeccctttooorrriiieeesss fffooorrr lllooocccaaallllllyyy---sssuuuppppppooorrrttteeeddd llliiibbbrrraaarrriiieeesss}}} ssspppccc {{{sssuuubbbdddiiirrreeeccctttooorrriiieeesss fffooorrr lllooocccaaalll ppprrrooogggrrraaammmsss wwwiiittthhh nnnooonnn--- ssstttaaannndddaaarrrddd cccooommmpppiiilllaaatttiiiooonnn rrreeeqqquuuiiirrreeemmmeeennntttsss}}} ssstttddd...rrr {{{sssooouuurrrccceee fffiiillleeesss fffooorrr lllooocccaaalll RRRaaatttfffooorrr ppprrrooogggrrraaammmsss}}} ssstttddd...ssshhh {{{sssooouuurrrccceee fffiiillleeesss fffooorrr lllooocccaaalll ssshhheeellllll ppprrrooogggrrraaammmsss}}} ssstttddd...ssstttaaacccccc {{{sssooouuurrrccceee fffiiillleeesss fffooorrr lllooocccaaalll RRRaaatttfffooorrr///'''ssstttaaacccccc''' ppprrrooogggrrraaammmsss}}} llliiibbb | ccc$$$mmmaaaiiinnn | {{{fffiiillleeesss tttooo bbbuuuiiilllddd ttthhheee CCC ssstttaaarrrtttoooffffff rrrooouuutttiiinnneee --------- | ooonnnlllyyy fffooorrr sssiiittteeesss wwwhhhiiiccchhh llliiiccceeennnssseee ttthhheee CCC cccooommmpppiiillleeerrr}}} | ccciiiooo | {{{sssooouuurrrccceee fffiiillleeesss fffooorrr CCC III///OOO llliiibbbrrraaarrryyy --------- ooonnnlllyyy fffooorrr | sssiiittteeesss wwwhhhiiiccchhh llliiiccceeennnssseee ttthhheee CCC cccooommmpppiiillleeerrr}}} eeedddttt {{{sssooouuurrrccceee fffiiillleeesss fffooorrr llliiinnneee eeedddiiitttooorrr rrrooouuutttiiinnneeesss}}} | mmmaaattthhh | {{{sssooouuurrrccceee fffiiillleeesss fffooorrr '''vvvssswwwtttmmmaaattthhh''' llliiibbbrrraaarrryyy}}} | ssshhh | sssrrrccc | {{{sssooouuurrrccceee fffiiillleeesss aaannnddd dddiiirrreeeccctttooorrriiieeesss fffooorrr '''vvvssshhhllliiibbb'''}}} | {{{mmmiiisssccceeellllllaaannneeeooouuusss fffiiillleeesss fffooorrr '''vvvssshhhllliiibbb'''}}} ssswwwttt ooobbbjjj {{{ooobbbjjjeeecccttt cccooodddeee fffiiillleeesss fffooorrr '''vvvssswwwtttlllbbb''' rrrooouuutttiiinnneeesss}}} sssrrrccc...aaa (archive containing source code for 'vswtlb' routines) {{{mmmiiisssccceeellllllaaannneeeooouuusss fffiiillleeesss fffooorrr llliiibbbrrraaarrryyy '''vvvssswwwtttlllbbb'''}}} | vvvcccggg | {{{sssooouuurrrccceee fffiiillleeesss fffooorrr ttthhheee vvvcccggg sssuuuppppppooorrrttt llliiibbbrrraaarrryyy --------- | ooonnnlllyyy fffooorrr sssiiittteeesss wwwhhhiiiccchhh llliiiccceeennnssseee ttthhheee CCC cccooommmpppiiillleeerrr}}} | vvvcccggg___mmmaaaiiinnn | {{{sssooouuurrrccceee fffooorrr mmmaaaiiinnn rrrooouuutttiiinnneee fffooorrr vvvcccggg fffooorrr iiinnndddiiivvviiiddduuuaaalllsss | ttthhhaaattt hhhaaavvveee wwwrrriiitttttteeennn ttthhheeeiiirrr ooowwwnnn fffrrrooonnnttt eeennndddsss fffooorrr vvvcccggg --------- | ooonnnlllyyy fffooorrr sssiiittteeesss wwwhhhiiiccchhh llliiiccceeennnssseee ttthhheee CCC cccooommmpppiiillleeerrr}}} ssspppccc {{{sssuuubbbdddiiirrreeeccctttooorrriiieeesss fffooorrr ppprrrooogggrrraaammmsss wwwiiittthhh nnnooonnnssstttaaannndddaaarrrddd cccooommmpppiiilllaaatttiiiooonnn rrreeeqqquuuiiirrreeemmmeeennntttsss}}} - 4 - Subsystem Manager's Guide ssstttddd...rrr {{{sssooouuurrrccceee fffiiillleeesss fffooorrr ssstttaaannndddaaarrrddd RRRaaatttfffooorrr ppprrrooogggrrraaammmsss}}} ssstttddd...ssshhh {{{sssooouuurrrccceee fffiiillleeesss fffooorrr ssstttaaannndddaaarrrddd ssshhheeellllll ppprrrooogggrrraaammmsss}}} ssstttddd...ssstttaaacccccc {{{sssooouuurrrccceee fffiiillleeesss fffooorrr ssstttaaannndddaaarrrddd RRRaaatttfffooorrr///'''ssstttaaacccccc''' ppprrrooogggrrraaammmsss}}} | eeexxxttt...ccc | {{{sssooouuurrrccceee fffiiillleeesss fffooorrr CCC ppprrrooogggrrraaammmsss iiinnn """===eeebbbiiinnn===""" --------- ooonnnlllyyy | fffooorrr sssiiittteeesss wwwhhhiiiccchhh llliiiccceeennnssseee ttthhheee CCC cccooommmpppiiillleeerrr}}} | eeexxxttt...rrr {{{sssooouuurrrccceee fffiiillleeesss fffooorrr RRRaaatttfffooorrr ppprrrooogggrrraaammmsss iiinnn """===eeebbbiiinnn==="""}}} eeexxxttt...ssshhh {{{sssooouuurrrccceee fffiiillleeesss fffooorrr ssshhheeellllll ppprrrooogggrrraaammmsss iiinnn """===eeebbbiiinnn==="""}}} | mmmiiisssccc | {{{SSSuuubbbsssyyysssttteeemmm sssuuuppppppooorrrttt aaannnddd mmmaaaiiinnnttteeennnaaannnccceee rrrooouuutttiiinnneeesss}}} | dddoooccc bbbuuuiiilllddd ggguuuiiidddeee (format a new version of the User's Guide) mmmaaannn (format a new version of the Reference Manual) rrreeebbbuuuiiilllddd (format a new Reference Manual entry) fffggguuuiiidddeee {{{fffiiillleeesss cccooonnntttaaaiiinnniiinnnggg fffooorrrmmmaaatttttteeeddd pppooorrrtttiiiooonnnsss ooofff ttthhheee UUUssseeerrr'''sss GGGuuuiiidddeee}}} fffmmmaaannn sss111 {{{fffooorrrmmmaaatttttteeeddd ssstttaaannndddaaarrrddd cccooommmmmmaaannnddd dddooocccuuummmeeennntttaaatttiiiooonnn}}} sss222 {{{fffooorrrmmmaaatttttteeeddd ssstttaaannndddaaarrrddd llliiibbbrrraaarrryyy dddooocccuuummmeeennntttaaatttiiiooonnn}}} sss333 {{{fffooorrrmmmaaatttttteeeddd lllooocccaaalll cccooommmmmmaaannnddd dddooocccuuummmeeennntttaaatttiiiooonnn}}} sss444 {{{fffooorrrmmmaaatttttteeeddd lllooocccaaalll llliiibbbrrraaarrryyy dddooocccuuummmeeennntttaaatttiiiooonnn}}} sss555 {{{fffooorrrmmmaaatttttteeeddd lllooowww---llleeevvveeelll cccooommmmmmaaannnddd dddooocccuuummmeeennntttaaatttiiiooonnn}}} sss666 {{{fffooorrrmmmaaatttttteeeddd lllooowww---llleeevvveeelll llliiibbbrrraaarrryyy dddooocccuuummmeeennntttaaatttiiiooonnn}}} {{{mmmiiisssccceeellllllaaannneeeooouuusss fffooorrrmmmaaatttttteeeddd pppooorrrtttiiiooonnnsss ooofff RRReeefffeeerrreeennnccceee MMMaaannnuuuaaalll}}} ggguuuiiidddeee {{{sssuuubbbdddiiirrreeeccctttooorrriiieeesss cccooonnntttaaaiiinnniiinnnggg pppooorrrtttiiiooonnnsss ooofff ttthhheee UUUssseeerrr'''sss GGGuuuiiidddeee,,, uuunnnfffooorrrmmmaaatttttteeeddd}}} hhhiiisssttt hhhiiissstttooorrryyy (history of changes to the Subsystem) - 5 - Subsystem Manager's Guide mmmaaannn sss111 {{{uuunnnfffooorrrmmmaaatttttteeeddd ssstttaaannndddaaarrrddd cccooommmmmmaaannnddd dddooocccuuummmeeennntttaaatttiiiooonnn}}} sss222 {{{uuunnnfffooorrrmmmaaatttttteeeddd ssstttaaannndddaaarrrddd llliiibbbrrraaarrryyy dddooocccuuummmeeennntttaaatttiiiooonnn}}} sss333 {{{uuunnnfffooorrrmmmaaatttttteeeddd lllooocccaaalll cccooommmmmmaaannnddd dddooocccuuummmeeennntttaaatttiiiooonnn}}} sss444 {{{uuunnnfffooorrrmmmaaatttttteeeddd lllooocccaaalll llliiibbbrrraaarrryyy dddooocccuuummmeeennntttaaatttiiiooonnn}}} sss555 {{{uuunnnfffooorrrmmmaaatttttteeeddd lllooowww---llleeevvveeelll cccooommmmmmaaannnddd dddooocccuuummmeeennntttaaatttiiiooonnn}}} sss666 {{{uuunnnfffooorrrmmmaaatttttteeeddd lllooowww---llleeevvveeelll llliiibbbrrraaarrryyy dddooocccuuummmeeennntttaaatttiiiooonnn}}} {{{mmmiiisssccceeellllllaaannneeeooouuusss uuunnnfffooorrrmmmaaatttttteeeddd pppooorrrtttiiiooonnnsss ooofff RRReeefffeeerrreeennnccceee MMMaaannnuuuaaalll}}} ppprrriiinnnttt ggguuuiiidddeee (print a copy of the User's Guide) mmmaaannn (print a copy of the Reference Manual) ssseee___hhh {{{fffiiillleeesss cccooonnntttaaaiiinnniiinnnggg ooonnn---llliiinnneee hhheeelllppp iiinnnfffooorrrmmmaaatttiiiooonnn fffooorrr '''ssseee'''}}} | mmmiiisssccc | {{{DDDooocccuuummmeeennntttaaatttiiiooonnn sssuuuppppppooorrrttt aaannnddd mmmaaaiiinnnttteeennnaaannnccceee rrrooouuutttiiinnneeesss}}} | _T_o_p_-_L_e_v_e_l _D_i_r_e_c_t_o_r_i_e_s. The top-level directories 'aux', 'bin', 'doc', 'extra', 'lbin', 'src', 'temp' and 'vars' are dedicated to the Subsystem. In addition, use of the Subsystem requires that several files be added to the Primos directories 'cmdnc0', 'lib', and 'system'. (A list of these files may be found in the section on Installation Procedures in this Guide.) | Previously, the 'cmdnc0' directory used for Subsystem files | had to be the directory to which the console was attached after a | cold start. Under the new revision (Revision 19) of the operat- | ing system, the 'cmdnc0' directory used for Subsystem support | commands must be the 'cmdnc0' located on the lowest numbered | logical disk partition, to ensure that users can enter the Sub- | system properly. The 'lib' directory used for Subsystem | libraries must also be on the lowest-numbered logical disk, so the libraries will be locatable by the loader. The 'system' directory used for Subsystem shared segment files should be the directory in which all standard Primos shared code resides, so that the shared Subsystem programs may be installed during a cold-start. | _D_i_r_e_c_t_o_r_y _S_e_c_u_r_i_t_y _a_n_d _P_l_a_c_e_m_e_n_t _o_n _D_i_s_k. The subsystem is | supplied with ACL protections but if the tape is restored onto a | password partition, the password protections will override the | ACL protections. Although the Subsystem will operate properly | regardless of the placement of its top-level directories, sub- | stantial reduction in overhead may be had by following these | recommendations. The following discussion normally describes the | necessary protections for password directories and then follows | that with the protections needed in the case of ACL directories. - 6 - Subsystem Manager's Guide The directories 'bin' and 'lbin' are accessed very frequently (about once per command) and so should be located on a | low-numbered logical disk. The files in these directories must | be readable by non-owners but should be protected against altera- | tion by ordinary users. This can be accomplished by placing an | owner password on the directories or by making the directories | ACL protected directories with permissions of "list", "use", and | "read" for everyone. (But see the _U_s_e_r_'_s _G_u_i_d_e _f_o_r _t_h_e _S_o_f_t_w_a_r_e _T_o_o_l_s _S_u_b_s_y_s_t_e_m _C_o_m_m_a_n_d _I_n_t_e_r_p_r_e_t_e_r, for information on "search rules.") Scratch files created by Subsystem programs reside in the directory 'temp'. The concept of a "temporary file directory" is necessary to allow editing of files on read-only disks or in directories in which the user has non-owner status. Depending on the application at hand, files in 'temp' may grow to excessive size, so it should be placed on a logical disk with plenty of available storage space. It is not accessed frequently, so its | placement is otherwise unconstrained. 'Temp' must be public; | that is, it must have either a blank owner password or, if it is | an ACL protected directory, permissions of "list", "use", "add", | "delete", "read", and "write" for everyone. Subdirectories of the directory 'vars' are used for storage of personal profile information. 'Vars' is accessed infrequently, and is typically small; it may be placed on any convenient logical disk. 'Vars' itself should have an owner pas- sword to preserve the privacy of individual users; it may not | have a non-owner password. If 'vars' is made an ACL protected | directory, it should have permissions of "list" and "use" for | everyone. The Subsystem manager must create in 'vars' a sub- directory for each Subsystem user, named by that user's login name. Each of these subdirectories should be protected by an owner password of the user's own choosing and should have no non- | owner password. If they are ACL protected, they should be given | ACL protection for the owner of "list", "use", "add", "delete", | "read", and "write" and "list" and "use" permissions for everyone | else. If the directory is ACL protected, the Subsystem will not | request a password to allow entry. If it is password protected, | the 'swt' command prompts for the owner password and records it internally before entering the Subsystem; this saved password is then used in all future references to the directory by the Sub- system. If the user wishes to change the directory's password, he must do so outside of the Subsystem, so that the Subsystem will be able to exit normally. Miscellaneous information that pertains to the Subsystem resides in the directory 'extra'. 'Extra' is relatively small and is frequently referenced (to check for messages sent from user to user via the 'to' command), so it should be placed on a low-numbered logical disk. All contents of 'extra' and its sub- directories should be readable by non-owners and free of non- | owner passwords. If it is ACL protected, each file should be | protected so that everyone can read it and each directory should | be protected with "list", "use", and "read" protections for | everyone. The subdirectories 'mail', 'gossip', and 'memo' must - 7 - Subsystem Manager's Guide | be public so that anyone can create a file in them ("list", | "use", "add", "delete", "read", and "write"). The files in the subdirectory 'news' should normally be writeable by anyone and its subdirectories public; however, the Subsystem Manager may see fit to restrict subscriptions to the news service by removing non-owner write access to the 'subscribers' file, and publishing of news articles by removing non-owner write access to the 'index' file. 'Src' contains all Subsystem source code. It is extremely large and very infrequently used. It should be placed on a high- | numbered logical disk, and, at the discretion of the Subsystem | Manager, be protected to prevent unauthorized access. 'Aux' contains several large auxiliary files, particularly the dictionary of English words and the list of prime numbers less than one million. It should be placed on a high-numbered logical disk. Files in 'aux' and its subdirectories should be readable by non-owners, and there should be no non-owner pass- words. An owner password may be employed at the discretion of | the Manager to enforce security. The ACL protections would be | "list", "use", and "read" permissions for everyone. If you | uncomment the template =new_word=, and leave it as | =aux=/spelling/new_words, then this file needs to writeable by | everyone. (Permissions of a/rw, or "read" and "write" ACL | permissions.) 'Doc' contains the formatted and unformatted versions of both the Reference Manual and the User's Guide. It should be placed on a high-numbered logical disk. Generally, its contents should be readable by non-owners. It may be owner password | protected at the discretion of the Manager, but should not have a | non-owner password (ACL permissions of "list", "use", and "read" | for everyone). The same applies to all of its subdirectories. AAAlllttteeerrrnnnaaatttiiivvveee DDDiiirrreeeccctttooorrryyy SSStttrrruuuccctttuuurrreeesss For various reasons (lack of disk space or naming conflicts, for example) the Subsystem manager may need to restructure the Subsystem or even remove portions of it entirely. This section describes the actions necessary to reconfigure the Subsystem directory structure to meet local needs. _T_e_m_p_l_a_t_e_s _a_n_d _T_o_p_-_L_e_v_e_l _D_i_r_e_c_t_o_r_i_e_s. File names (alias "pathnames") in the Subsystem feature a number of extensions beyond the capabilities of Primos treenames. (For a full discus- sion of pathnames, please see the _U_s_e_r_'_s _G_u_i_d_e _t_o _t_h_e _P_r_i_m_o_s _F_i_l_e _S_y_s_t_e_m in the _S_o_f_t_w_a_r_e _T_o_o_l_s _S_u_b_s_y_s_t_e_m _U_s_e_r_'_s _G_u_i_d_e.) The extension that bears on Subsystem directory structure is a simple macro substitution facility that goes by the name of "templates." When an identifier enclosed in equals bars (=) appears in a path- name, it is automatically replaced by some appropriate substitu- tion text. In particular, such "templates" have been provided for the names of all Subsystem top-level directories, and all Subsystem code follows the convention that top-level directories - 8 - Subsystem Manager's Guide are always named by a pathname containing the appropriate tem- plate. Reconfiguration of the Subsystem's directory structure may be accomplished simply by changing the substitution text that replaces the top-level directory templates. The templates and their substitution text may be found in the file 'template' in the directory 'extra' (on the Release Tape). (This file may be edited with either the Primos editor or one of the Subsystem editors.) For example, suppose that the directory 'doc' con- flicts with a local directory of the same name. Edit the tem- plate definition file, and change the following line doc //doc to doc //tools_doc then change the name of 'doc' to 'tools_doc'. The reconfigura- tion is complete. It should be noted that if the name or location of the directory 'extra' or of the template definition file itself is changed, the 'initswt' program run at cold start time must be given a command line argument that specifies the new location of the template file. See the section on Subsystem Installation for further details. As supplied, the template definitions for all top-level Sub- system directories use the omitted-packname option of the path- name syntax. This means that any time one of these directories is referenced, an ascending search of the MFDs on all logical disks is made until the directory is found. If circumstances prevent placement of the frequently-referenced Subsystem direc- tories on low-numbered disks, it is still possible to avoid the overhead of long directory searches by changing the template definitions to include explicit packnames or logical disk num- bers. If this is done, however, the Subsystem must be reinitialized any time one of its directories is moved to another pack. _O_f_f_-_L_i_n_e _S_t_o_r_a_g_e. Certain portions of the Subsystem are not required for everyday usage, and may be removed in order to conserve disk space. The following paragraphs list the direc- tories that may be stored off-line. The source code directory 'src' is extremely large and may be useless on a production system. It may be stored on tape with impunity (although doing so will cause the 'locate' and 'source' commands to cease functioning). The on-line documentation supplied with the Subsystem has been found extremely useful in the past, both to new users learn- ing the system and to expert users needing a refresher course on the usage of particular commands. However, none of it is - 9 - Subsystem Manager's Guide essential to the operation of the Subsystem; the entire directory 'doc' may be stored off-line. As a less drastic measure, the unformatted versions of the Reference Manual and User's Guide that reside in the subdirectories 'man' and 'guide' may be stored off-line, while everything else remains on disk. (This allows the 'help' and 'guide' commands and the 'h' command of 'se' to function properly.) If the dictionary of English words and the list of prime numbers are not frequently used, the directory 'aux' may be | stored off-line. This affects the commands 'spell', 'speling' | and 'rsa', the template =new_words= (if it is defined), and the | local math library routine 'prime'. IIInnnssstttaaallllllaaatttiiiooonnn PPPrrroooccceeeddduuurrreee This section covers the procedures necessary for installa- tion of the Subsystem. It lists the contents of the Installation Package and the Release Tape, and provides instructions for load- ing the tape and initializing the Subsystem. Before reading this section, a thorough study of the SSSuuubbbsssyyysssttteeemmm CCCooonnnfffiiiggguuurrraaatttiiiooonnn section of this Guide is recommended. SSSuuubbbsssyyysssttteeemmm IIInnnssstttaaallllllaaatttiiiooonnn PPPaaaccckkkaaagggeee | For new customers, the Subsystem Installation Package as | sent from Georgia Tech contains the following items: 1 Release Tape | 1 Copy of the Subsystem Manager's Guide | 1 Copy of the Reference Manual | 1 Copy of the User's Guide | Old customers who are updating to Release 9 will only receive the | Release Tape, the Conversion Guide, and the Manager's Guide. RRReeellleeeaaassseee TTTaaapppeee CCCooonnnttteeennntttsss The Subsystem Release Tape contains all files and direc- tories necessary for proper operation of the Subsystem. It is in standard MAGSAV/MAGRST format and contains four "logical tapes." Each logical tape contains a number of separate directories that normally would reside on the same logical disk. _L_o_g_i_c_a_l _T_a_p_e _1. The first logical tape contains the follow- ing three directories: cmdnc0 lib system and these directories contain the following files: - 10 - Subsystem Manager's Guide cmdnc0>swt used to enter the Subsystem cmdnc0>swtseg latest revision of SEG, modified slightly for the Subsystem. Its output is completely compatible with standard SEG. | cmdnc0>snplnk snaps dynamic pointer links (see below) lib>vswtlb shared Subsystem I/O and utility library lib>nvswtlb unshared version of vswtlb * lib>p4clib bootstrap Pascal compiler run-time-support library lib>vedtlb line editor library | lib>vswtmath high precision mathematical function library | lib>shortlb shortcall routines for FORTRAN | lib>vlslb linked string library | lib>vrnglb ring support library | lib>vshlib shared Shell utility library | system>cron.comi example startup file for 'cron' | system>ring.comi example startup file for 'ring' system>sh2030 shared portion of the command interpreter system>st2030 shared data area for templates system>se2031 shared portion of the screen editor system>sw2035 shared portion of the Subsystem library | system>sh4000 used to install the command interpreter system>sw4000 used to install the Subsystem library * system>initswt used to initialize pathname templates These files must be placed in the appropriate Primos directories | at your installation. They should be placed in 'cmdnc0', 'lib', | and 'system' on the lowest-numbered logical disk containing those | directories. _L_o_g_i_c_a_l _T_a_p_e _2. The second logical tape contains the fol- lowing directories: bin lbin extra 'Bin' is the standard Subsystem command directory. It contains the executable versions of all Georgia Tech-supported Subsystem commands. 'Lbin' is a command directory for locally-written tools. Commands in 'lbin' are normally useful at only one installation, or have not been found valuable enough to merit full support. 'Extra' contains miscellaneous information used by various parts of the Subsystem. In particular, it houses the mail, news and memo delivery directories, which tend to grow steadily in size over a period of time. - 11 - Subsystem Manager's Guide _L_o_g_i_c_a_l _T_a_p_e _3. The third logical tape contains the follow- ing directories: vars temp These directories should be placed on a disk partition with a large amount of free space, since files in 'temp' may become arbitrarily large. 'Vars' is used to store personal profile information for all Subsystem users. 'Temp' is a special directory dedicated to containing scratch files. _L_o_g_i_c_a_l _T_a_p_e _4. The fourth logical tape contains the fol- lowing directories: doc src aux These directories are all very large and infrequently accessed. They do not normally vary much in size. 'Doc' contains formatted and unformatted copies of all Sub- system documentation. 'Src' contains all releasable Subsystem source code. 'Aux' contains miscellaneous auxiliary files, such as the dictionary of English words and the list of prime numbers. LLLoooaaadddiiinnnggg ttthhheee TTTaaapppeee To load the release tape, follow the instructions below: 1. Assign a tape drive: | AAASSSSSSIIIGGGNNN MMMTTT000 2. Mount the release tape on the assigned drive. 3. Attach to the master file directory on the logical disk containing 'cmdnc0', 'lib', and 'system' (usually disk 0): | AAATTTTTTAAACCCHHH MMMFFFDDD <<>> <<>> | or if the tape is being restored to an ACL or priority ACL | protected partition, type | AAATTTTTTAAACCCHHH MMMFFFDDD <<>> 4. Load the contents of the first logical tape with MAGRST: | MMMAAAGGGRRRSSSTTT | Tape Unit (9 Trk): 000 - 12 - Subsystem Manager's Guide | Enter logical tape number: 111 | Ready to Restore: yyyeeesss (This will load the files in 'cmdnc0', 'lib', and 'system'.) 5. Attach to the master file directory on the logical disk selected for the 'bin', 'lbin' and 'extra' directories. 6. Load the contents of the next logical tape (i.e., reply "0" | to the "Enter logical tape number:" prompt) with MAGRST. (This will load the directories 'bin', 'lbin' and 'extra'.) 7. Attach to the master file directory on the logical disk selected for the 'temp' and 'vars' directories. It should have ample free space. 8. Load the contents of the next logical tape with MAGRST. (This will load directories 'vars' and 'temp'.) 9. Attach to the master file directory on a logical disk with a great deal of free space. 10. Load the contents of the next logical tape with MAGRST. (This will load directories 'aux', 'doc', and 'src'.) This completes the loading of the Subsystem from tape. RRReeecccooonnnfffiiiggguuurrraaatttiiiooonnn ooofff PPPrrriiimmmooosss fffooorrr ttthhheee SSSuuubbbsssyyysssttteeemmm Primos Revisions 18.0 and above have now used all normally available private memory segments. In order to bring up the Sub- system, it is necessary to increase the NUSEG parameter in the | Primos configuration file to at least 43 (octal), up from the | default of 40 (octal), to provide private segments for the Sub- system that do not conflict with standard Prime programs. It also implies that you cannot bring up the Subsystem without rebooting your system, unless you already have the NUSEG parameter set high enough. IIInnniiitttiiiaaallliiizzzaaatttiiiooonnn ooofff SSShhhaaarrreeeddd SSSeeegggmmmeeennntttsss Several important portions of the Subsystem reside in shared memory segments. Once the release tape is loaded, these segments must be initialized. | One of the enhancements provided with Version 9 is increased | security of shared segments. The SNPLNK ("Snap Link") program | shown in the commands below runs through a given segment and | "snaps" the dynamic subroutine linkages. In other words, all | pointers which are set up as dynamic links are turned into real | pointers. This is usually done when a program runs, by the Ring | 3 pointer fault handler. By snapping all the links at one time, | these segments can then be shared as read only. This will - 13 - Subsystem Manager's Guide | prevent an errant program from scrambling the shared libraries. | Type the following commands on your system console: OPR 1 | SHARE SYSTEM>SW2035 2035 700 | SHARE SYSTEM>SH2030 2030 700 | SHARE SYSTEM>ST2030 2030 700 | SHARE SYSTEM>SE2031 2031 700 R SYSTEM>SW4000 | R SYSTEM>SH4000 R SYSTEM>INITSWT | SNPLNK 1/2030; SHARE 2030 600 | SNPLNK 1/2031; SHARE 2031 600 | SNPLNK 1/2035; SHARE 2035 600 OPR 0 Ideally, the preceding commands would be placed in your cold- | start procedure file CMDNC0>C_PRMO or CMDNC0>PRIMOS.COMI, so they | will be performed automatically after every cold-start. Note: if you have changed the name or location of the template defini- tion file or the 'extra' directory, you must specify the new name of the template file on the invocation of 'initswt'. For exam- ple, if you have changed the name of the 'extra' directory to 'etc', use the following command instead of "r system>initswt": R SYSTEM>INITSWT ETC>TEMPLATE For installations that had a previous release of the Subsystem, this completes the installation procedure. The Subsystem should | now be ready to go. Otherwise, new Subsystem managers should read the next subsection, which describes the remaining steps. IIInnniiitttiiiaaalll LLLoooggg---iiinnn bbbyyy SSSYYYSSSTTTEEEMMM If this is your first Subsystem release, several further steps are necessary to complete installation. As delivered, the Subsystem has only one active user account: that for the login name SYSTEM, which is assumed to be used only by system administrative personnel. Once the Subsystem is loaded and initialized, the Subsystem Manager should log in as user SYSTEM and verify that the Subsystem is working. Login as user SYSTEM and type the following command: swt | If the 'vars' directory was restored on a password partition, | 'swt' will prompt for the owner password of SYSTEM's profile | directory. The Subsystem is delivered with a null password for SYSTEM, so just strike the RETURN key. The shell (Subsystem com- | mand interpreter) will then be executed. If the 'vars' directory | was restored on an ACL partition, the 'swt' will not prompt for | any password, but will immediately execute the shell. Before it - 14 - Subsystem Manager's Guide will accept any commands, the shell will prompt you with "Enter terminal type: ". You should respond with the mnemonic for your terminal type; if you do not know the correct mnemonic, respond with a "?" and the shell will provide a list of accep- table responses. After you have entered an acceptable mnemonic or a RETURN (if you do not wish a terminal type associated with your login session), the shell will be ready to accept commands. You should see a "]" prompt, indicating that the Subsystem is up and running. Modify the file "=installation=" to contain the name of your installation. (The easiest way to do this from the Subsystem is to type a command similar to the following: echo "Georgia Tech System B" >=installation= Simply replace "Georgia Tech System B" with the name of your installation.) Before the Subsystem can be released for general use, profile storage directories must be created for all potential users, and their names must be entered in the "=userlist=" file. In addition, descriptions of all terminals attached to the com- puter must be entered in the "=termlist=" and "=ttypes=" files. For information on these tasks, see the SSSuuubbbsssyyysssttteeemmm MMMaaannnaaagggeeemmmeeennnttt sec- tion of this Guide. RRReeesssooolllvvviiinnnggg SSShhhaaarrreeeddd SSSeeegggmmmeeennnttt CCCooonnnfffllliiiccctttsss If the segment numbers used by the shared Subsystem programs and libraries conflict with those used by other programs at your installation, you can change the Subsystem segment numbers; however, you must first install the Subsystem as supplied. Also | note that you must change the SHARE commands used in your | 'c_prmo' or 'primos.comi' cold start command file to reflect the | changed segment numbers. The Subsystem makes use of three shared segments: 2030 for the Shell and system template table, 2031 for the screen editor 'se', and 2035 for the shared library. | The directory for building the Shell is "=src=/lib/sh". In this directory there is a file named "segment" which contains the segment number to be used for the shared portion of the object code. First, change the contents of this file to the desired | segment number; then simply execute the Shell program 'build'. | This will produce three object codes files, 'sh', the interlude | program which should be placed in "=bin=" as 'sh' and "=system=" | as 'sh4000', "sh", the shared code which should be | copied to "=system=" for automatic sharing by your 'c_prmo' or | 'primos.comi' cold start procedure, and 'vshlib', which should be | copied to "=lib=". This copying can be done by executing the | Shell program 'install'. For example, the following would fix | the shell to run in segment 2037: - 15 - Subsystem Manager's Guide | cd =src=/lib/sh | echo "2037" >segment | build | install Also in segment 2030 is the shared portion of 'swt', the | Subsystem initialization program. To change its segment, attach | (using 'cd') to the directory "=src=/spc/swt.u", change the contents of the file "segment" to the desired segment number, and | execute the shell program 'build', just like changing the Shell's | segments. Then execute 'install' to copy the shared portion in the file "st" into "=system=" and copy 'swt' into "=cmdnc0=". (Please note that if you change the code for 'swt', it must generate no sector-zero links. If it does, you will wipe out the shell when sharing it!) Segment 2030 is also used for the storage of system tem- plates. If you must change the location of their storage area, you must alter the loader interface program 'ld' in order to specify a new absolute address for the storage area, then rebuild the Shell (as outlined above), the libraries (as outlined below), the program 'initswt', and any local program that uses the unshared version of the Subsystem library ('nvswtlb'). For further information on the implications of moving the template storage area, please contact Georgia Tech. The screen editor normally resides in segment 2031. To move it, attach to the directory "=src=/spc/se.u", change the contents of the file "segment" to the desired segment number, then execute the Shell program 'build'. This will yield two object code files: 'se', the interface program that should be placed in "=bin=", and "se", the shared portion that should be placed in "=system=" to be shared in at cold-start time. This copying can be done by executing the Shell program 'install'. The shared libraries normally reside in segment 2035. To move them, attach to the directory "=src=/lib/swt", change the contents of the file "segment" to the desired segment number, then execute the Shell program 'build'. The object code files, 'vswtlb' and 'nvswtlb' should be copied to the "=lib=" directory; the shared code file "sw" should be copied to "=system="; and the file 'inst' should be copied to "=system=" and renamed "sw4000". This copying can be done by executing the | Shell program 'install'. | SSSeeegggmmmeeennntttsss UUUssseeeddd | The following table lists the segments in virtual memory, | and how they are used by the operating system and various Sub- | system programs. | _S_e_g_m_e_n_t _U_s_e | | 0000 - 0401 Operating System - 16 - Subsystem Manager's Guide | 2030 Software Tools Shell | 2031 Software Tools Screen Editor | 2035 Software Tools Library | 2050 Fortran Library | 4000 - 4037 User Program | 4040 Software Tools Common | 4041 Software Tools Stack | 4042 Software Tools Common | 6000 Operating System Data | 6001 Fortran Library | 6002 Primos Ring 3 Stack | 6003 Operating System Stack | Some user programs use certain predefined user segments for their | own use, so you have to be careful where you load your programs. | For instance, if a program uses segment 4006, and you run it from | the shell, from within the screen editor, you will destroy the | screen editor's common blocks. If any of the programs or | routines that use these predefined segments are not in use, they | are available for user programs. For example, If the screen | editor is not in use, segments 4006 and 4007 can be used with no | problem, and if the Primos routine P$ALC is not being used (it is | used by C, Pascal, and PL/I programs) then segments 4010 through | 4027 become available. | _S_e_g_m_e_n_t _U_s_e | | 4000 - 4005 User Program | 4006 - 4007 Screen Editor Per User Common | 4010 - 4027 Primos Dynamic Memory -- P$ALC routine | 4036 - 4037 SEG Symbol Tables | CCChhhaaannngggeeesss fffooorrr PPPrrriiimmmooosss RRReeevvv... 111999...444 | When Rev. 19.4 of Primos is released, you will need to make | two changes to allow you to run the Subsystem under it. First, | change the definition of =cldata= to be "6002 12", instead of | "6002 6". There is a commented out template definition for this | in the =template= file. All you have to do is remove the leading | comment symbol, for this definition, and comment out the old one. | Secondly, in the file =src=/spc/swt.u/init_s.s, change the | definition of CLDATA$SM_FAULT_ERR from "XB%+90" to "XB%+91". | This is because several Primos internal data structures change | their location at Rev. 19.4. - 17 - Subsystem Manager's Guide CCCooonnnvvveeerrrsssiiiooonnn PPPrrroooccceeeddduuurrreee This section contains pointers for re-installing the Sub- system on a system running an older version of the Subsystem. UUUssseeerrr IIImmmpppaaacccttt Before trying to use a newer Subsystem release, first study the Conversion Guide included with the new release to determine what, if any, impact will be felt by your user community. If you need complete information on the changes made to programs, you can load the documentation directories "//doc/fman" and "//doc/fguide" from the release tape. Usually, a Subsystem release is largely compatible with the release it replaces. Those incompatibilities that do exist are noted in the Conversion Guide. If incompatible changes have been made to a command so that you determine it unreasonable to force your user community to convert to the new command, you have several alternatives: (1) you can write shell programs to cover the incompatibilities, (2) in many cases, you can install the old command from the previous release (you may have to recompile it, though), or (3) you can not install the new Subsystem release. If you find it necessary to take the third alternative, please contact us so that we can try to find a better solution to your dilemma. Compatibility is a different story when you have locally modified versions of Subsystem programs or you have locally writ- ten programs that take advantage of "secret knowledge" of the Subsystem's internals. In this situation, you must examine the newly released programs that interface with your local software to determine the changes necessary to interface with the new release. If you have difficulty in this area, please contact us and perhaps we can suggest possible solutions. IIInnnssstttaaalllllliiinnnggg ttthhheee NNNeeewww SSSuuubbbsssyyysssttteeemmm Once you have determined the suitability of the new Sub- system release and have mapped out a conversion plan, you are ready to test and install the new release. Unfortunately, two different versions of the Subsystem cannot run simultaneously because the Primos shared library mechanism has no provision for duplicate shared entry points. Therefore, to test and install the new Subsystem, you must bring up the new Subsystem only when no other users are running with the old Subsystem. Before loading the new release, you must first save the old Subsystem files and directories. You can then immediately restore the old Subsystem in the case that the new one malfunc- | tions. If you have about 16 million bytes of disk available, you can just change the directory names: - 18 - Subsystem Manager's Guide CNAME BIN OLD_BIN CNAME LBIN OLD_LBIN CNAME DOC OLD_DOC CNAME SRC OLD_SRC CNAME EXTRA OLD_EXTRA CNAME AUX OLD_AUX Otherwise, you must copy the directories to tape (or removable disk) and delete the original versions. If you copy the files to tape, copy 'extra' and change its name; do not remove it from disk -- you will need it later. Do not change the directories 'vars' and 'temp'; these can be used as they are. Be sure to save the Subsystem files in 'cmdnc0', 'lib', and 'system'. Then, load the release tape just as explained in the IIInnnssstttaaalll- lllaaatttiiiooonnn PPPrrroooccceeeddduuurrreee section, leaving out the load of 'vars' and 'temp'. After you place the new Subsystem files in 'system', 'cmdnc0', and 'lib', re-boot your system. (Unless you are familiar with the shared library re-installation procedures, a re-boot is the only safe way to re-install a shared library.) | The new Subsystem should now be available for use. | WWWhhhaaattt TTTooo DDDooo AAAbbbooouuuttt PPPrrreee---888...111 PPPrrrooogggrrraaammmsss | Any calls to the subroutine 'init' should be removed from | your programs. You should then recompile them, making sure that | nothing depends on the value of EOS being less than 0. In fact, | no program should depend on any properties of EOS. The Version 8 | Compatiblity libraries are no longer supported. You may, at your | own risk, continue using the V8-compatible libraries supplied | with Release 8.1. | MMMooodddiiifffiiicccaaatttiiiooonnnsss tttooo SSSuuubbbsssyyysssttteeemmm FFFiiillleeesss | Once you have installed the new release, you must move your | local modifications into 'extra'. First, compare the files | "=extra=/template" and "//old_extra/template" (using 'diff', if | you like); add any local templates to "=extra=/template". Then | update the templates: Exit the Subsystem and type | OPR 1 | SHARE 2030 700 | R SYSTEM>INITSWT | SHARE 2030 | OPR 0 Copy the following files from 'old_extra' to 'extra': installation phones terms users - 19 - Subsystem Manager's Guide | The 'users' file has changed format (see the section on adding | and deleting users under SSSuuubbbsssyyysssttteeemmm MMMaaannnaaagggeeemmmeeennnttt) so you might want | to copy it the following way | =ebin=/cvusr old_extra/users extra/users | =ebin=/cvusr is a shell file that takes the pathnames of the old | userlist and the new userlist as arguments, and expands the login | names to the 32 character length needed by the 'whois' program. | This conversion only needs to be done once, when the new Sub- | system is first installed and brought up. New customers do not | have to do this, of course. Delete the following directories in 'extra' and copy them from 'old_extra' using 'cp': gossip mail memo moot.u news You may want to examine the articles in 'news' before replacing them with your local articles. You must examine the following files and directories in 'extra' to determine if local changes need to be made: bug fmacro incl numsg ttypes vth | The shell uses a slightly different shell variable save file | format to allow special characters to be encoded as mnemonics and | prevent the file from getting scrambled if NEWLINE characters are | accidently entered in a variable's value. A program, 'csv', is | supplied to make this change simpler for each of the users. | 'Csv' takes a list of user names as standard input, opens up the | file "=vars=//.vars" and changes the appropriate shell | variable values. This will only need to be done when the system | is first brought up. If the directory "=vars=" contains only | user variable directories then a simple command to perform the | conversion is | lf -c =vars= | =ebin=/csv | or another way, if it contains other files, is to list the names | into a file, edit the file, and then redirect the input into | 'csv'. For example: - 20 - Subsystem Manager's Guide | lf -c =vars= >user_names | se user_names # make any changes here | user_names> =ebin=/csv | del user_names # don't need it any more Now, you may perform any tests that you like. We suggest that at minimum, you try the screen editor, a few shell files, and any other commands that are frequently used on your system. DDDooocccuuummmeeennntttaaatttiiiooonnn SSStttrrruuuccctttuuurrreee Given a question about the Subsystem, where does one go in order to find the answer? This section attempts to address this problem, at least to the extent of enabling the Subsystem Manager to identify the document required and produce a printed copy of it if needed. Software Tools Subsystem documentation is divided into two parts: the Reference Manual and the User's Guide. The Reference Manual is mostly technical information: usage summaries, listings of differences from standard _S_o_f_t_w_a_r_e _T_o_o_l_s programs, etc. The User's Guide is mostly "soft" information: tutorials, applications notes, and the like. Each has its place, and must be accessed in its own way. RRReeefffeeerrreeennnccceee MMMaaannnuuuaaalll The Reference Manual is normally the first port of call for anyone seeking an answer to a specific question. The Manual is composed of a number of entries, one for each command or sub- program in the Subsystem, divided into six sections: standard (i.e., supported by Georgia Tech) commands, standard subprograms, local (i.e., supported by the local installation, or not at all) commands, local subprograms, low-level commands, and low-level subprograms. The Manual is indexed by a simple list of entries and by an automatically generated key-word-in-context index. A copy of the Reference Manual, formatted for 8.5" by 11" paper at 10 characters per inch horizontal, 6 lines per inch vertical, may be spooled for printing with the command =doc=/print/man Frequent use of this command is not recommended because of the * manual's sheer size. Individual Manual entries may be printed with the 'help' command. Simply typing help ... or help ... - 21 - Subsystem Manager's Guide will cause the selected Manual entries to be printed on the user's terminal, with a pause between each screenful. The user may also type help -p | os >/dev/lps/f to obtain a printed copy of an entry exactly as it appears in the Manual. 'Help' may also be used to read the Manual's index. If "-i" is used in place of a command name, then the Manual's index will be printed. If "-f " is used in place of a command name, then only those index entries matching the given pattern will be printed. For example, all commands and subprograms whose Manual entry heading lines contain the word "string" could be identified by typing help -f string This may be useful for people just learning to use the Subsystem, who may know several names for a function they wish to perform, but not the exact command or subprogram they need. An unformatted copy of the Reference Manual resides in the directory "=doc=/man". A formatted version resides in "=doc=/fman". Should it ever be necessary to rebuild the format- ted version, simply type =doc=/build/man UUUssseeerrr'''sss GGGuuuiiidddeee The Guide is recommended for anyone just learning to use the Subsystem, as well as for those requiring a deeper knowledge of the workings of some of the more complex tools. It is actually a collection of separate papers, arranged roughly in the order required by a novice user. It is not intended as a quick reference; the Reference Manual performs that function. Most papers in the Guide contain a tutorial section and an applications notes section, for beginners and experienced users, respectively. Some papers also contain a formal definition sec- tion; these would be of use only to those requiring a very com- plete understanding of the workings of the Subsystem. The entire User's Guide, formatted for 8.5" by 11" paper, 10 characters per inch horizontal, 6 lines per inch vertical, may be spooled for printing by executing the following command: =doc=/print/guide The Guide is small enough that this operation is not overly expensive in terms of time or paper. - 22 - Subsystem Manager's Guide The 'guide' command may be used to print the individual papers that comprise the Guide. For example, guide ed would print the _I_n_t_r_o_d_u_c_t_i_o_n _t_o _t_h_e _S_o_f_t_w_a_r_e _T_o_o_l_s _T_e_x_t _E_d_i_t_o_r on the user's terminal, pausing after each screenful. To obtain a printed copy instead, one should type guide -p ed | os >/dev/lps/f It is generally good policy to have a number of copies of the _S_o_f_t_w_a_r_e _T_o_o_l_s _S_u_b_s_y_s_t_e_m _T_u_t_o_r_i_a_l and the _I_n_t_r_o_d_u_c_t_i_o_n _t_o _t_h_e _S_o_f_t_w_a_r_e _T_o_o_l_s _T_e_x_t _E_d_i_t_o_r on hand for distribution to new users. An unformatted copy of the User's Guide resides in the directory "=doc=/guide". Should it ever be necessary to rebuild the formatted copy in "=doc=/fguide", it can be done by typing =doc=/build/guide SSSuuubbbsssyyysssttteeemmm MMMaaannnaaagggeeemmmeeennnttt This section outlines the day-to-day responsibilities of the Subsystem Manager: adding and removing user accounts, keeping track of local hardware configuration changes, maintaining local tools, etc. AAAddddddiiinnnggg aaannnddd DDDeeellleeetttiiinnnggg UUUssseeerrrsss Adding and deleting Subsystem user accounts boils down to the maintenance of one file and one directory. The list of authorized users is addressed by the template "=userlist=". On a standard Subsystem, it resides in the file //extra/users. There is one line in the user list corresponding to each authorized Subsystem user. Users may appear in any order in the user list, although conventionally it is kept sorted alphabetically. The format of a line in the user list is as fol- lows: Columns Information | 1-32 User's login name, in upper case, left- justified, blank-padded | 33 Blank | 34-80 User's name and commentary information | Example: | 123456789012345678901234567890123456789... | BURDELL George P. Burdell (Development) - 23 - Subsystem Manager's Guide Whenever someone is added to the Subsystem user community, an appropriate entry must be made in "=userlist=". Whenever a user is no longer authorized to use the system, his entry must be removed. Each Subsystem user possesses a "profile" directory, which must be created for him by the Subsystem Manager. When adding an | account, create the profile directory with the command mkdir =vars=/ -o | if it is a password directory or just | mkdir =vars=/ | sacl =vars=/ =adlurw $rest=lu | if it is an ACL protected directory. "" represents the login name of the new user. "" represents a stan- dard file system owner password, which must be cited by the user | when he enters the Subsystem if his variables directory is pass- | word protected. Example: mkdir =vars=/gpb -o sesame When a user is removed from the system, his profile directory must be deleted. This can be done most conveniently with the 'del' command: del -sd =vars=/: For example, del -sd =vars=/gpb:sesame In addition to the above measures for removing a user's account, the Subsystem Manager should check for any undelivered mail, gos- sip messages, or news articles. See the OOOpppeeerrraaatttiiiooonnn ooofff CCCooommm- mmmuuunnniiicccaaatttiiiooonnnsss SSSyyysssttteeemmmsss subsection below. SSSpppeeeccciiifffyyyiiinnnggg LLLooocccaaalll HHHaaarrrdddwwwaaarrreee CCCooonnnfffiiiggguuurrraaatttiiiooonnn The screen editor 'se' and a number of other programs that employ the virtual terminal handler library need to know the type and make of the terminals attached to each AMLC line on the system. This information is contained in the terminal list, which resides in the file "=termlist=" (nominally "//extra/terms"). Each line of the terminal list has the follow- ing format: - 24 - Subsystem Manager's Guide Columns Information 1-3 Octal AMLC line number (000-177) 4 Blank 5-9 Three digit decimal user number of associated process, in parentheses 10 Blank 11-16 Terminal type (as recognized by the Subsystem); blank if unknown 17 Blank 18-80 Comments (usually physical location of terminal, etc.) For example: 12345678901234567890... 007 (009) b200 George Burdell's office (Room 1729) The contents of the "=termlist=" file must be kept up-to-date, or the 'e', 'whereis', 'se', and 'term_type' commands will cease to operate properly. AAAddddddiiinnnggg TTTeeerrrmmmiiinnnaaalll TTTyyypppeeesss | To extend the terminal type knowledge of the Subsystem, | there are three places where changes need to be made in Subsystem files. These locations are the "=ttypes=" file, the "=vth=" directory, and various files under the screen editor directory, | "=src=/spc/se.u". In all cases, the mnemonic for the new | terminal may not be longer than six characters. The "=ttypes=" file contains the terminal's general attributes. Its format consists of a mnemonic for the terminal name, the full terminal name, and then a series of flags. These flags currently indicate whether the terminal type is supported by 'se', whether the terminal type is supported by the VTH pac- kage, and whether the terminal type represents an upper-case only terminal. The file "=src=/spc/se.u/how_to_add_terminal_types" gives the details on adding new terminal types to the screen editor. Basically, new code must be added for the cursor movement routines and the editor must be recompiled and installed so that | it incorporates the new code. Also, the screen editor's 'usage' | routine, as well as the Reference Manual entry, should be updated | to include the mnemonic of the new terminal. To add a new terminal type to the VTH package, an initialization file must be created in the "=vth=" directory, with the same name as the mnemonic that you have chosen for that terminal type. To find out what the format and contents of this file should be, please refer to the other files in that directory for examples. * AAAddddddiiinnnggg LLLooocccaaalll TTToooooolllsss aaannnddd LLLiiibbbrrraaarrryyy RRRooouuutttiiinnneeesss - 25 - Subsystem Manager's Guide When the Subsystem is used for program development, there is a tendency for an installation to collect a set of locally-useful tools. Here are a few suggestions on how to incorporate these local tools into the Subsystem environment. Of course the primary repository for local commands is the directory 'lbin'. The Georgia Tech 'lbin' is supplied on the release tape as an example of a local command library, and because some of the commands contained therein may be of general use. To place a local tool in 'lbin', simply copy its object code into the directory and use the 'chat' command to make sure | it is readable by all users, or if the 'lbin' is ACL protected | then the command will automatically be readable. Since the command search rule employed by the command interpreter may be changed by the user, any number of local com- mand directories may be created. For example, a directory named 'games' might be created for the purpose of keeping employees out of the local arcade at lunchtime. A search rule including this directory might be ^int,^var,&,=lbin=/&,=bin=/&,//games/& Any of the programs in 'games' may then be invoked without need for using their full pathnames. Of course, local subprogram libraries may also be created at will. As with standard Primos, the only steps necessary to make such libraries accessible are to place them in 'lib' and make them readable by all users. AAAddddddiiinnnggg LLLooocccaaalll DDDooocccuuummmeeennntttaaatttiiiooonnn If local tools and libraries are added to the Subsystem (as outlined above), there will be a need for some means of document- ing them. Sections three and four of the Reference Manual are provided for this purpose. Section three of the Manual deals with local commands. To document such a command, one places a standard documentation file in "=doc=/man/s3" and uses "=doc=/build/rebuild" to place a formatted copy in "=doc=/fman/s3". The documentation may then be extracted by the 'help' command, or printed with the entire manual by executing "=doc=/print/man". A standard documentation file for a command has several distinguishing characteristics. First, the documentation for a tool named "xxx" resides in a file named "xxx.d". Second, the structure of the file's contents is determined by a number of standard text formatter macro commands. Each macro begins a separate subject in a manual entry. They must appear in the fol- lowing order: ".hd" (heading), ".ds" (description), ".es" (exam- ples), ".fl" (files used), ".me" (messages issued), ".bu" (bugs and deficiencies), and ".sa" (see also). If a section is empty, it should be omitted entirely. - 26 - Subsystem Manager's Guide Once a documentation file has been entered, it must be formatted and the formatted copy placed in a separate directory. The shell program "=doc=/build/rebuild" has been provided for this purpose. An example: =doc=/build/rebuild s3 xxx This would format the file "=doc=/man/s3/xxx.d" and place the result in "=doc=/fman/s3/xxx.d", where it may be accessed by 'help' and 'usage'. Section four of the Manual deals with local library sub- programs. The documentation procedure for subprograms is similar to that for major tools; an unformatted copy of the documentation is placed in "=doc=/man/s4", and a formatted copy in "=doc=/fman/s4". Again, this makes the documentation available through 'help'. Formatter macros for library routine documentation differ somewhat from those for command documentation. In order, they are: ".hd" (header), ".fs" (function of subprogram), ".im" (implementation sketch), ".am" (arguments modified by sub- program), ".ca" (other subprograms called by this subprogram), ".bu" (bugs or deficiencies), and ".sa" (see also). Again, if a section is empty, it should be omitted entirely. The rebuild procedure for subprogram documentation is very similar to that for command documentation; simply use "s4" in | place of "s3" in the "rebuild" command. | OOOpppeeerrraaatttiiiooonnn ooofff ttthhheee '''CCCrrrooonnn''' PPPrrrooogggrrraaammm | One of the new features of Version 9 of Software Tools is | the 'cron' program, which allows the system administrator to | arrange for the computer to automatically do tasks of a periodic | nature. The manual entry for 'cron' (help cron) will give you | the information you need in setting up 'cron'. As distributed, | "=cronfile=", contains an example entry and a brief description | of what cronfile entries should look like, and | "=system=/cron.comi" contains an example startup file to | initialize 'cron'. 'Cron' executes as an ordinary Software Tools | user so it must have an entry in "=varsdir=" and "=userlist=" | (see AAAddddddiiinnnggg aaannnddd DDDeeellleeetttiiinnnggg UUUssseeerrrsss in this section). The 'cron' user | must have all permission to the directory "=crondir=". As sup- | plied, 'cron' expects to be run as the system administrator with | an ACL protecting "=crondir=" ("=crondir=" is protected with | SYSTEM having $all access and everyone else has "list" and "use" | privileges). | The supplied Primos routine SPH should be used to start | 'cron'. The following command should be entered at the console | or placed in the Primos cold start command file ('c_prmo' or | 'primos.comi'): - 27 - Subsystem Manager's Guide | SPH SYSTEM>CRON.COMI -U -P -V 1 -G | where is the name under which 'cron' should run, | is 'cron's login project, and is the list of | file system groups with which the 'cron' user should be | associated. For example, the following will startup 'cron' with | all the default attributes and no groups: | SPH SYSTEM>CRON.COMI -U SYSTEM -P DEFAULT -V 1 -G OOOpppeeerrraaatttiiiooonnn ooofff CCCooommmmmmuuunnniiicccaaatttiiiooonnnsss SSSyyysssttteeemmmsss The Subsystem provides three different means of passing information from user to user: the postal service, the grapevine, and the news service. _P_o_s_t_a_l _S_e_r_v_i_c_e. Most electronic communication between Sub- system users is accomplished through the mail system. The 'mail' command stores arbitrary messages in the directory "=mail=" (nominally "//extra/mail"), from where they may be retrieved by the addressee at a later time. All letters are postmarked with the time of mailing and the login name of the sender. Whenever a user enters the Subsystem via 'swt', he is informed if there is any undelivered mail addressed to him. _G_r_a_p_e_v_i_n_e. 'Mail' is not real-time; a letter sent is | generally not received until the next time a user enters the Sub- | system, or if the user has set his mail notification in the | Shell, the next time the Shell notifies him. The "grapevine" managed by the 'to' command alleviates some of this problem. Messages sent from user to user via 'to' are stored in the direc- tory "=gossip=" (nominally "//extra/gossip"), which is searched by the command interpreter before executing each terminal-level command. Thus, the delay between sending a message with 'to' and its receipt by the addressee is no longer than the longest time he spends executing a command. Since users typically spend a great deal of time text editing, the screen editor has also been given the ability to display a message sent by 'to'. See the "om" command in 'se' for details. _N_e_w_s _S_e_r_v_i_c_e. Occasionally an item of general interest or special importance must be delivered to the user community at large. The Subsystem news service provides a means of delivering these articles, while making an archival copy of them and placing their headlines in an index file for later reference. Since the disk space required to store undelivered news articles may be prohibitively expensive, users who wish to receive news must "subscribe" to the service with the 'subscribe' command. This need only be done once in an account's lifetime. The list of subscribers may be found in the file "=news=/subscribers". - 28 - Subsystem Manager's Guide News articles are published with the 'publish' command. 'Publish' takes one file name argument. The named file is copied into the news boxes ("=news=/delivery/") of all sub- scribers, an archival copy is made in "=news=/articles", and the first line is entered into the index file "=news=/index" for later reference. News articles that were published incorrectly or are out- dated may be removed with the 'retract' command. 'Retract' can remove one or more articles at one time by specifying the article numbers as arguments. A notice of retraction for each article removed is placed in the news boxes of all subscribers who have seen the retracted article; subscribers who have not seen a retracted article are not notified of the retraction. Since removal of outdated news articles is not of great importance, such articles may be retracted quietly by using the "-q" option. When a subscriber enters the Subsystem, he is informed if there is any news he has not yet seen. He may then retrieve the article with the 'news' command. At any time, he may also use the 'news' command to review the index or any archived articles. MMMooodddiiifffyyyiiinnnggg ttthhheee DDDiiiccctttiiiooonnnaaarrryyy ooofff EEEnnngggllliiissshhh WWWooorrrdddsss The dictionary of words supplied with the Subsystem is still | rather incomplete, and may require additions from time to time. | The template =new_words= is commented out in the system tem- | plate file. If you make it an active template (by removing the | comment symbol), the 'spell' program will write into =new_words= | any words it finds which are not in the dictionary. (=new_words= | is defined to be =aux=/spelling/new_words.) You may then wish to | periodically clean up the file as follows: | cd =aux=/spelling | sort new_words | uniq >new_words | which will sort the file and remove duplicate entries. You can | then go through the file with a dictionary, and remove words | which are misspelled. | To add new words to the dictionary, the following procedure | is recommended. | Obtain a list of words to be added, or use =new_words= as | described above (or both). Obtain from each word as many derivative words as possible, by changing prefixes and suffixes, forming compounds, etc. Check each of these for correct spel- ling. | Attach to the directory "=aux=/spelling/new" and split the | new words into the word files there according to the following scheme: - 29 - Subsystem Manager's Guide dictionary ordinary English words gazetteer names and trademarks abbreviations abbreviations, acronyms glossary computer science terms Words may appear in more than one file; for example, "assemble" may appear both in the dictionary and in the glossary. When the new words have been split to their respective | files, append these files onto the files of the same name in | "=aux=/spelling." You may then empty out the files in | "=aux=/spelling/new" by 'echo'ing into them. Go back to | "=aux=/spelling", and execute the shell program 'build', which combines the files to form the file 'words', which is used by the | spelling check program. You may also run the program 'info' in | "=aux=/spelling" for more information. - 30 - ___TTT___AAA___BBB___LLL___EEE___ ___OOO___FFF___ ___CCC___OOO___NNN___TTT___EEE___NNN___TTT___SSS OOOvvveeerrrvvviiieeewww ................................................. 1 Purpose ............................................... 1 Summary of Contents ................................... 1 SSSuuubbbsssyyysssttteeemmm CCCooonnnfffiiiggguuurrraaatttiiiooonnn .................................. 2 Standard Directory Structure .......................... 2 Top-Level Directories .............................. 6 Directory Security and Placement on Disk ........... 6 Alternative Directory Structures ...................... 8 Templates and Top-Level Directories ................ 8 Off-Line Storage ................................... 9 IIInnnssstttaaallllllaaatttiiiooonnn PPPrrroooccceeeddduuurrreee ................................... 10 Subsystem Installation Package ........................ 10 Release Tape Contents ................................. 10 Logical Tape 1 ..................................... 10 Logical Tape 2 ..................................... 11 Logical Tape 3 ..................................... 11 Logical Tape 4 ..................................... 12 Loading the Tape ...................................... 12 Reconfiguration of Primos for the Subsystem ........... 13 Initialization of Shared Segments ..................... 13 Initial Log-in by SYSTEM .............................. 14 Resolving Shared Segment Conflicts .................... 15 Segments Used ......................................... 16 Changes for Primos Rev. 19.4 ......................... 17 CCCooonnnvvveeerrrsssiiiooonnn PPPrrroooccceeeddduuurrreee ..................................... 18 User Impact ........................................... 18 Installing the New Subsystem .......................... 18 What To Do About Pre-8.1 Programs ..................... 19 Modifications to Subsystem Files ...................... 19 DDDooocccuuummmeeennntttaaatttiiiooonnn SSStttrrruuuccctttuuurrreee .................................. 21 Reference Manual ...................................... 21 User's Guide .......................................... 22 SSSuuubbbsssyyysssttteeemmm MMMaaannnaaagggeeemmmeeennnttt ..................................... 23 Adding and Deleting Users ............................. 23 Specifying Local Hardware Configuration ............... 24 Adding Terminal Types ................................. 25 Adding Local Tools and Library Routines ............... 25 Adding Local Documentation ............................ 26 Operation of the 'Cron' Program ....................... 27 Operation of Communications Systems ................... 28 Postal Service ..................................... 28 Grapevine .......................................... 28 News Service ....................................... 28 - iii - Modifying the Dictionary of English Words ............. 29 - iv -