EPONA INSTALLATION INSTRUCTIONS
===============================

Table of contents
-----------------
  1. Installing Epona
  2. Upgrading Epona
  3. Setting up the IRCd
  4. Starting Epona
  5. Setting up a crontab
  6. Converting databases from another services package
  
You should also read the README and FAQ files!

1. Installing Epona
-------------------

IMPORTANT NOTE: it is not recommended to use (and therefore install)
Epona as root. Use an unprivilegied user instead -- the one you're
using for the ircd or a dedicated one will be good enough.

The very first thing you need to do is to get the Epona package
(if not already done). You may found it at the following places:

PegSoft (France) (always updated)
    ftp://ftp.pegsoft.net/epona/
    
ViaIRC (Brazil) (updated every day)
    ftp://ftp.viairc.com/epona/
LeCentre (France) (updated once a week)
    ftp://ftp.lecentre.net/mirror/ftp.pegsoft.net/epona/
AtomicFault (USA) (updated every day)
    ftp://ftp.atomicfault.com/mirror/epona/
Brazil Marketing Services (USA) (updated every day)
    ftp://ftp.brmarket.net/epona/

Next, unpack the package in your home directory, and go into the
created repertory.
  
Now type ./configure to start the configuration script. It will
ask you a few questions, and figure out how to compile Epona on
your system. If you are unsure about what to answer to a question,
use the default value. NOTE: although you may specify different
binary and data paths, it is RECOMMENDED that you use the same
value for both.

You can now type make to compile Epona. If there are errors in the
Makefile, try to use gmake instead. If it still doesn't work, you
(or the system administrator if it's a shell) must install GNU
make. You may find it at ftp://prep.ai.mit.edu/pub/gnu/.

Now type make install (or gmake install; see above). This will
install all the needed files in the paths you specified with the
configure script, and setup file permissions. You should ensure
that the data directory is not accessible by other users, as malicious 
users may cause troubles on your network if passwords are not 
encrypted, or read the memos of any user.

If you got errors during this process, please mail me with the 
*complete* error output, and don't forget to mention your OS, 
compiler and C library versions. 

Now go into the data directory (by default, ~/services). Copy the
example.conf file to services.conf, and open the latter with your 
favourite text editor. It contains all the configuration
directives Epona will use at startup. Read the instructions contained
in the file carefully. Using the default values is NOT a good idea,
and will most likely not work!

If you need help, you should subscribe to the Epona mailing list and
mail there to get help from other users. See the README file for more
information.

DON'T ask for help directly to me, as there are 99.99% chances you 
won't get an answer.

2. Upgrading Epona
------------------

If you got a .diff file and want to patch the old Epona sources with it, do 
the following:
  * Copy the .diff file into the root Epona sources directory.
  * Type patch -p1 <file.diff

To upgrade Epona, just follow the installation instructions described in
section 1. There are however a few specific guidelines:

  * IMPORTANT: Back up your old databases!
  * If you are upgrading to a new major release, ALWAYS restart a 
    fresh configuration file from example.conf.

Version 1.3.0 merges the AKILL database with the OperServ database. This is
an automatic process and you have nothing to do (just ensure that
AutoKillDB in services.conf is set correctly and maybe remove the AKILL
database after the conversion).

3. Setting up the IRCd
----------------------

Services are acting as an IRC server with pseudo-clients on it. To link
them to your network, you'll need to add some lines in the ircd.conf
of their hub server (as stated in the RemoteServer configuration
directive).

For samples below we'll take Services.LocalHost.Net as the name of
the Services (as stated in the ServerName configuration directive).

First, the C/N lines, that allow Services to link. They also need a
Y:line to work correctly.

Y:27:180:0:0:4000000
C:127.0.0.1:mypass:Services.LocalHost.Net::30
N:127.0.0.1:mypass:Services.LocalHost.Net::30

mypass is the same password you mentionned in the RemoteServer 
configuration directive. 127.0.0.1 is the IP from which Services
connect from (linking in localhost is the most efficient way
to run Services).

Then, you have to set-up an U:line, that will allow Services to
change channel modes, topics, and much more without being opped 
in the channel.

U:Services.LocalHost.Net:*:*

NOTE: if you have more than one server in your network, this line
MUST be added on ALL servers, or things won't work.

Finally, you'll need to add an H:line, to make the OperServ JUPE
command work correctly.

H:*::Services.LocalHost.Net

Don't forget to /rehash to apply changes.

4. Starting Epona
-----------------

Go into the directory where binaries were installed (by default,
~/services). Type ./services to launch Epona.

If there are syntax errors in the configuration file they will be 
displayed on the screen. Correct them until there are no errors 
anymore. A successful startup won't generate any message. 

Give to Services at least one minute to link to your network, as 
certain IRCds on some OSes may be really slow for the link process.
If nothing happens then, it is probably a configuration problem.
Try to launch Epona with ./services -debug -nofork to see any errors
that it encounters, and try to correct them.

If you need help to resolve errors, feel free to subscribe to the
Epona mailing list and ask there. See the README file for details.

5. Setting up a crontab
-----------------------

A crontab entry will allow you to check periodically whether Epona
is still running, and restart it if not. You'll need to have
Epona binaries and data installed in the same directory for this to
work without modification.

First rename the example.chk script that is in Epona path (by default, 
~/services) to services.chk and edit it. You'll need to modify the 
CONFIGURATION part of the file. Then ensure that the file is marked as 
executable by typing chmod +x services.chk, and try to launch the script 
to see if it works (Epona must not be started when you do this ;).

When this is done, you'll have to add the crontab entry. Type crontab -e.
This will open the default text editor with the crontab file. Enter the
following (with correct path):
*/5 * * * * /home/ircd/services/services.chk >/dev/null 2>&1
The */5 at the beginning means "check every 5 minutes". You may replace
the 5 with other another number if you want (but less than 60).
Save and exit, and it's installed.

6. Converting databases from another services package
-----------------------------------------------------

Epona has on-the-fly conversion capabilities for certain database
formats generated by other services package. You can choose
what converter should be compiled within Epona in the configure
script. You must then launch Epona with the correct parameter
on the command line (this may also be found in the configure script)
the first time you launch Epona (AND ONLY THE FIRST TIME!).

You must place the old databases in the Epona data directory before
the conversion. They must have the original default name, or they
won't be taken in account. They will be renamed with a suffix .old,
and converted databases will be created with the names you set
in services.conf (...DB directives).

You must note that, for some reasons, the databases will be converted
to ircservices-4.3.3 before being reconverted to the Epona current
format when the first save occurs. This means that any data for features
that were not existing in ircservices-4.3.3 will be lost, even
if these have currently equivalent features in Epona!

If a converter doesn't work for you, even partially, please let me know, 
and we'll try to fix the problem together. :)
