INSTALL.md

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