diff --git a/docs/connections.mdx b/docs/connections.mdx new file mode 100644 index 0000000..fe18ea3 --- /dev/null +++ b/docs/connections.mdx @@ -0,0 +1,49 @@ +--- +sidebar_position: 7 +id: "connections" +title: "Connections" +--- + +# Connections + +Wave allows users to connect to various machines and unify them together in a way that preserves the unique behavior of each. At the moment, this only extends to ssh remote connections but we hope to expand this to other types of connections soon. + +## Access a Connection in a Block + +The easiest way to access connections is to click the icon. From there, you can type `[user]@[host]` for the desired ssh remote. Alternatively, if the connection already exists in the dropdown list, you can either click it or navigate to it with arrow keys and press enter to connect. + +## What are wsh Shell Extensions? +`wsh` is a small program that helps manage waveterm regardless of which machine you are currently connected to. In order to not interrupt the normal flow of the remote session, we install it on your remote machine at `~/.waveterm/bin/wsh`. Then, when wave connects to your connection (and only when wave connects to your connection), `~/.waveterm/bin` is added to your `PATH` for that individual session. For more info on what `wsh` is capable of, see [wsh command](/wsh). And if you wish to view the source code of `wsh`, you can find it [here](https://github.com/wavetermdev/waveterm/tree/main/cmd/wsh). + +## Add a New Connection to the Dropdown + +The values that are loaded into the dropdown by default are obtained by parsing your `~/.ssh/config` and `/etc/ssh/ssh_config` files. Adding a new connection is as simple as adding a new `Host` to one of these files, typically the `~/.ssh/config` file. + +## SSH Config Parsing +At the moment, we are capable of parsing any SSH config file that does not contain the `Match` keyword. This keyword is incompatible with a library we are using, but we are hoping to fix that soon. While all other valid keywords are parsed, we only support the functionality of a small subset of them at the moment: +| Keyword | Description | +|---------|-------------| +| Host | The pattern to match when attempting to connect via `[user]@[host]`. We list hosts that do not contain any wildcards characters (`*`, `?`, or `!`). Even if a host pattern contains wildcards, it will still be parsed when determining the values associated with the keys as usual.| +| User | The user of the ssh remote connection. This will default to the current user on the local machine if not specified.| +| Port | The port to connect to the remote on. `22` is the default if not specified.| +| IdentityFile | This can be specified more than once per host. It gives the path to a private identity file (id_rsa, id_ed25519, id_ecdsa, etc.) that is used to authenticate the connection. Each will be tried in order, and they can be encrypted with a passphrase if desired. If no value is set, the default is to try in order: ~/.ssh/id_rsa, ~/.ssh/id_ecdsa, ~/.ssh/id_ecdsa_sk, ~/.ssh/id_ed25519_sk, ~/.ssh/id_dsa.| +|BatchMode| If set to true, user interaction via password, challenge/response, and publickey passphrase authentication will be disabled. It is set to false by default.| +|PubkeyAuthentication| (partial) This is used to specify if pubkey authentication should be attempted. It is partially implementented as the `unbound` and `host-bound` values simply work the same as the `yes` value. The default is `yes`.| +|PasswordAuthentication| This is used to specify if password authentication should be attempted. The default is `yes`.| +|KbdInteractiveAuthentication| This is used to specify if keyboard-interactive authentication should be attempted. The default is `yes`.| +|PreferredAuthentications| (partial) Specifies the order the client should attempt to authenticate in. It is partially implemented as it does not support `gssapi-with-mic` or `hostbased` authentication. The default is `publickey,keyboard-interactive,password`| +|AddKeysToAgent| (partial) This option will automatically add keys and their corresponding passphrase to your running ssh agent if it is enabled. It is partially supported as it can only accept `yes` and `no` as valid inputs. Other inputs such as `confirm` or a time interval will behave the same as `no`. The default value is `no`. + +### Example SSH Config Host +For a quick example, a host in your config file may look like: +``` +Host myhost + User username + HostName 203.0.113.254 + IdentityFile ~/.ssh/id_rsa + AddKeysToAgent yes +``` +You would then be able to access this connection with `myhost` or `username@myhost`. And if you wanted to manually specify a port such as port 2222, you could do that by either adding `Port 2222` to the config file or connecting to `username@myhost:2222`. + +## Managing Connections with the CLI +The `wsh` command gives some commands specifically for interacting with the connections. You can view these [here](/wsh#conn). \ No newline at end of file diff --git a/docs/faq.mdx b/docs/faq.mdx index da58b9f..64b2aa6 100644 --- a/docs/faq.mdx +++ b/docs/faq.mdx @@ -1,5 +1,5 @@ --- -sidebar_position: 7 +sidebar_position: 8 id: "faq" title: "FAQ" --- diff --git a/docs/index.mdx b/docs/index.mdx index 614adee..9af8e4c 100644 --- a/docs/index.mdx +++ b/docs/index.mdx @@ -2,11 +2,13 @@ sidebar_position: 1 id: "index" title: "Home" +hide_title: true +hide_table_of_contents: true --- import {Card, CardGroup} from '@site/src/components/card.tsx'; -## Welcome to Wave Terminal +# Welcome to Wave Terminal Wave is an [open-source](https://github.com/wavetermdev/waveterm) terminal that adds the ability to launch graphical widgets, controlled and integrated directly with the CLI. We support MacOS, Linux, and Windows ([Downloads](https://waveterm.dev/download)). @@ -19,6 +21,7 @@ References: * [Configuration](./config) * [Key Bindings](./keybindings) * [wsh command](./wsh) +* [Connections](./connections) * [Telemetry](./telemetry) * [FAQ](./faq) diff --git a/docs/releasenotes.mdx b/docs/releasenotes.mdx index 46099dc..e1f2ec0 100644 --- a/docs/releasenotes.mdx +++ b/docs/releasenotes.mdx @@ -1,7 +1,7 @@ --- id: "releasenotes" title: "Release Notes" -sidebar_position: 8 +sidebar_position: 9 --- # Release Notes diff --git a/src/css/custom.css b/src/css/custom.css index fd4214e..12702da 100644 --- a/src/css/custom.css +++ b/src/css/custom.css @@ -20,6 +20,18 @@ --ifm-color-primary-lightest: #8cd47d; } +.docs-doc-id-index article nav { + display: none; +} + +body .markdown h1:first-child { + --ifm-h1-font-size: 2rem; +} + +body .markdown h2 { + --ifm-h2-font-size: 1.75rem; +} + /* Adds extra margin between last navbar item and the dark mode toggle. */ .navbar__items--right .navbar__item:last-of-type { margin-right: 4px;