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