INSTALLING THE ETERNITY SERVER

There is now a mailing list for discussion of eternity servers.  That
mailing list might be a good place to discuss problems installing or
submitting documents.  Details in file LIST.

0. You should have untarred this into ~/public_html/ like so:

	% cd ~/public_html
	% gzip -c ~/eternity-0.10.tgz | tar xf -
	% mv eternity-0.10 eternity

1. Check that you have an sha1 executable.  If not compile the one in
   the sha1/ directory.  (Read file sha1/README for instructions on
   compiling)

   Check that sha1 functions correctly:

	% echo hello world | sha1
	22596363b3de40b06f981fb85d82312e8c0ed511
	%

   If you run into trouble, you can fall back to the sha1.pl one. 
   You can rename it to sha1 if you like.  The server only computes
   hashes on very small documents so it won't be much slower.

2. Find out where perl5 lives on your system.  (This system won't work
   with perl4).  You can find and check the version of perl like this

	% where perl
	/usr/local/bin/perl
	% /usr/local/bin/perl -v
	This is perl, version 5.003 ...
	%

   Or locate is a handy command if your system has it:

	% locate perl
	
   Or find:

	% find / -name perl\* -print


3. Edit eternity.conf to reflect your system

  eternity.conf has masses of comments in it.  If you can't figure
  anything out send me an email: aba@dcs.ex.ac.uk my PGP key is
  included with this distribution as adam-key.asc

  If you run into config problems please let me know so that
  I can fix them.

  You can check for the latest version at:

	  http://www.dcs.ex.ac.uk/~aba/eternity/ 

  A tip is to leave your news source set to "news" which is a small
  test newspool contained in this distribution with example eternity
  documents in it.  Once you've got eternity working serving docs out
  of that, you can turn it loose on your real newspool or an NNTP
  server.

4. Edit host.html to give a few words about you the providor/operator.  Eg.
   "This service providor is hosted by my isp isp.com" link to something?

5. (Optional) edit disclaimer.html to suit your tastes in disclaimer.
   The default one says in a small font:

    Note to censors: Eternity servers are specialised seach engines for
    reading web documents from USENET news.  The pages you request are
    actually USENET news posts which the server is searching for,
    reformatting and forwarding to you.  The administrator of this
    server has no control over the content of USENET news, and will not
    be held responsible for any documents you instruct this server to
    forward for you.

  Edit if you fancy.

6. Run configure:

	% perl configure

   If the file you want to edit has a .dist version, edit the .dist
   version.  You will see magic strings in them like @cgi@, don't
   disturb them as they are replaced by configure.  To update
   anything, edit all the .dist files you wish, and then run
   configure.

   Some files do not have .dist versions, this is because they don't
   need to be configured by configure, as they have no use for the
   values substituted into the magic variables @cgi@ and friends.  You
   can edit these files directly.

   If you have to edit files other than for cosmetic or style
   preference purposes to get something to work, tell me about it so I
   can fix it in the next release.  (Excluding eternity.conf of course
   which exists soley for you to edit).

7. cron

   If you've opted for the cron method of controlling how often
   eternity reads news, you'll need appropriate user priviledges to
   run cron jobs.  On some systems this might require root's
   assistance.  The job you want to run is:

	eternity -u

   Note also that your cron'd eternity should run as the same user as
   your eternity.cgi runs as, otherwise you may get permission
   problems.

8. Debugging

   If things go wrong, the first easy thing to check is that it's not
   to do with the interaction with the NNTP news server or local news
   spool.  There is a sample debugging news spool included with this
   distribution inside directory news.  There is one newsgroup in there,
   alt.anonymous.messages (the articles for which reside as you might
   expect, in: news/alt/anonymous/messages).

   Edit eternity.conf to make it say for it's news reading method

     news_spool = "news"

   Reset eternity with:

     % eternity -r

   Then do the update: if you're running with cgi_udate = on, just
   click on go for the eternity search on the eternity home page; if
   you're running with cgi_update = off, and therefore using cron, you
   can either start the cron job, or just run it from the command
   line:

     % eternity -u

   Then try using the go button on the eternity document index.  If
   there are no documents you've got problems.  (you should see URL:

	http://test.eternity/example1/ 

   in the document index with search term 

	http://*
   ) 

   One thing you can do at this point is to run dbmcat which will
   display the contents of eternity's article database.  The output
   should look like this:

	% 1531af3eb207fad611b1a04698832d5789d9d94f <3.test> \
		alt.anonymous.messages 3 \
		b652801cf75db5272bc1de5216428ab703ac0e27 1 exdirectory 1
	alt.anonymous.messages 3
	7e942d94fe4e47cf91951e0f4bb5a22d0fcf75e5 <1.test> \
		alt.anonymous.messages 1 \
		b652801cf75db5272bc1de5216428ab703ac0e27 1 directory 1
	http://test.eternity/example1/ Example Eternity Document
	79975a161851c6a2093e006c1c229a9f2bed1037 <2.test> \
		alt.anonymous.messages 2 \
		b652801cf75db5272bc1de5216428ab703ac0e27 1 exdirectory 1
	time 870957369
	%

   (Only the lines will be wrapped rather than ending with a slash
   and having leading tab on continuation lines as I have shown above to
   make it readable in a text document).

   If you don't get any of those, you can look at the log file for
   errors, just cat it.  If it's empty, you'll need to increase the
   verbosity of logging, and repeat.  The distribution setting is to
   log errors only.  Find line:

	my $logging = $err;

   in eternity.cgi.dist and change it to:

	my $logging = $all;

   You'll see just above that line some explanations of how to more
   finely control what is logged.

   Run configure again to update eternity.cgi with the changes you
   just made to eternity.cgi.dist:

	% perl configure

   Re-run the tests (eternity -r, then update as described above),
   read the log and see if it gives you any clues.  If not mail it to
   me with an explanation of what the symptoms of your failure were.

   If that all works but reading from a real news feed doesn't, first
   thing to check is that there are in fact some eternity documents in
   alt.anonymous.messages, they all have form 

	Subject: abcd1234fabef321abcd1234fabef321abcd1234

   Where the subject is a 40 digit hex number.  If there are no
   articles that'll be your problem.  If the your site doesn't carry
   alt.anonymous.messages arrange this.

   If there are articles and it's not reading them (not showing up in
   dbmcat output), then turn on verbose logging as described above
   read the log and see if you can work out whats going wrong.  If you
   can't make sense of the log file, email it to me and I'll see if I can
   help.

Adam Back <aba@dcs.ex.ac.uk>
PGP key is adam-key.asc
