tmate-ssh-server

You can run the tmate server using the official Docker image tmate/tmate-ssh-server.

Important Security Requirement: You must add the SYS_ADMIN capability to the container. This is required for the server to create nested containers (namespaces) to secure user sessions.

docker run --cap-add SYS_ADMIN tmate/tmate-ssh-server

To build the latest version of tmux from the Git repository, clone the source, run the autogen script, and then configure and make.

$ git clone https://github.com/tmux/tmux.git
$ cd tmux
$ sh autogen.sh
$ ./configure && make

To build tmux from a downloaded release tarball, ensure you have libevent 2.x installed, then run the configure and make commands.

$ ./configure && make
$ sudo make install

The tmate-ssh-server is configured using environment variables. Use these to define key locations, networking behavior, and proxy settings.

SSH_KEYS_PATH (mandatory): The path where the ssh keys are located.
HAS_WEBSOCKET: set to `1` if the tmate-websocket server exists (for HTML5 clients).
USE_PROXY_PROTOCOL: set to `1` if the ssh server is behind a load balancer that uses the proxy protocol enabled. This is useful to get client real IPs.
SSH_HOSTNAME: configures the SSH hostname to advertise to tmate hosts.
SSH_PORT_LISTEN: port on which the SSH server should listen on.
SSH_PORT_ADVERTISE: configures the SSH port to advertise to tmate hosts. Defaults to `SSH_PORT_LISTEN`.

If you need to debug tmux, you can run it with -v or -vv flags. This will generate server and client log files in your current working directory.

tmux -v
tmux -vv

The server maintains a global marked_pane state, which is used to track a specific session, windowlink, and window pane. This is typically used for command-finding or specific UI interactions.

• server_set_marked: Sets the current marked pane.
• server_clear_marked: Clears the marked pane state.
• server_is_marked: Checks if a specific session, windowlink, and pane match the currently marked pane and is still valid.
• server_check_marked: Validates if the currently marked pane is still valid.

void server_set_marked(struct session *s, struct winlink *wl, struct window_pane *wp);
void server_clear_marked(void);
int server_is_marked(struct session *s, struct winlink *wl, struct window_pane *wp);
int server_check_marked(void);

The server_start function is the primary entrypoint for starting the server process. It initializes internal data structures (windows, panes, sessions, etc.), sets up the socket, and enters the main process loop.

When compiled with the TMATE flag, the server uses a pre-existing tmux_socket_fd from the tmate_session object. Without TMATE, it creates a new Unix domain socket via server_create_socket and manages client connections through a socketpair.

/* 
 * server_start parameters:
 * @base: The libevent event base
 * @lockfd: File descriptor for a lock (if >= 0)
 * @lockfile: Path to the lockfile (if lockfd >= 0)
 */
int server_start(struct event_base *base, int lockfd, char *lockfile);

The server_send_exit function initiates a graceful shutdown of the server. It sets the exit request flag, waits for pending client commands to flush, and then iterates through all connected clients. For non-suspended clients, it sends a MSG_SHUTDOWN message to their peer. Finally, it destroys all active sessions.

void server_send_exit(void);

The server_update_socket function dynamically adjusts the file mode (permissions) of the Unix domain socket at socket_path.

If there are active (attached) sessions, it ensures the socket has execute permissions (S_IXUSR, S_IXGRP, S_IXOTH) in addition to read permissions. If no sessions are attached, it removes the execute permissions. This is used to control access to the socket based on whether sessions are currently active.

void server_update_socket(void);

The server_create_socket function creates a Unix domain socket (AF_UNIX) at the path specified by socket_path. It unlinks any existing socket at that path, binds the new socket, and sets it to listen with a backlog of 16. The socket is set to non-blocking mode.

/* Returns the socket file descriptor, or -1 on error */
int server_create_socket(void);