diff --git a/Troubleshooting.md b/Troubleshooting.md new file mode 100644 index 0000000..37496bf --- /dev/null +++ b/Troubleshooting.md @@ -0,0 +1,18 @@ +You're having issues connecting? There are a bunch of common problems, and this page tries to be a collection of possible issues. + +First, you should really really really use encryption (TLS, also called SSL). The reason is that WeeChat relay allows access to `/exec`, so if you don't use encryption, anyone who sniffs your browser could find out your password and execute arbitrary code on your server. So go ahead and get yourself a certificate from [Let's Encrypt](https://letsencrypt.org/). It's free, very easy to set up, and there are tons of guides out there. + +If you're on a mobile device, self-signed certificates are a world of hurt (especially on Apple devices). You're better of getting a trusted certificate from [Let's Encrypt](https://letsencrypt.org/). This is also worthwhile for desktop machines, as it's just less hassle all around. + +If it still doesn't work, here are some things you can try: +- navigate to `https://:/weechat` (e.g. `https://foo.bar:9002/weechat`) in your browser. Do you get a certificate warning/error? If so, your certificate isn't set up properly. Correct behaviour would be a blank page. +- did you run `/relay sslcertkey` after setting your certificate? Try re-running it. +- let our bot diagnose your TLS setup, query `lorelai` on freenode and type `>tls :` (substituting host and port as above) + +If you can connect fine with your desktop/laptop, but are having trouble on your phone, you're most likely missing one or more intermediate CAs in your `relay.pem`. You can diagnose this with `lorelai` as above. Include *all* relevant intermediates and re-run `/relay sslcertkey`. + +Finally, if none of this helps, join us in `#glowing-bear` on freenode. I'm sure we can figure this out! (Please don't open an issue about it, it's far easier to diagnose this over IRC) + +*** + +Note: if you don't want to have to have to run `/relay sslcertkey` every two to three months with Let's Encrypt, you can proxy the relay behind a web server. You can do this with [nginx](http://nginx.com/blog/websocket-nginx/) or [apache](https://httpd.apache.org/docs/2.4/mod/mod_proxy_wstunnel.html), for example. \ No newline at end of file