INSTALL.md

   1 # [ngIRCd](https://ngircd.barton.de) - Installation
   2
   3 This document describes how to install ngIRCd, the lightweight Internet Relay
   4 Chat (IRC) server.
   5
   6 The first section lists noteworthy changes to earlier releases; you definitely
   7 should read this when upgrading your setup! But you can skip over this section
   8 when you are working on a fresh installation.
   9
  10 The subsequent sections describe the steps required to build and install ngIRCd
  11 _from sources_. The information given here is not relevant when you are using
  12 packages provided by your operating system vendor or third-party repositories!
  13
  14 Please see the file `doc/QuickStart.md` in the `doc/` directory or on
  15 [GitHub](https://github.com/ngircd/ngircd/blob/master/doc/QuickStart.md) for
  16 information about _setting up_ and _running_ ngIRCd, including some real-world
  17 configuration examples.
  18
  19 ## Upgrade Information
  20
  21 This section lists important updates and breaking changes that you should be
  22 aware of *before* starting the upgrade:
  23
  24 Differences to version 26
  25
  26 - **Attention**:
  27   Starting with release 27, ngIRCd validates SSL/TLS certificates on outgoing
  28   server-server links by default and drops(!) connections when the remote
  29   certificate is invalid (for example self-signed, expired, not matching the
  30   host name, ...). Therefore you have to make sure that all relevant
  31   *certificates are valid* (or to disable certificate validation on this
  32   connection using the new `SSLVerify = false` setting in the affected
  33   `[Server]` block, where the remote certificate is not valid and you can not
  34   fix this issue).
  35
  36 Differences to version 25
  37
  38 - **Attention**:
  39   All already deprecated legacy options (besides the newly deprecated *Key* and
  40   *MaxUsers* settings, see below) were removed in ngIRCd 26, so make sure to
  41   update your configuration before upgrading, if you haven't done so already
  42   (you got a warning on daemon startup when using deprecated options): you can
  43   check your configuration using `ngircd --configtest` -- which is a good idea
  44   anyway ;-)
  45
  46 - Setting modes for predefined channels in *[Channel]* sections has been
  47   enhanced: now you can set *all* modes, like in IRC "MODE" commands, and have
  48   this setting multiple times per *[Channel]* block. Modifying lists (ban list,
  49   invite list, exception list) is supported, too.
  50
  51   Both the *Key* and *MaxUsers* settings are now deprecated and should be
  52   replaced by `Modes = +l <limit>` and `Modes = +k <key>` respectively.
  53
  54 Differences to version 22.x
  55
  56 - The *NoticeAuth* `ngircd.conf` configuration variable has been renamed to
  57   *NoticeBeforeRegistration*. The old *NoticeAuth* variable still works but
  58   is deprecated now.
  59
  60 - The default value of the SSL *CipherList* variable has been changed to
  61   "HIGH:!aNULL:@STRENGTH:!SSLv3" (OpenSSL) and "SECURE128:-VERS-SSL3.0"
  62   (GnuTLS) to disable the old SSLv3 protocol by default.
  63
  64   To enable connections of clients still requiring the weak SSLv3 protocol,
  65   the *CipherList* must be set to its old value (not recommended!), which
  66   was "HIGH:!aNULL:@STRENGTH" (OpenSSL) and "SECURE128" (GnuTLS), see below.
  67
  68 Differences to version 20.x
  69
  70 - Starting with ngIRCd 21, the ciphers used by SSL are configurable and
  71   default to "HIGH:!aNULL:@STRENGTH" (OpenSSL) or "SECURE128" (GnuTLS).
  72   Previous version were using the OpenSSL or GnuTLS defaults, "DEFAULT"
  73   and "NORMAL" respectively.
  74
  75 - When adding GLINE's or KLINE's to ngIRCd 21 (or newer), all clients matching
  76   the new mask will be KILL'ed. This was not the case with earlier versions
  77   that only added the mask but didn't kill already connected users.
  78
  79 - The *PredefChannelsOnly* configuration variable has been superseded by the
  80   new *AllowedChannelTypes* variable. It is still supported and translated to
  81   the appropriate *AllowedChannelTypes* setting but is deprecated now.
  82
  83 Differences to version 19.x
  84
  85 - Starting with ngIRCd 20, users can "cloak" their hostname only when the
  86   configuration variable *CloakHostModeX* (introduced in 19.2) is set.
  87   Otherwise, only IRC operators, other servers, and services are allowed to
  88   set mode +x. This prevents regular users from changing their hostmask to
  89   the name of the IRC server itself, which confused quite a few people ;-)
  90
  91 Differences to version 17.x
  92
  93 - Support for ZeroConf/Bonjour/Rendezvous service registration has been
  94   removed. The configuration option *NoZeroconf* is no longer available.
  95
  96 - The structure of `ngircd.conf` has been cleaned up and three new configuration
  97   sections have been introduced: *[Limits]*, *[Options]*, and *[SSL]*.
  98
  99   Lots of configuration variables stored in the *[Global]* section are now
 100   deprecated there and should be stored in one of these new sections (but
 101   still work in *[Global]*):
 102
 103   - *AllowRemoteOper*    -> [Options]
 104   - *ChrootDir*          -> [Options]
 105   - *ConnectIPv4*        -> [Options]
 106   - *ConnectIPv6*        -> [Options]
 107   - *ConnectRetry*       -> [Limits]
 108   - *MaxConnections*     -> [Limits]
 109   - *MaxConnectionsIP*   -> [Limits]
 110   - *MaxJoins*           -> [Limits]
 111   - *MaxNickLength*      -> [Limits]
 112   - *NoDNS*              -> [Options], and renamed to *DNS*
 113   - *NoIdent*            -> [Options], and renamed to *Ident*
 114   - *NoPAM*              -> [Options], and renamed to *PAM*
 115   - *OperCanUseMode*     -> [Options]
 116   - *OperServerMode*     -> [Options]
 117   - *PingTimeout*        -> [Limits]
 118   - *PongTimeout*        -> [Limits]
 119   - *PredefChannelsOnly* -> [Options]
 120   - *SSLCertFile*        -> [SSL], and renamed to *CertFile*
 121   - *SSLDHFile*          -> [SSL], and renamed to *DHFile*
 122   - *SSLKeyFile*         -> [SSL], and renamed to *KeyFile*
 123   - *SSLKeyFilePassword* -> [SSL], and renamed to *KeyFilePassword*
 124   - *SSLPorts*           -> [SSL], and renamed to *Ports*
 125   - *SyslogFacility*     -> [Options]
 126   - *WebircPassword*     -> [Options]
 127
 128   You should adjust your `ngircd.conf` and run `ngircd --configtest` to make
 129   sure that your settings are correct and up to date!
 130
 131 Differences to version 16.x
 132
 133 - Changes to the *MotdFile* specified in `ngircd.conf` now require a ngIRCd
 134   configuration reload to take effect (HUP signal, *REHASH* command).
 135
 136 Differences to version 0.9.x
 137
 138 - The option of the configure script to enable support for Zeroconf/Bonjour/
 139   Rendezvous/WhateverItIsNamedToday has been renamed:
 140
 141   - `--with-rendezvous`  ->  `--with-zeroconf`
 142
 143 Differences to version 0.8.x
 144
 145 - The maximum length of passwords has been raised to 20 characters (instead
 146   of 8 characters). If your passwords are longer than 8 characters then they
 147   are cut at an other position now.
 148
 149 Differences to version 0.6.x
 150
 151 - Some options of the configure script have been renamed:
 152
 153   - `--disable-syslog`  ->  `--without-syslog`
 154   - `--disable-zlib`    ->  `--without-zlib`
 155
 156   Please call `./configure --help` to review the full list of options!
 157
 158 Differences to version 0.5.x
 159
 160 - Starting with version 0.6.0, other servers are identified using asynchronous
 161   passwords: therefore the variable *Password* in *[Server]*-sections has been
 162   replaced by *MyPassword* and *PeerPassword*.
 163
 164 - New configuration variables, section *[Global]*: *MaxConnections*, *MaxJoins*
 165   (see example configuration file `doc/sample-ngircd.conf`!).
 166
 167 ## Standard Installation
 168
 169 *Note*: This sections describes installing ngIRCd *from sources*. If you use
 170 packages available for your operating system distribution you should skip over
 171 and continue with the *Configuration* section, see below.
 172
 173 ngIRCd is developed for UNIX-based systems, which means that the installation
 174 on modern UNIX-like systems that are supported by GNU autoconf and GNU
 175 automake ("`configure` script") should be no problem.
 176
 177 The normal installation procedure after getting (and expanding) the source
 178 files (using a distribution archive or Git) is as following:
 179
 180 1) Satisfy prerequisites
 181 2) `./autogen.sh` [only necessary when using "raw" sources with Git]
 182 3) `./configure`
 183 4) `make`
 184 5) `make install`
 185
 186 (Please see details below!)
 187
 188 Now the newly compiled executable "ngircd" is installed in its standard
 189 location, `/usr/local/sbin/`.
 190
 191 If no previous version of the configuration file exists (the standard name
 192 is `/usr/local/etc/ngircd.conf)`, a sample configuration file containing all
 193 possible options will be installed there. You'll find its template in the
 194 `doc/` directory: `sample-ngircd.conf`.
 195
 196 The next step is to configure and afterwards start the daemon. See the section
 197 *Configuration* below.
 198
 199 ### Satisfy prerequisites
 200
 201 When building from source, you'll need some other software to build ngIRCd:
 202 for example a working C compiler, make tool, and a few libraries depending on
 203 the feature set you want to enable at compile time (like IDENT, SSL, and PAM).
 204
 205 And if you aren't using a distribution archive ("tar.gz" file), but cloned the
 206 plain source archive, you need a few additional tools to generate the build
 207 system itself: GNU automake and autoconf, as well as pkg-config.
 208
 209 If you are using one of the "big" operating systems or Linux distributions,
 210 you can use the following commands to install all the required packages to
 211 build the sources including all optional features and to run the test suite:
 212
 213 #### Red Hat / Fedora based distributions
 214
 215 ``` shell
 216   yum install \
 217     autoconf automake expect gcc glibc-devel gnutls-devel \
 218     libident-devel make pam-devel pkg-config tcp_wrappers-devel \
 219     telnet zlib-devel
 220 ```
 221
 222 *Note:* More recent versions use the DNF package manager; so substitute "yum"
 223 with "dnf" in the command above. And neither "libident-devel" (IDENT support)
 224 nor "tcp_wrappers-devel" (TCP Wrappers) are provided any more!
 225
 226 So the resulting command looks like this:
 227
 228 ``` shell
 229   dnf install \
 230     autoconf automake expect gcc glibc-devel gnutls-devel \
 231     make pam-devel pkg-config telnet zlib-devel
 232 ```
 233
 234 #### Debian / Ubuntu based distributions
 235
 236 ``` shell
 237   apt-get install \
 238     autoconf automake build-essential expect libgnutls28-dev \
 239     libident-dev libpam-dev pkg-config libwrap0-dev libz-dev telnet
 240 ```
 241
 242 #### ArchLinux based distributions
 243
 244 ``` shell
 245   pacman -S --needed \
 246     autoconf automake expect gcc gnutls inetutils libident libwrap \
 247     make pam pkg-config zlib
 248 ```
 249
 250 #### macOS with Homebrew
 251
 252 To build ngIRCd on Apple macOS, you need either Xcode or the command line
 253 development tools. You can install the latter with the `xcode-select --install`
 254 command.
 255
 256 Additional tools and libraries that are not part of macOS itself are best
 257 installed with the [Homebrew](https://brew.sh) package manager:
 258
 259 ``` shell
 260   brew install autoconf automake gnutls libident pkg-config
 261 ```
 262
 263 Note: To actually use the GnuTLS and IDENT libraries installed by Homebrew, you
 264 need to pass the installation path to the `./configure` command (see below). For
 265 example like this:
 266
 267 ``` shell
 268   ./configure --with-gnutls=$(brew --prefix) --with-ident=$(brew --prefix) [...]
 269 ```
 270
 271 ### `./autogen.sh`
 272
 273 The first step, to run `./autogen.sh`, is *only* necessary if the `configure`
 274 script itself isn't already generated and available. This never happens in
 275 official ("stable") releases in "tar.gz" archives, but when cloning the source
 276 code repository using Git.
 277
 278 **This step is therefore only interesting for developers!**
 279
 280 The `autogen.sh` script produces the `Makefile.in`'s, which are necessary for
 281 the configure script itself, and some more files for `make(1)`.
 282
 283 To run `autogen.sh` you'll need GNU autoconf, GNU automake and pkg-config: at
 284 least autoconf 2.61 and automake 1.10 are required, newer is better. But don't
 285 use automake 1.12 or newer for creating distribution archives: it will work
 286 but lack "de-ANSI-fication" support in the generated Makefile's! Stick with
 287 automake 1.11.x for this purpose ...
 288
 289 So *automake 1.11.x* and *autoconf 2.67+* is recommended.
 290
 291 Again: "end users" do not need this step and neither need GNU autoconf nor GNU
 292 automake at all!
 293
 294 ### `./configure`
 295
 296 The `configure` script is used to detect local system dependencies.
 297
 298 In the perfect case, `configure` should recognize all needed libraries, header
 299 files and so on. If this shouldn't work, `./configure --help` shows all
 300 possible options.
 301
 302 In addition, you can pass some command line options to `configure` to enable
 303 and/or disable some features of ngIRCd. All these options are shown using
 304 `./configure --help`, too.
 305
 306 Compiling a static binary will avoid you the hassle of feeding a chroot dir
 307 (if you want use the chroot feature). Just do something like:
 308
 309 ``` shell
 310   CFLAGS=-static ./configure [--your-options ...]
 311 ```
 312
 313 Then you can use a void directory as ChrootDir (like OpenSSH's `/var/empty`).
 314
 315 ### `make`
 316
 317 The `make(1)` command uses the `Makefile`'s produced by `configure` and
 318 compiles the ngIRCd daemon.
 319
 320 ### `make install`
 321
 322 Use `make install` to install the server and a sample configuration file on
 323 the local system. Normally, root privileges are necessary to complete this
 324 step. If there is already an older configuration file present, it won't be
 325 overwritten.
 326
 327 These files and folders will be installed by default:
 328
 329 - `/usr/local/sbin/ngircd`: executable server
 330 - `/usr/local/etc/ngircd.conf`: sample configuration (if not already present)
 331 - `/usr/local/share/doc/ngircd/`: documentation
 332 - `/usr/local/share/man/`: manual pages
 333
 334 ### Additional features
 335
 336 The following optional features can be compiled into the daemon by passing
 337 options to the `configure` script. Most options can handle a `<path>` argument
 338 which will be used to search for the required libraries and header files in
 339 the given paths (`<path>/lib/...`, `<path>/include/...`) in addition to the
 340 standard locations.
 341
 342 - Syslog Logging (autodetected by default):
 343
 344   `--with-syslog[=<path>]` / `--without-syslog`
 345
 346   Enable (disable) support for logging to "syslog", which should be
 347   available on most modern UNIX-like operating systems by default.
 348
 349 - ZLib Compression (autodetected by default):
 350
 351   `--with-zlib[=<path>]` / `--without-zlib`
 352
 353   Enable (disable) support for compressed server-server links.
 354   The Z compression library ("libz") is required for this option.
 355
 356 - IO Backend (autodetected by default):
 357
 358   - `--with-select[=<path>]` / `--without-select`
 359   - `--with-poll[=<path>]` / `--without-poll`
 360   - `--with-devpoll[=<path>]` / `--without-devpoll`
 361   - `--with-epoll[=<path>]` / `--without-epoll`
 362   - `--with-kqueue[=<path>]` / `--without-kqueue`
 363
 364   ngIRCd can use different IO "backends": the "old school" `select(2)` and
 365   `poll(2)` API which should be supported by most UNIX-like operating systems,
 366   or the more efficient and flexible `epoll(7)` (Linux >=2.6), `kqueue(2)`
 367   (BSD) and `/dev/poll` APIs.
 368
 369   By default the IO backend is autodetected, but you can use `--without-xxx`
 370   to disable a more enhanced API.
 371
 372   When using the `epoll(7)` API, support for `select(2)` is compiled in as
 373   well by default, to enable the binary to run on older Linux kernels (<2.6),
 374   too.
 375
 376 - IDENT-Support:
 377
 378   `--with-ident[=<path>]`
 379
 380   Include support for IDENT ("AUTH") lookups. The "ident" library is
 381   required for this option.
 382
 383 - TCP-Wrappers:
 384
 385   `--with-tcp-wrappers[=<path>]`
 386
 387   Include support for Wietse Venemas "TCP Wrappers" to limit client access
 388   to the daemon, for example by using `/etc/hosts.{allow|deny}`.
 389   The "libwrap" is required for this option.
 390
 391 - PAM:
 392
 393   `--with-pam[=<path>]`
 394
 395   Enable support for PAM, the Pluggable Authentication Modules library.
 396   See `doc/PAM.txt` for details.
 397
 398 - SSL:
 399
 400   - `--with-openssl[=<path>]`
 401   - `--with-gnutls[=<path>]`
 402
 403   Enable support for SSL/TLS using OpenSSL or GnuTLS libraries.
 404   See `doc/SSL.md` for details.
 405
 406 - IPv6 (autodetected by default):
 407
 408   `--enable-ipv6` / `--disable-ipv6`
 409
 410   Enable (disable) support for version 6 of the Internet Protocol, which should
 411   be available on most modern UNIX-like operating systems by default.