shpool

shpool

shpool is a service that enables session persistence by allowing the creation of named shell sessions owned by shpool so that the session is not lost if the connection drops. shpool can be thought of as a lighter weight alternative to tmux or GNU screen. While tmux and screen take over the whole terminal and provide window splitting and tiling features, shpool only provides persistent sessions. The biggest advantage of this approach is that shpool does not break native scrollback or copy-paste.

Platform Support

shpool runs on linux and mac. Linux is the primary supported platform and mac currently still has a few tests which don't pass. HACKING.md has more info on the state of mac support. You may want to examine the test tree to see which tests are currently disabled to see the current state of mac support.

Installation

Installing from crates.io

Using systemd to run the daemon

Run

cargo install shpool
curl -fLo "${XDG_CONFIG_HOME:-$HOME/.config}/systemd/user/shpool.service" --create-dirs https://raw.githubusercontent.com/shell-pool/shpool/master/systemd/shpool.service
sed -i "s|/usr|$HOME/.cargo|" "${XDG_CONFIG_HOME:-$HOME/.config}/systemd/user/shpool.service"
curl -fLo "${XDG_CONFIG_HOME:-$HOME/.config}/systemd/user/shpool.socket" --create-dirs https://raw.githubusercontent.com/shell-pool/shpool/master/systemd/shpool.socket
systemctl --user enable shpool
systemctl --user start shpool
loginctl enable-linger

Without systemd

To install without setting up systemd, run

cargo install shpool

If you don't use systemd, you can either port the systemd/shpool.service file to your own init system and use that, or you can use autodaemonization mode to tell shpool to just fork a daemon process on the fly if it notices one is missing. Autodaemonization is enabled by default, so you don't need to do anything special to use it, though you can control its behavior with the nodaemonize config option and the -d/-D command line switches.

Installing with Homebrew

On macOS, shpool can be installed via Homebrew:

brew install shpool

To have the daemon start automatically at login:

brew services start shpool

Usage

Generally shpool is used to provide persistent sessions when sshing in to a remote host. To do so, shpool must be installed on the remote host. No extra software is required on the client. After installing and setting up, the typical usage pattern is to ssh into the host you have installed shpool on, then create a new named session by running shpool attach main. Here main is the name of the session. You'll want a separate named session for each terminal you use to connect to your remote host. If your connection drops or becomes stuck, you can ssh back into the remote host and re-attach to the same named session by running shpool attach main again.

If your terminal gets stuck and you forcibly close the window, you might find that shpool still think a terminal is connected to your session when you attempt to reattach. This is likely because an ssh proxy is holding the connection open in the vain hope that it will get some traffic again. You can just run shpool detach main to force the session to detach and allow you to attach.

This README covers basic usage, but you can also check out the wiki for more tips and tricks.

Troubleshooting

The troubleshooting wiki page contains some information about known pitfalls.

Configuration

You can customize some of shpools behavior by editing your ~/.config/shpool/config.toml file. For an in depth discussion of configuration options see CONFIG.md.

Templates

shpool supports a template syntax for generating values based on a central list of variables. This operates much like the shell environment. In shpool templates, variable substitution used {var} syntax.

Currently templates are supported in the following places:

• session names
• the attach --dir flag
• the attach --cmd flag
• the attach --start-cmd flag

The main purpose of templates is to support switching multiple sessions at once. Whenever a variable is changed with shpool var set <var-name> <new-value>, the shpool daemon will broadcast the complete variable set to all shpool attach processes so they can recompute all their templates. If the session name has changed as a result of this re-evaluation process, the shpool attach process will automatically hang up and reconnect to the new session. This allows you to have multiple terminals open that all switch the shpool session they are attached to at once. For example, if you start with the variable setting {workspace=shpool} and then run shpool attach '{workspace}-edit' in one terminal and shpool attach '{workspace}-main', you would initially connect to the shpool-edit and shpool-main sessions. You use these sessions to work on a patch for shpool for a while, but then halfway through you have to quickly fix a bug in your company's codebase so you run shpool var set workspace yourco. shpool will automatically disconnect from shpool-edit and shpool-main and connect to yourco-edit and yourco-main. After you finish your quick fix, you run shpool var set workspace shpool and you're right back where you were when you were working on the shpool patch.

Keybindings

shpool supports keybindings (well really for the moment it supports keybinding, but in principle we could add more). For the moment, the only binding is Ctrl-Space Ctrl-q to detach from the current session. If you wish, you can configure this to use a different keybinding. The full list of supported binding actions is defined by the Action enum in keybindings.rs.

Shell Config

bash

If you use bash, you may want to ensure that the huponexit option is set to make sure that child processes exit when you leave a shell. Without this setting, background processes you have spawned over the course of your shell session will stick around in the shpool daemon's process tree and eat up memory. To set this option add

shopt -s huponexit

to your ~/.bashrc.

Subcommands

shpool version

Show the current shpool version.

shpool daemon

The daemon subcommand causes shpool to run in daemon mode. When running in this mode, shpool listens for incoming connections and opens up subshells, retaining ownership of them in a table. In general, this subcommand will not be invoked directly by users, but will instead be called from a systemd unit file.

shpool attach

The attach subcommand connects to the shpool daemon instance, passing in a name. If the name is new, a new shell is created, and if it already exists it just attaches to the existing session so long as no other terminal is currently connected to that session. The --ttl flag can be used to limit how long the session will last.

shpool list

Lists all the current shell sessions. Supports a --json flag for a more machine friendly output format.

shpool detach

Detach from a one or more sessions without stopping them. Will detach the current session if run from inside a shpool session with no session name arguments.

shpool kill

Kills a named shell session.

shpool var

Manipulate shpool variables. Variables can be used in shpool session names using {var} syntax. See the templates section above for more on how to use shpool variables.

shpool set-log-level

Dynamically change the logging level of the shpool daemon. This is a diagnostic tool to aid in debugging when the daemon gets in a bad state without having to run at a verbose logging level all the time.

(Optional) Automatically Connect to shpool

Explicitly named sessions

Specifying session names yourself lets you assign logical roles such as text editing to each session.

ssh config

If you typically connect to a small number of sessions with the same jobs on a particular machine, custom ssh config blocks on your client machine are probably the best fit.

To do this, you can define "hosts" for sessions named main and edit in a config block in ~/.ssh/config on your client machine, like so

Host = main edit
    Hostname remote.host.example.com

    RemoteCommand shpool attach -f %k
    RequestTTY yes

You can then attach to these sessions with ssh main or ssh edit. %k expands to the "host" named on the command line.

shell function

If you would rather have a little more flexibility in specifying the session name and machine you are targeting, you can make a custom shell function to let you specify both at invocation time. Add

function shpool-ssh () {
    if [ $# -ne 2 ] ; then
        echo "usage: shpool-ssh <remote-machine> <session-name>" >&2
        return 1
    fi
    ssh -t "-oRemoteCommand=shpool attach -f $2" "$1"
}

to your .bashrc then invoke it like shpool-ssh remote.host.example.com main.

Local tty based

Rather than specify an explicit name when you connect, you can set up your system to automatically generate a shpool session name based on your local terminal emulator's tty number. To do so, you can add a block of custom ssh config in the ~/.ssh/config of your local machine like

Host = by-tty
    User remoteuser
    Hostname remote.host.example.com

    RemoteCommand shpool attach -f "ssh-$(basename $(tty))"
    RequestTTY yes

which you then invoke with ssh by-tty. You can apply the same principle of using $(basename $(tty)) to get a unique id for your local terminal to the custom shell function approach as well.

The local-tty based approach has the advantage that you don't need to specify a session name, but it can run into problems if you have to close the local window and open a new terminal, which can come up if your connection freezes rather than drops.

Comparison with other tools

tmux and GNU screen

tmux is probably the best known session persistence tool, and GNU screen has a similar feature set, so in comparison to shpool it can be thought of as belonging to the same category.

The main way that shpool differs from tmux is that tmux is a terminal multiplexer which necessarily means that it offers session persistence features, while shpool only aims to be a session persistence tool. In contrast to tmux the philosophy of shpool is that managing different terminals is the job of your display or window manager, not your session persistence tool. Every operating system has its own idioms for switching between applications, and there is no reason to switch to different idioms when switching between terminals. Especially for users of tiling window managers such as i3, sway or xmonad, tmux's multiplexing features are redundant.

While tmux renders terminal contents remotely and only paints the current view to the screen, shpool just directly sends all shell output back to the user's local terminal. This means that all rendering is handled by a single terminal state machine rather than going through tmuxs internal in-memory terminal before getting formatted and re-rendered by the local terminal. This has performance implications, and probably most importantly means that a terminal using shpool will feel completely native. Scrollback and copy-paste will work exactly as they do in your native terminal, while they can behave differently when using tmux.

mosh

mosh is another tool focused on providing persistent remote shell sessions. It differs from the other tools discussed here in that it has its own network protocol, which it bootstraps off of r