INSTALL

   1 atheme-services -- a set of services for IRC networks
   2 =====================================================
   3
   4 This program is free but copyrighted software; see the LICENSE file for
   5 details.
   6
   7 Information about Services may be found at https://atheme.github.io/
   8 Additional information can be found at: https://github.com/atheme/atheme/wiki
   9
  10 TABLE OF CONTENTS
  11 -----------------
  12
  13   1. Installation
  14   2. Upgrading
  15   3. Setting up IRCd
  16   4. Starting Services
  17   5. Setting up a crontab entry
  18   6. Compiling the contrib modules
  19
  20 You should also read the README and FAQ files.
  21
  22 1. INSTALLATION
  23 ---------------
  24
  25 You will need to obtain Atheme either by downloading the package from our
  26 website (https://atheme.github.io/) or git clone (https://github.com/atheme/atheme.git)
  27
  28 The IRCds supported by Services are listed in `dist/atheme.conf.example`.
  29 Although many others are supported, Services can provide the richest experience
  30 with Charybdis, InspIRCd, and UnrealIRCd.
  31
  32 NOTE: if you are using a third party package of Services, most of this section
  33 will not apply.
  34
  35 NOTE: if you are using a copy of Atheme downloaded from Git, you need to
  36 remember to run `git submodule update --init`. If not, you may ignore this
  37 step.
  38
  39 IMPORTANT NOTE: running services as 'root' is not supported. Use an
  40 unprivileged user account.
  41
  42 Services should compile and run on most POSIX compliant systems. The current
  43 version is known to work on:
  44
  45         FreeBSD 10.x                    (i386, amd64)
  46         FreeBSD 9.x                     (i386, amd64)
  47         FreeBSD 8.x                     (i386, amd64)
  48         Linux (glibc) 2.8–2.20                (i386, amd64)
  49         OS X 10.9                       (intel) (*)
  50         Windows XP+                     (i386, x64) (*)
  51
  52 Older versions have been tested on:
  53
  54         FreeBSD 7.0–7.4
  55         FreeBSD 6.0–6.3
  56         FreeBSD 5.0–5.5
  57         OpenBSD 3.5–3.8                       (i386, amd64, sparc)
  58         NetBSD 1.5–1.6                        (i386, amd64, sparc)
  59         NetBSD 2.0                      (i386, amd64, sparc, mips)
  60         NetBSD 3.0                      (i386)
  61         DragonFly 1.0, 1.2, 1.5
  62         Solaris 7–10                  (i86pc, sun4u)
  63         Solaris Express 10              (i86pc, sun4u)
  64         OS X 10.3.5, 10.4.1             (intel, powerpc)
  65
  66 Notes:
  67
  68  - (*) For OS X 10, install libmowgli (version 0.7.x) and pkg-config
  69    separately, possibly using a package/ports system. The included libmowgli
  70    does not work on OS X 10.
  71
  72  - (*) For Windows, please read doc/WINDOWS for compilation and installation
  73    instructions as well as a list of known caveats.
  74
  75  - Other BSD-based systems will probably work. Other SysV-based systems *might*
  76    work provided they support BSD sockets and POSIX function calls.
  77
  78  - Services requires a runtime linker. Systems which do not have a runtime
  79    linker will not be able to run services. However, most systems include a
  80    runtime linker these days.
  81
  82 1.1 Compiling
  83 -------------
  84
  85 If you are installing Services from Git and need libmowgli, please read the
  86 GIT-Access file for information on how to pull in libmowgli as a submodule.
  87
  88 Run the "configure" script:
  89
  90     $ ./configure --prefix=/path/to/install/
  91
  92 If no prefix is specified, the default install path is ~/atheme/.
  93
  94 If you're running a large network (more than 2000 users), you should
  95 pass the --enable-large-net switch to configure for enhanced performance.
  96
  97 The "configure" script will run several tests, write several files, and exit.
  98 Once this is done you will want to compile services. To do this, type:
  99
 100     $ make
 101
 102 After compilation, install services using:
 103
 104     $ make install
 105
 106 1.2 Errors
 107 ----------
 108
 109  - If you are on a BSD-based operating system, you may get an error like:
 110
 111        "Makefile", line 1: Need an operator
 112        "Makefile", line 2: Need an operator
 113        make: fatal errors encountered -- cannot continue
 114
 115    upon running 'make'. If so, run 'gmake' instead.
 116
 117  - If you get an error like this:
 118
 119        /usr/bin/install: cannot stat `es.mo': No such file or directory
 120        Failed to install es.mo!
 121
 122    You will need to install the 'gettext' package in your OS. Alternatively,
 123    recompile Atheme without NLS support:
 124
 125        $ ./configure --prefix=... --disable-nls
 126        $ make
 127
 128 1.3 Configuration
 129 -----------------
 130
 131 Next, you'll want to go to the directory you specified in "configure" and edit
 132 etc/atheme.conf. You'll need to change every setting or services will
 133 not work.
 134
 135 If you did not compile atheme yourself with the instructions above
 136 (eg. installing from a package manager), you can find example configuration
 137 files in the `dist/` directory of the Services' source code repository.
 138
 139 2. UPGRADING
 140 ------------
 141
 142 IMPORTANT NOTE: backup your configuration file and database!
 143
 144 All custom modules should be recompiled as well. Loading old modules can cause
 145 services to crash.
 146
 147 Sometimes upgrading requires more than recompiling and reinstalling. Be sure to
 148 read NEWS for important notes concerning the release. This file will let you
 149 know if you need to change your configuration or convert your database to a new
 150 format.
 151
 152 3. SETTING UP IRCD
 153 ------------------
 154
 155 Services acts as an IRC server with pseudo-clients on it. To link it to your
 156 network, you'll need to add some lines in your IRCd's configuration. Services
 157 connects to your IRCd, not the other way around.
 158
 159 It is suggested that you set up your IRCd (IRC operator access, etc) before
 160 trying to connect services. Many IRCds do not log much about server
 161 connections, so it is best to connect as an IRC operator and watch the server
 162 notices.
 163
 164 As for the actual lines that need to be added, every IRCd is different. Look
 165 for documentation for "connect{}" or "link{}" or "C/N lines" for your IRCd. You
 166 need to allow services to introduce other servers (e.g. "hub_mask" or H:line),
 167 otherwise it will probably be disconnected when the OperServ JUPE command is
 168 used.
 169
 170 Additionally, you need to do some configuration on all servers on the network.
 171 You need to reserve ("resv{}", "/resv", "Q line", etc) all nicks services uses
 172 to avoid normal users taking those nicks and causing trouble. Also, many IRCds
 173 need to be configured to grant special privileges to services ("service{}",
 174 "shared{}", "ulines{}", "U lines", etc).
 175
 176 See doc/IRCD for more details concerning IRCd-specific requirements for running
 177 services.
 178
 179 4. STARTING SERVICES
 180 --------------------
 181
 182 Go into the directory where you installed atheme-services (by default,
 183 ~/atheme/). If this is your first time running services, type
 184 "./bin/atheme-services -b" to create a database file.
 185
 186 Next, type ./bin/atheme-services to launch services.
 187
 188 Services will report any errors and/or detach into the background.
 189
 190 If services doesn't link and/or terminates without warning check the log file
 191 (var/atheme.log) to see what happened. If this tells you nothing try rerunning
 192 services via ./bin/atheme-services -dn for more verbose information.
 193
 194 5. SETTING UP A CRONTAB ENTRY
 195 -----------------------------
 196
 197 A crontab entry will allow you to check periodically whether services is still
 198 running, and restart it if not. You'll need to have atheme-services binaries
 199 and data installed in the same directory for this to work without modification.
 200
 201 First rename the etc/atheme.cron.example script that is in Atheme path (by
 202 default, ~/atheme/) and edit it. You'll need to modify the "cd" part of the
 203 file.  Then ensure that the file is marked as executable by typing "chmod +x
 204 atheme.cron.example" and try to launch the script to see if it works.
 205
 206 When this is done, you'll have to add the crontab entry. Type "crontab -e" This
 207 will open the default text editor with the crontab file. Enter the following
 208 (with correct path):
 209
 210     */5 * * * * ~/atheme/etc/atheme.cron.example >/dev/null 2>&1
 211
 212 The */5 at the beginning means "check every 5 minutes." You may replace the 5
 213 with other another number if you want (but less than 60). Save and exit, and
 214 it's installed.
 215
 216 6. COMPILING THE CONTRIB MODULES
 217 --------------------------------
 218
 219 In the Atheme source there is a directory called contrib filled with all sorts
 220 of modules that are not included in the main modules directory for one reason
 221 or another. Compiling these modules is very simple.
 222
 223 A README for what each contrib module does is at `modules/contrib/README`.
 224
 225 Pass the --enable-contrib switch to the configure script like so:
 226
 227     $ ./configure --enable-contrib
 228
 229 The contrib modules will then be in your atheme install directory (by default
 230 this is ~/atheme/) in the modules/contrib directory. you can then load them on
 231 a live network like:
 232
 233     /msg operserv modload contrib/os_kill
 234
 235 or in your atheme.conf by adding a loadmodule line like:
 236
 237     loadmodule "modules/contrib/os_kill";