Skip to content
This repository was archived by the owner on Nov 6, 2024. It is now read-only.

Commit d82286b

Browse files
authored
Add WSL to Docs (#81)
* feat: add docs for wsl connections This specifies a couple small things related to connections. It also adds the new wsh command for wsl connections. * fix: syntax error and capitalization
1 parent 58dc387 commit d82286b

File tree

2 files changed

+42
-4
lines changed

2 files changed

+42
-4
lines changed

docs/connections.mdx

Lines changed: 6 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -6,25 +6,27 @@ title: "Connections"
66

77
# Connections
88

9-
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.
9+
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 extends to SSH remote connections and local WSL connections.
1010

1111
## Access a Connection in a Block
1212

13-
The easiest way to access connections is to click the <i className="fa-sharp fa-laptop"/> 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.
13+
The easiest way to access connections is to click the <i className="fa-sharp fa-laptop"/> icon. From there, you can either type `[user]@[host]` for a desired SSH remote or type `wsl://<distribution name>` for a desired WSL distribution. 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.
1414

1515
## What are wsh Shell Extensions?
1616
`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).
1717

1818
## Add a New Connection to the Dropdown
1919

20-
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.
20+
The SSH 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.
21+
22+
WSL values are added by searching the installed WSL distributions as they appear in the Windows Registry.
2123

2224
## SSH Config Parsing
2325
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:
2426
| Keyword | Description |
2527
|---------|-------------|
2628
| 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.|
27-
| User | The user of the ssh remote connection. This will default to the current user on the local machine if not specified.|
29+
| User | The user of the SSH remote connection. This will default to the current user on the local machine if not specified.|
2830
| Port | The port to connect to the remote on. `22` is the default if not specified.|
2931
| 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.|
3032
|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.|

docs/wsh.mdx

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -88,6 +88,16 @@ This will use Wave's internal ssh implementation to connect to the specified rem
8888

8989
---
9090

91+
## wsl
92+
93+
```
94+
wsh wsl [-d <distribution name>]
95+
```
96+
97+
This will connect to a WSL distribution on the local machine. It will use the default if no distribution is provided.
98+
99+
---
100+
91101
## web
92102

93103
You can search for a given url using:
@@ -119,36 +129,62 @@ This command gives the status of all connections made since waveterm started.
119129

120130
### reinstall
121131

132+
For ssh connections,
122133
```
123134
wsh conn reinstall [user@host]
124135
```
125136

137+
For wsl connections,
138+
```
139+
wsh conn reinstall [wsl://<distribution name>]
140+
```
141+
126142
This command reinstalls the Wave Shell Extensions on the specified connection.
127143

128144
### disconnect
129145

146+
For ssh connections,
130147
```
131148
wsh conn disconnect [user@host]
132149
```
133150

151+
For wsl connections,
152+
```
153+
wsh conn disconnect [wsl://<distribution name>]
154+
```
155+
134156
This command completely disconnects the specified connection. This will apply to all blocks where the connection is being used
135157

136158
### connect
137159

160+
For ssh connections,
138161
```
139162
wsh conn connect [user@host]
140163
```
141164

165+
For wsl connections,
166+
```
167+
wsh conn connect [wsl://<distribution name>]
168+
```
169+
142170
This command connects to the specified connection but does not create a block for it.
143171

144172
### ensure
145173

174+
For ssh connections,
146175
```
147176
wsh conn ensure [user@host]
148177
```
149178

179+
For wsl connections,
180+
```
181+
wsh conn ensure [wsl://<distribution name>]
182+
```
183+
150184
This command connects to the specified connection if it isn't already connected.
151185

186+
---
187+
152188
### setconfig
153189

154190
```

0 commit comments

Comments
 (0)