Annotation of ircnowd/INSTALL.md, Revision 1.1.1.1
1.1 bountyht 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