ermyth -- a set of services for IRC networks ===================================================== This program is free but copyrighted software; see the LICENSE file for details. Information about Services may be found at http://ermyth.schmorp.de/. TABLE OF CONTENTS ----------------- 1. Installation 2. Upgrading 3. Setting up IRCd 4. Starting Services 5. Setting up a crontab entry You should also read the README and FAQ files. 1. INSTALLATION --------------- NOTE: if you are using a third party package of Services, most of this section will not apply. IMPORTANT NOTE: it is not recommended to use and install services as root. Use an unprivileged user account. Services should compile and run on most POSIX compliant systems. The list of platforms that ermyth has been tested on includes: FreeBSD 4.[8,9,10,11] FreeBSD 5.[0,1,2,3,4] FreeBSD 6.[0] FreeBSD 7.[0] OpenBSD 3.[5,6,7,8] (i386, amd64, sparc) NetBSD 1.[5,6] (i386, amd64, sparc) NetBSD 2.[0] (i386, amd64, sparc, mips) NetBSD 3.[0] (i386) DragonFly 1.[0,2,5] Linux (glibc) 2.6.x (i386, amd64) Solaris [7,8,9,10] (i86pc, sun4u) Solaris Express 10 (i86pc, sun4u) MacOS 10.[3.5,4.1] (intel, powerpc) Other BSD-based systems will probably work. Other SysV-based systems *might* work provided they support BSD sockets and POSIX function calls. Services requires a runtime linker. Systems which do not have a runtime linker will not be able to run services. However, most systems include a runtime linker these days. IRCd's known to be supported by Services are listed in the example config (dist/example.conf). The recommended ones are charybdis, ratbox, inspircd, asuka, beware ircd (bircd), nefarious and undernet-ircu (undernet). The easy way: run the "setup" script. This does it all for you: $ ./setup Follow the instructions and you're good to go. The slightly less easy but more traditional way: Run the "configure" script: $ ./configure --prefix=/path/to/install/ If you're running a large network (more than 2000 users), you should pass the --enable-large-net switch to configure for enhanced performance. The "configure" script will run several tests, write several files, and exit. Once this is done you will want to compile services. To do this, simply type: $ make Services will compile. To install, type: $ make install The newly-compiled binary and several supporting files will be copied to the directory you specified in the "configure" script. It is recommended to keep the source directory; you will need it to (re)compile modules later. Next, you'll want to go to the directory you specified in "configure" and edit etc/ermyth.conf. You'll need to change every setting or services will not work. 2. UPGRADING ------------ IMPORTANT NOTE: backup your configuration file and database! All custom modules should be recompiled as well. Loading old modules can cause services to crash. Sometimes upgrading requires more than recompiling and reinstalling. Be sure to read doc/RELEASE for important notes concerning the release. This file will let you know if you need to change your configuration or convert your database to a new format. 3. SETTING UP IRCD ------------------ Services acts as an IRC server with pseudo-clients on it. To link it to your network, you'll need to add some lines in your IRCd's configuration. Services connects to your IRCd, not the other way around. It is suggested that you set up your IRCd (IRC operator access, etc) before trying to connect services. Many IRCds do not log much about server connections, so it is best to connect as an IRC operator and watch the server notices. As for the actual lines that need to be added, every IRCd is different. Look for documentation for "connect{}" or "link{}" or "C/N lines" for your IRCd. You need to allow services to introduce other servers (e.g. "hub_mask" or "H line"), otherwise it will probably be disconnected when the OperServ JUPE command is used. To be perfectly honest, if you can't figure this out you should be running neither IRCd nor services. Additionally, you need to do some configuration on all servers on the network. You need to reserve ("resv{}", "/resv", "Q line", etc) all nicks services uses to avoid normal users taking those nicks and causing trouble. Also, many IRCds need to be configured to grant special privileges to services ("service{}", "shared{}", "ulines{}", "U lines", etc). See doc/IRCD for more details concerning IRCd-specific requirements for running services. 4. STARTING SERVICES -------------------- Go into the directory where you installed ermyth (by default, ~/ermyth/). Type ./bin/ermyth to launch services. Services will report any errors and/or detach into the background. If services doesn't link and/or terminates without warning check the log file (var/ermyth.log) to see what happened. If this tells you nothing try rerunning services via ./bin/ermyth -nd for more verbose information. 5. SETTING UP A CRONTAB ENTRY ----------------------------- A crontab entry will allow you to check periodically whether services is still running, and restart it if not. You'll need to have ermyth binaries and data installed in the same directory for this to work without modification. First rename the dist/ermyth.chk script that is in Ermyth path (by default, ~/ermyth/) and edit it. You'll need to modify the "cd" part of the file. Then ensure that the file is marked as executable by typing "chmod +x ermyth.chk" 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. Enter the following (with correct path): */5 * * * * /home/yourname/ermyth/etc/ermyth.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.