From 9293e34ea301b83c26e34c0f7d20d98d077271b8 Mon Sep 17 00:00:00 2001 From: jurij-jukic Date: Tue, 28 May 2024 11:57:21 +0200 Subject: [PATCH 1/6] section 9 clarify --- src/hosted-nodes.md | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/src/hosted-nodes.md b/src/hosted-nodes.md index da481ead..31bc13f2 100644 --- a/src/hosted-nodes.md +++ b/src/hosted-nodes.md @@ -74,11 +74,16 @@ HTTP requests routed to that local port will then appear to the remote host as o Create a SSH tunnel like so (again, replacing [assumed values with those in your `advanced details`](#accessing-your-kinodes-terminal)): ```bash +ssh -L 9090:localhost: -f -N +``` +e.g., +``` bash ssh -L 9090:localhost:8099 kexampleuser@template.hosting.kinode.net -f -N ``` + or, if you've added your host to your [`~/.ssh/config`](#ssh-config), ```bash -ssh -L 9090:localhost:8099 template -f -N +ssh -L 9090:localhost: -f -N ``` Now, `kit` requests sent to `9090` will be routed to the remote Kinode, e.g., @@ -86,3 +91,5 @@ Now, `kit` requests sent to `9090` will be routed to the remote Kinode, e.g., kit s foo -p 9090 ``` will function the same as for a locally-hosted Kinode. + +You will need to create an SSH tunnel each time you start a session. From aa92877f54e29b8dbed5d14db3690baa00c9319f Mon Sep 17 00:00:00 2001 From: hosted-fornet Date: Mon, 3 Jun 2024 09:39:34 -0700 Subject: [PATCH 2/6] hosted-nodes: add links --- src/hosted-nodes.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/src/hosted-nodes.md b/src/hosted-nodes.md index da481ead..9ee53f60 100644 --- a/src/hosted-nodes.md +++ b/src/hosted-nodes.md @@ -49,19 +49,19 @@ Rather than typing in a password to create a SSH connection, you can use a keypa #### Generating Keypair -https://docs.github.com/en/authentication/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent#generating-a-new-ssh-key +[How to generate a keypair](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent#generating-a-new-ssh-key) #### `ssh-agent` -https://docs.github.com/en/authentication/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent#adding-your-ssh-key-to-the-ssh-agent +[How to use `ssh-agent` to store a keypair](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent#adding-your-ssh-key-to-the-ssh-agent) #### SSH Config -https://www.digitalocean.com/community/tutorials/ssh-essentials-working-with-ssh-servers-clients-and-keys#defining-server-specific-connection-information +[How to use `~/.ssh/config` to make SSH easier to use](https://www.digitalocean.com/community/tutorials/ssh-essentials-working-with-ssh-servers-clients-and-keys#defining-server-specific-connection-information) #### Adding Public Key to Remote Node -https://www.digitalocean.com/community/tutorials/ssh-essentials-working-with-ssh-servers-clients-and-keys#copying-your-public-ssh-key-to-a-server-with-ssh-copy-id +[How to add the public key to a remote node to allow login with it](https://www.digitalocean.com/community/tutorials/ssh-essentials-working-with-ssh-servers-clients-and-keys#copying-your-public-ssh-key-to-a-server-with-ssh-copy-id) ## Using `kit` With Your Hosted Node From ac9bd703eb35aff472ae01a5e410270d5c916ba7 Mon Sep 17 00:00:00 2001 From: hosted-fornet Date: Mon, 3 Jun 2024 17:18:38 -0700 Subject: [PATCH 3/6] hosted-nodes: dont background --- src/hosted-nodes.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/src/hosted-nodes.md b/src/hosted-nodes.md index 9ee53f60..e4498e27 100644 --- a/src/hosted-nodes.md +++ b/src/hosted-nodes.md @@ -74,15 +74,17 @@ HTTP requests routed to that local port will then appear to the remote host as o Create a SSH tunnel like so (again, replacing [assumed values with those in your `advanced details`](#accessing-your-kinodes-terminal)): ```bash -ssh -L 9090:localhost:8099 kexampleuser@template.hosting.kinode.net -f -N +ssh -L 9090:localhost:8099 kexampleuser@template.hosting.kinode.net ``` or, if you've added your host to your [`~/.ssh/config`](#ssh-config), ```bash -ssh -L 9090:localhost:8099 template -f -N +ssh -L 9090:localhost:8099 template ``` - -Now, `kit` requests sent to `9090` will be routed to the remote Kinode, e.g., +You should see a `ssh` session open. +While this session is open, `kit` requests sent to `9090` will be routed to the remote Kinode, e.g., ``` kit s foo -p 9090 ``` will function the same as for a locally-hosted Kinode. + +Closing the `ssh` connections with `Ctrl+D` or typing `exit` will close the tunnel. From 29c6a19154ee2e90c0a96d8c1743c47072ccdfa9 Mon Sep 17 00:00:00 2001 From: hosted-fornet Date: Tue, 4 Jun 2024 12:55:44 -0700 Subject: [PATCH 4/6] add kit connect docs --- src/SUMMARY.md | 1 + src/hosted-nodes.md | 2 + src/kit-dev-toolkit.md | 1 + src/kit/connect.md | 83 ++++++++++++++++++++++++++++++++++++++++++ 4 files changed, 87 insertions(+) create mode 100644 src/kit/connect.md diff --git a/src/SUMMARY.md b/src/SUMMARY.md index 24b518c8..5e43bc05 100644 --- a/src/SUMMARY.md +++ b/src/SUMMARY.md @@ -32,6 +32,7 @@ - [`dev-ui`](./kit/dev-ui.md) - [`inject-message`](./kit/inject-message.md) - [`run-tests`](./kit/run-tests.md) + - [`connect`](./kit/connect.md) - [`reset-cache`](./kit/reset-cache.md) - [My First Kinode Application](./build-and-deploy-an-app.md) - [Environment Setup](./my_first_app/chapter_1.md) diff --git a/src/hosted-nodes.md b/src/hosted-nodes.md index da481ead..0313a691 100644 --- a/src/hosted-nodes.md +++ b/src/hosted-nodes.md @@ -72,6 +72,8 @@ The local limit is a security measure, since the HTTP RPC allows injection of ar To use `kit` with a hosted node, you need to create a SSH tunnel, which maps a port on your local machine to a port on the Kinode's remote host. HTTP requests routed to that local port will then appear to the remote host as originating from its localhost. +You can use [`kit connect`](./kit/connect.md) to create and destroy a SSH tunnel, or follow the instructions below to do it yourself. + Create a SSH tunnel like so (again, replacing [assumed values with those in your `advanced details`](#accessing-your-kinodes-terminal)): ```bash ssh -L 9090:localhost:8099 kexampleuser@template.hosting.kinode.net -f -N diff --git a/src/kit-dev-toolkit.md b/src/kit-dev-toolkit.md index 8ada41c7..fb3c67e7 100644 --- a/src/kit-dev-toolkit.md +++ b/src/kit-dev-toolkit.md @@ -15,4 +15,5 @@ * [`kit dev-ui`](./kit/dev-ui.md) * [`kit inject-message`](./kit/inject-message.md) * [`kit run-tests`](./kit/run-tests.md) +* [`kit connect`](./kit/connect.md) * [`kit reset-cache`](./kit/reset-cache.md) diff --git a/src/kit/connect.md b/src/kit/connect.md new file mode 100644 index 00000000..903b9bd7 --- /dev/null +++ b/src/kit/connect.md @@ -0,0 +1,83 @@ +# `kit connect` + +`kit connect` is a thin wrapper over `ssh` to make creating SSH tunnels to remote nodes easy. + +## Example Usage + +Without any configuration, get your SSH Address from Valet, as discussed [here](../hosted-nodes.md#accessing-your-kinodes-terminal). +Then use +``` +kit connect --host +``` +and paste in the password when prompted. +You will be prompted for your password twice. +This is to first determine the port to create the SSH tunnel to, and then to create the tunnel. +You can also provide the port (Valet displays it as Local HTTP Port) and only be prompted for password once: +``` +kit connect --host --port +``` + +It is recommended to [set up your SSH configuration on your local machine and the remote host]()../hosted-nodes.md#using-ssh-keys. +Then `kit connect` usage looks like: +``` +kit connect --host +``` +where `` here is defined in your `~/.ssh/config` file. + +To disconnect a SSH tunnel, use the `--disconnect` flag and the local port bound, by default, `9090`: +``` +kit connect 9090 --disconnect +``` + +## Discussion + +See discussion of why SSH tunnels are useful for development with `kit` [here](../hosted-nodes.md#using-kit-with-your-hosted-node). +Briefly, creating a SSH tunnel allows you to use `kit` with a remote hosted node in the same way you do with a local one. +Setting up your SSH configuration will make `kit connect` work better. +You can find instructions for doing so [here](../hosted-nodes.md#using-ssh-keys). + +## Arguments + +``` +$ kit connect --help +Connect (or disconnect) a ssh tunnel to a remote server + +Usage: kit connect [OPTIONS] [LOCAL_PORT] + +Arguments: + [LOCAL_PORT] Local port to bind [default: 9090] + +Options: + -d, --disconnect If set, disconnect an existing tunnel (default: connect a new tunnel) + -o, --host Host URL/IP Kinode is running on (not required for disconnect) + -p, --port Remote (host) port Kinode is running on + -h, --help Print help +``` + +### Optional positional arg: `LOCAL_PORT` + +The local port to bind for the SSH tunnel. +This is the port to direct `kit` commands to in order to have them routed to the hosted node. + +Defaults to `9090`. + +### `--disconnect` + +short: `-d` + +If set, disconnect the tunnel with given `LOCAL_PORT`. +Else, connect a new tunnel. + +### `--host` + +short: `-o` + +Connect tunnel to this host. +Required when connecting a new tunnel; not required when disconnecting. + +### `--port` + +short: `-p` + +The remote port to tunnel to. +If not given when creating a new tunnel, `kit` will first determine the remote port by creating a short-lived SSH connection to the remote host, then use that port. From c7adaabf3dd41f8783cf69d2bf35465e0af89ed7 Mon Sep 17 00:00:00 2001 From: jurij-jukic Date: Thu, 6 Jun 2024 20:18:11 +0200 Subject: [PATCH 5/6] prioritize kit connect --- src/hosted-nodes.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/hosted-nodes.md b/src/hosted-nodes.md index 1dee3458..bb1f5f6a 100644 --- a/src/hosted-nodes.md +++ b/src/hosted-nodes.md @@ -66,13 +66,13 @@ Rather than typing in a password to create a SSH connection, you can use a keypa ## Using `kit` With Your Hosted Node `kit` interacts with a Kinode through the Kinode's HTTP RPC. -However, Kinode limits HTTP RPC access to localhost: remote requests are rejected. +However, Kinode limits HTTP RPC access to localhost — remote requests are rejected. The local limit is a security measure, since the HTTP RPC allows injection of arbitrary messages with "root" capabilities. To use `kit` with a hosted node, you need to create a SSH tunnel, which maps a port on your local machine to a port on the Kinode's remote host. HTTP requests routed to that local port will then appear to the remote host as originating from its localhost. -You can use [`kit connect`](./kit/connect.md) to create and destroy a SSH tunnel, or follow the instructions below to do it yourself. +It is recommended to use [`kit connect`](./kit/connect.md) to create and destroy a SSH tunnel. Otherwise, you can also follow the instructions below to do it yourself. Create a SSH tunnel like so (again, replacing [assumed values with those in your `advanced details`](#accessing-your-kinodes-terminal)): ```bash From f44505e500ccca9a778b4966e0283b5f5e54c4dd Mon Sep 17 00:00:00 2001 From: hosted-fornet Date: Thu, 6 Jun 2024 14:06:56 -0700 Subject: [PATCH 6/6] hosted-nodes: fix some nits --- src/hosted-nodes.md | 14 ++++---------- 1 file changed, 4 insertions(+), 10 deletions(-) diff --git a/src/hosted-nodes.md b/src/hosted-nodes.md index 66cae112..52ee1124 100644 --- a/src/hosted-nodes.md +++ b/src/hosted-nodes.md @@ -26,19 +26,12 @@ As discussed in [Managing Your Kinode](#managing-your-kinode), navigate to: 4. `Show advanced details` In the advanced details, note the `SSH Address` and `SSH Password`. -Here and below, the following SSH details will be assumed (you'll need to replace them with yours from `advanced details`): - -Field | Value ---------------- | ----- -SSH Address | kexampleuser@template.hosting.kinode.net -SSH Password | 123456789 -Local HTTP Port | 8099 To access your Kinode remote instance, open a terminal and ```bash -ssh kexampleuser@template.hosting.kinode.net +ssh ``` -where `kexampleuser@template.hosting.kinode.net` should be the `user@kinode_name.hosting.kinode.net` in your `SSH Address`. +where `` should be replaced with the one from your Valet advanced details. You will be prompted for a password: copy-paste the `SSH Password`. You should now have a different terminal prompt, indicating you have `ssh`d into the remote instance hosting your Kinode. @@ -72,7 +65,8 @@ The local limit is a security measure, since the HTTP RPC allows injection of ar To use `kit` with a hosted node, you need to create a SSH tunnel, which maps a port on your local machine to a port on the Kinode's remote host. HTTP requests routed to that local port will then appear to the remote host as originating from its localhost. -It is recommended to use [`kit connect`](./kit/connect.md) to create and destroy a SSH tunnel. Otherwise, you can also follow the instructions below to do it yourself. +It is recommended to use [`kit connect`](./kit/connect.md) to create and destroy a SSH tunnel. +Otherwise, you can also follow the instructions below to do it yourself. Create a SSH tunnel like so (again, replacing [assumed values with those in your `advanced details`](#accessing-your-kinodes-terminal)): ```bash