mirror of
https://github.com/osmarks/ngircd.git
synced 2024-12-12 18:00:28 +00:00
Convert the FAQ to Markdown and enhance it!
This commit is contained in:
Alexander Barton
parent
2877706660
commit
5413518586
176
doc/FAQ.md
Normal file
176
doc/FAQ.md
Normal file
@ -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 <name> <password>` 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 <https://github.com/ngircd/ngircd/issues>. 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 <https://github.com/ngircd/ngircd/issues/new>!
|
||||||
|
The authors will be notified automagically :-)
|
||||||
109
doc/FAQ.txt
109
doc/FAQ.txt
@ -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 <http://ngircd.barton.de/>.
|
|
||||||
|
|
||||||
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 (<http://atheme.net/atheme.html>) or Anope (<http://www.anope.org>).
|
|
||||||
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 <https://github.com/ngircd/ngircd/issues>. 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 <https://github.com/ngircd/ngircd/issues/new>!
|
|
||||||
The author will be notified automagically :-)
|
|
||||||
|
|
||||||
@ -1,6 +1,6 @@
|
|||||||
#
|
#
|
||||||
# ngIRCd -- The Next Generation IRC Daemon
|
# 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
|
# 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
|
# it under the terms of the GNU General Public License as published by
|
||||||
@ -22,7 +22,7 @@ static_docs = \
|
|||||||
Capabilities.txt \
|
Capabilities.txt \
|
||||||
Commands.txt \
|
Commands.txt \
|
||||||
Contributing.txt \
|
Contributing.txt \
|
||||||
FAQ.txt \
|
FAQ.md \
|
||||||
HowToRelease.txt \
|
HowToRelease.txt \
|
||||||
Modes.txt \
|
Modes.txt \
|
||||||
PAM.txt \
|
PAM.txt \
|
||||||
|
|||||||
Loading…
Reference in New Issue
Block a user