Return to a.checklist CVS log

Up to [CSRG BSD Unix] / 43BSD / contrib / notes / doc

Annotation of 43BSD/contrib/notes/doc/a.checklist, revision 1.1

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.