43BSD/contrib/notes/doc/3.2 - annotate

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

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.

unix.superglobalmegacorp.com

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