wez/wezterm
1
1
Fork 0
mirror of https://github.com/wez/wezterm.git synced 2024-12-23 21:32:13 +03:00
Code Issues Projects Releases Wiki Activity

docs: improve multiplexing and ssh connection information

Browse Source
This commit is contained in:
Wez Furlong 2019-11-25 00:18:05 -08:00
parent cb9fd7db5b
commit 43bc9e7eaa
2 changed files with 87 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

57
docs/multiplexing.markdown
View File

@ -24,6 +24,43 @@ the mouse, clipboard and scrollback features of the terminal.
Key bindings allow you to spawn new tabs in the default local domain, Key bindings allow you to spawn new tabs in the default local domain,
the domain of the current tab, or a specific numbered domain. the domain of the current tab, or a specific numbered domain.
## SSH Domains
*wezterm also supports [regular ad-hoc ssh connections](ssh.html).
This section of the docs refers to running a wezterm daemon on the remote end
of a multiplexing session that uses ssh as a channel*
A connection to a remote wezterm multiplexer made via an ssh connection is
referred to as an *SSH domain*. **A compatible version of wezterm must be
installed on the remote system in order to use SSH domains**.
SSH domains are supported on all systems via libssh2.
To configure an SSH domain, place something like the following in
your `wezterm.toml` file:
```
[[ssh_domains]]
# This name identifies the domain
name = "my.server"
# The address to connect to
remote_address = "192.168.1.1"
# The username to use on the remote host
username = "wez"
```
To connect to the system, run:
```
$ wezterm connect my.server
```
This will launch an SSH session that connects to the specified address
and may pop up authentication dialogs (using SSH keys for auth is
strongly recommended!). Once connected, it will attempt to spawn
the wezterm multiplexer daemon on the remote host and connect to
it via a unix domain socket using a similar mechanism to that
described in the *Unix Domains* section below.
## Unix Domains ## Unix Domains
A connection to a multiplexer made via a unix socket is referred to A connection to a multiplexer made via a unix socket is referred to
@ -37,13 +74,22 @@ when wezterm is launched:
```toml ```toml
[[unix_domains]] [[unix_domains]]
name = "unix"
connect_automatically = true connect_automatically = true
``` ```
If you prefer to connect manually, omit the `connect_automatically` setting
(or set it to `false`) and then run:
```
$ wezterm connect unix
```
The possible configuration values are: The possible configuration values are:
```toml ```toml
[[unix_domains]] [[unix_domains]]
name = "unix"
# If true, connect to this unix domain when `wezterm` is started # If true, connect to this unix domain when `wezterm` is started
connect_automatically = true connect_automatically = true
@ -69,6 +115,7 @@ Inside your WSL instance, configure `wezterm.toml` with this snippet:
```toml ```toml
[[unix_domains]] [[unix_domains]]
name = "wsl"
# Override the default path to match the default on the host win32 # Override the default path to match the default on the host win32
# filesystem. This will allow the host to connect into the WSL # filesystem. This will allow the host to connect into the WSL
# container. # container.
@ -81,12 +128,21 @@ In the host win32 configuration, use this snippet:
```toml ```toml
[[unix_domains]] [[unix_domains]]
name = "wsl"
connect_automatically = true connect_automatically = true
serve_command = ["wsl", "wezterm", "start", "--daemonize", "--front-end", "MuxServer"] serve_command = ["wsl", "wezterm", "start", "--daemonize", "--front-end", "MuxServer"]
``` ```
Now when you start wezterm you'll be presented with a WSL tab. Now when you start wezterm you'll be presented with a WSL tab.
You can also set `connect_automatically = false` and use:
```
$ wezterm connect wsl
```
to manually connect into your WSL instance.
## TLS Domains ## TLS Domains
**Notice:** *TLS domains require external PKI infrastructure to authenticate **Notice:** *TLS domains require external PKI infrastructure to authenticate
@ -120,6 +176,7 @@ For each server that you wish to connect to, add a client section like this:
```toml ```toml
[[tls_clients]] [[tls_clients]]
name = "server.name"
# The host:port for the remote host # The host:port for the remote host
remote_address = "server.hostname:8080" remote_address = "server.hostname:8080"
# The client private key for your user. Guard this carefully as # The client private key for your user. Guard this carefully as

30
docs/ssh.markdown Normal file
View File

@ -0,0 +1,30 @@
---
title: SSH Connections
---
## SSH Connections
wezterm uses libssh2 to provide an integrated SSH client. The
client can be used to make ad-hoc SSH connections to remote hosts
by invoking the client:
```
$ wezterm ssh wez@my.server
```
(checkout `wezterm ssh -h` for more options).
When invoked in this way, wezterm may prompt you for SSH authentication
and once a connection is established, open a new terminal window with
your requested command, or your shell if you didn't specify one.
Creating a new tab will create a new channel in your existing session
so you won't need to re-authenticate for additional tabs that you
create.
SSH sessions created in this way are non-persistent and all associated
tabs will die if your network connection is interrupted.
Take a look at [the multiplexing section](multiplexing.html) for an
alternative configuration that connects to a remote wezterm instance
and preserves your tabs.