From cd182120649c87142ebb78cf25e2d0ffcd879dc2 Mon Sep 17 00:00:00 2001 From: Wez Furlong Date: Sat, 22 Jun 2019 18:19:13 -0700 Subject: [PATCH] add some docs on multiplexing --- docs/index.markdown | 4 +- docs/multiplexing.markdown | 171 +++++++++++++++++++++++++++++++++++++ 2 files changed, 174 insertions(+), 1 deletion(-) create mode 100644 docs/multiplexing.markdown diff --git a/docs/index.markdown b/docs/index.markdown index b439b5a7d..7dd759239 100644 --- a/docs/index.markdown +++ b/docs/index.markdown @@ -11,11 +11,13 @@ data-icon="octicon-cloud-download" data-size="large" aria-label="Download wez/we ## Features * Runs on Linux, macOS and Windows 10 -* Multiplex terminal tabs and windows on local and remote hosts, with native mouse and scrollback +* [Multiplex terminal tabs and windows on local and remote hosts, with native mouse and scrollback](multiplexing.html) * Ligatures, Color Emoji and font fallback, with true color and dynamic color schemes. * Hyperlinks * a full list of features can be found here +Looking for a [configuration reference?](configuration.html) + ![Screenshot](screenshots/one.png) *Screenshot of wezterm on X11, running vim* diff --git a/docs/multiplexing.markdown b/docs/multiplexing.markdown new file mode 100644 index 000000000..a3971f706 --- /dev/null +++ b/docs/multiplexing.markdown @@ -0,0 +1,171 @@ +--- +title: Multiplexing +--- + +**Notice:** *multiplexing is still a young feature and is evolving rapidly. +Your feedback is welcomed!* + +## Multiplexing + +The out-of-the-box experience with `wezterm` allows you to multiplex local tabs +and windows which will persist until they are closed. With a little extra +configuration you can enable local terminal multiplexing with features similar +to those in [tmux](https://github.com/tmux/tmux/wiki) or [screen](https://en.wikipedia.org/wiki/GNU_Screen). + +Multiplexing in `wezterm` is based around the concept of *multiplexing domains*; +a domain is a distinct set of windows and tabs. When wezterm starts up it +creates a default *local domain* to manage the windows and tabs in the UI, but it +can also be configured to start or connect to any number of additional domains. + +Once connected to a domain, `wezterm` can attach its windows and tabs to the +local native UI, providing a more natural experience for interacting with +the mouse and scrollback features of the terminal. + +Key bindings allow you to spawn new tabs in the default local domain, +the domain of the current tab, or a specific numbered domain. + +## Unix Domains + +A connection to a multiplexer made via a unix socket is referred to +as a *unix domain*. Unix domains are supported on all systems, +[even Windows](https://devblogs.microsoft.com/commandline/af_unix-comes-to-windows/) +and are a way to connect the native win32 GUI into the Windows Subsystem for Linux (WSL). + +The bare minimum configuration to enable a unix domain is this, which will +spawn a server if needed and then connect the gui to it automatically +when wezterm is launched: + +```toml +[[unix_domains]] +connect_automatically = true +``` + +The possible configuration values are: + +```toml +[[unix_domains]] +# If true, connect to this unix domain when `wezterm` is started +connect_automatically = true + +# The path to the socket. If unspecified, a resonable default +# value will be computed. +# socket_path = "/some/path" + +# If true, do not attempt to start this server if we try and fail to +# connect to it. +# no_serve_automatically = false + +# If true, bypass checking for secure ownership of the +# socket_path. This is not recommended on a multi-user +# system, but is useful for example when running the +# server inside a WSL container but with the socket +# on the host NTFS volume. +# skip_permissions_check = false +``` + +### Connecting into Windows Subsystem for Linux + +Inside your WSL instance, configure `wezterm.toml` with this snippet: + +```toml +[[unix_domains]] +# Override the default path to match the default on the host win32 +# filesystem. This will allow the host to connect into the WSL +# container. +socket_path = "/mnt/c/Users/USERNAME/.local/share/wezterm/sock" +# NTFS permissions will always be "wrong", so skip that check +skip_permissions_check = true +``` + +In the host win32 configuration, use this snippet: + +```toml +[[unix_domains]] +connect_automatically = true +``` + +Now when you start wezterm you'll be presented with a WSL tab. + +## TLS Domains + +**Notice:** *TLS domains require external PKI infrastructure to authenticate +both the client and the server side with each other. wezterm doesn't +provide an easy way to manage this at this time*. + +A connection to a multiplexer made via a [TLS](https://en.wikipedia.org/wiki/Transport_Layer_Security) +encrypted TCP connection is referred to as a *TLS Domain*. Configuring +a TLS Domain is currently a bit awkward and requires mutual certificate-based +authentication of both ends of the connection. There are no instructions +on how to set up the certificates at this time, but this will be expanded +as the user experience around this feature is fleshed out. + +### Requirements + +You provide a PKI infrastructure that can generate: + + * A certificate for the host with the CN set to the hostname + * A certificate for the client with the CN set to the unixname + of the connecting user. The server MUST also be running with + the `$USER` environment variable set to that unixname. + * The CA/chain of certificates must be available to verify those + certificates on both sides of the TLS session. + * **Guard the user certificate and key carefully** as it is the sole + means of authenticating the client and will allow execution of arbitrary + commands on the server as that user. + +### Configuring the client + +For each server that you wish to connect to, add a client section like this: + +```toml +[[tls_clients]] +# The host:port for the remote host +remote_address = "server.hostname:8080" +# The client private key for your user. Guard this carefully as +# posession of this secret allows executing commands as you on +# the remote host! The subject COMMONNAME (or CN) must match +# the USER environment variable that the server side runs as +# otherwise the connection will be rejected. +pem_private_key = "/secure/wez.key" +# The public certificate that corresponds to `pem_private_key` +pem_cert = "/secure/wez.pem" + +# A CA file or bundle to help verify certificates +pem_ca = "/secure/ca.pem" +# A list of CA files or directories containing CA files that will +# also be used to verify certificates. +pem_root_certs = ["/secure/trusted-certs"] +connect_automatically = true +``` + +### Configuring the server + +```toml +[[tls_servers]] +# The host:port combination on which the server will listen +# for connections +bind_address = "server.hostname:8080" +# The server private key +pem_private_key = "/secure/server.key" +# The public certificate that corresponds to the `pem_private_key`. +# The subject COMMONNAME (or CN) must match the hostname used +# by the client to connect to the server, or the client will +# refuse to connect. +pem_cert = "/secure/server.pem" + +# A CA file or bundle to help verify certificates +pem_ca = "/secure/ca.pem" +# A list of CA files or directories containing CA files that will +# also be used to verify certificates. +pem_root_certs = ["/secure/trusted-certs"] +``` + +### Starting the server + +At this time, `wezterm` doesn't provide a convenient way to automatically +start the server, so you will need to manually log in to the server host +and start it up: + +``` +$ wezterm start --front-end MuxServer --daemonize +```