From 37ce1d18b994d5d15b989f880461fe816ea98578 Mon Sep 17 00:00:00 2001 From: KronosTheLate <61620837+KronosTheLate@users.noreply.github.com> Date: Wed, 14 Jun 2023 11:50:34 +0200 Subject: [PATCH 1/5] include "troubleshooting.md" page --- docs/make.jl | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/docs/make.jl b/docs/make.jl index d80a725..ed9145c 100644 --- a/docs/make.jl +++ b/docs/make.jl @@ -4,11 +4,12 @@ makedocs(; modules=[RemoteREPL], format=Documenter.HTML(), pages=[ - "Overview" => "index.md", - "Tutorial" => "tutorial.md", - "How To" => "howto.md", - "Reference" => "reference.md", - "Design" => "design.md", + "Overview" => "index.md", + "Tutorial" => "tutorial.md", + "How To" => "howto.md", + "Reference" => "reference.md", + "Design" => "design.md", + "Troubleshooting" => "troubleshooting.md", ], repo="https://github.com/c42f/RemoteREPL.jl/blob/{commit}{path}#L{line}", sitename="RemoteREPL.jl", From 00f61ae8440f2664f5c8602215f3cb00875aadd9 Mon Sep 17 00:00:00 2001 From: KronosTheLate <61620837+KronosTheLate@users.noreply.github.com> Date: Wed, 14 Jun 2023 12:19:50 +0200 Subject: [PATCH 2/5] Create "troubleshooting.md" Add a bunch of potential error messages in "troubleshooting.md" --- "docs/src/\"troubleshooting.md\"" | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+) create mode 100644 "docs/src/\"troubleshooting.md\"" diff --git "a/docs/src/\"troubleshooting.md\"" "b/docs/src/\"troubleshooting.md\"" new file mode 100644 index 0000000..d41ed8d --- /dev/null +++ "b/docs/src/\"troubleshooting.md\"" @@ -0,0 +1,24 @@ +# Troubleshooting +This page will contain errors that have been seen before, and how they were fixed. The goal is that solutions to common problems are found here. +By "local REPL" a REPL running on the same computer as the host is meant. By "remote REPL", a REPL running on a different computer is meant. + +### IOError: connect: connection refused (ECONNREFUSED) +This error has been encountered when +1) Running `connect_repl()`, while attempting to connect to a local REPL. The problem was that no local REPL had previously run `serve_repl()`. To fix this, run `serve_repl()` in the local REPL. +2) Running `connect_remote()`, while attempting to connect to a local REPL. The problem was that no local REPL had previously run `serve_repl()`. To fix this, run `serve_repl()` in the local REPL. +3) Running `connect_remote()`, while attempting to connect to a remote REPL. The problem was that no address was provided. To fix this, pass an adress as a string to `connect_remote`, as in `connect_remote("pi@192.168.4.2")` + +### RemoteREPL stream was closed while reading header +This error has been encountered when +1) Running `connect_remote("pi@192.168.4.2")`, while attempting to connect to a remote REPL. The problem was that the remote REPL had not previously run `serve_repl()`. To fix this, run `serve_repl()` in the remote REPL. +2) Running `connect_repl("pi@192.168.4.2")`, while attempting to connect to a remote REPL. The problem was that the remote REPL had not previously run `serve_repl()`. To fix this, run `serve_repl()` in the remote REPL. + +### Bad owner or permissions on /home/username/.ssh/config +This error is raised by [this](https://github.com/openssh/openssh-portable/blob/947a3e829a5b8832a4768fd764283709a4ca7955/readconf.c#L1711) line of code, from OpenSSH. +The requirements translates to that "the config file must be owned by root or by the user running the ssh and can not be writable by any group or other users." +(Quoted from [this](https://superuser.com/questions/1212402/bad-owner-or-permissions-on-ssh-config-file) thread). The fix is therefore to remove write premissions for +any group or other users. On a linux system, this is acomplished by running the following code. +``` +chmod go-w /home/username/.ssh/config +``` +If you are using a different operating system, please google how to remove write premissions on files, and try to do the same thing. From 1cbe47f8e8427d267035319d8a9f4da7d62212c1 Mon Sep 17 00:00:00 2001 From: KronosTheLate <61620837+KronosTheLate@users.noreply.github.com> Date: Sun, 20 Aug 2023 10:38:33 +0200 Subject: [PATCH 3/5] Update docs/src/"troubleshooting.md" Co-authored-by: Claire Foster --- "docs/src/\"troubleshooting.md\"" | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git "a/docs/src/\"troubleshooting.md\"" "b/docs/src/\"troubleshooting.md\"" index d41ed8d..71f7671 100644 --- "a/docs/src/\"troubleshooting.md\"" +++ "b/docs/src/\"troubleshooting.md\"" @@ -19,6 +19,6 @@ The requirements translates to that "the config file must be owned by root or by (Quoted from [this](https://superuser.com/questions/1212402/bad-owner-or-permissions-on-ssh-config-file) thread). The fix is therefore to remove write premissions for any group or other users. On a linux system, this is acomplished by running the following code. ``` -chmod go-w /home/username/.ssh/config +chmod go-w /home/username/.ssh/* ``` If you are using a different operating system, please google how to remove write premissions on files, and try to do the same thing. From beaa73c4e61991a30508abd0f8ccbb56cd6a0498 Mon Sep 17 00:00:00 2001 From: KronosTheLate <61620837+KronosTheLate@users.noreply.github.com> Date: Sun, 20 Aug 2023 10:41:49 +0200 Subject: [PATCH 4/5] Update docs/src/"troubleshooting.md" Co-authored-by: Claire Foster --- "docs/src/\"troubleshooting.md\"" | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git "a/docs/src/\"troubleshooting.md\"" "b/docs/src/\"troubleshooting.md\"" index 71f7671..b5ff7bd 100644 --- "a/docs/src/\"troubleshooting.md\"" +++ "b/docs/src/\"troubleshooting.md\"" @@ -4,8 +4,7 @@ By "local REPL" a REPL running on the same computer as the host is meant. By "re ### IOError: connect: connection refused (ECONNREFUSED) This error has been encountered when -1) Running `connect_repl()`, while attempting to connect to a local REPL. The problem was that no local REPL had previously run `serve_repl()`. To fix this, run `serve_repl()` in the local REPL. -2) Running `connect_remote()`, while attempting to connect to a local REPL. The problem was that no local REPL had previously run `serve_repl()`. To fix this, run `serve_repl()` in the local REPL. +1) Running `connect_repl()` or `connect_remote()`, while attempting to connect to a local REPL. The problem was that no local REPL had previously run `serve_repl()`. To fix this, run `serve_repl()` in the local REPL. 3) Running `connect_remote()`, while attempting to connect to a remote REPL. The problem was that no address was provided. To fix this, pass an adress as a string to `connect_remote`, as in `connect_remote("pi@192.168.4.2")` ### RemoteREPL stream was closed while reading header From 7236ace3fc3186dbac352ea231a935fbd6d8d2ab Mon Sep 17 00:00:00 2001 From: KronosTheLate Date: Tue, 24 Oct 2023 15:43:46 +0200 Subject: [PATCH 5/5] gitignore .vscode, move troubleshooting sections,+ --- .gitignore | 1 + docs/src/howto.md | 27 ++++++++++++++++++++++++++- 2 files changed, 27 insertions(+), 1 deletion(-) diff --git a/.gitignore b/.gitignore index b067edd..23a2fb5 100644 --- a/.gitignore +++ b/.gitignore @@ -1 +1,2 @@ /Manifest.toml +.vscode/settings.json \ No newline at end of file diff --git a/docs/src/howto.md b/docs/src/howto.md index 66878f1..9a691dc 100644 --- a/docs/src/howto.md +++ b/docs/src/howto.md @@ -13,7 +13,7 @@ `ssh-agent` running with your private key loaded. If you've got some particular ssh options needed for the server, you'll find it convenient to set these up in the OpenSSH config file (`~/.ssh/config` on unix). For - example, + example, the config file could contain the following: ```ssh-config Host your.example.host User ubuntu @@ -127,3 +127,28 @@ In environments without any REPL integrations like Jupyter or Pluto notebooks yo connect_remote(); ``` which will allow you to use `@remote` without the REPL mode. +## Troubleshooting connection issues +Sometimes errors will be encountered. This section aims to show some errors experienced by users, and what the underlying problem was. We will use some terms in this section, introduced in the table below. +|Term|Explanation| +|---|---| +|"local REPL"|a REPL running on the same computer as the host. This could mean connecting two julia instances running on the same computer.| +|"remote REPL"|a REPL running on a different computer than the host.| +|"address"|a placeholder for the address you connect to, typically an IP-address. Examples of what an actual address could look like include "pi@192.168.4.2" and "youruser@example.com".| + +### Error: `IOError: connect: connection refused (ECONNREFUSED)` +This error has been encountered when +1) Running `connect_repl()` or `connect_remote()`, while attempting to connect to a local REPL. The problem was that no local REPL had previously run `serve_repl()`. To fix this, run `serve_repl()` in the local REPL. +2) Running `connect_remote()`, while attempting to connect to a remote REPL. The problem was that no address was provided. To fix this, pass an address as a string to `connect_remote`, as in `connect_remote("address")` + +### Error: `RemoteREPL stream was closed while reading header` +This error has been encountered when running `connect_remote("address")` or `connect_repl("address")`, while attempting to connect to a remote REPL. The problem was that the remote REPL had not previously run `serve_repl()`. To fix this, run `serve_repl()` in the remote REPL. + +### Error: `Bad owner or permissions on /home/username/.ssh/config` +This error is raised by [this](https://github.com/openssh/openssh-portable/blob/947a3e829a5b8832a4768fd764283709a4ca7955/readconf.c#L1711) line of code, from OpenSSH. +The requirements translates to that "the config file must be owned by root or by the user running the ssh and can not be writable by any group or other users." +(Quoted from [this](https://superuser.com/questions/1212402/bad-owner-or-permissions-on-ssh-config-file) thread). The fix is therefore to remove write permissions for +any group or other users. On a linux system, this is accomplished by running the following code. +``` +chmod go-w /home/username/.ssh/* +``` +If you are using a different operating system, please google how to remove write permissions on files, and try to do the same thing.