INSTALL

   1
   2                      ngIRCd - Next Generation IRC Server
   3                            http://ngircd.barton.de/
   4
   5                (c)2001-2011 Alexander Barton and Contributors.
   6                ngIRCd is free software and published under the
   7                    terms of the GNU General Public License.
   8
   9                                 -- INSTALL --
  10
  11
  12 I. Upgrade Information
  13 ~~~~~~~~~~~~~~~~~~~~~~
  14
  15 Differences to version 17
  16
  17 - Support for ZeroConf/Bonjour/Rendezvous service registration has been
  18   removed. The configuration option "NoZeroconf" is no longer available.
  19
  20 Differences to version 16
  21
  22 - Changes to the "MotdFile" specified in ngircd.conf now require a ngircd
  23   configuration reload to take effect (HUP signal, REHASH command).
  24
  25 Differences to version 0.9.x
  26
  27 - The option of the configure script to enable support for Zeroconf/Bonjour/
  28   Rendezvous/WhateverItIsNamedToday has been renamed:
  29     --with-rendezvous  ->  --with-zeroconf
  30
  31 Differences to version 0.8.x
  32
  33 - The maximum length of passwords has been raised to 20 characters (instead
  34   of 8 characters). If your passwords are longer than 8 characters then they
  35   are cut at an other position now.
  36
  37 Differences to version 0.6.x
  38
  39 - Some options of the configure script have been renamed:
  40     --disable-syslog  ->  --without-syslog
  41     --disable-zlib    ->  --without-zlib
  42   Please call "./configure --help" to review the full list of options!
  43
  44 Differences to version 0.5.x
  45
  46 - Starting with version 0.6.0, other servers are identified using asynchronous
  47   passwords: therefore the variable "Password" in [Server]-sections has been
  48   replaced by "MyPassword" and "PeerPassword".
  49
  50 - New configuration variables, section [Global]: MaxConnections, MaxJoins
  51   (see example configuration file "doc/sample-ngircd.conf"!).
  52
  53
  54 II. Standard Installation
  55 ~~~~~~~~~~~~~~~~~~~~~~~~~
  56
  57 ngIRCd is developed for UNIX-based systems, which means that the installation
  58 on modern UNIX-like systems that are supported by GNU autoconf and GNU
  59 automake ("configure") should be no problem.
  60
  61 The normal installation procedure after getting (and expanding) the source
  62 files (using a distribution archive or GIT) is as following:
  63
  64   1) ./autogen.sh       [only necessary when using GIT]
  65   2) ./configure
  66   3) make
  67   4) make install
  68
  69 (Please see details below!)
  70
  71 Now the newly compiled executable "ngircd" is installed in its standard
  72 location, /usr/local/sbin/.
  73
  74 The next step is to configure and afterwards starting the daemon. Please
  75 have a look at the ngircd(8) and ngircd.conf(5) manual pages for details
  76 and all possible options.
  77
  78 If no previous version of the configuration file exists (the standard name
  79 is /usr/local/etc/ngircd.conf), a sample configuration file containing all
  80 possible options will be installed there. You'll find its template in the
  81 doc/ directory: sample-ngircd.conf.
  82
  83
  84 1): "autogen.sh"
  85
  86 The first step, autogen.sh, is only necessary if the configure-script isn't
  87 already generated. This never happens in official ("stable") releases in
  88 tar.gz-archives, but when using GIT.
  89
  90 This step is therefore only interesting for developers.
  91
  92 autogen.sh produces the Makefile.in's, which are necessary for the configure
  93 script itself, and some more files for make. To run autogen.sh you'll need
  94 GNU autoconf and GNU automake (use recent versions! autoconf 2.53 and
  95 automake 1.6.1 are known to work).
  96
  97 Again: "end users" do not need this step!
  98
  99
 100 2): "./configure"
 101
 102 The configure-script is used to detect local system dependencies.
 103
 104 In the perfect case, configure should recognise all needed libraries, header
 105 files and so on. If this shouldn't work, "./configure --help" shows all
 106 possible options.
 107
 108 In addition, you can pass some command line options to "configure" to enable
 109 and/or disable some features of ngIRCd. All these options are shown using
 110 "./configure --help", too.
 111
 112 Compiling a static binary will avoid you the hassle of feeding a chroot dir
 113 (if you want use the chroot feature). Just do something like:
 114   CFLAGS=-static ./configure [--your-options ...]
 115 Then you can use a void directory as ChrootDir (like OpenSSH's /var/empty).
 116
 117
 118 3): "make"
 119
 120 The make command uses the Makefiles produced by configure and compiles the
 121 ngIRCd daemon.
 122
 123
 124 4): "make install"
 125
 126 Use "make install" to install the server and a sample configuration file on
 127 the local system. Normally, root privileges are necessary to complete this
 128 step. If there is already an older configuration file present, it won't be
 129 overwritten.
 130
 131 This files will be installed by default:
 132
 133 - /usr/local/sbin/ngircd: executable server
 134 - /usr/local/etc/ngircd.conf: sample configuration (if not already present)
 135 - /usr/local/share/doc/ngircd/: documentation
 136
 137
 138 III. Additional features
 139 ~~~~~~~~~~~~~~~~~~~~~~~~
 140
 141 The following optional features can be compiled into the daemon by passing
 142 options to the "configure" script. Most options can handle a <path> argument
 143 which will be used to search for the required libraries and header files in
 144 the given paths ("<path>/lib/...", "<path>/include/...") in addition to the
 145 standard locations.
 146
 147 * Syslog Logging (autodetected by default):
 148   --with-syslog[=<path>] / --without-syslog
 149
 150   Enable (disable) support for logging to "syslog", which should be
 151   available on most modern UNIX-like operating systems by default.
 152
 153 * ZLib Compression (autodetected by default):
 154   --with-zlib[=<path>] / --without-zlib
 155
 156   Enable (disable) support for compressed server-server links.
 157   The Z compression library ("libz") is required for this option.
 158
 159 * IO Backend (autodetected by default):
 160   --with-select[=<path>] / --without-select
 161   --with-poll[=<path>] / --without-poll
 162   --with-devpoll[=<path>] / --without-devpoll
 163   --with-epoll[=<path>] / --without-epoll
 164   --with-kqueue[=<path>] / --without-kqueue
 165
 166   ngIRCd can use different IO "backends": the "old school" select() and poll()
 167   API which should be supported by most UNIX-like operating systems, or the
 168   more efficient and flexible epoll() (Linux >=2.6), kqueue() (BSD) and
 169   /dev/poll APIs.
 170   By default the IO backend is autodetected, but you can use "--without-xxx"
 171   to disable a more enhanced API.
 172   When using the epoll() API, support for select() is compiled in as well by
 173   default to enable the binary to run on older Linux kernels (<2.6), too.
 174
 175 * IDENT-Support:
 176   --with-ident[=<path>]
 177
 178   Include support for IDENT ("AUTH") lookups. The "ident" library is
 179   required for this option.
 180
 181 * TCP-Wrappers:
 182   --with-tcp-wrappers[=<path>]
 183
 184   Include support for Wietse Venemas "TCP Wrappers" to limit client access
 185   to the daemon, for example by using "/etc/hosts.{allow|deny}".
 186   The "libwrap" is required for this option.
 187
 188 * PAM:
 189   --with-pam[=<path>]
 190
 191   Enable support for PAM, the Pluggable Authentication Modules library.
 192   See doc/PAM.txt for details.
 193
 194 * SSL:
 195   --with-openssl[=<path>]
 196   --with-gnutls[=<path>]
 197
 198   Enable support for SSL/TLS using OpenSSL or gnutls libraries.
 199   See doc/SSL.txt for details.
 200
 201 * IPv6:
 202   --enable-ipv6
 203
 204   Adds support for version 6 of the Internet Protocol.
 205
 206
 207 IV. Useful make-targets
 208 ~~~~~~~~~~~~~~~~~~~~~~~
 209
 210 The Makefile produced by the configure-script contains always these useful
 211 targets:
 212
 213  - clean: delete every product from the compiler/linker
 214    next step: -> make
 215
 216  - distclean: the above plus erase all generated Makefiles
 217    next step: -> ./configure
 218
 219  - maintainer-clean: erase all automatic generated files
 220    next step: -> ./autogen.sh
 221
 222
 223 V. Sample configuration file ngircd.conf
 224 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 225
 226 In the sample configuration file, there are comments beginning with "#" OR
 227 ";" -- this is only for the better understanding of the file.
 228
 229 The file is separated in four blocks: [Global], [Operator], [Server], and
 230 [Channel].
 231
 232 In the [Global] section, there is the main configuration like the server
 233 name and the ports, on which the server should be listening. IRC operators
 234 of this server are defined in [Operator] blocks. [Server] is the section
 235 where server links are configured. And [Channel] blocks are used to
 236 configure pre-defined ("persistent") IRC channels.
 237
 238 The meaning of the variables in the configuration file is explained in the
 239 "doc/sample-ngircd.conf", which is used as sample configuration file in
 240 /usr/local/etc after running "make install" (if you don't already have one)
 241 and in the "ngircd.conf" manual page.
 242
 243
 244 VI. Command line options
 245 ~~~~~~~~~~~~~~~~~~~~~~~~
 246
 247 These parameters could be passed to the ngIRCd:
 248
 249 -f, --config <file>
 250         The daemon uses the file <file> as configuration file rather than
 251         the standard configuration /usr/local/etc/ngircd.conf.
 252
 253 -n, --nodaemon
 254         ngIRCd should be running as a foreground process.
 255
 256 -p, --passive
 257         Server-links won't be automatically established.
 258
 259 -t, --configtest
 260         Reads, validates and dumps the configuration file as interpreted
 261         by the server. Then exits.
 262
 263 Use "--help" to see a short help text describing all available parameters
 264 the server understands, with "--version" the ngIRCd shows its version
 265 number. In both cases the server exits after the output.