From 541351858699bc7f196a197e417dce3b7f13b124 Mon Sep 17 00:00:00 2001 From: Alexander Barton Date: Tue, 9 Jan 2024 15:52:34 +0100 Subject: [PATCH] Convert the FAQ to Markdown and enhance it! --- doc/FAQ.md | 176 ++++++++++++++++++++++++++++++++++++++++++++++++ doc/FAQ.txt | 109 ------------------------------ doc/Makefile.am | 4 +- 3 files changed, 178 insertions(+), 111 deletions(-) create mode 100644 doc/FAQ.md delete mode 100644 doc/FAQ.txt diff --git a/doc/FAQ.md b/doc/FAQ.md new file mode 100644 index 00000000..2a0ae1dc --- /dev/null +++ b/doc/FAQ.md @@ -0,0 +1,176 @@ +# [ngIRCd](https://ngircd.barton.de) - FAQ, Tips & Tricks + +# General + +## Is it possible to link ngIRCd with other non-ngIRCd servers? + +Yes and no. Back in the beginning (2001, 2002, ...) the server-server protocol +used by ngIRCd was compatible to the original ircd used by IRCNet at that time, +version 2.10.3p3. And most probably this is still the case today, although not +actively tested for a long time. + +Please note that newer ircd versions (2.11.x) are *not* compatible any more! + +And other server-server protocols were never supported. + +## Is there a homepage with further information and downloads? + +Yes. Please visit https://ngircd.barton.de :-) + +## Why should I use ngIRCd instead of the original one? + +The `README.md` file and the [homepage](https://ngircd.barton.de) list a few +advantages of 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 WSL or Cygwin. + +# Building and Compilation + +## The `./configure` script is missing in the source directory!? + +When using sources checked out via *Git*, the `configure` script as well as the +`Makefile.in` templates must be generated using the GNU *automake*, *autoconf* +and *pkg-config* tools. To simplify this task run the `./autogen.sh` script +which will execute the required commands for you; then continue with executing +the `./configure` script as usual. + +Please see the `INSTALL.md` file for details! + +## Error message `aclocal: command not found` + +GNU *automake* is missing on your system but required for building Git versions +of ngIRCd. Install GNU automake 1.6 or later and try again. + +## Error message `autoheader: command not found`? + +GNU *autoconf* is missing on your system but required for building Git versions +of ngIRCd. Install GNU autoconf 2.52 or later and try again. + +## Error message `automake: configure.in: AM_INIT_AUTOMAKE must be used`? + +Most probably you are using version 1.5 of GNU automake which seems to be +incompatible to the build system of ngIRCd. Solution: upgrade to at least +version 1.6 of GNU automake. + +(If you are using Debian 3.0 "Woody" you can try to downgrade to version 1.4 of +GNU automake shipped with this distribution; it should work, too.) + +# Troubleshooting ngIRCd Runtime Issues + +Always start with: + +1. Make sure that ngIRCd parsed its configuration file as it was intended! + Run `ngircd --configest` and double-check its output! + +2. Check the logs of your system, especially the entries generated by ngIRCd! + Where you can find the log messages depends on your system and your setup: + it can be plain text files in `/var/log/` (syslog) or the systemd journal + database, for example. + +3. Ensure that the daemon started up successfully, is actually running and did + not stop/crash in the meantime. You can check this with your service + manager (like `systemctl status ngircd` on Linux systems using systemd) or + using `pgrep -l ngircd` to check for "ngircd" processes. If ngIRCd is not + running, try to restart the service and check the service status and the + logs (syslog, systemd journal) again! + +## Where is the log file stored? + +See introduction to this section above :-) + +## "Connection refused" errors + +1. Is the daemon really running? See introduction to this section above! + +2. Does ngIRCd listen on the correct interface(s) and port(s)? On Linux, you + can check this with `sudo ss -ltnp|awk '/ngircd/{print $4}`, for example. + Check your `Listen` and `Ports` settings in the `[Global]` (and `[SSL]`) + sections and the startup messages of the daemon, especially the lines + stating "Now listening on xxx:yyy (socket zzz)"! + +3. Are you able to connect to the ngIRCd service locally from the system the + daemon runs on? Test all the interface IP addresses you expect ngIRCd to + listen on, for example with a regular IRC client or tools like `telnet` or + `nc` ("net cat"): `telnet localhost 6667`, `nc 192.168.1.2 6667`, ... + + If all the above works as expected, the issue most probably is not with + ngIRCd or its configuration but the network layer. + +4. Are the port(s) ngIRCd listens on open and not blocked by a firewall? Check + the logs of your firewall solution (on the server itself and all firewalls + "in front of it") and use tools like `tcpdump` to check the network layer! + +## Issues related to running ngIRCd inside of a `chroot` environment + +**I cannot connect to remote peers when I use the chroot option, the following +is logged: `Can't resolve example.com: unknown error!`** + +See next question blow ... + +**When running ngIRCd inside a chroot, no IP addresses can be translated in DNS +names, errors like "Name or service not known" are logged!** + +On Linux/glibc with chroot enabled you need to put some libraries inside +the chroot as well, notably `libnss_dns`; maybe others. Unfortunately, even +linking ngIRCd statically does not help this. So you can either copy +all the required files into the chroot directory: + +``` bash +mkdir -p ./chroot/etc ./chroot/lib +cp -a /etc/hosts /etc/resolv.conf /etc/nsswitch.conf ./chroot/etc/ +cp -a /lib/libresolv* /lib/libnss_* ./chroot/lib/ +``` + +Or you can try to link ngIRCd against an other C library (like dietlibc) that do +not depend on NSS modules and these files. + +# IRC Features + +## I have added an `[Oper]` section, but how do I log in as an IRC operator? + +You can use the `/OPER ` command in your IRC client to become +an IRC operator as defined in an `[Oper]` block in your configuration file. + +ngIRCd will also log all OPER requests (using syslog), and if an OPER command +fails you can look there to determine why it did not work (bad password, +unauthorized host mask, ...). + +Please keep in mind that the "name" in the `/OPER` command is *not* related to +your nick name at all! + +## I am an IRC operator, but MODE doesn't work! + +By default, IRC operators are still not allowed to use `/MODE` globally. + +If you set `OperCanUseMode = yes` in your configuration, then IRC operators can +use the `/MODE` command for changing modes even when they are not joined to the +specific channel. + +## How can I "auto-op" users in channels? + +ngIRCd can't do this: you would have to use some "IRC Services", like +[Atheme](http://atheme.net/atheme.html) or [Anope](http://www.anope.org). + +See `doc/Services.txt` for setup instructions. + +# Bugs!? + +## Is there a list of known bugs and desired feature enhancements? + +Yes. Have a look at the bug tracking system (GitHub issues) for ngIRCd located +at . There you can file bug reports and +feature requests as well as search the bug database. + +## What should I do if I found a bug? + +Please file a bug report at ! +The authors will be notified automagically :-) diff --git a/doc/FAQ.txt b/doc/FAQ.txt deleted file mode 100644 index 3c5ec14e..00000000 --- a/doc/FAQ.txt +++ /dev/null @@ -1,109 +0,0 @@ - - ngIRCd - Next Generation IRC Server - - (c)2001-2010 by Alexander Barton, - alex@barton.de, http://www.barton.de/ - - ngIRCd is free software and published under the - terms of the GNU General Public License. - - -- FAQ: Frequently Asked Questions -- - - -I. General -~~~~~~~~~~ - -Q: Is it possible to link the ngIRCd with non-ngIRCd servers? -A: Yes. ngIRCd is compatible to the original ircd used by IRCNet. Actually - this is being tested with version 2.10.3p3. Please note that newer - versions (2.11.x) aren't compatible any more! - -Q: Is there a homepage with further information and downloads? -A: Yes. Please visit . - -Q: Why should I use ngIRCd instead of the original one? -A: ngIRCd offers several benefits: no problems with dynamic IPs, easy to - configure, open source (GPL), under active development. - - -II. Compilation -~~~~~~~~~~~~~~~ - -Q: I did a "Git checkout" but can't execute ./configure because the script - is missing in the generated directory!? -A: When using development versions via Git, the configure script as well as - the Makefile.in templates must be generated using GNU automake and GNU - autoconf. To simplify this task run the ./autogen.sh script which will - execute the required tools for you; then continue with executing the - ./configure script as usual. - -Q: The ./autogen.sh script complains "aclocal: command not found". -A: GNU automake is missing on your system but required for building Git - versions of ngIRCd. Install GNU automake 1.6 or later and try again. - -Q: The ./autogen.sh script stops with "autoheader: command not found". -A: GNU autoconf is missing on your system but required for building Git - versions of ngIRCd. Install GNU autoconf 2.52 or later and try again. - -Q: The ./autogen.sh script fails and the message "automake: configure.in: - AM_INIT_AUTOMAKE must be used" is displayed. -A: Most probably you are using version 1.5 of GNU automake which seems to be - incompatible to the build system of ngIRCd. Solution: upgrade to at least - version 1.6 of GNU automake. - (If you are using Debian 3.0 "Woody" you can try to downgrade to version - 1.4 of GNU automake shipped with this distribution; it should work, too.) - - -III. Runtime -~~~~~~~~~~~~ - -Q: Where is the log file located? -A: ngIRCd does not write its own log file. Instead, ngIRCd uses syslog(3). - Check the files in /var/log/ and/or consult the documentation for your - system logger daemon. - -Q: I cannot connect to remote peers when I use the chroot option, the - following is logged: "Can't resolve example.com: unknown error!". -A: see next question blow ... - -Q: When running ngIRCd inside a chroot, no IP addresses can be translated - in DNS names, errors like "Name or service not known" are logged. -A: On Linux/glibc with chroot enabled you need to put some libraries inside - the chroot as well, notably libnss_dns; maybe others. Unfortunately, even - linking ngIRCd statically does not help this. So you can either copy - all the required files into the chroot directory: - $ mkdir -p ./chroot/etc ./chroot/lib - $ cp -a /etc/hosts /etc/resolv.conf /etc/nsswitch.conf ./chroot/etc/ - $ cp -a /lib/libresolv* /lib/libnss_* ./chroot/lib/ - Or you can try to link ngIRCd against an other C library (like dietlibc) - that doesn't depend on NSS modules and/or these files. - -Q: I have added an [Oper] section, how do i log on as IRC operator? -A: You can use the /OPER command in your IRC client to become an IRC operator. - ngIRCd will also log all OPER requests (using syslog), if OPER fails you - can look there to determine why it did not work (bad password, unauthorized - host mask, etc.) - -Q: I am an IRC operator, but MODE doesn't work! -A: You need to set 'OperCanUseMode = yes' in ngircd.conf, then IRC operators - can use the MODE command for changing modes even when they are not joined - to the specific channel. - -Q: How can I "auto-op" users in channels? -A: ngIRCd can't do this: you would have to use some "IRC Services", like - Atheme () or Anope (). - See "doc/Services.txt" for setup instructions. - - -IV. Bugs!? -~~~~~~~~~~ - -Q: Is there a list of known bugs and desired feature enhancements? -A: Yes. Have a look at the bug tracking system (GitHub issues) for ngIRCd located - at . There you can file bug - reports and feature requests as well as search the bug database. - -Q: What should I do if I found a bug? -A: Please file a bug report at ! - The author will be notified automagically :-) - diff --git a/doc/Makefile.am b/doc/Makefile.am index 4ce26f06..d82480e9 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -1,6 +1,6 @@ # # ngIRCd -- The Next Generation IRC Daemon -# Copyright (c)2001-2020 Alexander Barton (alex@barton.de) and Contributors +# Copyright (c)2001-2024 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 @@ -22,7 +22,7 @@ static_docs = \ Capabilities.txt \ Commands.txt \ Contributing.txt \ - FAQ.txt \ + FAQ.md \ HowToRelease.txt \ Modes.txt \ PAM.txt \ -- 2.39.2