From bed40cc10a9d48b3c15d67de2765b2f6401ef2fe Mon Sep 17 00:00:00 2001 From: James Lu Date: Sun, 30 Jul 2017 07:54:58 -0500 Subject: [PATCH 01/10] faq: add point about maxnicklen misconfigurations and relay (cherry picked from commit c7f300357c12e6c1aac1cf7fd7e76a42aef5f447) --- docs/faq.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/docs/faq.md b/docs/faq.md index edbcbc9..ce6658d 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -35,3 +35,9 @@ In no particular order: - Proper protocol negotiation leading to fewer DoS possibilities: - Better support for channel modes such as +fjMOR, etc. - Configurable nick length limits for 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`). From 54dab5f1077fe819e7bf67172c0b8d5ddd15b5d6 Mon Sep 17 00:00:00 2001 From: James Lu Date: Sun, 30 Jul 2017 07:57:05 -0500 Subject: [PATCH 02/10] faq: remove obsolete note about clientbot support The answer is fairly obvious now, and it's even mentioned in the readme. (cherry picked from commit 01dc2505e2c2aff9ca0a30a22bca63eed220287f) --- docs/faq.md | 4 ---- 1 file changed, 4 deletions(-) diff --git a/docs/faq.md b/docs/faq.md index ce6658d..3160955 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -12,10 +12,6 @@ You must use SPACES and not tabs in your configuration! (`\t` is the escaped cod 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 From c16ca14fba372005e42572f4c53f96767fb1d79c Mon Sep 17 00:00:00 2001 From: James Lu Date: Sun, 30 Jul 2017 23:40:26 +0800 Subject: [PATCH 03/10] faq: reword "advantages over Janus" section (cherry picked from commit 9dcc94129256e3d7f037514397fba11fc001d1e1) --- docs/faq.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/faq.md b/docs/faq.md index 3160955..f1df808 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -22,15 +22,15 @@ 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"! From f18f7de9f7e0697d904b475b42e19d6c0c80efec Mon Sep 17 00:00:00 2001 From: James Lu Date: Sun, 30 Jul 2017 23:42:23 +0800 Subject: [PATCH 04/10] faq: sort by subtopic (cherry picked from commit 42ce9c83b5e6827cd1140ef4ff482248b78ccc11) --- docs/faq.md | 14 ++++++++++---- 1 file changed, 10 insertions(+), 4 deletions(-) diff --git a/docs/faq.md b/docs/faq.md index f1df808..a558c8e 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -1,20 +1,22 @@ # 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 ### 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) -### 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? @@ -37,3 +39,7 @@ PyLink provides, in no particular order: 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 From b41234ad793b6ac86e76ff94623319a5b258bca0 Mon Sep 17 00:00:00 2001 From: James Lu Date: Mon, 31 Jul 2017 00:01:07 +0800 Subject: [PATCH 05/10] faq: add a troubleshooting guide for connection failures (cherry picked from commit bc5474a43a73a40303b6ba3a62c02825aa2a33c9) --- docs/faq.md | 20 +++++++++++++++++++- 1 file changed, 19 insertions(+), 1 deletion(-) diff --git a/docs/faq.md b/docs/faq.md index a558c8e..2c76653 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -12,9 +12,27 @@ You must use **spaces** and not tabs to indent your configuration file! (`\t` is ## Linking / connection issues +### PyLink won't connect to my network! + +As a general guide, you should check the following before asking for support: + +1) 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 solution 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. :) + ### 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) ## Relay issues From c9734cc0af84d5e1d696fee95840324003714b08 Mon Sep 17 00:00:00 2001 From: James Lu Date: Mon, 31 Jul 2017 00:06:19 +0800 Subject: [PATCH 06/10] faq: add "Relay users are missing" section (cherry picked from commit 0d9c53a4f401f74ad9fdc369ab0c065f53d6b948) --- docs/faq.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/faq.md b/docs/faq.md index 2c76653..6f7811b 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -61,3 +61,7 @@ However, if the nick mentioned is legal on IRC, this issue is likely caused by a ### 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! From 8e67017c818a92dc4e6fd7d251de4126d43ff548 Mon Sep 17 00:00:00 2001 From: James Lu Date: Mon, 31 Jul 2017 00:19:26 +0800 Subject: [PATCH 07/10] faq: be slightly less excited (cherry picked from commit cc4890184cc00ebc736697cbe5609c7e14bf386c) --- docs/faq.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/faq.md b/docs/faq.md index 6f7811b..373aab2 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -54,7 +54,7 @@ PyLink provides, in no particular order: ### 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! +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`). From 5d000c9930d1dbffa16466f3397898e179e0ef74 Mon Sep 17 00:00:00 2001 From: James Lu Date: Mon, 31 Jul 2017 00:19:53 +0800 Subject: [PATCH 08/10] faq: add a section regarding #463 (sporadic SSL-related errors) (cherry picked from commit 99acd06e02f8543f8d9196fa63913f57fe42a9a8) --- docs/faq.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/faq.md b/docs/faq.md index 373aab2..aecaf5e 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -30,6 +30,10 @@ As a general guide, you should check the following before asking for support: 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) From 381d96552b9900098912a13ee5f08878cdfa4134 Mon Sep 17 00:00:00 2001 From: James Lu Date: Mon, 31 Jul 2017 00:27:48 +0800 Subject: [PATCH 09/10] faq: fix formatting in the connection troubleshooting guide (cherry picked from commit f1f8f91bd7b6097c962b047b5b644b0c6bb9632b) --- docs/faq.md | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/docs/faq.md b/docs/faq.md index aecaf5e..94fd2e1 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -16,17 +16,17 @@ You must use **spaces** and not tabs to indent your configuration file! (`\t` is As a general guide, you should check the following before asking for support: -1) 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 solution to test this! 😬 +- 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 solution 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 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. :) From 7b281e4b0481d76bedb2561c3a1e0ff69774097b Mon Sep 17 00:00:00 2001 From: James Lu Date: Mon, 31 Jul 2017 00:29:04 +0800 Subject: [PATCH 10/10] faq: tweak wording (cherry picked from commit 17a4bbea87686d814eb2292d0142f8a8fdf591b4) --- docs/faq.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/faq.md b/docs/faq.md index 94fd2e1..1218a50 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -10,7 +10,7 @@ You are missing dependencies - re-read https://github.com/GLolol/PyLink/blob/mas 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 +## Linking / Connection issues ### PyLink won't connect to my network! @@ -22,7 +22,7 @@ As a general guide, you should check the following before asking for support: 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 solution to test this! 😬 + - 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).