43BSDReno/share/doc/usd/11.notes/3.2 - annotate

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

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.

unix.superglobalmegacorp.com

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