INSTALL

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