.MH "Subsystem Configuration"
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 conventions that must be followed if
changes are made.
.SH "Standard Directory Structure"
The following chart outlines the structure of the major
Subsystem directories as supplied on the Release Tape:
.nf
.sp 2
.ne 4
[bf aux]
    [bf primes]  (file of prime numbers less than 1,000,000)
    [bf spelling]
        [bf {dictionaries of English words, place names, etc.}]

.ne 2
[bf bin]
    [bf {standard Subsystem commands, supported by GT}]

.ne 2
[bf lbin]
    [bf {locally-supported commands}]

.ne 2
[bf temp]
    [bf {scratch files created by Subsystem programs}]

[cc]mc |
.ne 6
[cc]mc
[bf vars]
    [bf {subdirectory for each user}]
        [bf .mail]     (old mail storage)
        [bf .vars]     (shell variable storage)
        [bf .template] (user template definitions)
[cc]mc |
        [bf .hist]     (user shell session storage)
[cc]mc

.ne 3
[bf extra]
    [bf bin]
        [bf {programs called by shell files in 'bin'}]

.ne 2
    [bf bug]
        [bf {bug reports gathered by 'bug'}]

.ne 2
[cc]mc |
    [bf cron]
        [bf {example files for use by the 'cron' program}]

[cc]mc
    [bf clist] (list of command names used by 'guess')

.ne 2
    [bf gossip]
        [bf {file for each user, for messages sent by 'to'}]

[cc]mc *
[cc]mc
    [bf installation] (installation name)

.ne 2
    [bf mail]
        [bf {file for each user, for messages sent by 'mail'}]

.ne 2
    [bf memo]
        [bf {file for each user, for memoranda from 'memo'}]

.ne 2
    [bf moot.u]
        [bf {files used by 'moot'}]

.ne 9
    [bf news]
[cc]mc *
[cc]mc
        [bf articles]
            [bf {files containing one news article each}]
        [bf index]       (index to all past news articles)
        [bf subscribers] (list of news service subscribers)

        [bf delivery]
            [bf {file for each user, for undelivered news}]

    [bf phones] (list of phone numbers used by 'phone')

    [bf terms] (list of terminals attached to the system)

    [bf users] (list of authorized Subsystem users)

.ne 2
    [bf fmacro]
        [bf {miscellaneous text formatter macro files}]

.ne 2
    [bf incl]
[cc]mc |
        [bf {macro definitions for Ratfor, C, and PMA}]
[cc]mc

    [bf numsg]    (propaganda message sent to new users)

    [bf template] (pathname template definition file)

.ne 2
    [bf vth]
        [bf {files describing terminal hardware characteristics}]

.ne 2
    [bf ttypes] (list of Subsystem-supported terminals and their
        characteristics)

.ne 14
[bf src]

    [bf lcl]
        [bf lib]
            [bf {subdirectories for locally-supported libraries}]
        [bf spc]
            [bf {subdirectories for local programs with non-]
             [bf standard compilation requirements}]
        [bf std.r]
            [bf {source files for local Ratfor programs}]
        [bf std.sh]
            [bf {source files for local shell programs}]
        [bf std.stacc]
            [bf {source files for local Ratfor/'stacc' programs}]

.ne 3
    [bf lib]
[cc]mc |
        [bf c$main]
                [bf {files to build the C startoff routine ---]
                [bf only for sites which license the C compiler}]
.ne 3
        [bf cio]
            [bf {source files for C I/O library --- only for]
            [bf  sites which license the C compiler}]
.ne 2
[cc]mc
        [bf edt]
            [bf {source files for line editor routines}]
[cc]mc |
.ne 2
        [bf math]
            [bf {source files for 'vswtmath' library}]
.ne 4
        [bf sh]
            [bf src]
                [bf {source files and directories for 'vshlib'}]
            [bf {miscellaneous files for 'vshlib'}]
[cc]mc
.ne 6
        [bf swt]
            [bf obj]
                [bf {object code files for 'vswtlb' routines}]
            [bf src.a]
                (archive containing source code for 'vswtlb' routines)
            [bf {miscellaneous files for library 'vswtlb'}]
[cc]mc |
.ne 3
        [bf vcg]
            [bf {source files for the vcg support library ---]
            [bf  only for sites which license the C compiler}]
.ne 3
        [bf vcg_main]
            [bf {source for main routine for vcg for individuals]
            [bf  that have written their own front ends for vcg ---]
            [bf  only for sites which license the C compiler}]
[cc]mc

.ne 3
    [bf spc]
        [bf {subdirectories for programs with nonstandard]
         [bf compilation requirements}]

.ne 2
    [bf std.r]
        [bf {source files for standard Ratfor programs}]

.ne 2
    [bf std.sh]
        [bf {source files for standard shell programs}]

.ne 2
    [bf std.stacc]
        [bf {source files for standard Ratfor/'stacc' programs}]

[cc]mc |
.ne 3
    [bf ext.c]
        [bf {source files for C programs in "=ebin=" --- only]
        [bf  for sites which license the C compiler}]

[cc]mc
.ne 2
    [bf ext.r]
        [bf {source files for Ratfor programs in "=ebin="}]

.ne 2
    [bf ext.sh]
        [bf {source files for shell programs in "=ebin="}]

[cc]mc |
.ne 2
    [bf misc]
        [bf {Subsystem support and maintenance routines}]

[cc]mc
.ne 5
[bf doc]
    [bf build]
        [bf guide]   (format a new version of the User's Guide)
        [bf man]     (format a new version of the Reference Manual)
        [bf rebuild] (format a new Reference Manual entry)

.ne 3
    [bf fguide]
        [bf {files containing formatted portions of the]
         [bf User's Guide}]

.ne 14
    [bf fman]
        [bf s1]
            [bf {formatted standard command documentation}]
        [bf s2]
            [bf {formatted standard library documentation}]
        [bf s3]
            [bf {formatted local command documentation}]
        [bf s4]
            [bf {formatted local library documentation}]
        [bf s5]
            [bf {formatted low-level command documentation}]
        [bf s6]
            [bf {formatted low-level library documentation}]
        [bf {miscellaneous formatted portions of Reference Manual}]

.ne 3
    [bf guide]
        [bf {subdirectories containing portions of the User's]
         [bf Guide, unformatted}]

.ne 2
    [bf hist]
        [bf history] (history of changes to the Subsystem)

.ne 14
    [bf man]
        [bf s1]
            [bf {unformatted standard command documentation}]
        [bf s2]
            [bf {unformatted standard library documentation}]
        [bf s3]
            [bf {unformatted local command documentation}]
        [bf s4]
            [bf {unformatted local library documentation}]
        [bf s5]
            [bf {unformatted low-level command documentation}]
        [bf s6]
            [bf {unformatted low-level library documentation}]
        [bf {miscellaneous unformatted portions of Reference Manual}]

.ne 3
    [bf print]
        [bf guide] (print a copy of the User's Guide)
        [bf man]   (print a copy of the Reference Manual)

.ne 2
    [bf se_h]
        [bf {files containing on-line help information for 'se'}]

[cc]mc |
.ne 2
    [bf misc]
        [bf {Documentation support and maintenance routines}]

[cc]mc
.ne 6
.fi
.PH "Top-Level Directories"
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.)
.pp
[cc]mc |
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 operating 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 Subsystem properly.
The 'lib' directory used for Subsystem libraries must also be
[cc]mc
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.
.PH "Directory Security and Placement on Disk"
[cc]mc |
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,
substantial 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.
[cc]mc
.pp
The directories 'bin' and 'lbin' are accessed very frequently
(about once per command) and so should be located on a low-numbered
logical disk.
[cc]mc |
The files in these directories must be readable by non-owners
but should be protected against alteration 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.
[cc]mc
(But see the
[ul User's Guide for the Software Tools Subsystem Command Interpreter],
for information on "search rules.")
.pp
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.
[cc]mc |
'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.
[cc]mc
.pp
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 password to preserve the privacy
of individual users; it may not have a non-owner password.
[cc]mc |
If 'vars' is made an ACL protected directory, it should have
permissions of "list" and "use" for everyone.
[cc]mc
The Subsystem manager must create in 'vars' a subdirectory 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.
[cc]mc |
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
[cc]mc
internally before entering the Subsystem; this saved password is then
used in all future references to the directory by the Subsystem.
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.
.pp
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 subdirectories should be readable
by non-owners and free of non-owner passwords.
[cc]mc |
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.
[cc]mc
The subdirectories 'mail', 'gossip', and 'memo' must be public
[cc]mc |
so that anyone can create a file in them ("list", "use", "add", "delete",
"read", and "write").
[cc]mc
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.
.pp
'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
[cc]mc |
discretion of the Subsystem Manager, be protected to prevent
[cc]mc
unauthorized access.
.pp
'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 passwords.
An owner password may be employed at the discretion of the Manager
to enforce security.
[cc]mc |
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.)
[cc]mc
.pp
'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
[cc]mc |
Manager, but should not have a non-owner password (ACL permissions
of "list", "use", and "read" for everyone).
[cc]mc
The same applies to all of its subdirectories.
.SH "Alternative Directory Structures"
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.
.PH "Templates and Top-Level Directories"
File names (alias "pathnames") in the Subsystem feature a number
of extensions beyond the capabilities of Primos treenames.
(For a full discussion of pathnames, please see the
[ul User's Guide to the Primos File System] in the
[ul Software Tools Subsystem User's Guide].)
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 pathname, it is automatically replaced by some appropriate
substitution 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 are always
named by a pathname containing the appropriate template.
.pp
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' conflicts with a
local directory of the same name.
Edit the template definition file, and change the following line
.be 5
doc         //doc
.ee
to
.be
doc         //tools_doc
.ee
then change the name of 'doc' to 'tools_doc'.
The reconfiguration is complete.
.pp
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.
.pp
As supplied, the template definitions for all top-level Subsystem
directories use the omitted-packname option of the pathname 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 directories 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
numbers.
If this is done, however, the Subsystem must be reinitialized any
time one of its directories is moved to another pack.
.PH "Off-Line Storage"
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 directories that may be stored
off-line.
.pp
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).
.pp
The on-line documentation supplied with the Subsystem has been found
extremely useful in the past, both to new users learning the system
and to expert users needing a refresher course on the usage of
particular commands.
However, none of it is 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.)
.pp
If the dictionary of English words and the list of prime numbers
are not frequently used, the directory 'aux' may be stored off-line.
[cc]mc |
This affects the commands 'spell', 'speling' and 'rsa',
the template =new_words= (if it is defined),
and the local math
[cc]mc
library routine 'prime'.
