1e96e16e24517cb654db7f52b59b137e4a59efeb
[ngircd-alex.git] / INSTALL
1
2                      ngIRCd - Next Generation IRC Server
3                            http://ngircd.barton.de/
4
5                (c)2001-2011 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 17
16
17 - Support for ZeroConf/Bonjour/Rendezvous service registration has been
18   removed. The configuration option "NoZeroconf" is no longer available.
19
20 - The structure of ngircd.conf has been cleaned up and three new configuration
21   sections have been introduced: [Limits], [Options], and [SSL].
22   Lots of configuration variables stored in the [Global] section are now
23   deprecated there and should be stored in one of these new sections (but
24   still work in [Global]):
25     "AllowRemoteOper"    -> [Options]
26     "ChrootDir"          -> [Options]
27     "ConnectIPv4"        -> [Options]
28     "ConnectIPv6"        -> [Options]
29     "ConnectRetry"       -> [Limits]
30     "MaxConnections"     -> [Limits]
31     "MaxConnectionsIP"   -> [Limits]
32     "MaxJoins"           -> [Limits]
33     "MaxNickLength"      -> [Limits]
34     "NoDNS"              -> [Options], and renamed to "DNS"
35     "NoIdent"            -> [Options], and renamed to "Ident"
36     "NoPAM"              -> [Options], and renamed to "PAM"
37     "OperCanUseMode"     -> [Options]
38     "OperServerMode"     -> [Options]
39     "PingTimeout"        -> [Limits]
40     "PongTimeout"        -> [Limits]
41     "PredefChannelsOnly" -> [Options]
42     "SSLCertFile"        -> [SSL], and renamed to "CertFile"
43     "SSLDHFile"          -> [SSL], and renamed to "DHFile"
44     "SSLKeyFile"         -> [SSL], and renamed to "KeyFile"
45     "SSLKeyFilePassword" -> [SSL], and renamed to "KeyFilePassword"
46     "SSLPorts"           -> [SSL], and renamed to "Ports"
47     "SyslogFacility"     -> [Options]
48     "WebircPassword"     -> [Options]
49   You should adjust your ngircd.conf and run "ngircd --configtest" to make
50   sure that your settings are correct and up to date!
51
52 Differences to version 16
53
54 - Changes to the "MotdFile" specified in ngircd.conf now require a ngircd
55   configuration reload to take effect (HUP signal, REHASH command).
56
57 Differences to version 0.9.x
58
59 - The option of the configure script to enable support for Zeroconf/Bonjour/
60   Rendezvous/WhateverItIsNamedToday has been renamed:
61     --with-rendezvous  ->  --with-zeroconf
62
63 Differences to version 0.8.x
64
65 - The maximum length of passwords has been raised to 20 characters (instead
66   of 8 characters). If your passwords are longer than 8 characters then they
67   are cut at an other position now.
68
69 Differences to version 0.6.x
70
71 - Some options of the configure script have been renamed:
72     --disable-syslog  ->  --without-syslog
73     --disable-zlib    ->  --without-zlib
74   Please call "./configure --help" to review the full list of options!
75
76 Differences to version 0.5.x
77
78 - Starting with version 0.6.0, other servers are identified using asynchronous
79   passwords: therefore the variable "Password" in [Server]-sections has been
80   replaced by "MyPassword" and "PeerPassword".
81
82 - New configuration variables, section [Global]: MaxConnections, MaxJoins
83   (see example configuration file "doc/sample-ngircd.conf"!).
84
85
86 II. Standard Installation
87 ~~~~~~~~~~~~~~~~~~~~~~~~~
88
89 ngIRCd is developed for UNIX-based systems, which means that the installation
90 on modern UNIX-like systems that are supported by GNU autoconf and GNU
91 automake ("configure") should be no problem.
92
93 The normal installation procedure after getting (and expanding) the source
94 files (using a distribution archive or GIT) is as following:
95
96   1) ./autogen.sh       [only necessary when using GIT]
97   2) ./configure
98   3) make
99   4) make install
100
101 (Please see details below!)
102
103 Now the newly compiled executable "ngircd" is installed in its standard
104 location, /usr/local/sbin/.
105
106 The next step is to configure and afterwards starting the daemon. Please
107 have a look at the ngircd(8) and ngircd.conf(5) manual pages for details
108 and all possible options -- and don't forget to run "ngircd --configtest"
109 to validate your configuration file!
110
111 If no previous version of the configuration file exists (the standard name
112 is /usr/local/etc/ngircd.conf), a sample configuration file containing all
113 possible options will be installed there. You'll find its template in the
114 doc/ directory: sample-ngircd.conf.
115
116
117 1): "autogen.sh"
118
119 The first step, autogen.sh, is only necessary if the configure-script isn't
120 already generated. This never happens in official ("stable") releases in
121 tar.gz-archives, but when using GIT.
122
123 This step is therefore only interesting for developers.
124
125 autogen.sh produces the Makefile.in's, which are necessary for the configure
126 script itself, and some more files for make. To run autogen.sh you'll need
127 GNU autoconf and GNU automake (use recent versions! autoconf 2.53 and
128 automake 1.6.1 are known to work).
129
130 Again: "end users" do not need this step!
131
132
133 2): "./configure"
134
135 The configure-script is used to detect local system dependencies.
136
137 In the perfect case, configure should recognise all needed libraries, header
138 files and so on. If this shouldn't work, "./configure --help" shows all
139 possible options.
140
141 In addition, you can pass some command line options to "configure" to enable
142 and/or disable some features of ngIRCd. All these options are shown using
143 "./configure --help", too.
144
145 Compiling a static binary will avoid you the hassle of feeding a chroot dir
146 (if you want use the chroot feature). Just do something like:
147   CFLAGS=-static ./configure [--your-options ...]
148 Then you can use a void directory as ChrootDir (like OpenSSH's /var/empty).
149
150
151 3): "make"
152
153 The make command uses the Makefiles produced by configure and compiles the
154 ngIRCd daemon.
155
156
157 4): "make install"
158
159 Use "make install" to install the server and a sample configuration file on
160 the local system. Normally, root privileges are necessary to complete this
161 step. If there is already an older configuration file present, it won't be
162 overwritten.
163
164 These files and folders will be installed by default:
165
166 - /usr/local/sbin/ngircd: executable server
167 - /usr/local/etc/ngircd.conf: sample configuration (if not already present)
168 - /usr/local/share/doc/ngircd/: documentation
169 - /usr/local/share/man/: manual pages
170
171
172 III. Additional features
173 ~~~~~~~~~~~~~~~~~~~~~~~~
174
175 The following optional features can be compiled into the daemon by passing
176 options to the "configure" script. Most options can handle a <path> argument
177 which will be used to search for the required libraries and header files in
178 the given paths ("<path>/lib/...", "<path>/include/...") in addition to the
179 standard locations.
180
181 * Syslog Logging (autodetected by default): 
182   --with-syslog[=<path>] / --without-syslog
183
184   Enable (disable) support for logging to "syslog", which should be
185   available on most modern UNIX-like operating systems by default.
186
187 * ZLib Compression (autodetected by default):
188   --with-zlib[=<path>] / --without-zlib
189
190   Enable (disable) support for compressed server-server links.
191   The Z compression library ("libz") is required for this option.
192   
193 * IO Backend (autodetected by default):
194   --with-select[=<path>] / --without-select
195   --with-poll[=<path>] / --without-poll
196   --with-devpoll[=<path>] / --without-devpoll
197   --with-epoll[=<path>] / --without-epoll
198   --with-kqueue[=<path>] / --without-kqueue  
199
200   ngIRCd can use different IO "backends": the "old school" select() and poll()
201   API which should be supported by most UNIX-like operating systems, or the
202   more efficient and flexible epoll() (Linux >=2.6), kqueue() (BSD) and
203   /dev/poll APIs.
204   By default the IO backend is autodetected, but you can use "--without-xxx"
205   to disable a more enhanced API.
206   When using the epoll() API, support for select() is compiled in as well by
207   default to enable the binary to run on older Linux kernels (<2.6), too.
208
209 * IDENT-Support:
210   --with-ident[=<path>]
211
212   Include support for IDENT ("AUTH") lookups. The "ident" library is
213   required for this option.
214
215 * TCP-Wrappers:
216   --with-tcp-wrappers[=<path>] 
217
218   Include support for Wietse Venemas "TCP Wrappers" to limit client access
219   to the daemon, for example by using "/etc/hosts.{allow|deny}".
220   The "libwrap" is required for this option.
221
222 * PAM:
223   --with-pam[=<path>]
224
225   Enable support for PAM, the Pluggable Authentication Modules library.
226   See doc/PAM.txt for details.
227
228 * SSL:
229   --with-openssl[=<path>]
230   --with-gnutls[=<path>]
231
232   Enable support for SSL/TLS using OpenSSL or gnutls libraries.
233   See doc/SSL.txt for details.
234
235 * IPv6:
236   --enable-ipv6
237
238   Adds support for version 6 of the Internet Protocol.
239
240
241 IV. Useful make-targets
242 ~~~~~~~~~~~~~~~~~~~~~~~
243
244 The Makefile produced by the configure-script contains always these useful
245 targets:
246
247  - clean: delete every product from the compiler/linker
248    next step: -> make
249
250  - distclean: the above plus erase all generated Makefiles
251    next step: -> ./configure
252
253  - maintainer-clean: erase all automatic generated files
254    next step: -> ./autogen.sh
255
256
257 V. Sample configuration file ngircd.conf
258 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
259
260 In the sample configuration file, there are comments beginning with "#" OR
261 ";" -- this is only for the better understanding of the file.
262
263 The file is separated in five blocks: [Global], [Features], [Operator],
264 [Server], and [Channel].
265
266 In the [Global] section, there is the main configuration like the server
267 name and the ports, on which the server should be listening. Options in
268 the [Features] section enable or disable functionality in the daemon.
269 IRC operators of this server are defined in [Operator] blocks, remote
270 servers are configured in [Server] sections, and [Channel] blocks are
271 used to configure pre-defined ("persistent") IRC channels.
272
273 The meaning of the variables in the configuration file is explained in the 
274 "doc/sample-ngircd.conf", which is used as sample configuration file in
275 /usr/local/etc after running "make install" (if you don't already have one)
276 and in the ngircd.conf(5) manual page.
277
278
279 VI. Command line options
280 ~~~~~~~~~~~~~~~~~~~~~~~~
281
282 These parameters could be passed to the ngIRCd:
283
284 -f, --config <file>
285         The daemon uses the file <file> as configuration file rather than
286         the standard configuration /usr/local/etc/ngircd.conf.
287
288 -n, --nodaemon
289         ngIRCd should be running as a foreground process.
290
291 -p, --passive
292         Server-links won't be automatically established.
293
294 -t, --configtest
295         Reads, validates and dumps the configuration file as interpreted
296         by the server. Then exits.
297
298 Use "--help" to see a short help text describing all available parameters
299 the server understands, with "--version" the ngIRCd shows its version
300 number. In both cases the server exits after the output.
301
302 Please see the ngircd(8) manual page for complete details!