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

Table of contents
-----------------
  1. Installing Epona
  2. Upgrading Epona
  3. Setting up the IRCd
  4. Starting Epona
  5. Setting up cron jobs
  
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.

Make sure you have gcc 3.3 or later installed to compile Epona, and that
the C++ compiler (g++) is installed too. I can't guarantee Epona will
compile/run correctly with other compilers. perl needs to be installed.
as well.

Besides gcc, the following packages are needed for all features to be
enabled:
  * Bzip2 library
  * MySQL client libraries 4.1.13 or later;
  * OpenSSL
  * Zlib

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

PegSoft (France) (always up-to-date)
    ftp://ftp.pegsoft.net/epona/

Next, unpack the package in your home directory, and go into the
created repertory.

Source code needs to be configured before it is compiled, so you'll now
have to run the configure script by typing:

    ./configure options

where options can be one or more of the following:

* --prefix=path: installs Epona in a different location than the
  the default ($HOME/epona).
* --with-ircd=type: selects the IRCd used by the network to
  which your services will be linked. Possible type values: bahamut,
  dreamforge, sequana, unreal and ultimate. (REQUIRED)

* --with-bzlib=DIR: specifies an alternative root path for the system
  bzlib installation. By default, the configure looks for bzlib library
  in /usr/local, or /usr if it isn't found in /usr/local. If it can't
  find it at all, then some modules are disabled.
* --with-mysql=DIR: specifies an alternative path for the mysql_config
  script installed with MySQL. By default, the configure script looks
  for it in the directories listed in the PATH environment variable.
  If MySQL can't be found, then some modules are disabled.
* --with-openssl=DIR: specifies an alternative root path for the system
  OpenSSL installation. By default, the configure looks for OpenSSL
  library in /usr/local, or /usr if it isn't found in /usr/local. If it
  can't find it at all, then some modules are disabled.
* --with-zlib=DIR: specifies an alternative root path for the system
  zlib installation. By default, the configure looks for zlib library
  in /usr/local, or /usr if it isn't found in /usr/local. If it can't
  find it at all, then some modules are disabled.

You can now type make to compile Epona.

Now type make install. This will install all the needed files in the
directory determined by the configure script. You should ensure
that this directory is not accessible by other users, as malicious 
people 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 installation directory (by default, ~/epona). Copy
the epona.conf.dist file to epona.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 only the default values is NOT a good
idea, and will most likely not work! You may then need to edit the
configuration files of the modules you're going to use.

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 to me directly; I unfortunately don't have the time
to answer all technical questions (but I'm reading the mailing list so
I'll be able to give you my thoughts if your problem is very special.)

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 make distclean so that the source tree returns to its initial
    uncompiled and unconfigured state (you may get compilation errors
    if you don't do this).
  * 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: Always backup your data!
  * If you are upgrading to a new major release, it is recommended to
    redo configuration from scrach through the new epona.conf.dist.

2.1 Upgrading from Epona 1.0, 1.1 or 1.2
----------------------------------------

Starting with Epona 1.5, this is not supported anymore. You should
try to load and save your databases with the last release of Epona 1.4.

2.2  Upgrading from Epona 1.3 or 1.4
------------------------------------

* The installation process has changed. But if you're reading this, you
should have already read section 1 of this file, right? :P

* The binary has been renamed to "epona", and the default configuration
file to "epona.conf". You should update any script (I'm thinking to the
crontab script in particular) or other stuff that rely on the old names.

* The configuration file has entirely changed so you must start a new
configuration from scratch.

* Rotated log files are now stored in an index by the logfile module
which is used to determine how many files were rotated and which to
delete first. As a result, old log files won't be deleted by the
logfile module. You must delete them manually when you don't need
them anymore.

* Epona can't retrieve data from the old databases anymore. But fret
  not, it is still possible to convert your old data ! In order to
  do this, configure Epona properly, copy your old databases to the
  main directory as set by the directory directive in epona.conf,
  and follow these steps:
  
    - Go to the directory where you copied the old databases:
      $ cd ~/epona
    - Create a directory to export the old data to:
      $ mkdir xml
    - Export the old data. Replace yourircd with either bahamut,
      dreamforge, ultimate or unreal, depending on the ircd Epona
      was connected to when saving the old databases.
      $ ./epona -m dbexport --source=legacydb --dir=xml --ircd=yourircd
    - Finally import the data. Replace dbmod with whatever database
      module you are going to use.
      $ ./epona -m dbimport --target=dbmod --dir=xml

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

Epona is 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 services::connect configuration
directive).

For examples below we'll use services.localhost.net as the name of
the services pseudo-server (as stated in the services::name
configuration directive).

3.1 Unreal
----------

Add a link block to allow services to link to the network.

link services.localhost.net
{
	username *;
	hostname 127.0.0.1;
	bind-ip *;
	port 6667;
	hub *;
	password-connect "ircservices";
	password-receive "ircservices";
	class servers;
};

mypass is the same password you mentionned in the services::password 
configuration directive. 127.0.0.1 is the IP from which services
connect from (linking to localhost is the most efficient way
to run services). The "hub *" is needed by the OperServ JUPE command.

Then, you have to put services in the ulines, so they can change
channel modes, topics, and much more without being opped on the
channel.

ulines {
	epona.teepi.net;
};

3.2 Bahamut
-----------

First, there are a few options we need to check for correctness.

options {
    ... other options ...
    servtype hub;
    services_name services.localhost.net;
    stats_name services.localhost.net;
    ... other options ...
};

Setting the services_name and stats_name to the name of the services'
pseudo-server will enable the services-specific aliases (/nickserv,
/chanserv etc.) Also, make sure the servtype is set to hub AND NOT
serviceshub, as this would enable "optimizations" that are not
compatible with Epona.

Next, the directives to allow services to link to the network.

class {
    name 30;
    pingfreq 600;
    maxusers 0;
    connfreq 120;
    maxsendq 3500000;
};

connect {
    name "services.localhost.net";
    host "*@127.0.0.1";
    apasswd "mypass";
    cpasswd "mypass";
    flags H;
    class "30";
};

mypass is the same password you mentionned in the services::password 
configuration directive. 127.0.0.1 is the IP from which services
connect from (linking to localhost is the most efficient way
to run services). The H flag is needed by the OperServ JUPE command.

Then, you have to make services a super-server, so they can change
channel modes, topics, and much more without being opped on the
channel.

super {
    services.localhost.net;
};

3.3 Other IRCds
---------------

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 services::password 
configuration directive. 127.0.0.1 is the IP from which services
connect from (linking to 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 
on 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 installation directory (by default, ~/epona). Type 
./epona to launch Epona.

If there are syntax errors in the configuration file they will be 
displayed on the screen. Other errors may arise too. Correct them
until there are no errors anymore. On successful startup, Epona
says it's going into background. 

Give to Epona at least one minute to link to your network, as 
certain IRCds on some OSes may be really slow for the link process.
Note that this delay may be longer if you set up compressors in
the logfile module.

If nothing happens then, it is probably a configuration problem.
Try to launch Epona with ./epona -df 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 cron jobs
-----------------------

Epona comes with crontab scripts that help you do various maintenance
tasks automatically. Adding them as cron jobs, while optional, is
highly recommended, so that they will be run periodically.

a. epona.chk
------------

This script checks whether Epona is still running, and restarts it if not.

First rename the epona.chk.dist script that has been installed by Epona
(by default, it's in ~/epona/sbin) to epona.chk (or what you like most)
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 epona.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 (if you
hate the default editor, type EDITOR=yourfavoriteeditorname crontab -e). 
Enter the following (change path as appropriate):

*/5 * * * * /home/ircd/epona/sbin/epona.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.

b. db-backup.sh
---------------

This script is useful to do periodic backups of your data, no matter
what database module you're using. Its use is therefore highly
recommended.

First rename the db-backup.sh.dist script that has been installed by
Epona (by default, it's in ~/epona/sbin) to db-backup.sh (or what you
like most) 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 db-backup.sh, and try to launch the script to see if it works.

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 (if you
hate the default editor, type EDITOR=yourfavoriteeditorname crontab -e). 
Enter the following (change path as appropriate):

3 0 * * * /home/ircd/epona/sbin/db-backup.sh >/dev/null 2>&1

This runs the backup script every day, 3 minutes after midnight.