2 ngIRCd - Next Generation IRC Server
3 http://ngircd.barton.de/
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.
12 I. Upgrade Information
13 ~~~~~~~~~~~~~~~~~~~~~~
15 Differences to version 17
17 - Support for ZeroConf/Bonjour/Rendezvous service registration has been
18 removed. The configuration option "NoZeroconf" is no longer available.
20 Differences to version 16
22 - Changes to the "MotdFile" specified in ngircd.conf now require a ngircd
23 configuration reload to take effect (HUP signal, REHASH command).
25 Differences to version 0.9.x
27 - The option of the configure script to enable support for Zeroconf/Bonjour/
28 Rendezvous/WhateverItIsNamedToday has been renamed:
29 --with-rendezvous -> --with-zeroconf
31 Differences to version 0.8.x
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.
37 Differences to version 0.6.x
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!
44 Differences to version 0.5.x
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".
50 - New configuration variables, section [Global]: MaxConnections, MaxJoins
51 (see example configuration file "doc/sample-ngircd.conf"!).
54 II. Standard Installation
55 ~~~~~~~~~~~~~~~~~~~~~~~~~
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.
61 The normal installation procedure after getting (and expanding) the source
62 files (using a distribution archive or GIT) is as following:
64 1) ./autogen.sh [only necessary when using GIT]
69 (Please see details below!)
71 Now the newly compiled executable "ngircd" is installed in its standard
72 location, /usr/local/sbin/.
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 -- and don't forget to run "ngircd --configtest"
77 to validate your configuration file!
79 If no previous version of the configuration file exists (the standard name
80 is /usr/local/etc/ngircd.conf), a sample configuration file containing all
81 possible options will be installed there. You'll find its template in the
82 doc/ directory: sample-ngircd.conf.
87 The first step, autogen.sh, is only necessary if the configure-script isn't
88 already generated. This never happens in official ("stable") releases in
89 tar.gz-archives, but when using GIT.
91 This step is therefore only interesting for developers.
93 autogen.sh produces the Makefile.in's, which are necessary for the configure
94 script itself, and some more files for make. To run autogen.sh you'll need
95 GNU autoconf and GNU automake (use recent versions! autoconf 2.53 and
96 automake 1.6.1 are known to work).
98 Again: "end users" do not need this step!
103 The configure-script is used to detect local system dependencies.
105 In the perfect case, configure should recognise all needed libraries, header
106 files and so on. If this shouldn't work, "./configure --help" shows all
109 In addition, you can pass some command line options to "configure" to enable
110 and/or disable some features of ngIRCd. All these options are shown using
111 "./configure --help", too.
113 Compiling a static binary will avoid you the hassle of feeding a chroot dir
114 (if you want use the chroot feature). Just do something like:
115 CFLAGS=-static ./configure [--your-options ...]
116 Then you can use a void directory as ChrootDir (like OpenSSH's /var/empty).
121 The make command uses the Makefiles produced by configure and compiles the
127 Use "make install" to install the server and a sample configuration file on
128 the local system. Normally, root privileges are necessary to complete this
129 step. If there is already an older configuration file present, it won't be
132 These files and folders will be installed by default:
134 - /usr/local/sbin/ngircd: executable server
135 - /usr/local/etc/ngircd.conf: sample configuration (if not already present)
136 - /usr/local/share/doc/ngircd/: documentation
137 - /usr/local/share/man/: manual pages
140 III. Additional features
141 ~~~~~~~~~~~~~~~~~~~~~~~~
143 The following optional features can be compiled into the daemon by passing
144 options to the "configure" script. Most options can handle a <path> argument
145 which will be used to search for the required libraries and header files in
146 the given paths ("<path>/lib/...", "<path>/include/...") in addition to the
149 * Syslog Logging (autodetected by default):
150 --with-syslog[=<path>] / --without-syslog
152 Enable (disable) support for logging to "syslog", which should be
153 available on most modern UNIX-like operating systems by default.
155 * ZLib Compression (autodetected by default):
156 --with-zlib[=<path>] / --without-zlib
158 Enable (disable) support for compressed server-server links.
159 The Z compression library ("libz") is required for this option.
161 * IO Backend (autodetected by default):
162 --with-select[=<path>] / --without-select
163 --with-poll[=<path>] / --without-poll
164 --with-devpoll[=<path>] / --without-devpoll
165 --with-epoll[=<path>] / --without-epoll
166 --with-kqueue[=<path>] / --without-kqueue
168 ngIRCd can use different IO "backends": the "old school" select() and poll()
169 API which should be supported by most UNIX-like operating systems, or the
170 more efficient and flexible epoll() (Linux >=2.6), kqueue() (BSD) and
172 By default the IO backend is autodetected, but you can use "--without-xxx"
173 to disable a more enhanced API.
174 When using the epoll() API, support for select() is compiled in as well by
175 default to enable the binary to run on older Linux kernels (<2.6), too.
178 --with-ident[=<path>]
180 Include support for IDENT ("AUTH") lookups. The "ident" library is
181 required for this option.
184 --with-tcp-wrappers[=<path>]
186 Include support for Wietse Venemas "TCP Wrappers" to limit client access
187 to the daemon, for example by using "/etc/hosts.{allow|deny}".
188 The "libwrap" is required for this option.
193 Enable support for PAM, the Pluggable Authentication Modules library.
194 See doc/PAM.txt for details.
197 --with-openssl[=<path>]
198 --with-gnutls[=<path>]
200 Enable support for SSL/TLS using OpenSSL or gnutls libraries.
201 See doc/SSL.txt for details.
206 Adds support for version 6 of the Internet Protocol.
209 IV. Useful make-targets
210 ~~~~~~~~~~~~~~~~~~~~~~~
212 The Makefile produced by the configure-script contains always these useful
215 - clean: delete every product from the compiler/linker
218 - distclean: the above plus erase all generated Makefiles
219 next step: -> ./configure
221 - maintainer-clean: erase all automatic generated files
222 next step: -> ./autogen.sh
225 V. Sample configuration file ngircd.conf
226 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
228 In the sample configuration file, there are comments beginning with "#" OR
229 ";" -- this is only for the better understanding of the file.
231 The file is separated in five blocks: [Global], [Features], [Operator],
232 [Server], and [Channel].
234 In the [Global] section, there is the main configuration like the server
235 name and the ports, on which the server should be listening. Options in
236 the [Features] section enable or disable functionality in the daemon.
237 IRC operators of this server are defined in [Operator] blocks, remote
238 servers are configured in [Server] sections, and [Channel] blocks are
239 used to configure pre-defined ("persistent") IRC channels.
241 The meaning of the variables in the configuration file is explained in the
242 "doc/sample-ngircd.conf", which is used as sample configuration file in
243 /usr/local/etc after running "make install" (if you don't already have one)
244 and in the ngircd.conf(5) manual page.
247 VI. Command line options
248 ~~~~~~~~~~~~~~~~~~~~~~~~
250 These parameters could be passed to the ngIRCd:
253 The daemon uses the file <file> as configuration file rather than
254 the standard configuration /usr/local/etc/ngircd.conf.
257 ngIRCd should be running as a foreground process.
260 Server-links won't be automatically established.
263 Reads, validates and dumps the configuration file as interpreted
264 by the server. Then exits.
266 Use "--help" to see a short help text describing all available parameters
267 the server understands, with "--version" the ngIRCd shows its version
268 number. In both cases the server exits after the output.
270 Please see the ngircd(8) manual page for complete details!