INSTALL

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