diff --git a/src/SUMMARY.md b/src/SUMMARY.md index 9b1d427e..0a8b8da4 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) - [`boot-real-node`](./kit/boot-real-node.md) - [My First Kinode Application](./build-and-deploy-an-app.md) diff --git a/src/hosted-nodes.md b/src/hosted-nodes.md index da481ead..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. @@ -49,40 +42,50 @@ 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 `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. +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 -ssh -L 9090:localhost:8099 kexampleuser@template.hosting.kinode.net -f -N +ssh -L 9090:localhost: +``` +e.g., +``` bash +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: ``` - -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. diff --git a/src/kit-dev-toolkit.md b/src/kit-dev-toolkit.md index 8c18f7d2..7a976ba0 100644 --- a/src/kit-dev-toolkit.md +++ b/src/kit-dev-toolkit.md @@ -15,5 +15,6 @@ * [`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) * [`kit boot-real-node`](./kit/boot-real-node.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.