Return to 3.2 CVS log

Up to [CSRG BSD Unix] / 43BSDReno / share / doc / usd / 11.notes

Annotation of 43BSDReno/share/doc/usd/11.notes/3.2, revision 1.1

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

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