;;; -*-Indented-Text-*-

INSTALLATION INSTRUCTIONS FOR NOTES 2.9
---------------------------------------

NOTE: It is better to install this in a separate, empty directory, since
the layout of the distribution may be different from the last one.


Examples
--------

There are sample scripts in the "samples/" subdirectory.  You may want to
refer to them as you go through installation.


Installing Notes
----------------
To install Notes on a new system, do the following:

1. If you are converting from a Notesfile system other than Notes 2.X, or
   from Notes 2.X version earlier than 2.7, read the section below on
   "Converting Your Notes Database".

2. Edit create users 'notes' and 'anonymous', and group 'notes'.  The home
   directory of user "notes" will hold all the utilites and config
   information for the Notes system.  The make files may still runs scripts
   that read /etc/passwd for this information, so set this first!

3. You will need GNU Make 3.45 or later (though versions 3.X where X < 45
   may work too). 

4. List all files with extention ".gmake".  You should see the following:
	config.gmake	-- customization and configuration
	notes.gmake	-- main makefile for this directory
	common.gmake	-- included by notes.gmake and other makefiles
	bsd4.3.gmake,	-- system-dependent makefiles; you select
	hp-ux.gmake,	   one of them in config.gmake
	etc.

5. Look through the system-dependent gmake files to see if any of them suit
   your system.  If none do, copy one that is closest and adjust it for
   your system.

6. Edit config.gmake, setting your preferences.  Make sure you specify the
   right system-dependent gmake file there.

7. If you want to use the parallel compilation options, you may need to
   edit notes.gmake to set MFLAGS (for example, "MFLAGS=-j8 -l12.0" --
   "no more than 8 jobs, and no new jobs if load average is above 12.0") 

8. Running as user "notes" or yourself, type "make -f notes.gmake",
   where "make" is the GNU Make program.  This will make all the notes
   binaries, but will not install them.  (You may want to use other
   options to the GNU make, such as the parallel compilation options
   shown in above.)

9. Running as "root", type "make -f notes.gmake setup".  This will make the
   directories that you specified in the Makefile, and will install some
   essential files.  It will attempt to create a $LIBDIR/config with default
   entries, but if that file already exists, it will not be touched.

10. The default config file is unlikely to be exactly what you want.
    Read notes-config(5) (for example, 'nroff -man man/notes-config.5 | more')
    and edit the file $LIBDIR/config to fit your needs.

11. Running as "root", type "make install".  This will install the binaries
    and the manual pages. 

12.  Make sure the groups you are interested in are not listed in
     ~notes/invalid.  


Setting Up Network Connections
------------------------------

This version of Notes uses News B format to interchange articles.  (It can
use NNTP for this purpose, see below.)  It also can use Notes format (the
programs to do it are untested in 2.9), but the News format is greatly
preferred.  If you can get a News format feed, do so.  If you want to
interchange articles between two systems running this version of Notes, use
the News format.  The Notes interchange is strictly for backwards
compatability, and even then, it is better to use the News format through a
News gateway at the old Notes side.

*************************************************************************
*DON'T PUT THIS VERSION OF NOTES DOWNSTREAM OF AN OLD-FORMAT NOTES SITE!*
*Doing so may cause a flood of duplicate articles on USENET.		*
*************************************************************************

The two kinds (new and old) of connections are setup differently.  For both
kinds, the sequencer file is kept in "LIBDIR/sys/<sysname>.seq".  On
systems that impose 14-character limit on filenames, beware of system names
that are longer than twelve characters.  (Sigh.)

A new exit code has been added to nfrcv and newsinput (aka "rnews" and
"unbatch").  An exit 3 means that the incoming articles were in a fatally
bad format.  This is fairly useful when you get messages back from uucp
about a failed nfrcv or unbatch.


UUCP, cron, etc.
----------------

Cron will need to transmit notes periodically.  Add user "notes" to
cron.allow.  Also, add rnews (a script), unbatch, cunbatch (a script), and
(only if you plan to use old transmission format) nfrcv to
/usr/lib/uucp/L.cmds.

You will need to copy the News and Notes receiving programs to
someplace where uucp can find them, probably /bin.  Alternatively,
install scripts that fire off the approriate command, like this:

	/bin/rnews, /bin/unbatch:
	  /usr/local/lib/notes/newsinput

	/bin/nfrcv:
	  /usr/local/lib/notes/nfrcv

Symbolic links come in handy here on systems that support them.


Initializing a Sequencer
------------------------

If you do not have a sequencer file for a particular system,
newsoutput will only send the previous two days worth of articles.  To
set a sequencer, use the seqset(8) command.  The "-w" flag sets "when".
Seqset takes the same flags as newsoutput, such as "-f".

   seqset -t newsvax -w "now"  "*"
   seqset -t newsvax -w "may 3 1986"  "local.*" "net.*" "!*.sources"
   seqset -t newsvax -w "last week"  -f sys/newsvax.out
   seqset -t newsvax -w "yesterday"  "*"
   seqset -t newsvax -w "3:00 pm apr 24"  "mod.*"


Setting up News Connections
---------------------------

This is covered accurately in the manual shipped with this version.
[The manual has not been updated between versions 2.8 and 2.9 -- Jacob]

Notes always sends News format articles in "batches".  If you are
transmitting to a News system, that system must be able to handle
batches.  Notes may receive single articles or batches.

Nearly all systems will use the "sendbatch" command.  

It is exactly like NetNews sendbatch, but uses several files in the
$LIBDIR/sys directory rather than a sys file.  See sendbatch(8).

The command "sendbatch newsvax hplabs notesvax" sends batches to all
three systems listed.

Here are the files used by sendbatch:

 $LIBDIR/sys/newsvax.seq  -- sequencer for newsvax                             
 $LIBDIR/sys/newsvax.out  -- files to send to newsvax, in notesrc(5) format    
 $LIBDIR/sys/newsvax.cmd  -- command used to send batches to newsvax,          
                if missing, sendbatch uses: "uux - -r -z newsvax!rnews"


The "newbatch" Command
----------------------

A few systems will need special control over when batches are sent.
The "newbatch" command makes batches for a single system.  This
command might be run at night:

    newbatch hplabs "ba.*" "ca.*" "mod.*" "net.*"

WARNING -- If you use the newbatch command, your connections are no
longer described by the "system.out" file in sys!  This makes your
connections much harder to track.


Setting up Notes Connections
----------------------------

If at all possible, use the same programs to communicate with old Notes
sites, and let them worry about conversion.  If it is NOT possible, read
on... 

Notes format articles are received by the "nfrcv" command.  This is
built by "make install".  Make sure that it is installed setuid
"notes", and setgid "daemon".  [I'm not sure why it needs to be daemon --
all our stuff is in group notes... but then, we don't use nfrcv -- Jacob]

Notes format articles are send by "newsoutput -o".  The "-o" flag
means "old format", i.e. Notes.  Articles sent in Notes format are
logged as "via OLDNOTES" in net.log.

By default, articles are sent using "uux".  For special cases, you
may edit the file LIBDIR/nfxmit.  This file actually fires off
the command for tranporting the notes to the remote machine.  Note
that if you send to a system whose name matches "hptest*", then the
notes are appended to the file "/tmp/nftest".  This is very useful.

WARNING -- reinstalling Notes will overwrite nfxmit!  The previous
version is saved as nfxmitsh.BAK.


Using NNTP for transmission of articles
---------------------------------------

This version of Notes can exchange articles with other systems using NNTP.
The NNTP implementation is partial: no support for reading or posting is
provided, only for interchange.

Most limitations of this NNTP implementation stem from Notes' inability to
locate articles quickly by their Message-Id.  For this reason, Notes will
never decline an article -- it will accept it, and then discard it as a
duplicate.

On the output side, the -N option to newsoutput will place articles in a
spool directory, one article per file.  The standard nntpxmit can then be
used to offer them to NNTP neighbors and send over those that are accepted.

The scripts spoolnntp and sendnntp can be used for NNTP transmission to
other systems.  Spoolnntp runs 'newsoutput -N', and sendnntp scoops up the
spooled articles and sends them across.  The two scripts can be run from
cron with different frequency, to make it easier to schedule spooling and
transmission around your system's and your network's busy times.

Enabling NNTP in the config.gmake file will compile the necessary code into
newsoutput, but it will NOT build the nntp support routines.  You need to
make them separately.  The directory nntp/ contains source code that can be
used. 


Converting Your Notes Database
------------------------------

Be warned that this conversion takes a LONG time (on the order of 12 hours
for 7 days worth of net.* on an HP series 200 machine) [those weren't that
fast by today's standards, but then, the net was much smaller, too...--Jacob],
and that you'd be much better off to simply start from scratch.

The easiest way to convert is to copy the desired notesfiles from a
machine that has already converted.  Some earlier version of Notes
kept the local hostname in the notesfile, but that is fixed in this
version.

You need the "nfdump" program FROM YOUR EXISTING NOTES SYSTEM to convert a
notesfile.  The "nfdump" program may not be installed on your system.  If
you have source, then you may be able to make it.  Try "make nfdump".
Often, the Makefile does not make "nfdump" as part of "make all".

If you are determined to convert anyway (and have "nfdump"), then here
is the procedure.

This release of Notes uses a different database format than other versions
of Notes.  To convert a single notesfile, we dump the notesfile in an ASCII
format, using a utility from the old system, then reload it with a utility
from the new system.  The dumping program is usually called "nfdump".  To
load the file into the new system, we use "nfrcv -e -t".

Here is an example of how to convert a notesfile:

   /somewhere/oldnotes/nfdump hp.general - |  \
	/elsewhere/newnotes/nfrcv -e -t hp.general hp-mysystem

The "-t" option instructs nfrcv to "trust" the incoming notes to
be in correct order and to contain no duplicates.  This is much faster,
but is not always safe.  The new version of notes is able to clean
up some duplicates that other Notes systems cannot catch.

In particular, if an article came in through two incompatable
News->Notes gateways, it will show up twice in Notes, once with a
unique ID like "1234", and once with "-123400", or "-123401".  With
the "-t" flag, these duplicates will remain.  Without the flag, the
duplicates will be recognized, and only one will be kept.

I do NOT recommend using "-t".

There are currently no tools for converting the sequencers from old
to new format.  This is not a big job, it just isn't done yet.

If all this sounds like a pain, it is.  It is often better to just
turn off your Notes feed for a few days, read everything, delete all
the old stuff, and install the new Notes.  You can actually convert
the few Notesfiles that you keep for a long time.


Things To Do
------------
Use notesfiles for archives instead of the oldnotes format.

Allow users to type "net.all" in addition to "net.*".

Allow users to delete notes that have been networked out.  Send a
cancel ctlmsg.

Improve the detection and logging of News header errors.

Put together a better system for controlling article distribution
(replace the safety-net).  [The "safety net" is only compiled in with
-DHPVERSION --Jacob]

Write conversion routines for sequencers.

Add some more things to the config file, like access-template and
invalid.


	-- Walter Underwood [original, for 2.7]
	[Modified for 2.9 by Jacob Gore <gore@eecs.nwu.edu>]
