ngircd-tor/INSTALL

303 lines
10 KiB
Plaintext
Raw Normal View History

ngIRCd - Next Generation IRC Server
http://ngircd.barton.de/
(c)2001-2011 Alexander Barton and Contributors.
2003-03-04 14:46:53 +01:00
ngIRCd is free software and published under the
terms of the GNU General Public License.
2003-03-04 14:46:53 +01:00
-- INSTALL --
2002-12-18 13:19:07 +01:00
2003-03-04 14:46:53 +01:00
I. Upgrade Information
~~~~~~~~~~~~~~~~~~~~~~
2002-12-18 13:19:07 +01:00
Differences to version 17
- Support for ZeroConf/Bonjour/Rendezvous service registration has been
removed. The configuration option "NoZeroconf" is no longer available.
- The structure of ngircd.conf has been cleaned up and two new configuration
sections have been introduced: [Limits] and [Options].
Lots of configuration variables stored in the [Global] section are now
deprecated there and should be stored in one of these new sections (but
still work in [Global]):
"AllowRemoteOper" -> [Options]
"ChrootDir" -> [Options]
"ConnectIPv4" -> [Options]
"ConnectIPv6" -> [Options]
"ConnectRetry" -> [Limits]
"MaxConnections" -> [Limits]
"MaxConnectionsIP" -> [Limits]
"MaxJoins" -> [Limits]
"MaxNickLength" -> [Limits]
"NoDNS" -> [Options], and renamed to "DNS"
"NoIdent" -> [Options], and renamed to "Ident"
"NoPAM" -> [Options], and renamed to "PAM"
"OperCanUseMode" -> [Options]
"OperServerMode" -> [Options]
"PingTimeout" -> [Limits]
"PongTimeout" -> [Limits]
"PredefChannelsOnly" -> [Options]
"SSLCertFile" -> [Options]
"SSLDHFile" -> [Options]
"SSLKeyFile" -> [Options]
"SSLKeyFilePassword" -> [Options]
"SSLPorts" -> [Options]
"SyslogFacility" -> [Options]
"WebircPassword" -> [Options]
You should adjust your ngircd.conf and run "ngircd --configtest" to make
sure that your settings are correct and up to date!
Differences to version 16
- Changes to the "MotdFile" specified in ngircd.conf now require a ngircd
configuration reload to take effect (HUP signal, REHASH command).
2005-07-08 18:23:00 +02:00
Differences to version 0.9.x
- The option of the configure script to enable support for Zeroconf/Bonjour/
Rendezvous/WhateverItIsNamedToday has been renamed:
--with-rendezvous -> --with-zeroconf
Differences to version 0.8.x
- The maximum length of passwords has been raised to 20 characters (instead
of 8 characters). If your passwords are longer than 8 characters then they
are cut at an other position now.
2003-03-07 15:45:10 +01:00
Differences to version 0.6.x
- Some options of the configure script have been renamed:
--disable-syslog -> --without-syslog
--disable-zlib -> --without-zlib
Please call "./configure --help" to review the full list of options!
2003-03-04 14:46:53 +01:00
Differences to version 0.5.x
2002-12-18 13:19:07 +01:00
- Starting with version 0.6.0, other servers are identified using asynchronous
2003-03-04 14:46:53 +01:00
passwords: therefore the variable "Password" in [Server]-sections has been
replaced by "MyPassword" and "PeerPassword".
2003-03-04 14:46:53 +01:00
- New configuration variables, section [Global]: MaxConnections, MaxJoins
(see example configuration file "doc/sample-ngircd.conf"!).
2003-03-04 14:46:53 +01:00
II. Standard Installation
~~~~~~~~~~~~~~~~~~~~~~~~~
2003-03-24 00:13:15 +01:00
ngIRCd is developed for UNIX-based systems, which means that the installation
on modern UNIX-like systems that are supported by GNU autoconf and GNU
2003-03-04 14:46:53 +01:00
automake ("configure") should be no problem.
2003-03-04 14:46:53 +01:00
The normal installation procedure after getting (and expanding) the source
files (using a distribution archive or GIT) is as following:
1) ./autogen.sh [only necessary when using GIT]
2003-03-04 14:46:53 +01:00
2) ./configure
3) make
4) make install
2004-09-03 22:01:12 +02:00
(Please see details below!)
Now the newly compiled executable "ngircd" is installed in its standard
location, /usr/local/sbin/.
The next step is to configure and afterwards starting the daemon. Please
have a look at the ngircd(8) and ngircd.conf(5) manual pages for details
2011-03-23 01:08:49 +01:00
and all possible options -- and don't forget to run "ngircd --configtest"
to validate your configuration file!
2004-09-03 22:01:12 +02:00
If no previous version of the configuration file exists (the standard name
is /usr/local/etc/ngircd.conf), a sample configuration file containing all
possible options will be installed there. You'll find its template in the
doc/ directory: sample-ngircd.conf.
2003-03-08 13:34:55 +01:00
2003-03-04 14:46:53 +01:00
1): "autogen.sh"
2003-03-04 14:46:53 +01:00
The first step, autogen.sh, is only necessary if the configure-script isn't
already generated. This never happens in official ("stable") releases in
tar.gz-archives, but when using GIT.
This step is therefore only interesting for developers.
2003-03-04 14:46:53 +01:00
autogen.sh produces the Makefile.in's, which are necessary for the configure
script itself, and some more files for make. To run autogen.sh you'll need
2003-03-08 13:34:55 +01:00
GNU autoconf and GNU automake (use recent versions! autoconf 2.53 and
automake 1.6.1 are known to work).
2003-03-04 14:46:53 +01:00
Again: "end users" do not need this step!
2003-03-08 13:34:55 +01:00
2): "./configure"
The configure-script is used to detect local system dependencies.
In the perfect case, configure should recognise all needed libraries, header
2003-03-04 14:46:53 +01:00
files and so on. If this shouldn't work, "./configure --help" shows all
possible options.
2003-03-04 14:46:53 +01:00
In addition, you can pass some command line options to "configure" to enable
and/or disable some features of ngIRCd. All these options are shown using
"./configure --help", too.
Compiling a static binary will avoid you the hassle of feeding a chroot dir
(if you want use the chroot feature). Just do something like:
CFLAGS=-static ./configure [--your-options ...]
Then you can use a void directory as ChrootDir (like OpenSSH's /var/empty).
2003-03-08 13:34:55 +01:00
3): "make"
2002-05-08 17:44:43 +02:00
2003-03-04 14:46:53 +01:00
The make command uses the Makefiles produced by configure and compiles the
ngIRCd daemon.
2002-05-08 17:44:43 +02:00
2003-03-08 13:34:55 +01:00
4): "make install"
2002-05-08 17:44:43 +02:00
2003-03-04 14:46:53 +01:00
Use "make install" to install the server and a sample configuration file on
the local system. Normally, root privileges are necessary to complete this
step. If there is already an older configuration file present, it won't be
overwritten.
2002-05-08 17:44:43 +02:00
2011-03-23 01:08:49 +01:00
These files and folders will be installed by default:
2002-05-08 17:44:43 +02:00
- /usr/local/sbin/ngircd: executable server
2003-03-04 14:46:53 +01:00
- /usr/local/etc/ngircd.conf: sample configuration (if not already present)
2003-04-22 01:31:39 +02:00
- /usr/local/share/doc/ngircd/: documentation
2011-03-23 01:08:49 +01:00
- /usr/local/share/man/: manual pages
III. Additional features
~~~~~~~~~~~~~~~~~~~~~~~~
The following optional features can be compiled into the daemon by passing
options to the "configure" script. Most options can handle a <path> argument
which will be used to search for the required libraries and header files in
the given paths ("<path>/lib/...", "<path>/include/...") in addition to the
standard locations.
* Syslog Logging (autodetected by default):
--with-syslog[=<path>] / --without-syslog
Enable (disable) support for logging to "syslog", which should be
available on most modern UNIX-like operating systems by default.
* ZLib Compression (autodetected by default):
--with-zlib[=<path>] / --without-zlib
Enable (disable) support for compressed server-server links.
The Z compression library ("libz") is required for this option.
* IO Backend (autodetected by default):
--with-select[=<path>] / --without-select
--with-poll[=<path>] / --without-poll
--with-devpoll[=<path>] / --without-devpoll
--with-epoll[=<path>] / --without-epoll
--with-kqueue[=<path>] / --without-kqueue
ngIRCd can use different IO "backends": the "old school" select() and poll()
API which should be supported by most UNIX-like operating systems, or the
more efficient and flexible epoll() (Linux >=2.6), kqueue() (BSD) and
/dev/poll APIs.
By default the IO backend is autodetected, but you can use "--without-xxx"
to disable a more enhanced API.
When using the epoll() API, support for select() is compiled in as well by
default to enable the binary to run on older Linux kernels (<2.6), too.
* IDENT-Support:
--with-ident[=<path>]
Include support for IDENT ("AUTH") lookups. The "ident" library is
required for this option.
* TCP-Wrappers:
--with-tcp-wrappers[=<path>]
Include support for Wietse Venemas "TCP Wrappers" to limit client access
to the daemon, for example by using "/etc/hosts.{allow|deny}".
The "libwrap" is required for this option.
2010-07-11 17:01:45 +02:00
* PAM:
--with-pam[=<path>]
Enable support for PAM, the Pluggable Authentication Modules library.
See doc/PAM.txt for details.
2010-08-11 23:24:02 +02:00
* SSL:
--with-openssl[=<path>]
--with-gnutls[=<path>]
Enable support for SSL/TLS using OpenSSL or gnutls libraries.
See doc/SSL.txt for details.
* IPv6:
--enable-ipv6
Adds support for version 6 of the Internet Protocol.
IV. Useful make-targets
2003-03-04 14:46:53 +01:00
~~~~~~~~~~~~~~~~~~~~~~~
2003-03-04 14:46:53 +01:00
The Makefile produced by the configure-script contains always these useful
targets:
2003-03-04 14:46:53 +01:00
- clean: delete every product from the compiler/linker
next step: -> make
2003-03-04 14:46:53 +01:00
- distclean: the above plus erase all generated Makefiles
next step: -> ./configure
- maintainer-clean: erase all automatic generated files
2003-03-04 14:46:53 +01:00
next step: -> ./autogen.sh
2002-03-03 14:07:01 +01:00
V. Sample configuration file ngircd.conf
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2002-05-08 17:44:43 +02:00
2003-03-04 14:46:53 +01:00
In the sample configuration file, there are comments beginning with "#" OR
";" -- this is only for the better understanding of the file.
2002-05-08 17:44:43 +02:00
2011-03-23 01:08:49 +01:00
The file is separated in five blocks: [Global], [Features], [Operator],
[Server], and [Channel].
2003-03-10 01:23:34 +01:00
In the [Global] section, there is the main configuration like the server
2011-03-23 01:08:49 +01:00
name and the ports, on which the server should be listening. Options in
the [Features] section enable or disable functionality in the daemon.
IRC operators of this server are defined in [Operator] blocks, remote
servers are configured in [Server] sections, and [Channel] blocks are
used to configure pre-defined ("persistent") IRC channels.
2002-05-08 17:44:43 +02:00
2003-03-04 14:46:53 +01:00
The meaning of the variables in the configuration file is explained in the
"doc/sample-ngircd.conf", which is used as sample configuration file in
2003-03-10 01:23:34 +01:00
/usr/local/etc after running "make install" (if you don't already have one)
2011-03-23 01:08:49 +01:00
and in the ngircd.conf(5) manual page.
2002-05-08 17:44:43 +02:00
VI. Command line options
2003-03-04 14:46:53 +01:00
~~~~~~~~~~~~~~~~~~~~~~~~
2002-05-08 17:44:43 +02:00
2003-03-04 14:46:53 +01:00
These parameters could be passed to the ngIRCd:
2002-05-08 17:44:43 +02:00
-f, --config <file>
2003-03-04 14:46:53 +01:00
The daemon uses the file <file> as configuration file rather than
the standard configuration /usr/local/etc/ngircd.conf.
2002-05-08 17:44:43 +02:00
-n, --nodaemon
2003-03-04 14:46:53 +01:00
ngIRCd should be running as a foreground process.
2002-05-08 17:44:43 +02:00
-p, --passive
2003-03-04 14:46:53 +01:00
Server-links won't be automatically established.
2002-05-08 17:44:43 +02:00
2004-02-22 23:12:44 +01:00
-t, --configtest
2003-03-04 14:46:53 +01:00
Reads, validates and dumps the configuration file as interpreted
by the server. Then exits.
2002-05-08 17:44:43 +02:00
2003-03-04 14:46:53 +01:00
Use "--help" to see a short help text describing all available parameters
the server understands, with "--version" the ngIRCd shows its version
number. In both cases the server exits after the output.
2011-03-23 01:08:49 +01:00
Please see the ngircd(8) manual page for complete details!