From b94868fceca6499ed63941730098803a44126bc8 Mon Sep 17 00:00:00 2001 From: Oleg Solomka Date: Sat, 25 Jun 2022 00:50:24 +0000 Subject: [PATCH] [readme]: add note about automatic SSH setup for GH CLI >= 2.13.0 --- README.md | 25 ++++++++++++------------- docs/SSH_SETUP.md | 18 ++++++++++++++++++ 2 files changed, 30 insertions(+), 13 deletions(-) create mode 100644 docs/SSH_SETUP.md diff --git a/README.md b/README.md index ee561cd..a4edd72 100644 --- a/README.md +++ b/README.md @@ -1,10 +1,10 @@ ## Codespaces Network Bridge -๐Ÿงช *The extension is currently in Preview stage, so some hiccups are expected. Please help us to improve [by submitting feedback](https://github.com/github/gh-net#troubleshooting)!* +๐Ÿงช *The extension is currently in the Preview stage, so some hiccups are expected. Please help us to improve [by submitting feedback](https://github.com/github/gh-net#troubleshooting)!* image -This [GitHub CLI](https://cli.github.com/) extension allows to bridge network between a Codespace and your local machine, so the `Codespace` can reach out to any remote resource that is reachable from your machine. In another words, it uses your local machine as a network `gateway` to get to those resources. +This [GitHub CLI](https://cli.github.com/) extension allows you to bridge the network between a Codespace and your local machine, so the `Codespace` can reach out to any remote resource that is reachable from your machine. In other words, it uses your local machine as a network `gateway` to get to those resources. For instance, if you are using a `VPN` client to connect to private enterprise network to access a database or any other remote resources, this extension enables you to use those private resources from within a Codespace. @@ -12,12 +12,11 @@ For instance, if you are using a `VPN` client to connect to private enterprise n ## Prerequisites +1. This extension depends on the latest features of [GitHub CLI](https://cli.github.com/)(>= v2.8.0). Please make sure [to upgrade it](https://github.com/cli/cli#installation). -1. This extension depends on the latest features of GitHub CLI(>= v2.8.0), please make sure [to upgrade it](https://github.com/cli/cli#installation). If run the `gh codespace select` command opens the codespace selection dialog, you are good to go. +2. The extension relies on `gh codespace ssh` command to establish SSH tunnel to a Codespace. If you use [GitHub CLI >=2.13.0](https://github.com/cli/cli/releases/tag/v2.13.0) the `SSH` config is created automatically for your Codespaces, otherwise refer to [SSH setup](./docs/SSH_SETUP.md) instructions. -2. The extension relies on `gh codespace ssh` command to establish SSH tunnel to a Codespace, hence you need to setup ssh keys if you didn't before. If you can do `sudo gh codespace ssh` (`sudo` is important since kernel might use different identity under non-root user) and connect to a Codespace successfully, - you are good to go. Refer to [Generating a new SSH key and adding it to the 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) for more info. List of known issues and workarounds for them can be found [here](https://github.com/github/gh-net/issues?q=is%3Aissue+is%3Aopen+label%3Aknown-issue). - -3. If your codespace uses a non-default image, ensure that both the [GitHub CLI](https://cli.github.com/), `openssh-server` and `sudo` are installed inside the codespace. Some distros need an `ssh` group too. Please see [linux dependencies doc](./docs/LINUX_DEPENDENCIES.md) for per-distro instructions. +3. If your codespace uses a non-default image, ensure that both the [GitHub CLI](https://cli.github.com/), `openssh-server`, and `sudo` are installed inside the codespace. Some distros need an `ssh` group too. Please see [linux dependencies doc](./docs/LINUX_DEPENDENCIES.md) for per-distro instructions. ## Installation @@ -33,7 +32,7 @@ Linux: sudo gh extension install github/gh-net ``` -The `sudo` is required during extension installation on Linux due to https://github.com/cli/cli/issues/5456. Hopefully it won't be the case in the future. +The `sudo` permissions are required during extension installation on Linux due to https://github.com/cli/cli/issues/5456. Hopefully, it won't be the case in the future. ## Usage @@ -43,9 +42,10 @@ To start network forwarding from a Codespace to a local machine, run: sudo gh net start ``` -Connection issues? Please see https://github.com/github/gh-net/issues/9 for some common solutions. +Connection issues? Please see https://github.com/github/gh-net/issues/9 and [SSH setup doc](./docs/SSH_SETUP.md) for some of the known solutions. + -This will provide codespace selection dialog: +The command will first open a Codespace selection dialog: image @@ -55,12 +55,11 @@ Select a codespace and press enter. The extension will connect to selected codes There are two panels in the connected view of the extension: -- Panel on the left (`NAT`) shows the network address translation table for currently opened connections. For stateful protocols(e.g. `TCP`) the records are cleaned up automatically after connection is closed so the records will come and go as connection is established and closed. For stateless protocols (e.g. `UDP` or `ICMP`) or unsuccessful `TCP` connections the records are cleaned up after some time, so those will show up in the list for some time. -- Panel on the right (`DNS`) shows the resolved `DNS` records, as `hostname`, `record` and `time-to-live` (`TTL`) values. +- Panel on the left (`NAT`) shows the network address translation table for currently opened connections. For stateful protocols(e.g. `TCP`) the records are cleaned up automatically after a connection is closed, so the records will come and go as connections are established and teardown. For stateless protocols (e.g. `UDP` or `ICMP`) or unsuccessful `TCP` connections, the records are cleaned up after a delay; hence those may show up in the list for some time. +- Panel on the right (`DNS`) shows the resolved `DNS` records, as `hostname`, `record`, and `time-to-live` (`TTL`) values. Press `q` or `ctrl + c` to stop the extension. - ### CLI Options - `--gui`: Enable/disable GUI mode. [`true` | `false`] [default: `true`] @@ -148,7 +147,7 @@ For list of supported network protocols refer to [this doc](./docs/SUPPORTED_NET - Something is missing? Please create a [โœจ feature request](https://github.com/github/gh-net/issues/new?assignees=&labels=enhancement&template=feature_request.md&title=). - Something is incorrect? Please create a [๐Ÿ› bug report](https://github.com/github/gh-net/issues/new?assignees=&labels=bug&template=bug_report.md&title=). -- For list of known issues refer to [๐Ÿ‘‰ this list](https://github.com/github/gh-net/issues?q=is%3Aissue+is%3Aopen+label%3Aknown-issue). +- For known issues, refer to [๐Ÿ‘‰ this list](https://github.com/github/gh-net/issues?q=is%3Aissue+is%3Aopen+label%3Aknown-issue). ## Useful links diff --git a/docs/SSH_SETUP.md b/docs/SSH_SETUP.md new file mode 100644 index 0000000..dc32731 --- /dev/null +++ b/docs/SSH_SETUP.md @@ -0,0 +1,18 @@ +## Setting up SSH to connect to Codespaces + +> Note: Starting from [GitHub CLI 2.13.0](https://github.com/cli/cli/releases/tag/v2.13.0) the `SSH` config is created automatically for all your Codespaces. You can skip all instructions in this doc if you use the appropriate CLI version. We recommend upgrading; please see [Installation](https://github.com/cli/cli#installation) section of GitHub CLI for the upgrading steps. + +The extension relies on `gh codespace ssh` command to establish `SSH` tunnel to a Codespace; hence you need to set up `SSH` keys if you haven't yet. A good way to test the setap is to do `sudo gh codespace ssh` (`sudo` is vital since kernel might use a different identity under a non-root user). If you can connect to a Codespace successfully, you are all set. Refer to [Generating a new SSH key and adding it to the 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) for more info. A list of known issues and workarounds for them can be found in the [Common issues](#common-issues) section below and in issues marked with the [known-issue label](https://github.com/github/gh-net/issues?q=is%3Aissue+is%3Aopen+label%3Aknown-issue). + +Because `sudo` needs to be used to start the `gh-net` extension, the `SSH` config has to go to the default location for the `root` user, which is `/root/.ssh/` on `Linux` machines. However, the `MacOSX` machines can use `~/.ssh/` as the default location even for the `root` user, so no special config treatment is needed for the Mac machines. + + +### Common issues + +- `SSH` key has a passphrase, and it's impossible to enter it when prompted. + +Make sure to add the key to the `SSH` agent before you try to connect to a Codespace. Refer to [adding you key to 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) section for step-by-step instructions. + +- The `Enter password for user@codespace:` prompt pops up, but no password work. + +It means that the correct `SSH` key or/and config were not picked up by `SSH` agent. Please refer to the previous section's solution to resolve this.