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