doc/FAQ.md

   1 # [ngIRCd](https://ngircd.barton.de) - FAQ, Tips & Tricks
   2
   3 # General
   4
   5 ## Is it possible to link ngIRCd with other non-ngIRCd servers?
   6
   7 Yes and no. Back in the beginning (2001, 2002, ...) the server-server protocol
   8 used by ngIRCd was compatible to the original ircd used by IRCNet at that time,
   9 version 2.10.3p3. And most probably this is still the case today, although not
  10 actively tested for a long time.
  11
  12 Please note that newer ircd versions (2.11.x) are *not* compatible any more!
  13
  14 And other server-server protocols were never supported.
  15
  16 ## Is there a homepage with further information and downloads?
  17
  18 Yes. Please visit https://ngircd.barton.de :-)
  19
  20 ## Why should I use ngIRCd instead of the original one?
  21
  22 The `README.md` file and the [homepage](https://ngircd.barton.de) list a few
  23 advantages of ngIRCd:
  24
  25 - Well arranged (lean) configuration file.
  26 - Simple to build, install, configure, and maintain.
  27 - Supports IPv6 and SSL.
  28 - Can use PAM for user authentication.
  29 - Lots of popular user and channel modes are implemented.
  30 - Supports "cloaking" of users.
  31 - No problems with servers that have dynamic IP addresses.
  32 - Freely available, modern, portable and tidy C source.
  33 - Wide field of supported platforms, including AIX, A/UX, FreeBSD, HP-UX,
  34   IRIX, Linux, macOS, NetBSD, OpenBSD, Solaris and Windows with WSL or Cygwin.
  35
  36 # Building and Compilation
  37
  38 ## The `./configure` script is missing in the source directory!?
  39
  40 When using sources checked out via *Git*, the `configure` script as well as the
  41 `Makefile.in` templates must be generated using the GNU *automake*, *autoconf*
  42 and *pkg-config* tools. To simplify this task run the `./autogen.sh` script
  43 which will execute the required commands for you; then continue with executing
  44 the `./configure` script as usual.
  45
  46 Please see the `INSTALL.md` file for details!
  47
  48 ## Error message `aclocal: command not found`
  49
  50 GNU *automake* is missing on your system but required for building Git versions
  51 of ngIRCd. Install GNU automake 1.6 or later and try again.
  52
  53 ## Error message `autoheader: command not found`?
  54
  55 GNU *autoconf* is missing on your system but required for building Git versions
  56 of ngIRCd. Install GNU autoconf 2.52 or later and try again.
  57
  58 ## Error message `automake: configure.in: AM_INIT_AUTOMAKE must be used`?
  59
  60 Most probably you are using version 1.5 of GNU automake which seems to be
  61 incompatible to the build system of ngIRCd. Solution: upgrade to at least
  62 version 1.6 of GNU automake.
  63
  64 (If you are using Debian 3.0 "Woody" you can try to downgrade to version 1.4 of
  65 GNU automake shipped with this distribution; it should work, too.)
  66
  67 # Troubleshooting ngIRCd Runtime Issues
  68
  69 Always start with:
  70
  71 1.  Make sure that ngIRCd parsed its configuration file as it was intended!
  72     Run `ngircd --configest` and double-check its output!
  73
  74 2.  Check the logs of your system, especially the entries generated by ngIRCd!
  75     Where you can find the log messages depends on your system and your setup:
  76     it can be plain text files in `/var/log/` (syslog) or the systemd journal
  77     database, for example.
  78
  79 3.  Ensure that the daemon started up successfully, is actually running and did
  80     not stop/crash in the meantime. You can check this with your service
  81     manager (like `systemctl status ngircd` on Linux systems using systemd) or
  82     using `pgrep -l ngircd` to check for "ngircd" processes. If ngIRCd is not
  83     running, try to restart the service and check the service status and the
  84     logs (syslog, systemd journal) again!
  85
  86 ## Where is the log file stored?
  87
  88 See introduction to this section above :-)
  89
  90 ## "Connection refused" errors
  91
  92 1.  Is the daemon really running? See introduction to this section above!
  93
  94 2.  Does ngIRCd listen on the correct interface(s) and port(s)? On Linux, you
  95     can check this with `sudo ss -ltnp|awk '/ngircd/{print $4}`, for example.
  96     Check your `Listen` and `Ports` settings in the `[Global]` (and `[SSL]`)
  97     sections and the startup messages of the daemon, especially the lines
  98     stating "Now listening on xxx:yyy (socket zzz)"!
  99
 100 3.  Are you able to connect to the ngIRCd service locally from the system the
 101     daemon runs on? Test all the interface IP addresses you expect ngIRCd to
 102     listen on, for example with a regular IRC client or tools like `telnet` or
 103     `nc` ("net cat"): `telnet localhost 6667`, `nc 192.168.1.2 6667`, ...
 104
 105     If all the above works as expected, the issue most probably is not with
 106     ngIRCd or its configuration but the network layer.
 107
 108 4.  Are the port(s) ngIRCd listens on open and not blocked by a firewall? Check
 109     the logs of your firewall solution (on the server itself and all firewalls
 110     "in front of it") and use tools like `tcpdump` to check the network layer!
 111
 112 ## Issues related to running ngIRCd inside of a `chroot` environment
 113
 114 **I cannot connect to remote peers when I use the chroot option, the following
 115 is logged: `Can't resolve example.com: unknown error!`**
 116
 117 See next question blow ...
 118
 119 **When running ngIRCd inside a chroot, no IP addresses can be translated in DNS
 120 names, errors like "Name or service not known" are logged!**
 121
 122 On Linux/glibc with chroot enabled you need to put some libraries inside
 123 the chroot as well, notably `libnss_dns`; maybe others. Unfortunately, even
 124 linking ngIRCd statically does not help this. So you can either copy
 125 all the required files into the chroot directory:
 126
 127 ``` bash
 128 mkdir -p ./chroot/etc ./chroot/lib
 129 cp -a /etc/hosts /etc/resolv.conf /etc/nsswitch.conf ./chroot/etc/
 130 cp -a /lib/libresolv* /lib/libnss_* ./chroot/lib/
 131 ```
 132
 133 Or you can try to link ngIRCd against an other C library (like dietlibc) that do
 134 not depend on NSS modules and these files.
 135
 136 # IRC Features
 137
 138 ## I have added an `[Oper]` section, but how do I log in as an IRC operator?
 139
 140 You can use the `/OPER <name> <password>` command in your IRC client to become
 141 an IRC operator as defined in an `[Oper]` block in your configuration file.
 142
 143 ngIRCd will also log all OPER requests (using syslog), and if an OPER command
 144 fails you can look there to determine why it did not work (bad password,
 145 unauthorized host mask, ...).
 146
 147 Please keep in mind that the "name" in the `/OPER` command is *not* related to
 148 your nick name at all!
 149
 150 ## I am an IRC operator, but MODE doesn't work!
 151
 152 By default, IRC operators are still not allowed to use `/MODE` globally.
 153
 154 If you set `OperCanUseMode = yes` in your configuration, then IRC operators can
 155 use the `/MODE` command for changing modes even when they are not joined to the
 156 specific channel.
 157
 158 ## How can I "auto-op" users in channels?
 159
 160 ngIRCd can't do this: you would have to use some "IRC Services", like
 161 [Atheme](http://atheme.net/atheme.html) or [Anope](http://www.anope.org).
 162
 163 See `doc/Services.txt` for setup instructions.
 164
 165 # Bugs!?
 166
 167 ## Is there a list of known bugs and desired feature enhancements?
 168
 169 Yes. Have a look at the bug tracking system (GitHub issues) for ngIRCd located
 170 at <https://github.com/ngircd/ngircd/issues>. There you can file bug reports and
 171 feature requests as well as search the bug database.
 172
 173 ## What should I do if I found a bug?
 174
 175 Please file a bug report at <https://github.com/ngircd/ngircd/issues/new>!
 176 The authors will be notified automagically :-)