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