@(#) $Header: INSTALL,v 1.7 96/12/30 17:23:41 leres Exp $ (LBL)

We are a InterNetNews site and so these instructions are biased towards
this news system. This package is known to compile and nominally run
under SunOS 4.1.4 and Solaris 2.5; it configures and compiles under
BSD/OS 2.1 and OSF 3.2. If you port it to a new system, please forward
any changes to dexpire@ee.lbl.gov.

You will need an ANSI C compiler to build dexpire. If your compiler is
not ANSI compliant, use the GNU C compiler, available via anonymous
ftp:

	ftp://prep.ai.mit.edu/pub/gnu/gcc-*.tar.gz

Dexpire uses statvfs() or statfs() to determine disk usage. If your
system doesn't have one of these, you'll have to add some code to
disk.c. Since disk_usage() is only invoked once, it would be acceptable
to fork() and parse the output of /bin/df.

Dexpire uses autoconf. So the first thing to do after unpacking the
files is to run configure:

	./configure

The configure scripts builds and runs the test program blocktest to
make sure that dexpire's assumptions about the filesystem block size
are correct. It tests to the st_blocks field of the stat structure.
Dexpire assumes that the units are in 512 byte blocks (perhaps rounded
up to the next even block because the filesystem fragment size is 1024
bytes). If blocktest doesn't successfully build and report:

	blocktest: Success: This machine appears to use 512 byte blocks

then your os is somewhat unusual and running dexpire might be dangerous
(e.g. it might free twice as much space as requested).

Next, configure dexpire.h. Although the location of the various files
and directories can be changed with flags, it's usually more convenient
to have the defaults match your system.

Next build the programs:

	make

Now configure a dexplist file. If you currently use the C News expire,
it's pretty easy to convert a explist file to the dexplist format;
basically, edit it down so that you only have the first 3 fields.
Otherwise, make a copy of the sample dexplist and start hacking.

Now compile and test. If you have more than one spool filesystem, read
the dexpire man page to see how to use the -f flag. It's strongly
recommended that you use -n until you're sure everything works ok. Try
something like:

	dexpire -vn -f 100M

Put the output on a file so you can examine it at your leisure. Make
sure the reported disk statistics match what /bin/df says. The first
pass should always find at least one article that could be deleted. The
end of the run should report a reasonable number of articles and the
correct number of bytes to be deleted.

Include are sample scripts for both C News and InterNetNews. The are
good starting places as wrapper scripts for running dexpire and
histtrim. In particular, dohisttrim knows how to lock a the news system
and how to build the dbm/dbz history file.

If your new dexpire policy differs from your old expire setup, it isn't
unusual for there to be hundreds of consecutive unproductive passes.
But since dexpire caches article timestamps, these extra passes use
very little cpu time (and perform no I/O); and after the news system
catches up with the new policy, things will settle down to 10 to 20
passes.

The sample dodexpire script for InterNetNews (called dodexpire.inn)
uses a script called makedexplist to create a dexplist dynamically. The
idea is to default most groups to a very low priority but raise the
priority of newsgroups recently read. In order to use makedexplist,
you must add a few lines to your news.daily script (at some point after
the syslog file has been rotated). For example we use:

	## topgroups
	rotate_files ${MOST_LOGS}/topgroups/topgroupslog 90
	topgroups > ${MOST_LOGS}/topgroups/topgroupslog

The rotate_files script is used to keep 90 days worth of top group
statistics.  the topgroups file takes the file dexplist.base, appends
recently read newsgroups at priority 100 and then appends a default
rule.

Our news node is a Sun SS2 running SunOS 4.1.4. Our spool filesystem
consists of two 2 GB Seagate scsi disks.

FILES
-----
CHANGES			- description of differences between releases
FILES			- list of files exported as part of the distribution
INSTALL			- this file
Makefile.in		- compilation rules (input to the configure script)
README			- this file
VERSION			- version of this release
aclocal.m4		- autoconf macros
blocktest.c		- block size test program
config.guess		- autoconf support
config.sub		- autoconf support
configure		- configure script (run this first)
configure.in		- configure script source
dexpire.8		- manual entry
dexpire.c		- main program
dexpire.h		- configuration
dexplist		- sample control file
disk.c			- disk usage routines
disk.h			- forward declarations
disktest.c		- disk filesystem test program
dodexpire.cnews		- sample dexpire script (C News version)
dodexpire.inn		- sample dexpire script (InterNetNews version)
dohisttrim.cnews	- sample histtrim script (C News version)
dohisttrim.inn		- sample histtrim script (InterNetNews version)
err.c			- 4.4 BSD err() and friends
err.h			- forward declarations
file.c			- active and dexplist parsers
file.h			- forward declarations
gdbrc			- gdb debugging macros
hash.c			- hash table utilities
hash.h			- forward declarations
histtrim.8		- manual entry
histtrim.c		- history file trimmer
install-sh		- BSD style install script
lbl/gnuc.h		- gcc macros and defines
lbl/os-*.h		- os dependent defines and prototypes
makedexplist		- script to dynamically create a dexplist file
mkdep			- BSD style dependency script
patchlevel.h		- patchlevel (required by some weenies)
rotate_files		- script to rotate log files
runexp.8		- manual entry
runexp.c		- process explicit expires
setproctitle.c		- set process title routine
setproctitle.h		- forward declarations
strerror.c		- 4.4 BSD strerror()
topgroups		- script to watch which newsgroups are read
util.c			- random utility routines
util.h			- forward declarations
