Return to a.checklist CVS log

Up to [CSRG BSD Unix] / 43BSDReno / share / doc / usd / 11.notes

Annotation of 43BSDReno/share/doc/usd/11.notes/a.checklist, revision 1.1

1.1     ! root        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.

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