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