![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to a.checklist CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [CSRG BSD Unix] / 43BSD / contrib / notes / doc|
Return to a.checklist CVS log | Up to [CSRG BSD Unix] / 43BSD / contrib / notes / doc |
1.1 root 1: .ls 1
2: .ap A "Notesfile Installation Checklist"
3:
4: .a1 "Installing Notesfile Code"
5:
6: You can be sure that you have modified all necessary constants
7: in the notesfile system by following this simple checklist.
8:
9: .bz
10: .iz
11: change to the notesfile source directory
12: .iz
13: tar x
14: [reads the notesfile tape]
15: .iz
16: cd src
17: .iz
18: [edit] parms.h
19: .iz
20: ARCHTIME.
21: Default for how long unmodified note strings hang around.
22: .iz
23: WORKSETSIZE.
24: The default number of notes to leave in a notesfile when archiving.
25: .iz
26: DFLTSH.
27: This should be left as the Bourne shell, /bin/sh -RBE
28: .iz
29: DFLTED.
30: The editor to use if no NFED or EDITOR environment variable
31: exists.
32: .iz
33: SEQFILE.
34: This is the name of a file in the utility directory which contains
35: a list of notesfiles for users without an NFSEQ environment variable.
36: The default is probably just fine.
37: .iz
38: DFLTSEQ.
39: For users without an NFSEQ environment variable and when the file
40: specified by the SEQFILE definition above doesn't exist, we
41: finally fall back to using the notesfiles specified by this string.
42: The nice thing about having things in SEQFILE is that you don't
43: have to recompile the notesfile software everytime you wish to
44: change the default set of notesfiles; instead you edit a file.
45: .iz
46: MAILER.
47: The program which will do mailing.
48: If you are in a networked environment, this mailer should
49: manage to route letters to far away places for you.
50: The notesfile system only retains the name of the destination site;
51: a path to that site is not kept.
52: .iz
53: SUPERMAILER.
54: This should be defined if you have an intelligent mail program.
55: Intelligent here means that you can edit the letter and other
56: fun things.
57: .iz
58: PAGER.
59: A program which shows 1 screenful of information at a time.
60: .iz
61: WRITE.
62: A program which allows online user-user communication
63: (such as /bin/write).
64: .iz
65: FULLDOMAIN.
66: This defines the domain name of your local systems. For many
67: USENET sites, this should be ``UUCP''.
68: Other examples include ``ARPA'' and ``Uiuc.ARPA''.
69: This should not include the system name.
70: In the UIUC Computer Science Department, we have machines named
71: ``uiucdcs'', ``uiucdcsb'', and so on;
72: our value for FULLDOMAIN is ``Uiuc.ARPA''.
73: The notesfile code puts
74: things together to yield ``uiucdcsb.Uiuc.ARPA'' as a
75: full domain name for one of our machines.
76: Note that you do NOT need to place a ``.'' at the beginning of
77: the domain name; the notesfile software does this for you.
78: .ix
79: IDDOMAIN.
80: This switch is (for now) undefined.
81: When defined it indicates the the unique id's associated with
82: notes are to have a system component containing the system
83: name and the string defined by FULLDOMAIN.
84: The eventual goal is that this will be defined.
85: Currently, there are problems with using long strings
86: for unique identifiers. This is related to the old notesfile
87: structure which used a 10 character maximum and didn't check for
88: overflow.
89: .br
90: So for now, leave this undefined.
91: I'm not sure when it will be good to enable this option.
92: .iz
93: Select a kernel type for your machine.
94: If no kernel is selected, the code may compile but most
95: likely will not run.
96: .iz
97: PROMPT.
98: If you wish the system to give a command prompt.
99: Otherwise the notesfile system is promptless.
100: .iz
101: USERHOST.
102: If this is defined, the notesfile system uses the convention
103: ``user@host'' to indicate where an article originated.
104: If undefined, the notesfile system uses a ``host!user''
105: notation.
106: If you are running in an environment which supports Internet
107: style names, you may choose to use this.
108: .iz
109: DYNADIR.
110: When defined, the notesfile system will determine the default
111: spool directory notesfiles from /etc/passwd.
112: The home directory for the user ``notes'' (actually whatever is
113: specified in the Makefile) is read from /etc/passwd and the
114: parent directory is used as the default spool directory.
115: Thus if notes' home directory is ``/usr/spool/notes/.utilities'',
116: the default directory is ``/usr/spool/notes''.
117: This assumes that notes' home directory is in the .utilities
118: directory.
119: .sp
120: This is useful for the case where a single binary will be run
121: on several machines with differing disk layouts.
122: On one, the database might live in /usr/spool/notes; another
123: host might have the data base in /mnt/notes.
124: By using DYNADIR and moving the ``notes'' home directory
125: on various machines, only one binary is needed.
126: .sp
127: If the notes database lives in the same place on all of your
128: machines, a better approach is to use the MSTDIR definition
129: in the Makefile.
130: .iz
131: K_KEY.
132: When defined, the ``k'' and ``K'' keys act similarly to the
133: ``q'' and ``Q' keys respectively.
134: The choice is up to you.
135: Defining them allows reading of notes with one hand.
136: However some people get aggravated when the miss the ``j'' key
137: and hit the ``k'' key.
138: All the documentation considers the ``k'' key to be active.
139: .iz
140: BIGTEXT.
141: Define this is you want to allow notes longer than 65000 bytes.
142: Note that if you have old notesfiles, you will have to dump and
143: reload them with the ``nfdump'' and ``nfload'' programs before
144: the new code will work on them.
145: .iz
146: .ft B
147: The following definitions are pretty much ``stock'' and
148: usually aren't changed.
149: .ft P
150: .iz
151: NFMAINT.
152: This is the name of the notesfile which receives control messages,
153: error reports and other notesfile logging functions.
154: I do not recommend #undef'ing this.
155: .iz
156: AUTOCREATE.
157: When defined, network receptions of previously undefined notesfiles
158: will cause the creation of that notesfile.
159: If undefined, the reception will fail if the notesfile doesn't
160: exist.
161: This is used in environments such as USENET where new notesfiles
162: are often created remotely.
163: .iz
164: STATS.
165: If defined, the statistics keeping code is enabled. If undefined,
166: the notesfile system will not keep statistics.
167: Keeping statistics involves no space overhead and relatively
168: little time overhead; I recommend leaving this defined.
169: .iz
170: FASTSEQ.
171: Enables code which ``fails-quickly'' by determining in an
172: inexpensive operation if there can't be any new articles.
173: When there might be new articles,
174: a more thorough and time consuming algorithm
175: is used.
176: .iz
177: DUMPCORE.
178: This defines a subdirectory of the notesfile utility directory
179: where core images generated by internal consistency checks are
180: placed. If undefined, the errors will be logged but no core
181: image is generated.
182: .iz
183: FASTFORK.
184: This definition enables a quick forking algorithm which
185: exec's the desired program immediately instead of going through
186: the system(III) interface.
187: It avoids an extra fork()/execl() and shell startup costs.
188: However some functionality is lost.
189: .iz
190: [finished editing parms.h]
191: .iz
192: [edit] Makefile
193: .iz
194: select BIN.
195: The directory where user commands are kept.
196: The Makefile will NOT create this directory.
197: At UIUC, we use /usr/bin. Another common choice is
198: /usr/local.
199: .iz
200: MSTDIR.
201: The default directory for notesfiles.
202: The Makefile WILL make this directory for you.
203: This is typically /usr/spool/notes.
204: .iz
205: ARCHDIR.
206: Old notes never die, they go here instead;
207: the Makefile WILL make this directory for you.
208: .iz
209: NET.
210: This is the directory where the notesfile networking programs
211: ``nfxmit'' and ``nfrcv'' will be placed.
212: In most cases, ``/usr/bin'' is a good choice.
213: You may wish to change it if your UUCP or other networking
214: mechanisms use other directories.
215: This directory must already exist;
216: the Makefile will not create it.
217: .iz
218: AUTOSEQ.
219: The invocation name for the automatic sequencer.
220: For multiple names like `autoseq', `readnotes' and `autonotes',
221: make links to the file ``/usr/bin/notes'' with the appropriate
222: names (assuming that BIN = `/usr/bin').
223: .iz
224: NOTES.
225: The username of the user who ``owns'' all the notesfiles.
226: .iz
227: NOTESUID.
228: The numeric userid of the notesfile ``owner''.
229: For example NOTES = notes, NOTESUID = 10.
230: .iz
231: NOTESGRP.
232: The name of the group to which the ``NOTES'' signon belongs.
233: .ft B
234: It is strongly recommended that this be a special group
235: just for the notes database and programs.
236: .ft P
237: .iz
238: ANON.
239: The name of the ``anonymous'' user.
240: .iz
241: ANONUID.
242: The numeric userid of the ``anonymous'' user;
243: this should be an idle user id since it is not allowed to
244: run the notesfile program.
245: .iz
246: LIBDIR.
247: The directory to contain ``libnfcom.a'', a user accessible library
248: of routines.
249: This is distributed as /usr/local/lib.
250: .iz
251: CFLAGS.
252: You may wish to arrange for split I/D loading on a PDP-11
253: (the -i flag).
254: It may also be prudent to optimize the code (-O flag).
255: If code size is an issue, remove the RCSIDENT definition;
256: when defined, version control information is included in the
257: binaries and they are correspondingly larger.
258: .iz
259: [finished editing]
260: Makefile
261: .iz
262: [may need to become super-user at this point]
263: .iz
264: type ``make base''
265: and assess its completion.
266: It will tell you if all went well.
267: .ft B
268: If you are merely installing a new version of the notesfile code,
269: you should type ``touch base'' instead of ``make base''.
270: .ft P
271: .iz
272: Signon as notesfile ``owner''.
273: While remaining super-user isn't a fatal flaw at this point, it
274: does mean that several default notesfiles won't be generated.
275: These can be created by hand if you forget.
276: Nothing from this point on (including future code updates) requires
277: super-user privileges.
278: .iz
279: cd src
280: .iz
281: .ft B
282: If you are merely installing a new version of the code,
283: type ``touch spool'' now. This tells the makefile that the spool
284: directories already exist.
285: .ft P
286: .iz
287: make boot.
288: This is the final step, it should complete with a message
289: that the system is installed.
290: An error message when doing the ``mknf -on nfmaint nfgripes''
291: probaby means you are still super-user.
292: Don't sweat it; just become notes and type the ``mknf'' command
293: line over. Everything is now fine.
294: .iz
295: You may have to be Super-User for the next step depending on the
296: modes of your manual directory, /usr/man.
297: .iz
298: cd ../man.
299: [the man page directory for notesfiles]
300: .iz
301: make install.
302: to install the man(I) pages for the notesfile system.
303: They are placed, by default, in the directories /usr/man/man1,
304: /usr/man/man3, and /usr/man/man8.
305: .iz
306: Examine the ``Samples'' directory for templates of files normally
307: in the notesfile utility directory.
308: These files include shell scripts to run through cron(8) which
309: queue network transmissions, expire old notes, and
310: map between notesfiles and news.
311: .iz
312: Modify UUCP's ``uuxqt.c'' to allow remote execution of ``nfrcv''.
313: This is unnecessary if no notesfile networking will be done
314: or if another remote execution mechanism will be used.
315: Some versions of UUCP have a file ``/usr/lib/uucp/L.cmds''
316: which contains names of permitted commands.
317: .iz
318: Modify /etc/rc to remove notesfile locks at boot time.
319: [4.2 BSD machines might prefer to use /etc/rc.local.]
320: Add the command ``rm -f /usr/spool/notes/.locks/*''.
321: .ez
322:
323: .a1 "Upgrading Existing Notesfile Databases"
324:
325: Revision 1.7 of the notesfile system requires converting
326: existing notesfile databases to a new format.
327: A set of programs to accomplish this task are included in the
328: distribution.
329: The ``nfdump'' program converts notesfiles into an ASCII representation.
330: The ``nfload'' program converts this ASCII representation back
331: into a properly formatted notesfile.
332: To convert an existing notesfile database, these steps are what I
333: follow:
334:
335: .bz
336: .iz
337: Compile ``nfdump'' with the OLD notes distribution.
338: If your version of the software is old enough not to have a copy
339: of nfdump,
340: I suggest you either try to adapt the version in the current
341: distribution or using the networking programs ``nfxmit'' and ``nfrcv''
342: to get the information between the old and new databases.
343: .iz
344: Compile ``nfload'' with the NEW notes distribution.
345: .iz
346: cd /usr/spool/notes
347: .iz
348: mkdir .OLD
349: .iz
350: mv * .OLD
351: .iz
352: run the following script:
353: .nf
354: .br
355: #! /bin/csh -f
356: foreach i (`ls .OLD`)
357: echo $i start
358: nfdump-old /usr/spool/notes/.OLD/$i - | nfload-new $i
359: echo $i done
360: end
361: echo ALL DONE
362: .fi
363: .iz
364: rm -rf .OLD
365: .ez
366:
367: You will also have to convert the sequencer information.
368: In the ``utility/seq-cvt'' directory there are a pair of programs
369: ``seqtoascii'' and ``seqtobinary''.
370: To convert the sequencer information:
371:
372: .bz
373: .iz
374: make ``seqtoascii'' using the OLD structs.h and parms.h.
375: .iz
376: make ``seqtobinary'' using the NEW structs.h and parms.h.
377: .iz
378: cd /usr/spool/notes/.sequencer
379: .iz
380: mkdir .OLD
381: .iz
382: mv * .OLD
383: .iz
384: run this shell script:
385: .nf
386: .br
387: #!/bin/csh -f
388: foreach i (`ls .OLD`)
389: echo $i
390: seqtoascii .OLD/$i | seqtobinary $i
391: end
392: echo ALL DONE
393: .fi
394: .iz
395: rm -rf .OLD
396: .iz
397: If you are going to use the FULLDOMAIN option, you may want
398: to go ahead and perform the following steps:
399: .iz
400: run this shell script, appropriately modified to reflect
401: your domain setup.
402: This one reflects the naming at UIUC.
403: .nf
404: .br
405: #!/bin/csh -f
406: foreach i (Sy:*)
407: echo $i
408: ln $i $i.UUCP
409: ln $i $i.Uiuc.ARPA
410: end
411: echo ALL DONE
412: .fi
413: .iz
414: You have now converted your notesfile database to 1.7 format.
415: Install the new binaries and fire away.
416: .ex
417:
418:
419: .a1 "Hints on Installing Notesfiles on Multiple Systems"
420:
421: Notesfile binaries are portable across similar machines.
422: User-id's and hostnames are determined by examining /etc/passwd
423: and through system calls.
424:
425: To install the Notesfile system on a network of like machines
426: (a collection of 68000 workstations for example)
427: one machine must go through the procedure detailed above.
428: A shell script ``rinstall'' is included in the notesfile
429: source directory.
430: This shell script will propagate copies across the network.
431: Rinstall is a simple script that assumes the correct
432: hierarchies exist on the target machines.
433: It was written to use the 4.2 BSD ``rcp'' and ``rsh'' programs
434: to copy files and remotely execute commands.
435: Different networking commands will require changes to the shell
436: script.
437:
438: To generate the proper hierarchies on other systems,
439: copy the Makefile to each of the machines and make both
440: ``base'' and ``spool''. This will create the proper files
441: and directories for the notesfile system.
442: Then return to the master machine and run the rinstall script
443: to send binaries to each of the other machines.
444:
445: The ``Samples'' directory of the Notesfile distribution
446: contains example cron scripts for sending information between
447: a network of systems running notesfiles.
448: These shell scripts can prove helpful in setting up notesfile
449: transmissions around your local network.
450:
451: .a1 "Mail to Notesfiles"
452:
453: To use the nfmail program with the 4.1 BSD /etc/delivermail
454: or the 4.2 BSD /usr/lib/sendmail
455: insert lines of the following form in the file /usr/lib/aliases.
456:
457: .in +1i
458: .nf
459: somenotes: ``|/usr/spool/notes/.utilities/nfmail somenotes''
460: gripes: ``|/usr/spool/notes/.utilities/nfmail problems''
461: .fi
462: .in
463:
464: .a1 "The Notesfiles/News Gateway"
465:
466: The notesfile/news gateway may need a little more tickling to
467: convince it to work properly. For more information on how to set this
468: up properly, see section 3.5 (``Interfacing to News'') and look at
469: the file `Src/newsgate.h'.
470: Appendix B (``Interfacing Notesfiles to News'')
471: is another source of information for connecting the two systems.
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.