diff --git a/docs/faq.md b/docs/faq.md index edbcbc9..1218a50 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -1,24 +1,44 @@ # PyLink FAQ +## Startup errors + ### I get errors like "ImportError: No module named 'yaml'" when I start PyLink You are missing dependencies - re-read https://github.com/GLolol/PyLink/blob/master/README.md#installation ### I get errors like "yaml.scanner.ScannerError: while scanning for the next token, found character '\t' that cannot start any token" -You must use SPACES and not tabs in your configuration! (`\t` is the escaped code for a tab, which is disallowed by YAML) +You must use **spaces** and not tabs to indent your configuration file! (`\t` is the escaped code for a tab, which is disallowed by YAML) + +## Linking / Connection issues + +### PyLink won't connect to my network! + +As a general guide, you should check the following before asking for support: + +- Is the target network's IRCd showing failed connection attempts? + - If not: + 1) Is PyLink connecting to the right port (i.e. one the IRCd is listening on?) + 2) Is the target network's IRCd actually binding to the port you're trying to use? If there is a port conflict with another program, the IRCd may fail to bind but *still start* on other ports that are free. + 3) Is the target port firewalled on the target machine? + 4) Is there a working connection between the source and target servers? Use ping to test this, as sometimes routing issues between providers can cause servers to become unreachable. + - If your servers are purposely blocking ping, it's up to you to find another way to test this! 😬 + + - If so: + 1) Check for recvpass/sendpass/server hostname/IP mismatches - usually the IRCd will tell you if you're running into one of these, provided you have the right server notices enabled (consult your IRCd documentation for how to do this). + 2) Make sure you're not connecting with SSL on a non-SSL port, or vice versa. + +If these steps haven't helped you so far, it doesn't hurt to ask for help. :) + +### My networks keep disconnecting with SSL errors! + +See https://github.com/GLolol/PyLink/issues/463 - this seems to be caused by a regression in OpenSSL 1.0.2, which ships with distros such as Ubuntu 16.04 LTS. Unfortunately, the only workarounds so far are to either disable SSL/TLS, or wrap a plain IRC connection in an external service (stunnel, OpenVPN, etc.) ### I turned autoconnect for PyLink on, and now I'm getting errors! -PyLink does not support inbound connections - much like regular services such as Atheme or Anope, it only connects outwards *to* IRCds. (If you don't understand what this means, it means you should turn autoconnect OFF for PyLink) +PyLink does not support inbound connections - much like regular services such as Atheme or Anope, it only connects outwards *to* IRCds. (If you don't understand what this means, it means you should turn autoconnect **off** for PyLink) -### Does PyLink support Clientbot relay like Janus? - -Yes. However, Clientbot support is in alpha stages as of PyLink 0.10 and is far from complete: [Clientbot TODO](https://github.com/GLolol/PyLink/issues?q=is%3Aissue+is%3Aopen+label%3Aprotocols%2Fclientbot). - -### Clientbot doesn't relay both ways! - -Load the `relay_clientbot` plugin. https://github.com/GLolol/PyLink/blob/e1fab8c/example-conf.yml#L303-L306 +## Relay issues ### Does everyone need to install PyLink Relay for it to work? @@ -26,12 +46,26 @@ Load the `relay_clientbot` plugin. https://github.com/GLolol/PyLink/blob/e1fab8c InterJanus-style links between PyLink daemons are not supported yet; see https://github.com/GLolol/PyLink/issues/99 for any progress regarding that. -### What are PyLink Relay's benefits over Janus? +### What are PyLink's advantages over Janus? -In no particular order: +PyLink provides, in no particular order: - More complete support for modern IRCds (UnrealIRCd 4.x, InspIRCd 2.0, charybdis 4, Nefarious IRCu, etc.). -- PyLink is built upon a flexible, maintainable codebase. -- Cross platform (*nix, Windows, and probably others too). -- Proper protocol negotiation leading to fewer DoS possibilities: +- A flexible, maintainable codebase extensible beyond Relay. +- Cross platform functionality (*nix, Windows, and probably others too). +- Proper protocol negotiation leading to fewer SQUIT/DoS possibilities: - Better support for channel modes such as +fjMOR, etc. - - Configurable nick length limits for relayed users. + - Proper support for nick length limits with relayed users. + +### My IRCd SQUITs the relay server with errors like "Bad nickname introduced"! + +First, check whether the SQUIT message includes the nick that triggered the netsplit. If this nick includes any characters not allowed in regular IRC, such as the slash ("/"), or is otherwise an invalid nick (e.g. beginning with a hyphen or number), this likely indicates a bug in PyLink Relay. These problems should be reported on the issue tracker. + +However, if the nick mentioned is legal on IRC, this issue is likely caused by a max nick length misconfiguration: i.e. the relay server is introducing nicks too long for the target network. This can be fixed by setting the `maxnicklen` option in the affected network's PyLink `server:` block to the same value as that network's `005` `NICKLEN` (that is, the `NICKLEN=` value in `/raw version`). + +### Clientbot doesn't relay both ways! + +Load the `relay_clientbot` plugin. https://github.com/GLolol/PyLink/blob/e1fab8c/example-conf.yml#L303-L306 + +### Relay is occasionally dropping users from channels! + +This usually indicates a serious bug in either Relay or PyLink's protocol modules, and should be reported as an issue. When asking for help, please state which IRCds your PyLink instance is linking to: specifically, which IRCd the missing users are *from* and which IRCd the users are missing *on*. Also, be prepared to send debug logs as you reproduce the issue!