[BACK]Return to INSTALL.md CVS log [TXT][DIR] Up to [local] / ircnowd

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