			INSTALLATION.nnmaster
			---------------------
The  following is extra information for installing nnmaster type
indexes

			BIN_DIRECTORY
                        ------------
The followin program are specific to the nnmaster version
	nnadmin		The administration program (link to nn)
	nngoback	Mark older articles as unread (link to nn)
	nngrab		Faster keyword search
	nnstats		Collection and expiration statistics
	nnusage		Show usage statistics

	      STEP 2.6: WHERE DO YOU WANT THE DATABASE?
	      -----------------------------------------

The following definitions in config.h are used to control where the
database maintained by nnmaster is stored.  The database consists of a
couple of files containing global information for all existing groups,
and a pair of files for each non-empty group.  The database requires
some disk space to hold the necessary information.  On average about
100 bytes per article in the system, or about 5% of the space
allocated to the news articles.

The database is intended to be shared together with the news spool
directory in a networked environment provided that NETWORK_DATABASE is
defined in config.h.

If DB_DIRECTORY is not defined, the global database files will be
located in a directory named NEWS_DIRECTORY/.nn, and the per-group
files will be located in each individual news group's directory (named
.nnd and .nnx).  Using this strategy will normally require that
nnmaster is owned "news" (OWNER in config.h).

The location of the database can be changed via the following
definitions in config.h:

DB_DIRECTORY 		(optional, default = see above)
	The directory containing the global database information files.
	If you share /usr/spool/news via NFS or RFS, you can set DB to
	something like /usr/spool/news/.nn to share it automatically
	with /usr/spool/news.

DB_DATA_DIRECTORY	(optional, default = DB_DIRECTORY/DATA)
	When DB_DIRECTORY is defined, the per-group files will no
	longer be stored in the group directories, but in a single
	common directory specified by DB_DATA_DIRECTORY.  The files in
	this directory will be named either by group number or by
	group name (if DB_LONG_NAMES is also defined).


The files config.h and NNTP describes how to share the database
between several machines (also when you don't use NNTP).


NOTICE: Since nnmaster runs setuid OWNER, all users can potentially
	kill the running master, initialize the database etc. if they
	have access to execute the master.  So either restrict the
	permissions to execute nnmaster or the access to the directory
	containing it.  The default installation puts modes -rwsr-s---
	on nnmaster and leaves the directory "open" which may not be
	adequate for you.


				STEP 5

		       INITIALIZE THE DATABASE
		       -----------------------

If you have installed the nnmaster on the current system, you now have
to initialize the database:

	$ su		 -- also as superuser
	# ./inst INIT

If something goes wrong in this step, e.g. problems with the active
file, you must redo the initialization after fixing the other
problems.

When the INIT operation completes, a database with empty entries for
all the currently existing groups will have been created.  If you want
some special actions to be performed for specific groups as described
in the nnmaster manual, you must now edit the GROUPS file created by
nnmaster in the DB_DIRECTORY.  If you modify the GROUPS file, you must
run the following command to register the changes to the GROUPS file.

	$ MASTER_DIRECTORY/nnmaster -G

When you are ready, you must start nnmaster to enter all the existing
articles into the database.  If you use the following command,
nnmaster will fork and return immediately; its background child will
continue to update the database whenever new articles arrive:
It will ignore articles which are more than 45 days old (-O).

	$ MASTER_DIRECTORY/nnmaster -r -O45

It may take quite a while before all existing articles have been
entered into the database.  You can use nnadmin's (U)pdate and (S)tat
commands to trace the progress and the (L)og command to see if it has
finished (a C entry will occur).  You will see that many groups will
be BLOCKED, but the number should decrease as nnmaster gets through
more and more groups.

You can also use the following command to do the initial collection of
articles from a terminal and get a nice trace of the action:

	$ MASTER_DIRECTORY/nnmaster -D -O45

One or two numbers will be shown while a group is being collected.
The first number is the number of the article currently being read.
The (optional) second number will be the number of old (or bad)
articles which nnmaster has ignored in the group so far.


NOTICE: If the system file you have used does not specify how to
	detatch a process from its controlling terminal, the nnmaster
	may die when you log out.

When nnmaster has finished the initial collection the articles, you
can nnadmin's (V)alidate command to verify that the database build by
nnmaster is consistent (restart nnadmin before verifying).


				STEP 6

			 UPDATE SYSTEM FILES
			 -------------------

You will have to edit some of the scripts and files on your system to
get the database and other support files updates automatically, also
following system shutdown, crashes, etc.


	    STEP 6.1: START NNMASTER WHEN SYSTEM IS BOOTED
	    ----------------------------------------------

To have the database updated at all times, the nnmaster should be
started when the system is booted.

There will be a file named /etc/rc, a directory /etc/rc.d, or
something similar on your system which contains commands that are
executed when the system is booted.  The following commands should be
added to the boot scripts:

	rm -f MASTER_DIRECTORY/MPID
	MASTER_DIRECTORY/nnmaster -l -r -C


Alternatively, you can arrange for cron to run the master regularly.
In this case, you should not use the -r and -C options.  Instead, you
should let cron execute the command 'nnadmin Z' once a day to
validate the database.  For example:

	0,10,20,30,40,50 * * * * MASTER/nnmaster -LM
	0 0 * * * BIN/nnadmin Z


WARNING: If you share the database via NFS or RFS, nnmaster should run
	 only on the system where the database actually resides!!
	 And preferably it should run on the host where the news spool
	 directory is located as well.  This will improve speed as well
	 as reliability (NFS can suffer from time out problems).


		STEP 6.2: SETUP EXPIRE ON THE DATABASE
		--------------------------------------

To run expire on the database, you simply have to execute the
following command (with sufficient privileges):

	BIN_DIRECTORY/nnadmin =EYW

You should arrange for expire to be run on nn's database whenever you
have run expire on the news directories.

Supposing you run the expire from your crontab, you may simply add the
above command to the crontab at an appropriate time when you are
certain that news' expire is completed.

If you run nnmaster from cron rather than in daemon mode, you can use
the following command to run expire on the database.

	nnmaster -F -k ""

This form allows you to run expire on selected groups rather than on
all groups as initiated by the above nnadmin command.  See the
nnmaster manual for further details.


	 STEP 6.3: SAVE A COPY OF THE ACTIVE FILE ONCE A DAY
	 ---------------------------------------------------

The `nngoback' program requires that the program `back_act' is
executed once (and only once) every day to maintain suitable copies of
the active files for the last 14 days.  In a network environment, it
should execute on the same host as the nnmaster.

Simply arrange for back_act to be invoked by cron once a day
(preferably just before the batch of news for `today' arrives).  For
example, assuming the news is received just before midnight (syntax
and location of crontab entry may vary):

In /usr/spool/cron/crontabs/news (System V):
	00 23 * * * MASTER_DIRECTORY/back_act
or in /usr/lib/crontab (BSD):
	00 23 * * * su - news MASTER_DIRECTORY/back_act

The default setup allows you to go 14 days back with nngoback, but if
you don't keep news that long, there is no reason to keep that many
copies of the active file either.  In that case, you can supply the
maximum number of days as an argument to back_act.  Of course, you can
also keep more than 14 copies of the active file to allow nngoback to
go more than 14 days back by giving back_act an argument larger than 14.


	  STEP 6.4:  PREPARE FOR NNSPEW TO BE RUN REGULARLY
	  -------------------------------------------------

The nngrab program will run faster if a dedicated subject database in
addition to the normal database is available.  To maintain this
additional database, the program nnspew must be executed regularly,
e.g. from cron.  Every 3-6 hours should be sufficient to keep the
database reasonably up-to-date, e.g.

In /usr/spool/cron/crontabs/news (System V):
	2 6,12,18 * * * MASTER_DIRECTORY/nnspew
or in /usr/lib/crontab (BSD):
	2 6,12,18 * * * su - news MASTER_DIRECTORY/nnspew

				STEP 8

		       TEST THE BASIC FUNCTIONS
		       ------------------------
First you should check that nnmaster does collect the articles it is
supposed to.  Here, nnadmin is a great help, since you can peek around
in all the database files and see what nnmaster is doing.  nnadmin
takes a snap-shot of the database when it starts up, but you can take
a new snap-shot anytime using the (U)pdate command.

Also look at the (L)og to see that there were no problems while
collecting the articles.

			UPDATING THE SOFTWARE
			---------------------

Patches to this software will be distributes as context diff's which
can be applied using Larry Wall's `patch' program.

After applying the patches, you will need to redo the compilation and
installation steps:

	$ patch -p0 < PATCH_FILE	(or use nn's :patch command)
	$ make all
	$ su
	# ./inst u

To be able to install a new nnmaster, the currently running master (if
any) will be stopped automatically, and it has to be started manually
when the installation is complete (unless it is setup to be run by cron).

Notice that unless it is explicitly required in the patch, there is no
need to reinitialize the database after applying the patch.
