INSTALL.md

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