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