001
2020-03-29
alex
# [ngIRCd](https://ngircd.barton.de) - Internet Relay Chat Server
003
2020-03-29
alex
This document explains how to install ngIRCd, the lightweight Internet Relay
004
2020-03-29
alex
Chat (IRC) server.
006
2020-03-29
alex
The first section lists noteworthy changes to earlier releases; you definitely
007
2020-03-29
alex
should read this when upgrading your setup! But you can skip over this section
008
2020-03-29
alex
when you do a fresh installation.
010
2020-03-29
alex
All the subsequent sections describe the steps required to install and
011
2020-03-29
alex
configure ngIRCd.
013
2020-03-29
alex
## Upgrade Information
015
2020-03-29
alex
Differences to version 25
017
2020-04-20
alex
- **Attention**:
018
2020-04-20
alex
All already deprecated legacy options (besides the newly deprecated *Key* and
019
2020-04-20
alex
*MaxUsers* settings, see below) were removed in ngIRCd 26, so make sure to
020
2020-04-20
alex
update your configuration before upgrading, if you haven't done so already
021
2020-04-20
alex
(you got a warning on daemon startup when using deprecated options): you can
022
2020-04-20
alex
check your configuration using `ngircd --configtest` -- which is a good idea
023
2020-04-20
alex
anyway ;-)
025
2020-03-29
alex
- Setting modes for predefined channels in *[Channel]* sections has been
026
2020-03-29
alex
enhanced: now you can set *all* modes, like in IRC "MODE" commands, and have
027
2020-03-29
alex
this setting multiple times per *[Channel]* block. Modifying lists (ban list,
028
2020-03-29
alex
invite list, exception list) is supported, too.
030
2020-03-29
alex
Both the *Key* and *MaxUsers* settings are now deprecated and should be
031
2020-03-29
alex
replaced by `Modes = +l <limit>` and `Modes = +k <key>` respectively.
033
2020-03-29
alex
Differences to version 22.x
035
2020-03-29
alex
- The *NoticeAuth* `ngircd.conf` configuration variable has been renamed to
036
2020-03-29
alex
*NoticeBeforeRegistration*. The old *NoticeAuth* variable still works but
037
2020-03-29
alex
is deprecated now.
039
2020-03-29
alex
- The default value of the SSL *CipherList* variable has been changed to
040
2020-03-29
alex
"HIGH:!aNULL:@STRENGTH:!SSLv3" (OpenSSL) and "SECURE128:-VERS-SSL3.0"
041
2020-03-29
alex
(GnuTLS) to disable the old SSLv3 protocol by default.
043
2020-03-29
alex
To enable connections of clients still requiring the weak SSLv3 protocol,
044
2020-03-29
alex
the *CipherList* must be set to its old value (not recommended!), which
045
2020-03-29
alex
was "HIGH:!aNULL:@STRENGTH" (OpenSSL) and "SECURE128" (GnuTLS), see below.
047
2020-03-29
alex
Differences to version 20.x
049
2020-03-29
alex
- Starting with ngIRCd 21, the ciphers used by SSL are configurable and
050
2020-03-29
alex
default to "HIGH:!aNULL:@STRENGTH" (OpenSSL) or "SECURE128" (GnuTLS).
051
2020-03-29
alex
Previous version were using the OpenSSL or GnuTLS defaults, "DEFAULT"
052
2020-03-29
alex
and "NORMAL" respectively.
054
2020-03-29
alex
- When adding GLINE's or KLINE's to ngIRCd 21 (or newer), all clients matching
055
2020-03-29
alex
the new mask will be KILL'ed. This was not the case with earlier versions
056
2020-03-29
alex
that only added the mask but didn't kill already connected users.
058
2020-03-29
alex
- The *PredefChannelsOnly* configuration variable has been superseded by the
059
2020-03-29
alex
new *AllowedChannelTypes* variable. It is still supported and translated to
060
2020-03-29
alex
the appropriate *AllowedChannelTypes* setting but is deprecated now.
062
2020-03-29
alex
Differences to version 19.x
064
2020-03-29
alex
- Starting with ngIRCd 20, users can "cloak" their hostname only when the
065
2020-03-29
alex
configuration variable *CloakHostModeX* (introduced in 19.2) is set.
066
2020-03-29
alex
Otherwise, only IRC operators, other servers, and services are allowed to
067
2020-03-29
alex
set mode +x. This prevents regular users from changing their hostmask to
068
2020-03-29
alex
the name of the IRC server itself, which confused quite a few people ;-)
070
2020-03-29
alex
Differences to version 17.x
072
2020-03-29
alex
- Support for ZeroConf/Bonjour/Rendezvous service registration has been
073
2020-03-29
alex
removed. The configuration option *NoZeroconf* is no longer available.
075
2020-03-29
alex
- The structure of `ngircd.conf` has been cleaned up and three new configuration
076
2020-03-29
alex
sections have been introduced: *[Limits]*, *[Options]*, and *[SSL]*.
078
2020-03-29
alex
Lots of configuration variables stored in the *[Global]* section are now
079
2020-03-29
alex
deprecated there and should be stored in one of these new sections (but
080
2020-03-29
alex
still work in *[Global]*):
082
2020-03-29
alex
- *AllowRemoteOper* -> [Options]
083
2020-03-29
alex
- *ChrootDir* -> [Options]
084
2020-03-29
alex
- *ConnectIPv4* -> [Options]
085
2020-03-29
alex
- *ConnectIPv6* -> [Options]
086
2020-03-29
alex
- *ConnectRetry* -> [Limits]
087
2020-03-29
alex
- *MaxConnections* -> [Limits]
088
2020-03-29
alex
- *MaxConnectionsIP* -> [Limits]
089
2020-03-29
alex
- *MaxJoins* -> [Limits]
090
2020-03-29
alex
- *MaxNickLength* -> [Limits]
091
2020-03-29
alex
- *NoDNS* -> [Options], and renamed to *DNS*
092
2020-03-29
alex
- *NoIdent* -> [Options], and renamed to *Ident*
093
2020-03-29
alex
- *NoPAM* -> [Options], and renamed to *PAM*
094
2020-03-29
alex
- *OperCanUseMode* -> [Options]
095
2020-03-29
alex
- *OperServerMode* -> [Options]
096
2020-03-29
alex
- *PingTimeout* -> [Limits]
097
2020-03-29
alex
- *PongTimeout* -> [Limits]
098
2020-03-29
alex
- *PredefChannelsOnly* -> [Options]
099
2020-03-29
alex
- *SSLCertFile* -> [SSL], and renamed to *CertFile*
100
2020-03-29
alex
- *SSLDHFile* -> [SSL], and renamed to *DHFile*
101
2020-03-29
alex
- *SSLKeyFile* -> [SSL], and renamed to *KeyFile*
102
2020-03-29
alex
- *SSLKeyFilePassword* -> [SSL], and renamed to *KeyFilePassword*
103
2020-03-29
alex
- *SSLPorts* -> [SSL], and renamed to *Ports*
104
2020-03-29
alex
- *SyslogFacility* -> [Options]
105
2020-03-29
alex
- *WebircPassword* -> [Options]
107
2020-03-29
alex
You should adjust your `ngircd.conf` and run `ngircd --configtest` to make
108
2020-03-29
alex
sure that your settings are correct and up to date!
110
2020-03-29
alex
Differences to version 16.x
112
2020-03-29
alex
- Changes to the *MotdFile* specified in `ngircd.conf` now require a ngIRCd
113
2020-03-29
alex
configuration reload to take effect (HUP signal, *REHASH* command).
115
2020-03-29
alex
Differences to version 0.9.x
117
2020-03-29
alex
- The option of the configure script to enable support for Zeroconf/Bonjour/
118
2020-03-29
alex
Rendezvous/WhateverItIsNamedToday has been renamed:
120
2020-03-29
alex
- `--with-rendezvous` -> `--with-zeroconf`
122
2020-03-29
alex
Differences to version 0.8.x
124
2020-03-29
alex
- The maximum length of passwords has been raised to 20 characters (instead
125
2020-03-29
alex
of 8 characters). If your passwords are longer than 8 characters then they
126
2020-03-29
alex
are cut at an other position now.
128
2020-03-29
alex
Differences to version 0.6.x
130
2020-03-29
alex
- Some options of the configure script have been renamed:
132
2020-03-29
alex
- `--disable-syslog` -> `--without-syslog`
133
2020-03-29
alex
- `--disable-zlib` -> `--without-zlib`
135
2020-03-29
alex
Please call `./configure --help` to review the full list of options!
137
2020-03-29
alex
Differences to version 0.5.x
139
2020-03-29
alex
- Starting with version 0.6.0, other servers are identified using asynchronous
140
2020-03-29
alex
passwords: therefore the variable *Password* in *[Server]*-sections has been
141
2020-03-29
alex
replaced by *MyPassword* and *PeerPassword*.
143
2020-03-29
alex
- New configuration variables, section *[Global]*: *MaxConnections*, *MaxJoins*
144
2020-03-29
alex
(see example configuration file `doc/sample-ngircd.conf`!).
146
2020-03-29
alex
## Standard Installation
148
2020-03-29
alex
*Note*: This sections describes installing ngIRCd *from sources*. If you use
149
2020-03-29
alex
packages available for your operating system distribution you should skip over
150
2020-03-29
alex
and continue with the *Configuration* section, see below.
152
2020-03-29
alex
ngIRCd is developed for UNIX-based systems, which means that the installation
153
2020-03-29
alex
on modern UNIX-like systems that are supported by GNU autoconf and GNU
154
2020-03-29
alex
automake ("`configure` script") should be no problem.
156
2020-03-29
alex
The normal installation procedure after getting (and expanding) the source
157
2020-03-29
alex
files (using a distribution archive or Git) is as following:
159
2020-03-29
alex
1) Satisfy prerequisites
160
2020-03-29
alex
2) `./autogen.sh` [only necessary when using "raw" sources with Git]
161
2020-03-29
alex
3) `./configure`
162
2020-03-29
alex
4) `make`
163
2020-03-29
alex
5) `make install`
165
2020-03-29
alex
(Please see details below!)
167
2020-03-29
alex
Now the newly compiled executable "ngircd" is installed in its standard
168
2020-03-29
alex
location, `/usr/local/sbin/`.
170
2020-03-29
alex
If no previous version of the configuration file exists (the standard name
171
2020-03-29
alex
is `/usr/local/etc/ngircd.conf)`, a sample configuration file containing all
172
2020-03-29
alex
possible options will be installed there. You'll find its template in the
173
2020-03-29
alex
`doc/` directory: `sample-ngircd.conf`.
175
2020-03-29
alex
The next step is to configure and afterwards start the daemon. See the section
176
2020-03-29
alex
*Configuration* below.
178
2020-03-29
alex
### Satisfy prerequisites
180
2020-03-29
alex
When building from source, you'll need some other software to build ngIRCd:
181
2020-03-29
alex
for example a working C compiler, make tool, and a few libraries depending on
182
2020-03-29
alex
the feature set you want to enable at compile time (like IDENT, SSL, and PAM).
184
2020-03-29
alex
And if you aren't using a distribution archive ("tar.gz" file), but cloned the
185
2020-03-29
alex
plain source archive, you need a few additional tools to generate the build
186
2020-03-29
alex
system itself: GNU automake and autoconf, as well as pkg-config.
188
2020-03-29
alex
If you are using one of the "big" operating systems or Linux distributions,
189
2020-03-29
alex
you can use the following commands to install all the required packages to
190
2020-03-29
alex
build the sources including all optional features and to run the test suite:
192
2020-03-29
alex
#### Red Hat / Fedora based distributions
194
2020-03-29
alex
``` shell
195
2020-03-29
alex
yum install \
196
2020-03-29
alex
autoconf automake expect gcc glibc-devel gnutls-devel \
197
2020-03-29
alex
libident-devel make pam-devel pkg-config tcp_wrappers-devel \
198
2020-03-29
alex
telnet zlib-devel
201
2020-03-29
alex
#### Debian / Ubuntu based distributions
203
2020-03-29
alex
``` shell
204
2020-03-29
alex
apt-get install \
205
2020-03-29
alex
autoconf automake build-essential expect libgnutls28-dev \
206
2020-03-29
alex
libident-dev libpam-dev pkg-config libwrap0-dev libz-dev telnet
209
2020-06-20
alex
#### ArchLinux based distributions
211
2020-06-20
alex
``` shell
212
2020-06-20
alex
pacman -S --needed \
213
2020-06-20
alex
autoconf automake expect gcc gnutls inetutils libident libwrap \
214
2020-06-20
alex
make pam pkg-config zlib
217
2020-03-29
alex
### `./autogen.sh`
219
2020-03-29
alex
The first step, to run `./autogen.sh`, is *only* necessary if the `configure`
220
2020-03-29
alex
script itself isn't already generated and available. This never happens in
221
2020-03-29
alex
official ("stable") releases in "tar.gz" archives, but when cloning the source
222
2020-03-29
alex
code repository using Git.
224
2020-03-29
alex
**This step is therefore only interesting for developers!**
226
2020-03-29
alex
The `autogen.sh` script produces the `Makefile.in`'s, which are necessary for
227
2020-03-29
alex
the configure script itself, and some more files for `make(1)`.
229
2020-03-29
alex
To run `autogen.sh` you'll need GNU autoconf, GNU automake and pkg-config: at
230
2020-03-29
alex
least autoconf 2.61 and automake 1.10 are required, newer is better. But don't
231
2020-03-29
alex
use automake 1.12 or newer for creating distribution archives: it will work
232
2020-03-29
alex
but lack "de-ANSI-fication" support in the generated Makefile's! Stick with
233
2020-03-29
alex
automake 1.11.x for this purpose ...
235
2020-03-29
alex
So *automake 1.11.x* and *autoconf 2.67+* is recommended.
237
2020-03-29
alex
Again: "end users" do not need this step and neither need GNU autoconf nor GNU
238
2020-03-29
alex
automake at all!
240
2020-03-29
alex
### `./configure`
242
2020-03-29
alex
The `configure` script is used to detect local system dependencies.
244
2020-03-29
alex
In the perfect case, `configure` should recognize all needed libraries, header
245
2020-03-29
alex
files and so on. If this shouldn't work, `./configure --help` shows all
246
2020-03-29
alex
possible options.
248
2020-03-29
alex
In addition, you can pass some command line options to `configure` to enable
249
2020-03-29
alex
and/or disable some features of ngIRCd. All these options are shown using
250
2020-03-29
alex
`./configure --help`, too.
252
2020-03-29
alex
Compiling a static binary will avoid you the hassle of feeding a chroot dir
253
2020-03-29
alex
(if you want use the chroot feature). Just do something like:
255
2020-03-29
alex
``` shell
256
2020-03-29
alex
CFLAGS=-static ./configure [--your-options ...]
259
2020-03-29
alex
Then you can use a void directory as ChrootDir (like OpenSSH's `/var/empty`).
261
2020-03-29
alex
### `make`
263
2020-03-29
alex
The `make(1)` command uses the `Makefile`'s produced by `configure` and
264
2020-03-29
alex
compiles the ngIRCd daemon.
266
2020-03-29
alex
### `make install`
268
2020-03-29
alex
Use `make install` to install the server and a sample configuration file on
269
2020-03-29
alex
the local system. Normally, root privileges are necessary to complete this
270
2020-03-29
alex
step. If there is already an older configuration file present, it won't be
271
2020-03-29
alex
overwritten.
273
2020-03-29
alex
These files and folders will be installed by default:
275
2020-03-29
alex
- `/usr/local/sbin/ngircd`: executable server
276
2020-03-29
alex
- `/usr/local/etc/ngircd.conf`: sample configuration (if not already present)
277
2020-03-29
alex
- `/usr/local/share/doc/ngircd/`: documentation
278
2020-03-29
alex
- `/usr/local/share/man/`: manual pages
280
2020-03-29
alex
### Additional features
282
2020-03-29
alex
The following optional features can be compiled into the daemon by passing
283
2020-03-29
alex
options to the `configure` script. Most options can handle a `<path>` argument
284
2020-03-29
alex
which will be used to search for the required libraries and header files in
285
2020-03-29
alex
the given paths (`<path>/lib/...`, `<path>/include/...`) in addition to the
286
2020-03-29
alex
standard locations.
288
2020-03-29
alex
- Syslog Logging (autodetected by default):
290
2020-03-29
alex
`--with-syslog[=<path>]` / `--without-syslog`
292
2020-03-29
alex
Enable (disable) support for logging to "syslog", which should be
293
2020-03-29
alex
available on most modern UNIX-like operating systems by default.
295
2020-03-29
alex
- ZLib Compression (autodetected by default):
297
2020-03-29
alex
`--with-zlib[=<path>]` / `--without-zlib`
299
2020-03-29
alex
Enable (disable) support for compressed server-server links.
300
2020-03-29
alex
The Z compression library ("libz") is required for this option.
302
2020-03-29
alex
- IO Backend (autodetected by default):
304
2020-03-29
alex
- `--with-select[=<path>]` / `--without-select`
305
2020-03-29
alex
- `--with-poll[=<path>]` / `--without-poll`
306
2020-03-29
alex
- `--with-devpoll[=<path>]` / `--without-devpoll`
307
2020-03-29
alex
- `--with-epoll[=<path>]` / `--without-epoll`
308
2020-03-29
alex
- `--with-kqueue[=<path>]` / `--without-kqueue`
310
2020-03-29
alex
ngIRCd can use different IO "backends": the "old school" `select(2)` and
311
2020-03-29
alex
`poll(2)` API which should be supported by most UNIX-like operating systems,
312
2020-03-29
alex
or the more efficient and flexible `epoll(7)` (Linux >=2.6), `kqueue(2)`
313
2020-03-29
alex
(BSD) and `/dev/poll` APIs.
315
2020-03-29
alex
By default the IO backend is autodetected, but you can use `--without-xxx`
316
2020-03-29
alex
to disable a more enhanced API.
318
2020-03-29
alex
When using the `epoll(7)` API, support for `select(2)` is compiled in as
319
2020-03-29
alex
well by default, to enable the binary to run on older Linux kernels (<2.6),
322
2020-03-29
alex
- IDENT-Support:
324
2020-03-29
alex
`--with-ident[=<path>]`
326
2020-03-29
alex
Include support for IDENT ("AUTH") lookups. The "ident" library is
327
2020-03-29
alex
required for this option.
329
2020-03-29
alex
- TCP-Wrappers:
331
2020-03-29
alex
`--with-tcp-wrappers[=<path>]`
333
2020-03-29
alex
Include support for Wietse Venemas "TCP Wrappers" to limit client access
334
2020-03-29
alex
to the daemon, for example by using `/etc/hosts.{allow|deny}`.
335
2020-03-29
alex
The "libwrap" is required for this option.
339
2020-03-29
alex
`--with-pam[=<path>]`
341
2020-03-29
alex
Enable support for PAM, the Pluggable Authentication Modules library.
342
2020-03-29
alex
See `doc/PAM.txt` for details.
346
2020-03-29
alex
- `--with-openssl[=<path>]`
347
2020-03-29
alex
- `--with-gnutls[=<path>]`
349
2020-03-29
alex
Enable support for SSL/TLS using OpenSSL or GnuTLS libraries.
350
2020-03-29
alex
See `doc/SSL.txt` for details.
354
2020-03-29
alex
`--enable-ipv6`
356
2020-03-29
alex
Adds support for version 6 of the Internet Protocol.
358
2020-03-29
alex
## Configuration
360
2020-03-29
alex
Please have a look at the `ngircd(8)` and `ngircd.conf(5)` manual pages for
361
2020-03-29
alex
details and all possible command line and configuration options -- **and don't
362
2020-03-29
alex
forget to run `ngircd --configtest` to validate your configuration file!**
364
2020-03-29
alex
After installing ngIRCd, a sample configuration file will be set up (if it
365
2020-03-29
alex
does not exist already). By default, when installing from sources, the file is
366
2020-03-29
alex
named `/usr/local/etc/ngircd.conf` (other common names, especially for
367
2020-03-29
alex
distribution packages, are `/etc/ngircd.conf` or `/etc/ngircd/ngircd.conf`).
369
2020-03-29
alex
You can find the template of the sample configuration file in the `doc/`
370
2020-03-29
alex
directory as `sample-ngircd.conf` and
371
2020-03-29
alex
[online](https://ngircd.barton.de/doc/sample-ngircd.conf) on the homepage. It
372
2020-03-29
alex
contains all available options.
374
2020-03-29
alex
In the sample configuration file, there are comments beginning with `#` *or*
375
2020-03-29
alex
`;` -- this is only for the better understanding of the file, both comment
376
2020-03-29
alex
styles are equal.
378
2020-03-29
alex
The file is separated in five blocks: *[Global]*, *[Features]*, *[Operator]*,
379
2020-03-29
alex
*[Server]*, and *[Channel]*.
381
2020-03-29
alex
In the *[Global]* section, there is the main configuration like the server
382
2020-03-29
alex
name and the ports, on which the server should be listening. Options in
383
2020-03-29
alex
the *[Features]* section enable or disable functionality in the daemon.
384
2020-03-29
alex
IRC operators of this server are defined in *[Operator]* blocks, remote
385
2020-03-29
alex
servers are configured in *[Server]* sections, and *[Channel]* blocks are
386
2020-03-29
alex
used to configure pre-defined ("persistent") IRC channels.
388
2020-03-29
alex
### Manual Pages Online
390
2020-03-29
alex
- Daemon: [ngircd.8](https://manpages.debian.org/ngircd.8)
391
2020-03-29
alex
- Configutation file: [ngircd.conf.5](https://manpages.debian.org/ngircd.conf.5)
393
2020-03-29
alex
## Command line options
395
2020-03-29
alex
ngIRCd supports the following command line options:
397
2020-03-29
alex
- `-f`, `--config <file>`
399
2020-03-29
alex
The daemon uses the file `<file>` as configuration file rather than
400
2020-03-29
alex
the standard configuration `/usr/local/etc/ngircd.conf`.
402
2020-03-29
alex
- `-n`, `--nodaemon`
404
2020-03-29
alex
ngIRCd should be running as a foreground process.
406
2020-03-29
alex
- `-p`, `--passive`
408
2020-03-29
alex
Server-links won't be automatically established.
410
2020-03-29
alex
- `-t`, `--configtest`
412
2020-03-29
alex
Reads, validates and dumps the configuration file as interpreted
413
2020-03-29
alex
by the server. Then exits.
415
2020-03-29
alex
Use `--help` to see a short help text describing all available parameters
416
2020-03-29
alex
the server understands, with `--version` the ngIRCd shows its version
417
2020-03-29
alex
number. In both cases the server exits after the output.
419
2020-03-29
alex
Please see the `ngircd(8)` manual page for more details!
