| 1 |
Ermyth -- a set of services for IRC networks |
| 2 |
===================================================== |
| 3 |
|
| 4 |
Ermyth is free software: you can redistribute it and/or modify |
| 5 |
it under the terms of the GNU General Public License as published by |
| 6 |
the Free Software Foundation, either version 3 of the License, or |
| 7 |
(at your option) any later version. |
| 8 |
|
| 9 |
Information about Ermyth may be found at http://ermyth.xinutec.org/. |
| 10 |
|
| 11 |
TABLE OF CONTENTS |
| 12 |
----------------- |
| 13 |
1. Installation |
| 14 |
2. Upgrading |
| 15 |
3. Setting up IRCd |
| 16 |
4. Starting Ermyth |
| 17 |
5. Setting up a crontab entry |
| 18 |
|
| 19 |
You should also read the README and FAQ files. |
| 20 |
|
| 21 |
1. INSTALLATION |
| 22 |
--------------- |
| 23 |
|
| 24 |
NOTE: if you are using a third party package of Ermyth, most of this section |
| 25 |
will not apply. |
| 26 |
|
| 27 |
IMPORTANT NOTE: it is not recommended to use and install services as root. |
| 28 |
Use an unprivileged user account. |
| 29 |
|
| 30 |
Ermyth should compile and run on most POSIX compliant systems. The list of |
| 31 |
platforms that ermyth has been tested on includes: |
| 32 |
FreeBSD 4.[8,9,10,11] |
| 33 |
FreeBSD 5.[0,1,2,3,4] |
| 34 |
FreeBSD 6.[0] |
| 35 |
FreeBSD 7.[0] |
| 36 |
OpenBSD 3.[5,6,7,8] (i386, amd64, sparc) |
| 37 |
NetBSD 1.[5,6] (i386, amd64, sparc) |
| 38 |
NetBSD 2.[0] (i386, amd64, sparc, mips) |
| 39 |
NetBSD 3.[0] (i386) |
| 40 |
DragonFly 1.[0,2,5] |
| 41 |
Linux (glibc) 2.6.x (i386, amd64) |
| 42 |
Solaris [7,8,9,10] (i86pc, sun4u) |
| 43 |
Solaris Express 10 (i86pc, sun4u) |
| 44 |
MacOS 10.[3.5,4.1] (intel, powerpc) |
| 45 |
|
| 46 |
Other BSD-based systems will probably work. Other SysV-based systems *might* |
| 47 |
work provided they support BSD sockets and POSIX function calls. |
| 48 |
|
| 49 |
IRCd's known to be supported by Ermyth are listed in the example |
| 50 |
config (dist/example.conf). The recommended ones are charybdis, ratbox, |
| 51 |
inspircd, asuka, beware ircd (bircd), nefarious and undernet-ircu |
| 52 |
(undernet). |
| 53 |
|
| 54 |
The easy way: run the "setup" script. This does it all for you: |
| 55 |
$ ./setup |
| 56 |
|
| 57 |
Follow the instructions and you're good to go. |
| 58 |
|
| 59 |
The slightly less easy but more traditional way: |
| 60 |
|
| 61 |
Run the "configure" script: |
| 62 |
$ ./configure --prefix=/path/to/install/ |
| 63 |
|
| 64 |
If you're running a large network (more than 2000 users), you should |
| 65 |
pass the --enable-large-net switch to configure for enhanced performance. |
| 66 |
|
| 67 |
The "configure" script will run several tests, write several files, and exit. |
| 68 |
Once this is done you will want to compile services. To do this, simply |
| 69 |
type: |
| 70 |
$ make |
| 71 |
|
| 72 |
Ermyth will compile. To install, type: |
| 73 |
$ make install |
| 74 |
|
| 75 |
The newly-compiled binary and several supporting files will be copied to the |
| 76 |
directory you specified in the "configure" script. |
| 77 |
|
| 78 |
It is recommended to keep the source directory; you will need it to |
| 79 |
(re)compile modules later. |
| 80 |
|
| 81 |
Next, you'll want to go to the directory you specified in "configure" and edit |
| 82 |
etc/ermyth.conf. You'll need to change every setting or services will |
| 83 |
not work. |
| 84 |
|
| 85 |
2. UPGRADING |
| 86 |
------------ |
| 87 |
|
| 88 |
IMPORTANT NOTE: backup your configuration file and database! |
| 89 |
|
| 90 |
All custom modules should be recompiled as well. Loading old modules can |
| 91 |
cause services to crash. |
| 92 |
|
| 93 |
Sometimes upgrading requires more than recompiling and reinstalling. Be sure to |
| 94 |
read doc/RELEASE for important notes concerning the release. This file will |
| 95 |
let you know if you need to change your configuration or convert your database |
| 96 |
to a new format. |
| 97 |
|
| 98 |
3. SETTING UP IRCD |
| 99 |
------------------ |
| 100 |
|
| 101 |
Ermyth acts as an IRC server with pseudo-clients on it. To link it to |
| 102 |
your network, you'll need to add some lines in your IRCd's |
| 103 |
configuration. Ermyth connects to your IRCd, not the other way around. |
| 104 |
|
| 105 |
It is suggested that you set up your IRCd (IRC operator access, etc) before |
| 106 |
trying to connect services. Many IRCds do not log much about server |
| 107 |
connections, so it is best to connect as an IRC operator and watch the |
| 108 |
server notices. |
| 109 |
|
| 110 |
As for the actual lines that need to be added, every IRCd is different. Look |
| 111 |
for documentation for "connect{}" or "link{}" or "C/N lines" for your IRCd. You |
| 112 |
need to allow services to introduce other servers (e.g. "hub_mask" or "H |
| 113 |
line"), otherwise it will probably be disconnected when the OperServ |
| 114 |
JUPE command is used. |
| 115 |
|
| 116 |
To be perfectly honest, if you can't figure this out you should be running |
| 117 |
neither IRCd nor services. |
| 118 |
|
| 119 |
Additionally, you need to do some configuration on all servers on the network. |
| 120 |
You need to reserve ("resv{}", "/resv", "Q line", etc) all nicks |
| 121 |
services uses to avoid normal users taking those nicks and causing |
| 122 |
trouble. Also, many IRCds need to be configured to grant special |
| 123 |
privileges to services ("service{}", "shared{}", "ulines{}", "U lines", |
| 124 |
etc). |
| 125 |
|
| 126 |
See doc/IRCD for more details concerning IRCd-specific requirements for |
| 127 |
running services. |
| 128 |
|
| 129 |
4. STARTING SERVICES |
| 130 |
-------------------- |
| 131 |
|
| 132 |
Go into the directory where you installed ermyth (by default, |
| 133 |
~/ermyth/). Type ./bin/ermyth to launch services. |
| 134 |
|
| 135 |
Ermyth will report any errors and/or detach into the background. |
| 136 |
|
| 137 |
If services doesn't link and/or terminates without warning check the log |
| 138 |
file (var/ermyth.log) to see what happened. If this tells you nothing try |
| 139 |
rerunning services via ./bin/ermyth -nd for more verbose |
| 140 |
information. |
| 141 |
|
| 142 |
5. SETTING UP A CRONTAB ENTRY |
| 143 |
----------------------------- |
| 144 |
|
| 145 |
A crontab entry will allow you to check periodically whether services is |
| 146 |
still running, and restart it if not. You'll need to have ermyth |
| 147 |
binaries and data installed in the same directory for this to work |
| 148 |
without modification. |
| 149 |
|
| 150 |
First rename the dist/ermyth.chk script that is in Ermyth path (by default, |
| 151 |
~/ermyth/) and edit it. You'll need to modify the "cd" part of the file. |
| 152 |
Then ensure that the file is marked as executable by typing |
| 153 |
"chmod +x ermyth.chk" and try to launch the script to see if it works. |
| 154 |
|
| 155 |
When this is done, you'll have to add the crontab entry. Type "crontab -e" |
| 156 |
This will open the default text editor with the crontab file. Enter the |
| 157 |
following (with correct path): |
| 158 |
|
| 159 |
*/5 * * * * /home/yourname/ermyth/etc/ermyth.chk >/dev/null 2>&1 |
| 160 |
|
| 161 |
The */5 at the beginning means "check every 5 minutes." You may replace |
| 162 |
the 5 with other another number if you want (but less than 60). Save and exit, |
| 163 |
and it's installed. |
