Convert INSTALL and README files to Markdown
authorAlexander Barton <alex@barton.de>
Tue, 11 Feb 2020 20:00:18 +0000 (21:00 +0100)
committerAlexander Barton <alex@barton.de>
Sun, 29 Mar 2020 20:33:51 +0000 (22:33 +0200)
This requires some changes to the build system, for example to comply
with the expectations of the GNU autoconf/automake tools ...

INSTALL [deleted file]
INSTALL.md [new file with mode: 0644]
Makefile.am
README [deleted file]
README.md [new file with mode: 0644]
configure.ng
contrib/MacOSX/ngIRCd.xcodeproj/project.pbxproj
doc/Makefile.am

diff --git a/INSTALL b/INSTALL
deleted file mode 100644 (file)
index 1dc75eb..0000000
--- a/INSTALL
+++ /dev/null
@@ -1,370 +0,0 @@
-
-                     ngIRCd - Next Generation IRC Server
-                           http://ngircd.barton.de/
-
-               (c)2001-2020 Alexander Barton and Contributors.
-               ngIRCd is free software and published under the
-                   terms of the GNU General Public License.
-
-                                -- INSTALL --
-
-
-I. Upgrade Information
-~~~~~~~~~~~~~~~~~~~~~~
-
-Differences to version 22.x
-
-- The "NoticeAuth" ngircd.conf configuration variable has been renamed to
-  "NoticeBeforeRegistration". The old "NoticeAuth" variable still works but
-  is deprecated now.
-
-- The default value of the SSL "CipherList" variable has been changed to
-  "HIGH:!aNULL:@STRENGTH:!SSLv3" (OpenSSL) and "SECURE128:-VERS-SSL3.0"
-  (GnuTLS) to disable the old SSLv3 protocol by default.
-  To enable connections of clients still requiring the weak SSLv3 protocol,
-  the "CipherList" must be set to its old value (not recommended!), which
-  was "HIGH:!aNULL:@STRENGTH" (OpenSSL) and "SECURE128" (GnuTLS), see below.
-
-Differences to version 20.x
-
-- Starting with ngIRCd 21, the ciphers used by SSL are configurable and
-  default to "HIGH:!aNULL:@STRENGTH" (OpenSSL) or "SECURE128" (GnuTLS).
-  Previous version were using the OpenSSL or GnuTLS defaults, "DEFAULT"
-  and "NORMAL" respectively.
-
-- When adding GLINE's or KLINE's to ngIRCd 21 (or newer), all clients matching
-  the new mask will be KILL'ed. This was not the case with earlier versions
-  that only added the mask but didn't kill already connected users.
-
-- The "PredefChannelsOnly" configuration variable has been superseded by the
-  new "AllowedChannelTypes" variable. It is still supported and translated to
-  the appropriate "AllowedChannelTypes" setting but is deprecated now.
-
-Differences to version 19.x
-
-- Starting with ngIRCd 20, users can "cloak" their hostname only when the
-  configuration variable "CloakHostModeX" (introduced in 19.2) is set.
-  Otherwise, only IRC operators, other servers, and services are allowed to
-  set mode +x. This prevents regular users from changing their hostmask to
-  the name of the IRC server itself, which confused quite a few people ;-)
-
-Differences to version 17.x
-
-- 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 three new configuration
-  sections have been introduced: [Limits], [Options], and [SSL].
-  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"        -> [SSL], and renamed to "CertFile"
-    "SSLDHFile"          -> [SSL], and renamed to "DHFile"
-    "SSLKeyFile"         -> [SSL], and renamed to "KeyFile"
-    "SSLKeyFilePassword" -> [SSL], and renamed to "KeyFilePassword"
-    "SSLPorts"           -> [SSL], and renamed to "Ports"
-    "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.x
-
-- Changes to the "MotdFile" specified in ngircd.conf now require a ngircd
-  configuration reload to take effect (HUP signal, REHASH command).
-
-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.
-
-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!
-
-Differences to version 0.5.x
-
-- Starting with version 0.6.0, other servers are identified using asynchronous
-  passwords: therefore the variable "Password" in [Server]-sections has been
-  replaced by "MyPassword" and "PeerPassword".
-
-- New configuration variables, section [Global]: MaxConnections, MaxJoins
-  (see example configuration file "doc/sample-ngircd.conf"!).
-
-
-II. Standard Installation
-~~~~~~~~~~~~~~~~~~~~~~~~~
-
-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
-automake ("configure") should be no problem.
-
-The normal installation procedure after getting (and expanding) the source
-files (using a distribution archive or Git) is as following:
-
-  0) Satisfy prerequisites
-  1) ./autogen.sh  [only necessary when using Git]
-  2) ./configure
-  3) make
-  4) make install
-
-(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
-and all possible options -- and don't forget to run "ngircd --configtest"
-to validate your configuration file!
-
-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.
-
-
-0): Satisfy prerequisites
-
-When building from source, you'll need some other software to build ngIRCd:
-for example a working C compiler, make tool, and a few libraries depending on
-the feature set you want to enable at compile time (like IDENT, SSL, and PAM).
-
-And if you aren't using a distribution archive ("tar.gz" file), but cloned the
-plain source archive, you need a few additional tools to generate the build
-system itself: GNU automake and autoconf, as well as pkg-config.
-
-If you are using one of the "big" operating systems or Linux distributions,
-you can use the following commands to install all the required packages to
-build the sources including all optional features and to run the test suite:
-
-* Red Hat / Fedora based distributions:
-
-  yum install \
-    autoconf automake expect gcc glibc-devel gnutls-devel \
-    libident-devel make pam-devel pkg-config tcp_wrappers-devel telnet zlib-devel
-
-* Debian / Ubuntu based distributions:
-
-  apt-get install \
-    autoconf automake build-essential expect libgnutls28-dev \
-    libident-dev libpam-dev pkg-config libwrap0-dev libz-dev telnet
-
-
-1): "autogen.sh"
-
-The first step, autogen.sh, is ONLY necessary if the "configure" script itself
-isn't already generated. This never happens in official ("stable") releases in
-"tar.gz" archives, but when cloning the source code repository using Git.
-
-This step is therefore only interesting for developers.
-
-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
-GNU autoconf, GNU automake and pkg-config: at least autoconf 2.61 and automake
-1.10 are required, newer is better. But don't use automake 1.12 or newer for
-creating distribution archives: it will work but lack "de-ANSI-fication" support
-in the generated Makefile's! Stick with automake 1.11.x for this purpose ...
-So automake 1.11.x and autoconf 2.67+ is recommended.
-
-Again: "end users" do not need this step and neither need GNU autoconf nor GNU
-automake at all!
-
-
-2): "./configure"
-
-The configure-script is used to detect local system dependencies.
-
-In the perfect case, configure should recognize all needed libraries, header
-files and so on. If this shouldn't work, "./configure --help" shows all
-possible options.
-
-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).
-
-
-3): "make"
-
-The make command uses the Makefiles produced by configure and compiles the
-ngIRCd daemon.
-
-
-4): "make install"
-
-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.
-
-These files and folders will be installed by default:
-
-- /usr/local/sbin/ngircd: executable server
-- /usr/local/etc/ngircd.conf: sample configuration (if not already present)
-- /usr/local/share/doc/ngircd/: documentation
-- /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.
-
-* PAM:
-  --with-pam[=<path>]
-
-  Enable support for PAM, the Pluggable Authentication Modules library.
-  See doc/PAM.txt for details.
-
-* 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
-~~~~~~~~~~~~~~~~~~~~~~~
-
-The Makefile produced by the configure-script contains always these useful
-targets:
-
- - clean: delete every product from the compiler/linker
-   next step: -> make
-
- - distclean: the above plus erase all generated Makefiles
-   next step: -> ./configure
-
- - maintainer-clean: erase all automatic generated files
-   next step: -> ./autogen.sh
-
-
-V. Sample configuration file ngircd.conf
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-In the sample configuration file, there are comments beginning with "#" OR
-";" -- this is only for the better understanding of the file.
-
-The file is separated in five blocks: [Global], [Features], [Operator],
-[Server], and [Channel].
-
-In the [Global] section, there is the main configuration like the server
-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.
-
-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
-/usr/local/etc after running "make install" (if you don't already have one)
-and in the ngircd.conf(5) manual page.
-
-
-VI. Command line options
-~~~~~~~~~~~~~~~~~~~~~~~~
-
-These parameters could be passed to the ngIRCd:
-
--f, --config <file>
-       The daemon uses the file <file> as configuration file rather than
-       the standard configuration /usr/local/etc/ngircd.conf.
-
--n, --nodaemon
-       ngIRCd should be running as a foreground process.
-
--p, --passive
-       Server-links won't be automatically established.
-
--t, --configtest
-       Reads, validates and dumps the configuration file as interpreted
-       by the server. Then exits.
-
-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.
-
-Please see the ngircd(8) manual page for complete details!
diff --git a/INSTALL.md b/INSTALL.md
new file mode 100644 (file)
index 0000000..788c234
--- /dev/null
@@ -0,0 +1,393 @@
+# [ngIRCd](https://ngircd.barton.de) - Internet Relay Chat Server
+
+This document explains how to install ngIRCd, the lightweight Internet Relay
+Chat (IRC) server.
+
+The first section lists noteworthy changes to earlier releases; you definitely
+should read this when upgrading your setup! But you can skip over this section
+when you do a fresh installation.
+
+All the subsequent sections describe the steps required to install and
+configure ngIRCd.
+
+## Upgrade Information
+
+Differences to version 22.x
+
+- The *NoticeAuth* `ngircd.conf` configuration variable has been renamed to
+  *NoticeBeforeRegistration*. The old *NoticeAuth* variable still works but
+  is deprecated now.
+
+- The default value of the SSL *CipherList* variable has been changed to
+  "HIGH:!aNULL:@STRENGTH:!SSLv3" (OpenSSL) and "SECURE128:-VERS-SSL3.0"
+  (GnuTLS) to disable the old SSLv3 protocol by default.
+
+  To enable connections of clients still requiring the weak SSLv3 protocol,
+  the *CipherList* must be set to its old value (not recommended!), which
+  was "HIGH:!aNULL:@STRENGTH" (OpenSSL) and "SECURE128" (GnuTLS), see below.
+
+Differences to version 20.x
+
+- Starting with ngIRCd 21, the ciphers used by SSL are configurable and
+  default to "HIGH:!aNULL:@STRENGTH" (OpenSSL) or "SECURE128" (GnuTLS).
+  Previous version were using the OpenSSL or GnuTLS defaults, "DEFAULT"
+  and "NORMAL" respectively.
+
+- When adding GLINE's or KLINE's to ngIRCd 21 (or newer), all clients matching
+  the new mask will be KILL'ed. This was not the case with earlier versions
+  that only added the mask but didn't kill already connected users.
+
+- The *PredefChannelsOnly* configuration variable has been superseded by the
+  new *AllowedChannelTypes* variable. It is still supported and translated to
+  the appropriate *AllowedChannelTypes* setting but is deprecated now.
+
+Differences to version 19.x
+
+- Starting with ngIRCd 20, users can "cloak" their hostname only when the
+  configuration variable *CloakHostModeX* (introduced in 19.2) is set.
+  Otherwise, only IRC operators, other servers, and services are allowed to
+  set mode +x. This prevents regular users from changing their hostmask to
+  the name of the IRC server itself, which confused quite a few people ;-)
+
+Differences to version 17.x
+
+- 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 three new configuration
+  sections have been introduced: *[Limits]*, *[Options]*, and *[SSL]*.
+
+  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*        -> [SSL], and renamed to *CertFile*
+  - *SSLDHFile*          -> [SSL], and renamed to *DHFile*
+  - *SSLKeyFile*         -> [SSL], and renamed to *KeyFile*
+  - *SSLKeyFilePassword* -> [SSL], and renamed to *KeyFilePassword*
+  - *SSLPorts*           -> [SSL], and renamed to *Ports*
+  - *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.x
+
+- Changes to the *MotdFile* specified in `ngircd.conf` now require a ngIRCd
+  configuration reload to take effect (HUP signal, *REHASH* command).
+
+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.
+
+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!
+
+Differences to version 0.5.x
+
+- Starting with version 0.6.0, other servers are identified using asynchronous
+  passwords: therefore the variable *Password* in *[Server]*-sections has been
+  replaced by *MyPassword* and *PeerPassword*.
+
+- New configuration variables, section *[Global]*: *MaxConnections*, *MaxJoins*
+  (see example configuration file `doc/sample-ngircd.conf`!).
+
+## Standard Installation
+
+*Note*: This sections describes installing ngIRCd *from sources*. If you use
+packages available for your operating system distribution you should skip over
+and continue with the *Configuration* section, see below.
+
+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
+automake ("`configure` script") should be no problem.
+
+The normal installation procedure after getting (and expanding) the source
+files (using a distribution archive or Git) is as following:
+
+1) Satisfy prerequisites
+2) `./autogen.sh` [only necessary when using "raw" sources with Git]
+3) `./configure`
+4) `make`
+5) `make install`
+
+(Please see details below!)
+
+Now the newly compiled executable "ngircd" is installed in its standard
+location, `/usr/local/sbin/`.
+
+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`.
+
+The next step is to configure and afterwards start the daemon. See the section
+*Configuration* below.
+
+### Satisfy prerequisites
+
+When building from source, you'll need some other software to build ngIRCd:
+for example a working C compiler, make tool, and a few libraries depending on
+the feature set you want to enable at compile time (like IDENT, SSL, and PAM).
+
+And if you aren't using a distribution archive ("tar.gz" file), but cloned the
+plain source archive, you need a few additional tools to generate the build
+system itself: GNU automake and autoconf, as well as pkg-config.
+
+If you are using one of the "big" operating systems or Linux distributions,
+you can use the following commands to install all the required packages to
+build the sources including all optional features and to run the test suite:
+
+#### Red Hat / Fedora based distributions
+
+``` shell
+  yum install \
+    autoconf automake expect gcc glibc-devel gnutls-devel \
+    libident-devel make pam-devel pkg-config tcp_wrappers-devel \
+    telnet zlib-devel
+```
+
+#### Debian / Ubuntu based distributions
+
+``` shell
+  apt-get install \
+    autoconf automake build-essential expect libgnutls28-dev \
+    libident-dev libpam-dev pkg-config libwrap0-dev libz-dev telnet
+```
+
+### `./autogen.sh`
+
+The first step, to run `./autogen.sh`, is *only* necessary if the `configure`
+script itself isn't already generated and available. This never happens in
+official ("stable") releases in "tar.gz" archives, but when cloning the source
+code repository using Git.
+
+**This step is therefore only interesting for developers!**
+
+The `autogen.sh` script produces the `Makefile.in`'s, which are necessary for
+the configure script itself, and some more files for `make(1)`.
+
+To run `autogen.sh` you'll need GNU autoconf, GNU automake and pkg-config: at
+least autoconf 2.61 and automake 1.10 are required, newer is better. But don't
+use automake 1.12 or newer for creating distribution archives: it will work
+but lack "de-ANSI-fication" support in the generated Makefile's! Stick with
+automake 1.11.x for this purpose ...
+
+So *automake 1.11.x* and *autoconf 2.67+* is recommended.
+
+Again: "end users" do not need this step and neither need GNU autoconf nor GNU
+automake at all!
+
+### `./configure`
+
+The `configure` script is used to detect local system dependencies.
+
+In the perfect case, `configure` should recognize all needed libraries, header
+files and so on. If this shouldn't work, `./configure --help` shows all
+possible options.
+
+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:
+
+``` shell
+  CFLAGS=-static ./configure [--your-options ...]
+```
+
+Then you can use a void directory as ChrootDir (like OpenSSH's `/var/empty`).
+
+### `make`
+
+The `make(1)` command uses the `Makefile`'s produced by `configure` and
+compiles the ngIRCd daemon.
+
+### `make install`
+
+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.
+
+These files and folders will be installed by default:
+
+- `/usr/local/sbin/ngircd`: executable server
+- `/usr/local/etc/ngircd.conf`: sample configuration (if not already present)
+- `/usr/local/share/doc/ngircd/`: documentation
+- `/usr/local/share/man/`: manual pages
+
+### 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(2)` and
+  `poll(2)` API which should be supported by most UNIX-like operating systems,
+  or the more efficient and flexible `epoll(7)` (Linux >=2.6), `kqueue(2)`
+  (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(7)` API, support for `select(2)` 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.
+
+- PAM:
+
+  `--with-pam[=<path>]`
+
+  Enable support for PAM, the Pluggable Authentication Modules library.
+  See `doc/PAM.txt` for details.
+
+- 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.
+
+## Configuration
+
+Please have a look at the `ngircd(8)` and `ngircd.conf(5)` manual pages for
+details and all possible command line and configuration options -- **and don't
+forget to run `ngircd --configtest` to validate your configuration file!**
+
+After installing ngIRCd, a sample configuration file will be set up (if it
+does not exist already). By default, when installing from sources, the file is
+named `/usr/local/etc/ngircd.conf` (other common names, especially for
+distribution packages, are `/etc/ngircd.conf` or `/etc/ngircd/ngircd.conf`).
+
+You can find the template of the sample configuration file in the `doc/`
+directory as `sample-ngircd.conf` and
+[online](https://ngircd.barton.de/doc/sample-ngircd.conf) on the homepage. It
+contains all available options.
+
+In the sample configuration file, there are comments beginning with `#` *or*
+`;` -- this is only for the better understanding of the file, both comment
+styles are equal.
+
+The file is separated in five blocks: *[Global]*, *[Features]*, *[Operator]*,
+*[Server]*, and *[Channel]*.
+
+In the *[Global]* section, there is the main configuration like the server
+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.
+
+### Manual Pages Online
+
+- Daemon: [ngircd.8](https://manpages.debian.org/ngircd.8)
+- Configutation file: [ngircd.conf.5](https://manpages.debian.org/ngircd.conf.5)
+
+## Command line options
+
+ngIRCd supports the following command line options:
+
+- `-f`, `--config <file>`
+
+  The daemon uses the file `<file>` as configuration file rather than
+  the standard configuration `/usr/local/etc/ngircd.conf`.
+
+- `-n`, `--nodaemon`
+
+  ngIRCd should be running as a foreground process.
+
+- `-p`, `--passive`
+
+  Server-links won't be automatically established.
+
+- `-t`, `--configtest`
+
+  Reads, validates and dumps the configuration file as interpreted
+  by the server. Then exits.
+
+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.
+
+Please see the `ngircd(8)` manual page for more details!
index d7ff72bc7b3df7ea0da788edf4a5ed964c4b9095..5ac537f621d599f6743e74f0bf3a17008d946277 100644 (file)
@@ -9,11 +9,9 @@
 # Please read the file COPYING, README and AUTHORS for more information.
 #
 
-AUTOMAKE_OPTIONS = gnu
-
 SUBDIRS = doc src man contrib
 
-EXTRA_DIST = autogen.sh configure.ng .clang_complete .mailmap
+EXTRA_DIST = README.md INSTALL.md autogen.sh configure.ng .clang_complete .mailmap
 
 clean-local: osxpkg-clean
        rm -f build-stamp*
diff --git a/README b/README
deleted file mode 100644 (file)
index e9aadba..0000000
--- a/README
+++ /dev/null
@@ -1,89 +0,0 @@
-
-                     ngIRCd - Next Generation IRC Server
-                           http://ngircd.barton.de/
-
-               (c)2001-2020 Alexander Barton and Contributors.
-               ngIRCd is free software and published under the
-                   terms of the GNU General Public License.
-
-                                -- README --
-
-
-I. Introduction
-~~~~~~~~~~~~~~~
-
-ngIRCd is a free, portable and lightweight Internet Relay Chat server for
-small or private networks, developed under the GNU General Public License
-(GPL; please see the file COPYING for details). It is simple to configure,
-can cope with dynamic IP addresses, and supports IPv6 as well as SSL. It is
-written from scratch and not based on the original IRCd.
-
-The name ngIRCd means next generation IRC daemon, which is a little bit
-exaggerated: lightweight Internet Relay Chat server most probably would be a
-better name :-)
-
-Please see the INSTALL document for installation and upgrade information!
-
-
-II. Status
-~~~~~~~~~~~
-
-ngIRCd should be quite feature complete and stable to be used as daemon in
-real world IRC networks.
-
-It is not the goal of ngIRCd to implement all the nasty behaviors of the
-original ircd, but to implement most of the useful commands and semantics
-specified by the RFCs that are used by existing clients.
-
-
-III. Features (or: why use ngIRCd?)
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-- Well arranged (lean) configuration file.
-- Simple to build, install, configure, and maintain.
-- Supports IPv6 and SSL.
-- Can use PAM for user authentication.
-- Lots of popular user and channel modes are implemented.
-- Supports "cloaking" of users.
-- No problems with servers that have dynamic IP addresses.
-- Freely available, modern, portable and tidy C source.
-- Wide field of supported platforms, including AIX, A/UX, FreeBSD, HP-UX,
-  IRIX, Linux, Mac OS X, NetBSD, OpenBSD, Solaris, and Windows with Cygwin.
-- ngIRCd is being actively developed since 2001.
-
-
-IV. Documentation
-~~~~~~~~~~~~~~~~~
-
-More documentation can be found in the "doc/" directory and the homepage of
-ngIRCd: <http://ngircd.barton.de/>.
-
-
-V. Download
-~~~~~~~~~~~
-
-The homepage of the ngIRCd is <http://ngircd.barton.de/>; you will find
-the newest information about the ngIRCd and the most recent ("stable")
-releases there.
-
-Visit our source code repository at GitHub if you are interested in the
-latest development version: <https://github.com/ngircd/ngircd>.
-
-
-VI. Problems, Bugs, Patches
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Please don't hesitate to contact us if you encounter problems:
-
-- On IRC: <irc://irc.barton.de/ngircd>
-- Via the mailing list: <ngircd-ml@ngircd.barton.de>
-
-See <http://ngircd.barton.de/support.php> for details.
-
-If you find bugs in ngIRCd (which will be there most probably ...), please
-report them to our issue tracker at GitHub:
-
-- Bug tracker: <https://github.com/ngircd/ngircd/issues>
-- Patches, "pull requests": <https://github.com/ngircd/ngircd/pulls>
-
-There you can read about known bugs and limitations, too.
diff --git a/README.md b/README.md
new file mode 100644 (file)
index 0000000..144e407
--- /dev/null
+++ b/README.md
@@ -0,0 +1,76 @@
+# [ngIRCd](https://ngircd.barton.de) - Internet Relay Chat Server
+
+## Introduction
+
+*ngIRCd* is a free, portable and lightweight *Internet Relay Chat* ([IRC])
+server for small or private networks, developed under the terms of the GNU
+General Public License ([GPL]); please see the file `COPYING` for licensing
+information.
+
+The server is simple to configure, can cope with dynamic IP addresses, and
+supports IPv6 as well as SSL. It is written from scratch and not based on the
+original IRCd.
+
+The name ngIRCd means *next generation IRC daemon*, which is a little bit
+exaggerated: *lightweight Internet Relay Chat server* most probably would have
+been a better name :-)
+
+Please see the `INSTALL.md` document for installation and upgrade information,
+online available here: <https://ngircd.barton.de/doc/INSTALL.md>!
+
+## Status
+
+ngIRCd should be quite feature complete and stable to be used as daemon in
+real world IRC networks.
+
+It is not the goal of ngIRCd to implement all the nasty behaviors of the
+original ircd, but to implement most of the useful commands and semantics
+specified by the RFCs that are used by existing clients.
+
+## Features (or: why use ngIRCd?)
+
+- Well arranged (lean) configuration file.
+- Simple to build, install, configure, and maintain.
+- Supports IPv6 and SSL.
+- Can use PAM for user authentication.
+- Lots of popular user and channel modes are implemented.
+- Supports "cloaking" of users.
+- No problems with servers that have dynamic IP addresses.
+- Freely available, modern, portable and tidy C source.
+- Wide field of supported platforms, including AIX, A/UX, FreeBSD, HP-UX,
+  IRIX, Linux, macOS, NetBSD, OpenBSD, Solaris, and Windows with Cygwin.
+- ngIRCd is being actively developed since 2001.
+
+## Documentation
+
+The **homepage** of the ngIRCd project is <https://ngircd.barton.de>.
+
+More documentation can be found in the `doc/` directory and
+[online](https://ngircd.barton.de/documentation).
+
+## Downloads & Source Code
+
+You can find the latest information about the ngIRCd and the most recent
+stable release on the [news](https://ngircd.barton.de/news) and
+[downloads](https://ngircd.barton.de/download) pages of the homepage.
+
+Visit our source code repository at [GitHub](https://github.com) if you are
+interested in the latest development code: <https://github.com/ngircd/ngircd>.
+
+## Problems, Bugs, Patches
+
+Please don't hesitate to contact us if you encounter problems:
+
+- On IRC: <irc://irc.barton.de/ngircd>
+- Via the mailing list: <ngircd-ml@ngircd.barton.de>
+
+See <http://ngircd.barton.de/support> for details.
+
+If you find any bugs in ngIRCd (which most probably will be there ...), please
+report them to our issue tracker at GitHub:
+
+- Bug tracker: <https://github.com/ngircd/ngircd/issues>
+- Patches, "pull requests": <https://github.com/ngircd/ngircd/pulls>
+
+[IRC]: https://wikipedia.org/wiki/Internet_Relay_Chat
+[GPL]: https://wikipedia.org/wiki/GNU_General_Public_License
index a3855dbebee95b1bd33059ce16b16a87abb9a4a5..d1f731bc8c05093b65fd55f3a451653a932bfc02 100644 (file)
@@ -29,7 +29,7 @@ AC_CONFIG_SRCDIR([src/ngircd/ngircd.c])
 AC_CONFIG_HEADER([src/config.h])
 AC_CANONICAL_HOST
 
-AM_INIT_AUTOMAKE([-Wall 1.10 ]ng_color_tests)
+AM_INIT_AUTOMAKE([-Wall 1.10 foreign ]ng_color_tests)
 
 m4_ifdef([AM_SILENT_RULES], [AM_SILENT_RULES([yes])])
 
index d67ac8945f6f199e4890cf1cfd6962d78c11288f..2fe59a9deaa83f6d45bb46cf9253c36e05d08c9b 100644 (file)
                FA322D5E0CEF750F001761B3 /* config.guess */ = {isa = PBXFileReference; fileEncoding = 5; lastKnownFileType = text.script.sh; name = config.guess; path = ../../config.guess; sourceTree = SOURCE_ROOT; };
                FA322D5F0CEF750F001761B3 /* config.sub */ = {isa = PBXFileReference; fileEncoding = 5; lastKnownFileType = text.script.sh; name = config.sub; path = ../../config.sub; sourceTree = SOURCE_ROOT; };
                FA322D610CEF750F001761B3 /* COPYING */ = {isa = PBXFileReference; fileEncoding = 5; lastKnownFileType = text; name = COPYING; path = ../../COPYING; sourceTree = SOURCE_ROOT; };
-               FA322D620CEF750F001761B3 /* INSTALL */ = {isa = PBXFileReference; fileEncoding = 5; lastKnownFileType = text; name = INSTALL; path = ../../INSTALL; sourceTree = SOURCE_ROOT; };
+               FA322D620CEF750F001761B3 /* INSTALL.md */ = {isa = PBXFileReference; fileEncoding = 5; lastKnownFileType = net.daringfireball.markdown; name = INSTALL.md; path = ../../INSTALL.md; sourceTree = SOURCE_ROOT; };
                FA322D630CEF750F001761B3 /* Makefile.am */ = {isa = PBXFileReference; fileEncoding = 5; lastKnownFileType = text; name = Makefile.am; path = ../../Makefile.am; sourceTree = SOURCE_ROOT; };
                FA322D640CEF750F001761B3 /* NEWS */ = {isa = PBXFileReference; fileEncoding = 5; lastKnownFileType = text; name = NEWS; path = ../../NEWS; sourceTree = SOURCE_ROOT; };
-               FA322D650CEF750F001761B3 /* README */ = {isa = PBXFileReference; fileEncoding = 5; lastKnownFileType = text; name = README; path = ../../README; sourceTree = SOURCE_ROOT; };
+               FA322D650CEF750F001761B3 /* README.md */ = {isa = PBXFileReference; fileEncoding = 5; lastKnownFileType = net.daringfireball.markdown; name = README.md; path = ../../README.md; sourceTree = SOURCE_ROOT; };
                FA322D6A0CEF7523001761B3 /* changelog */ = {isa = PBXFileReference; fileEncoding = 5; lastKnownFileType = text; path = changelog; sourceTree = "<group>"; };
                FA322D6B0CEF7523001761B3 /* compat */ = {isa = PBXFileReference; fileEncoding = 5; lastKnownFileType = text; path = compat; sourceTree = "<group>"; };
                FA322D6C0CEF7523001761B3 /* control */ = {isa = PBXFileReference; fileEncoding = 5; lastKnownFileType = text; path = control; sourceTree = "<group>"; };
                                FA322D5A0CEF750F001761B3 /* AUTHORS */,
                                FA322D5C0CEF750F001761B3 /* ChangeLog */,
                                FA322D610CEF750F001761B3 /* COPYING */,
-                               FA322D620CEF750F001761B3 /* INSTALL */,
+                               FA322D620CEF750F001761B3 /* INSTALL.md */,
                                FA322D640CEF750F001761B3 /* NEWS */,
-                               FA322D650CEF750F001761B3 /* README */,
+                               FA322D650CEF750F001761B3 /* README.md */,
                                FA322D5B0CEF750F001761B3 /* autogen.sh */,
                                FA322D5E0CEF750F001761B3 /* config.guess */,
                                FA322D5F0CEF750F001761B3 /* config.sub */,
index 5913c94ee1fdd05fbd34808c80d3e11646e79cb3..5c8a5d8554d6691e1b04fbf048e5f73185388eee 100644 (file)
@@ -1,6 +1,6 @@
 #
 # ngIRCd -- The Next Generation IRC Daemon
-# Copyright (c)2001-2015 Alexander Barton (alex@barton.de) and Contributors
+# Copyright (c)2001-2020 Alexander Barton (alex@barton.de) and Contributors
 #
 # This program is free software; you can redistribute it and/or modify
 # it under the terms of the GNU General Public License as published by
@@ -39,7 +39,7 @@ doc_templates = sample-ngircd.conf.tmpl
 
 generated_docs = sample-ngircd.conf
 
-toplevel_docs = ../AUTHORS ../COPYING ../ChangeLog ../INSTALL ../NEWS ../README
+toplevel_docs = ../AUTHORS ../COPYING ../ChangeLog ../INSTALL.md ../NEWS ../README.md
 
 SUBDIRS = src