Return to 3.2 CVS log

Up to [CSRG BSD Unix] / 43BSD / contrib / notes / doc

Annotation of 43BSD/contrib/notes/doc/3.2, revision 1.1

1.1     ! root        1: .ls 1
        !             2: .se "Initial Installation & Parameters"
        !             3: 
        !             4:        Installation of the notesfile system requires
        !             5: the following:
        !             6: 
        !             7: .bx
        !             8: .ix
        !             9: A working familiarity with version 7 UNIX
        !            10: (and UUCP for intersystem transfers).
        !            11: .ix
        !            12: The notesfile distribution tape.
        !            13: .ix
        !            14: A signon for the notesfile owner.
        !            15: This signon should be in its own group.  The notes
        !            16: package runs set-gid; mixing the notes group with other
        !            17: groups is not recommended.
        !            18: .ix
        !            19: An ``anonymous'' signon.
        !            20: This signon should be an unused user-id.
        !            21: The notesfile system prohibits this user-id from reading and
        !            22: writing notes.
        !            23: .ix
        !            24: The ability to write into the directories where the notesfile
        !            25: binaries and data base are to live.
        !            26: .ex
        !            27: 
        !            28:        Appendix A (``Notesfile Installation Checklist'') is a helpful
        !            29: guide for installing the notesfile system.
        !            30: The distribution is made from a VAX running 4.2 Bsd.
        !            31: In most cases there are only a few files that need to be
        !            32: modified:
        !            33: ``src/parms.h'',
        !            34: ``src/Makefile'',
        !            35: and
        !            36: ``src/newsgate.h'' (if you are interfacing to USENET).
        !            37: 
        !            38:        First: read in the
        !            39: distribution tape.
        !            40: The tape is a TAR format tape. 
        !            41: This will read in several directories worth of data. 
        !            42: The ``src'' directory contains all source code for the notesfile
        !            43: system and the internal help files.
        !            44: The ``doc'' directory contains an nroff source for the user manual and
        !            45: the macros that were used to generate it.
        !            46: The ``man'' directory contains the nroff sources
        !            47: for the 
        !            48: notesfile manual pages.
        !            49: The ``Samples'' directory is a collection of various system files from our
        !            50: machine;
        !            51: they are included to provide examples in setting the matching files on
        !            52: your system.
        !            53: 
        !            54:        After the tape has been read in, select the appropriate parameters.
        !            55: 
        !            56: .ss "Selecting Appropriate Constants"
        !            57: 
        !            58:        Before compiling the notesfile system, 
        !            59: it must be configured to match your system.
        !            60: The location of spooling directories and command directories,
        !            61: the UNIX kernel,
        !            62: and
        !            63: policies on ``non-standard'' software
        !            64: may require changes in the default configuration.
        !            65: 
        !            66:        Cofiguring the notesfile system is accomplished through
        !            67: modifying two files, both in the ``src'' directory of
        !            68: the distribution.
        !            69: The ``parms.h'' file contains information on values for
        !            70: the default archival time,
        !            71: UNIX kernel type,
        !            72: and
        !            73: the behavior of the notesfile system such as whether
        !            74: to keep core images when the notesfile system detects an
        !            75: internal error.
        !            76: The ``Makefile'' file contains defintions
        !            77: of the spooling and command directories,
        !            78: the notesfile ``owner'',
        !            79: and
        !            80: the ``anonymous'' user.
        !            81: 
        !            82:        The distribution is configured for a UNIX 4.2 BSD system.
        !            83: The most frequently changed values,
        !            84: after the kernel definition,
        !            85: are the notesfile ``owner'' and the location of spooling
        !            86: and command directories.
        !            87: 
        !            88:        Appendix A (``Notesfile Installation Checklist'')
        !            89: details each of the options in ``parms.h'' and ``Makefile''.
        !            90: It describes the meaning of the option and the effects of
        !            91: changing the value.
        !            92: The recommended method for choosing an appropriate configuration
        !            93: is to sit at a terminal with the checklist and mark each option
        !            94: as it is selected or rejected.
        !            95: 
        !            96: .ss "Compiling the Notesfile System"
        !            97: 
        !            98:        After all the appropriate parameters are set up, the next step is
        !            99: to generate the notesfile system.
        !           100: First, the requisite directories and files
        !           101: in /usr/bin (or wherever) should be manufactured.
        !           102: This procedure should be run exactly once and will probably have to be run
        !           103: by the superuser.
        !           104: To make these files type:
        !           105: 
        !           106: .nf
        !           107:        make base
        !           108: .fi
        !           109: 
        !           110: The next phase should be run while signed in as the notesfile ``owner''.
        !           111: Type:
        !           112: 
        !           113: .nf
        !           114:        make boot
        !           115: .fi
        !           116: 
        !           117:        If all goes well, this should end with a message to the effect
        !           118: that the notesfile system has been installed
        !           119: (approximately 17 minutes on a VAX-11/780)
        !           120: If anything goes wrong, perusal of the terminal dialogue should
        !           121: point out the offending steps.
        !           122: The most likely cause of errors will be a missing directory.
        !           123: 
        !           124:        To replace the notesfile software
        !           125: any time after these two steps have been run, type:
        !           126: 
        !           127: .nf
        !           128:        make install
        !           129: .fi
        !           130: 
        !           131:        If at some time you are must change some of the internal constants
        !           132: of the notesfile package (such as string lengths and blocking factors),
        !           133: all the existing notesfiles on your system will be incompatible with the
        !           134: new instantiation of the program.  
        !           135: The ``nfdump'' and ``nfload'' programs are useful for converting
        !           136: the data base from one format to another.
        !           137: The ``nfdump'' program should be compiled with the old configuration
        !           138: and the ``nfload'' program should be compiled with the new configuration.
        !           139: Documentation on these programs can be found in the appendices.
        !           140: 
        !           141: .ss "User Subroutines"
        !           142: 
        !           143:        The notesfile package contains several routines available
        !           144: to users in general.
        !           145: The nfabort routine generates a core image, places it in a specified
        !           146: place, logs the fact in a notesfile, and terminates.
        !           147: The nfcomment routine allows users to log text in a notesfile.
        !           148: These routines are useful for debugging information, and communication
        !           149: between program developers and users.
        !           150: Users can load these routines by specifying `-lnfcom' on 
        !           151: the `cc' or `ld' command lines.
        !           152: 
        !           153:        The normal installation procedure (``make install'') will 
        !           154: compile the nfcomment routine and place it in the library directory.
        !           155: As distributed, the file is placed in the ``/usr/local/lib'' directory.
        !           156: To change this, modify the definition of ``LIBDIR'' in `Makefile'.
        !           157: 
        !           158: .se "Installing the Man(1) Documentation"
        !           159: 
        !           160:        Install the man(1) pages for the notesfile with the following
        !           161: commands.
        !           162: They are best done as super-user.
        !           163: 
        !           164: .nf
        !           165: .ne 2
        !           166:        cd man
        !           167:        make install
        !           168: .fi
        !           169: 
        !           170: The nroff sources for the documentation will be installed in the
        !           171: directory /usr/man in subdirectories man1, man3, and man8.
        !           172: 
        !           173: .se "Interfacing to News(I)"
        !           174: 
        !           175:        The notesfile system interfaces to the news(I)
        !           176: system.
        !           177: The newsinput program parses articles from the news system
        !           178: and inserts them in the appropriate notesfiles.
        !           179: The newsoutput program moves notes from the notesfile system
        !           180: to the news system.
        !           181: Neither program will move text between the two systems if the notesfile
        !           182: is not enabled for networking (see section 3.1.5).
        !           183: Newsoutput will not retransmit articles inserted by newsinput.
        !           184: Sites sharing notesfiles can all run both newsinput and newsoutput.
        !           185: 
        !           186:        Appendix B contains instructions on how to interface
        !           187: a notesfile system to a news system.
        !           188: Configurations for isolated notesfiles sites, notesfile subnetworks,
        !           189: mapping between notesfile and newsgroup names,
        !           190: and a checklist for the gateway installation are included.
        !           191: 
        !           192:        Since the notes system stores the
        !           193: entire text of a single notesfile
        !           194: in a single file, a notesfile system uses less space than the
        !           195: same scale news system.
        !           196: The notesfile system is generally more space efficient
        !           197: than B news.
        !           198: 
        !           199: .se "Housekeeping"
        !           200: 
        !           201:        Notesfiles has a number of utilities to manage it's
        !           202: data base.
        !           203: A number of shell scripts are included with the distribution
        !           204: which invoke the archival programs and trim logging files
        !           205: which otherwise grow without bounds.
        !           206: These shell scripts are included in the ``Samples'' subdirectory
        !           207: of the notesfile distribution and 
        !           208: can be invoked automatically through cron(8).
        !           209: 
        !           210: .ss "Cleaning up Disk Space"
        !           211: 
        !           212:        When a note or response is deleted, a hole is left in that notesfile.
        !           213: This makes for quick deletion but tends to leave some disk space wasted.
        !           214: The compress option on the director page is one way that this space is
        !           215: reclaimed.
        !           216: The nfarchive program (see section 3.7.2) also returns unused space.
        !           217: Have cron run the nfarchive program weekly to automate
        !           218: space reclamation.
        !           219: 
        !           220: .ss "Automatic Removal of Notes"
        !           221: 
        !           222:        The nfarchive program archives notes untouched for more than
        !           223: a specified number of days.
        !           224: Archived notes and their responses are stored in 
        !           225: an ``archive'' notesfile.
        !           226: ``Archive'' notesfiles are typically found in the directory
        !           227: /usr/spool/oldnotes; this may vary between installations.
        !           228: The archives can be accessed automatically using the ``N'' command
        !           229: from the index, note and response displays or
        !           230: by explicitly naming the notesfile
        !           231: (notes /usr/spool/oldnotes/mynotes).
        !           232: The notes are deleted after they have been archived. 
        !           233: After the archival, a compression of the notesfile is performed to
        !           234: recover the space formerly occupied by the archived notes.
        !           235: Nfarchive assumes that all months have 30 days and all years have 12 months.
        !           236: The format of the nfarchive command line is:
        !           237: 
        !           238:        nfarchive [-d] [-m+ or -m-] [-#] [-w#] [-f file] topic
        !           239: 
        !           240:        The -d option specifies that no archiving is to take place;
        !           241: the notes eligible are to be deleted.
        !           242: 
        !           243:        The -m option specifies whether to check the director message
        !           244: status before archiving notes.
        !           245: Use ``-m+'' to archive notes which meet the age requirement and have
        !           246: the director message on.
        !           247: The ``-m-'' option archives notes of sufficient age with the director
        !           248: message turned off.
        !           249: If this option is omitted, notes are archived on the basis of age only.
        !           250: 
        !           251:        The -# option specifies the age of eligible notes. The
        !           252: increment is days.
        !           253: The default is determined by the value of ARCHTIME in `parms.h' and 
        !           254: is distributed as fourteen days.
        !           255: Each notesfile can specify a (possibly) different expiration
        !           256: threshold.
        !           257: Normally the notesfile will specify `default' and nfarchive
        !           258: uses the time specified on its command line.
        !           259: Ages specified in a notesfile override the times given on the
        !           260: nfarchive command line.
        !           261: 
        !           262:        The -w# parameter specifies the working set size to
        !           263: use for notesfiles which do not specify a working set size.
        !           264: This determines a minimum number of notes to remain in a notesfile.
        !           265: If unspecified, the default working set size is 0.
        !           266: This value can be changed through the WORKSETSIZE variable
        !           267: in ``parms.h''.
        !           268: 
        !           269:        Working sets and expiration thresholds work together 
        !           270: in the following manner.
        !           271: Nfarchive first determines a maximum number of notes to delete.
        !           272: This is calculated from the number of notes in the notesfile
        !           273: (total notes minus ``holes'' caused by deletions)
        !           274: and the working set size.
        !           275: The archival program proceeds through the notesfile deleting
        !           276: notes older than the expiration threshold until it runs
        !           277: out of notes or the maximum number of notes has been deleted.
        !           278: 
        !           279:        The -f option specifies a file containing a list of notesfiles
        !           280: to be archived.
        !           281: Multiple -f parameters are permitted and can be intermixed with
        !           282: `topic' parameters.
        !           283: Notesfile name pattern matching is performed on both `topic' parameters
        !           284: and the entries in a file specified by the -f option.
        !           285: 
        !           286:        Mapping between an active notesfile and its archive is
        !           287: listed in the file ``.utilities/net.aliases/Archive-into''.
        !           288: This file contains pairs of ABSOLUTE notesfile names
        !           289: (``/usr/spool/notes/mynotes'' instead of ``mynotes'').
        !           290: The first entry specifies the active notesfile;
        !           291: the second entry specifies the archive notesfile.
        !           292: Notesfiles not appearing in the archive mapping file will
        !           293: be placed in ``/usr/spool/oldnotes'' with the same
        !           294: final component as the active notesfile.
        !           295: Conflicts are possible.
        !           296: If unmapped, the notesfiles ``/usr/spool/notes/mynotes'' and
        !           297: ``/some/other/place/mynotes'' will be archived into
        !           298: the same archive ``/usr/spool/oldnotes/mynotes''.
        !           299: 
        !           300: .ss "Cleaning Sequencer Files"
        !           301: 
        !           302:        A tool to remove sequencer entries for deleted users will be 
        !           303: included in future releases of the notesfile package. 
        !           304: This tool will traverse the sequencer directory removing files
        !           305: belonging to users whose signons no longer exist.
        !           306: The process can be made automatic by including an entry in the cron table.
        !           307: 
        !           308:        A second sequencer related utility will traverse
        !           309: the sequencer directory
        !           310: and remove entries for deleted notesfiles.
        !           311: A similar user program will be provided to permit users to remove
        !           312: their sequencer entries for notesfiles that they no longer peruse.
        !           313: 
        !           314: .ss "Additions to System Boot"
        !           315: 
        !           316:        Since the notesfile system maintains several lock files to 
        !           317: ensure mutual exclusion of each notesfile, a line similar to the following
        !           318: should be added to the /etc/rc file.
        !           319: 
        !           320:        rm -f /usr/spool/notes/.locks/*
        !           321: 
        !           322:        Make sure `/usr/spool/notes' matches the MSTDIR parameter in the
        !           323: Makefile. 
        !           324: This line will remove any locks left if the system has
        !           325: crashed.

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.