Security on Opensource internals

tmux Sanitises Window Names Against Injection

Jay Hubbert — Fri, 02 Oct 2026 08:30:00 +0000

TL;DR: clean_name() is tmux’s one defence against name-based injection, and it works by encoding rather than filtering: it stores names in a form where the dangerous characters are unrepresentable, rather than keeping a blocklist of bad names.

Window names in tmux are not just strings. They end up in status lines, in control-mode notifications, in #{window_name} format expansions, and in hook commands that are expanded and then parsed as commands. A window name containing #{...} or a quote is a potential injection point.

The defence is a single function called clean_name(). Its history is a good illustration of how injection defence actually evolves: patch, get bypassed, patch again, get bypassed again.

The function

tmux.c:

 c
 
 
char *
clean_name(const char *name, int untrusted)
{
	char	*copy, *cp, *new_name;

	if (!utf8_isvalid(name))
		return (NULL);
	copy = xstrdup(name);
	for (cp = copy; *cp != '\0'; cp++) {
		if (untrusted && cp[0] == '#' && cp[1] == '(')
			*cp = '_';
	}
	utf8_stravis(&new_name, copy, VIS_OCTAL|VIS_CSTYLE|VIS_TAB|VIS_NL);
	free(copy);
	return (new_name);
}

Three things happen:

UTF-8 validation. An invalid sequence is rejected outright, and the caller gets NULL. This isn’t cosmetic: utf8_stravis() walks the string with the UTF-8 decoder, and a malformed string would desynchronise the walk.
#( → _( for untrusted names. The untrusted flag marks names that came from inside a pane — a program that set the terminal title via OSC 0 or OSC 2. A title is the one place where a hostile process can put arbitrary bytes into a name, so #( is defanged there.
vis(3)-style escaping. utf8_stravis() escapes everything that isn’t plainly printable.

Why `vis(3)` and not a hand-rolled check

tmux uses the BSD vis(3) family — bundled in compat/vis.c and compat/unvis.c — because “escape the dangerous characters” is a problem with a long tail, and vis has already enumerated the tail.

The important part is what happens to the characters that are not printable. vis()’s definition of visibility (compat/vis.c) is:

 c
 
 
#define	isvisible(c,flag)						\
	(((c) == '\\' || (flag & VIS_ALL) == 0) &&			\
	(((u_int)(c) <= UCHAR_MAX && isascii((u_char)(c)) &&		\
	(((c) != '*' && (c) != '?' && (c) != '[' && (c) != '#') ||	\
		(flag & VIS_GLOB) == 0) && isgraph((u_char)(c))) ||	\

The #, *, ? and [ exclusions only apply when VIS_GLOB is set. tmux doesn’t set it, so those characters are ordinary visible characters and are stored as-is. # in a window name survives as #.

What does get escaped is everything non-printable, because VIS_CSTYLE and VIS_OCTAL together make vis() fall through to its encoding branches:

 c
 
 
	if (flag & VIS_CSTYLE) {
		switch(c) {
		case '\n':
			*dst++ = '\\';
			*dst++ = 'n';
			goto done;
		case '\r':
			*dst++ = '\\';
			*dst++ = 'r';
			goto done;

so a newline in a name becomes the two characters \ and n, a tab becomes \t, a carriage return becomes \r, and any other non-printable byte becomes an octal escape such as \001. That matters for the control-mode protocol, where a raw newline in a %%window-renamed notification would forge a protocol line.

The consequence for format injection is subtler than it looks. A window name can contain #{, and it can contain #(. Neither is re-expanded when the name is substituted into a status line, because a format expansion’s result isn’t itself expanded — only the E and T modifiers re-expand. So the #{...} in a name is inert text. The #( in a name is not inert, because a format can contain a shell job, and that’s exactly what the explicit rewrite in clean_name() is for.

 c
 
 
	if (flag & VIS_CSTYLE) {
		switch(c) {
		case '\n':
			*dst++ = '\\';
			*dst++ = 'n';
			goto done;
		case '\r':
			*dst++ = '\\';
			*dst++ = 'r';
			goto done;

so a newline in a name becomes the two characters \ and n. That is important for the control-mode protocol, where a raw newline in a %%window-renamed notification would forge a protocol line.

VIS_NL is in the flag list too, and it’s worth being precise about what it does: in BSD vis, VIS_NL means “also encode newline characters” — it is an instruction to encode, not an exemption. Combined with VIS_CSTYLE the newline comes out as \n.

Where it is applied

clean_name() is called from a small, deliberate set of places:

Call site	Context
`window_set_name()` (`window.c`)	window renames, `untrusted` flag passed through
`screen.c:242`	pane title from OSC
`screen.c:256`	pane path from OSC 7
`input.c:3284`	OSC title parsing, `untrusted = 1`
`cmd-rename-session.c:63`	session rename
`cmd-new-window.c:92`, `cmd-new-session.c`	`-n` names
`names.c:169`	the shared “find next unused name” helper
`paste.c:232`, `paste.c:300`	paste buffer names
`cmd-break-pane.c:173`	broken-pane names

The untrusted distinction shows up only in the OSC title path. A name set by a command (rename-window foo) keeps its # characters, because a user typing # into a window name is not an attack. A name set by a program inside a pane has #( rewritten to _(.

Note that the stored name is the sanitised one — there’s no separate “display” form that gets un-escaped. A name that contained a newline is stored with a literal backslash-n in it and displayed that way. That keeps the invariant simple: whatever is in w->name is safe to interpolate into a status line, a control-mode notification or a format.

The history

The git log tells the story of how this went wrong, repeatedly.

d339ab51 — “Sanitize pane titles and window and session names more consistently and strictly, prevents C0 characters and other nonvisible characters causing problems. Reported (with a different fix) by Chris Monardo in GitHub issue 4999.”

Before this, some names were validated and some were not. C0 characters in a window name could produce all kinds of weirdness in the status line and in control-mode output.

64e83caf / eb653314 — “Be more strict about what names and titles we allow and reject them immediately when possible, but allow # again for those directly set by commands (but not escape sequences). From Barrett Ruth in GitHub issue 5175.”

This is the interesting one. The strict version rejected names containing #. That was too strict: users legitimately want # in window names (vim #1, ssh box#2), and the fix was to allow # where it’s harmless while keeping it defanged where it isn’t — the untrusted flag.

746dd91e — “Sanitize paste buffer names in paste_set and paste_rename, GitHub issue 5032 from Barrett Ruth.”

Paste buffer names were a separate hole. They’re format-expanded in places, and they weren’t being cleaned. Fixed by routing them through clean_name() too.

518fcf7e — “Do not sanitize title when popping it from stack, also add a limit to number of pushed titles.”

Terminals push and pop titles with OSC 9/10 and OSC 133. Popping a title restores a previously sanitised title, so sanitising again would double-escape it. The fix was to skip sanitisation on pop, and to cap the title stack so a program can’t grow it without bound.

That last one is a nice illustration of the general tension: sanitisation isn’t idempotent, and a system that both stores and restores sanitised values has to know which side of the boundary each value came from.

What is not defended

A few things to be clear about:

Session and window names aren’t restricted in length or character set beyond “valid UTF-8”. They can contain spaces, quotes, semicolons. The defence is escaping, not rejection.
The command parser’s ${VAR} splicing is a separate issue. A name is escaped; an environment variable isn’t. See How tmux Format Expansion Runs Shell Commands.
Control-mode output from commands isn’t escaped. Names are; command output isn’t. See tmux Control Mode Is an Unauthenticated Command Channel.
A name isn’t escaped for the shell. run-shell "echo #{window_name}" will expand the name and then hand the result to /bin/sh -c. The name is escaped for tmux’s format and control-mode syntaxes, not for sh.

That last one is the most common way people get burned. If a window name comes from an untrusted source and you interpolate it into a shell command, you need shell quoting. cmd_template_replace() provides %% and %1 for exactly this, and they have different escaping rules:

 c
 
 
/*
 * Replace the first %% or any %idx in template by s. %% is intended for use in
 * single quotes, so ' is escaped. %%% and %idx% are for double quotes, so a
 * list of special characters is escaped. %idx is left unescaped.
 */

%1 is deliberately not escaped, on the assumption you’ll quote it yourself. That’s the trap: %1 inside double quotes is fine, %1 inside single quotes isn’t, and %% inside single quotes escapes the quote character but isn’t safe in double quotes.

Wrapping up

clean_name() is a good example of defence that works by encoding rather than filtering. tmux doesn’t maintain a blocklist of dangerous window names. It stores names in a form where the dangerous characters are unrepresentable.

A blocklist would have to know about #{, #(, newlines, quotes, ;, backticks, $(, and every future syntax tmux adds. An encoder only has to know about the characters that aren’t printable — plus the one piece of syntax that genuinely has to be spelled out, #(, which is why that one is handled by hand in clean_name() rather than by vis.

The cost is that the stored and displayed forms are the same, which is simple, but that sanitisation isn’t idempotent. Anything that stores a sanitised value and later restores it — the terminal title stack — has to know which side of the boundary each value came from. That bug is exactly what commit 518fcf7e fixed.

tmux Control Mode Is an Unauthenticated Command Channel

Jay Hubbert — Sat, 19 Sep 2026 09:00:00 +0000

TL;DR: tmux -C gives you a scriptable protocol with zero authentication — anything that can open the socket can run run-shell. Worse, command output is written into the stream verbatim, so a program that prints a line starting with % can forge a notification in your client.

tmux -C puts tmux into control mode: instead of drawing a screen, the client speaks a line protocol and gets structured events back. It’s the mechanism behind tmux integrations in editors, status bars, scripts and CI systems.

It’s also, in its current form, an unauthenticated remote command channel with a subtle framing problem.

This article is about how control mode works, what it will let you do, and where the sharp edges are.

What control mode looks like

A control-mode client is an ordinary tmux client that happens to have CLIENT_CONTROL set instead of CLIENT_TERMINAL. The flag is set in tmux.c:

 c
 
 
	case 'C':
		if (flags & CLIENT_CONTROL)
			flags |= CLIENT_CONTROLCONTROL;
		else
			flags |= CLIENT_CONTROL;
		break;

-C is control mode. -CC is “control control”: the client puts its own terminal into a raw mode and wraps the protocol in ESC P 1000 p ... ESC \ so that a control client’s output can be embedded in a terminal without being interpreted.

The protocol itself is not a separate wire format. It’s the ordinary client/server IPC (imsg over the UNIX socket), plus a text protocol layered on top. tmux-protocol.h has no control-mode messages at all; everything goes through MSG_COMMAND.

The grammar is documented in the man page under CONTROL MODE, and the implementation is in control.c (about 1100 lines) plus control-notify.c.

Reading commands

The whole command surface is this function (control.c):

 c
 
 
/* Control client input callback. Read lines and fire commands. */
static void
control_read_callback(__unused struct bufferevent *bufev, void *data)
{
	struct client		*c = data;
	struct control_state	*cs = c->control_state;
	struct evbuffer		*buffer = cs->read_event->input;
	char			*line, *error;
	struct cmdq_state	*state;
	enum cmd_parse_status	 status;

	for (;;) {
		line = evbuffer_readln(buffer, NULL, EVBUFFER_EOL_LF);
		if (line == NULL)
			break;
		log_debug("%s: %s: %s", __func__, c->name, line);
		if (*line == '\0') { /* empty line detach */
			free(line);
			c->flags |= CLIENT_EXIT;
			break;
		}

		state = cmdq_new_state(NULL, NULL, CMDQ_STATE_CONTROL);
		status = cmd_parse_and_append(line, NULL, c, state, &error);
		if (status == CMD_PARSE_ERROR)
			cmdq_append(c, cmdq_get_callback(control_error, error));
		cmdq_free_state(state);

		free(line);
	}
}

Every line is parsed with the same parser as an interactive tmux command line and appended to the command queue. There is no allow-list of “safe” control-mode commands. run-shell, source-file, new-session, kill-server — all of it is available.

That’s the point of the design: control mode is meant to be a complete alternative interface, not a restricted one. The restriction story is the server ACL, and it’s described in How tmux Secures its UNIX Socket. Short version: if you can open the socket, you can run commands. A read-only ACL entry limits you to commands flagged CMD_READONLY and disables #() shell jobs in formats.

The reply framing

Replies are wrapped in a guard block so a client can associate output with the command that produced it:

text

%begin 1712345678 0 1
%output %3 some text
%end 1712345678 0 1

The guard lines are emitted from exactly one place, which is deliberate (control.c):

 c
 
 
/*
 * Write a %begin, %end or %error guard around a command's output. This is
 * the only place guard lines are produced, so the block depth is maintained
 * here; when the outermost block closes any deferred notifications are
 * flushed after it. "guard" is always one of the fixed strings from cmdq_guard,
 * never user text.
 */
void
control_write_guard(struct client *c, const char *guard, long t, u_int number,
 int flags)
{
	struct control_state	*cs = c->control_state;
	char			*line;

	if (cs == NULL)
		return;

	if (strcmp(guard, "begin") == 0)
		cs->guard_depth++;

	xasprintf(&line, "%%%s %ld %u %d", guard, t, number, flags);
	control_write_line(c, line);

	if (strcmp(guard, "begin") != 0 && cs->guard_depth > 0 &&
	 --cs->guard_depth == 0)
		control_flush_deferred(c);
}

Notifications (things like %window-renamed or %layout-change) are deferred while a guard block is open, so a notification can never appear in the middle of a command’s output. That was a bug fix in its own right (commit 6db5175e, issue 5458).

Where the protocol gets interesting: the raw sink

Here’s the function that writes arbitrary text into the control stream:

 c
 
 
/*
 * Write a line of command output or error text. This is a sink for arbitrary
 * user-controlled text (command output, capture-pane, error messages), so it
 * must never try to interpret the content: guard tracking is done only in
 * control_write_guard.
 */
void
control_write(struct client *c, const char *fmt, ...)
{
	struct control_state	*cs = c->control_state;
	char			*line;
	va_list			 ap;

	if (cs == NULL)
		return;

	va_start(ap, fmt);
	xvasprintf(&line, fmt, ap);
	va_end(ap);

	control_write_line(c, line);
}

The comment is the whole story. control_write() is a sink: it takes text that may have come from anywhere — a run-shell job, capture-pane, display-message, an error message that echoes back user input — and puts it on the wire verbatim.

Now look at what reaches it:

cmdq_error() in cmd-queue.c writes error text straight through.
server_client_print() writes command output.
capture-pane -p writes the pane contents.
display-message writes a %%message %s line.

Only one of these paths escapes the payload: pane output streamed with %output, which is octal-escaped (control.c):

 c
 
 
	for (i = 0; i < size; i++) {
		if (new_data[i] < ' ' || new_data[i] == '\\') {
			evbuffer_add_printf(message, "\\%03o", new_data[i]);
		} else {
			start = i;
			while (i + 1 < size &&
			 new_data[i + 1] >= ' ' &&
			 new_data[i + 1] != '\\')
				i++;
			evbuffer_add(message, new_data + start, i - start + 1);
		}
	}

So bytes from a pane are safe, but bytes from a command are not.

The consequence is that a program running in a pane, or a run-shell job, that prints a line starting with % can inject a forged notification into the client’s stream:

text

%output %1 fake pane output
%window-renamed @1 pwned

The tmux server itself will not be confused — that’s exactly what the control_write() comment is defending. But a client that parses %-prefixed lines will act on it. If your control-mode client does something security-relevant with %%window-renamed (updating a supervisor’s window list, say), then any command whose output you forward into the control stream is a potential injection point.

The practical mitigation for a client is to only trust % lines that arrive in the right structural position — inside a %begin/%end block, or in the notification section — and to treat the body of a block as opaque data.

A note on window names

Notifications interpolate names directly:

 c
 
 
		if (winlink_find_by_window_id(&cs->windows, w->id) != NULL) {
			control_notify_write(c, "%%window-renamed @%u %s",
			 w->id, w->name);

A window name cannot contain a raw newline, because names go through clean_name(), which uses utf8_stravis() with VIS_OCTAL|VIS_CSTYLE|VIS_NL. VIS_CSTYLE turns newlines into the two characters \n, and VIS_OCTAL turns # into \043 (since # is not a “visible” character to vis(3)).

So a name cannot forge a new line, but it can contain spaces and %, which a naive client might still mis-parse.

DoS protections

Control mode has accumulated a few defences against misbehaving clients, mostly added in response to issues:

 c
 
 
#define CONTROL_BUFFER_LOW 512
#define CONTROL_BUFFER_HIGH 8192
#define CONTROL_MAXIMUM_AGE 300000
#define CONTROL_MAXIMUM_REPLY_BUFFER (64 * 1024 * 1024)

CONTROL_BUFFER_HIGH is a watermark on the write buffer: a client that stops reading will be paused rather than allowed to grow the server’s memory without bound.
CONTROL_MAXIMUM_AGE (five minutes) drops clients that have not consumed their data.
CONTROL_MAXIMUM_REPLY_BUFFER (64 MB) bounds the memory used by buffered command replies — commit a3129249, issue 5565. A client that issues a command producing a huge reply gets disconnected with “too far behind” rather than being allowed to exhaust the server.

There’s also a pile of fixes around clients dying at awkward moments: “do not attempt to write to control clients which have been destroyed”, “do not let a stuck client prevent the server from exiting”, “do not make pty fds blocking again or control mode clients can get stuck”.

Using it responsibly

If you’re writing a control-mode client:

Do not trust the framing of text you did not generate. Treat the contents of a %begin/%end block as opaque bytes, not as protocol.
Do not pipe the output of an arbitrary command into a control client.
Remember there is no authentication. The socket permissions are the entire access control. If your control client listens on a socket other users can reach, it is a remote shell.
Consider server-access -r. A read-only ACL entry is the supported way to give a less-trusted integration query-only access.

Wrapping up

Control mode is a good idea that has not yet grown the security model the rest of the world expects from a network protocol. Everything is UNIX-socket-local, which is why it has survived for a decade — but the control_write() sink means it is one run-shell away from being a protocol injection target.

Here’s the thing: control mode is a decade-old protocol that has outgrown the era it was designed in. Everything that makes it safe today — UNIX-socket locality, filesystem permissions — is an accident of its deployment, not a property of its design. Treat it that way.

tmux Secures its UNIX Socket

Jay Hubbert — Tue, 04 Aug 2026 10:00:00 +0000

TL;DR: There is no password, no token, no challenge-response in tmux. If you can open the socket, you own the session — so the entire security model is socket permissions, a 0700 per-user directory, and an optional in-memory ACL keyed on the peer’s real uid/gid from getpeereid(3).

A tmux server is a daemon that owns real ptys. Any process that can talk to its UNIX socket can run commands as the user who started the server, including run-shell and source-file.

There is no password, no token, no challenge-response anywhere in the tmux source — grep -rn "passphrase" . returns nothing.

That means the entire security model of tmux is:

the permissions on the socket file,
the permissions on the directory containing it,
an optional in-memory ACL keyed on the peer’s uid and gid,
and a pile of path handling to make sure the socket ends up somewhere an attacker cannot pre-create.

This is a walk through all four, based on the OpenBSD-flavoured tmux tree at commit 6f655f48 (version 3.7b plus ~1300 commits).

The socket is the boundary

The server creates its socket in server_create_socket() (server.c):

 c
 
 
/* Create server socket. */
int
server_create_socket(uint64_t flags, char **cause)
{
	struct sockaddr_un	sa;
	size_t			size;
	mode_t			mask;
	int			fd, saved_errno;

	memset(&sa, 0, sizeof sa);
	sa.sun_family = AF_UNIX;
	size = strlcpy(sa.sun_path, socket_path, sizeof sa.sun_path);
	if (size >= sizeof sa.sun_path) {
		errno = ENAMETOOLONG;
		goto fail;
	}
	unlink(sa.sun_path);

	if ((fd = socket(AF_UNIX, SOCK_STREAM, 0)) == -1)
		goto fail;

	if (flags & CLIENT_DEFAULTSOCKET)
		mask = umask(S_IXUSR|S_IXGRP|S_IRWXO);
	else
		mask = umask(S_IXUSR|S_IRWXG|S_IRWXO);
	if (bind(fd, (struct sockaddr *)&sa, sizeof sa) == -1) {

The umask() dance is the first line of defence, and it’s deliberately different for the two kinds of socket:

Socket	Selected by	umask	Resulting mode
default	no `-S`	`0117`	`0660` — owner and group read/write
custom	`-S /path`	`0177`	`0600` — owner only

The default socket is group-writable on purpose: it lives in a private 0700 directory, but the group bits let a shared tmux work for a team without every member needing to be root or the same user. Everything else about group membership is handled by the ACL below.

Note also unlink(sa.sun_path) before bind(). The server removes whatever file is already at that path. That’s convenient — it cleans up stale sockets — but it means the socket path must be somewhere only the owner can write to. Otherwise another user could plant a file there and have it deleted, or, worse, race the server for the name.

The 0700 directory under /tmp

The default socket path is built by make_label() (tmux.c). The steps matter:

 c
 
 
	xasprintf(&base, "%s/tmux-%ld", path, (long)uid);
	free(path);
	if (mkdir(base, S_IRWXU) != 0 && errno != EEXIST) {
		xasprintf(cause, "couldn't create directory %s (%s)", base,
		 strerror(errno));
		goto fail;
	}
	if (lstat(base, &sb) != 0) {
		...
	}
	if (!S_ISDIR(sb.st_mode)) {
		xasprintf(cause, "%s is not a directory", base);
		goto fail;
	}
	if (sb.st_uid != uid || (sb.st_mode & TMUX_SOCK_PERM) != 0) {
		xasprintf(cause, "directory %s has unsafe permissions", base);
		goto fail;
	}
	xasprintf(&path, "%s/%s", base, label);

Four separate protections:

The directory is created 0700, so only the owner can list or enter it.
lstat() is used, not stat(). A symlink pointing at a directory is rejected because lstat sees the symlink, not the target. This is the classic /tmp/tmux-$UID symlink attack, closed.
The owner must be the current uid, so a directory left behind by a recycled uid is refused.
TMUX_SOCK_PERM is 007 — other rwx is forbidden. Group bits are explicitly allowed, matching the 0660 socket.

The directory list itself is validated. check_socket_path() rejects relative paths and any .. component:

 c
 
 
static int
check_socket_path(const char *path, char **cause)
{
	char	*copy, *next, *tmp;

	if (*path != '/') {
		xasprintf(cause, "socket directory %s is not an absolute path",
		 path);
		return (0);
	}
	copy = tmp = xstrdup(path);
	while ((next = strsep(&tmp, "/")) != NULL) {
		if (strcmp(next, "..") == 0) {
			xasprintf(cause, "socket directory %s contains ..",
			 path);
			free(copy);
			return (0);
		}
	}

The list comes from TMUX_SOCK, which is "$TMUX_TMPDIR:" _PATH_TMP, and each candidate is realpath()-resolved before use.

One rough edge: the `-L` label

Look again at the last line of make_label():

 c
 
	xasprintf(&path, "%s/%s", base, label);

The label isn’t validated at all. -L takes a name for the socket inside the tmux-$UID directory, and a label containing a slash or .. escapes that directory:

text

tmux -L ../victim

resolves to /tmp/tmux-1000/../victim. The socket is then created there with mode 0660 and unlink()ed by the client on startup.

This isn’t a privilege escalation by itself — you still need to be the same user — but it means the 0700 directory guarantee doesn’t hold for -L labels, and the unlink() in client_connect() will delete a file at that path. The -S option is worse in the same way: it skips the directory entirely, and only the 0600 socket mode protects it.

Gotcha: if you use -L for multiple tmux servers, treat the label as trusted input. It isn’t validated the way the socket path is.

The ACL: real peer credentials

The optional access control list is the interesting part, because it’s based on the credentials of the connecting process rather than anything the client claims. The kernel gives the server the peer’s uid and gid via getpeereid(3), and tmux reads them once, at accept time (proc.c):

 c
 
 
	imsgbuf_allow_fdpass(&peer->ibuf);
	event_set(&peer->event, fd, EV_READ, proc_event_cb, peer);

	if (getpeereid(fd, &peer->uid, &peer->gid) != 0) {
		peer->uid = (uid_t)-1;
		peer->gid = (gid_t)-1;
	}

The failure case is nicely handled: if getpeereid fails, the peer gets uid and gid of (uid_t)-1, and every ACL lookup for them fails. It fails closed.

The check itself is in server-acl.c:

 c
 
 
static struct server_acl_entry *
server_acl_check(struct client *c)
{
	struct server_acl_entry	*entry;
	uid_t			 uid;
	gid_t			 gid;

	uid = proc_get_peer_uid(c->peer);
	if (uid == (uid_t)-1)
		return (NULL);

	entry = server_acl_entry_find(uid, 0);
	if (entry != NULL)
		return (entry);

	gid = proc_get_peer_gid(c->peer);
	if (gid == (uid_t)-1)
		return (NULL);

	return (server_acl_entry_find(gid, SERVER_ACL_IS_GROUP));
}

So the policy is:

the uid entry wins if there is one; only otherwise is the gid consulted,
there’s no “other” or “anyone” entry type — only users and groups,
each entry is either read-only or read-write,
root is always allowed, and the owner is always allowed, and neither can be changed.

The default policy is set in server_acl_init():

 c
 
 
void
server_acl_init(void)
{
	RB_INIT(&server_acl_entries);

	if (getuid() != 0)
		server_acl_allow(0, 0);
	server_acl_allow(getuid(), 0);
}

Note the entries live in a plain in-memory red-black tree. There’s no ACL file. Restart the server and the list is gone. That’s a deliberate trade-off: it keeps the attacker’s ability to write to a well-known configuration file out of the picture.

The server-access command is a thin wrapper over this. It resolves names with getpwnam()/getgrnam(), refuses to change the owner or root, and treats -r/-w as implying -a:

 c
 
 
	if ((~flags & SERVER_ACL_IS_GROUP) && (id == 0 || id == getuid())) {
		cmdq_error(item, "%s owns the server, can't change access", name);
		return (CMD_RETURN_ERROR);
	}

Read-only is enforced in two places

A read-only ACL entry sets CLIENT_READONLY on the joining client (server_acl_join()). That flag is then checked twice:

in cmd-queue.c, a read-only client may only run commands whose entry has the CMD_READONLY flag:

 c
 
 
	flags = !!(state->flags & CMDQ_STATE_CONTROL);
	cmdq_guard(item, "begin", flags);
	if (flags &&
	 saved != NULL &&
	 (saved->flags & CLIENT_READONLY) &&
	 (~entry->flags & CMD_READONLY)) {
		cmdq_error(item, "client is read-only");

in format.c, shell jobs in formats are disabled outright for read-only clients:

 c
 
 
	if (c != NULL && (c->flags & CLIENT_READONLY))
		ft->flags |= FORMAT_NOJOBS;

That second one is the important one, because #(command) inside a format string is a shell execution, and a status line is a format string.

The ACL is only consulted at accept time

server_accept() is the only place the ACL gates entry:

 c
 
 
	c = server_client_create(newfd);
	if (!server_acl_join(c)) {
		c->exit_message = xstrdup("access not allowed");
		c->retval = 1;
		c->flags |= CLIENT_EXIT;
	}

Clients that are already connected are only re-evaluated when the ACL itself is changed — and even then, only for deny/allow-write/deny-write operations, not for a plain server-access -a, because server_acl_update() isn’t called from server_acl_allow(). A client that connected before you added it to the ACL keeps its access.

Also worth noting: the very first client — the one that caused the server to start — is created directly in server_client_create() and never passes through server_accept(), so it’s implicitly authorised.

The execute bit dance

There’s one more piece of socket permission logic, in server_update_socket():

 c
 
 
/* Update socket execute permissions based on whether sessions are attached. */
void
server_update_socket(void)
{
	struct session	*s;
	static int	 last = -1;
	int		 n, mode;
	struct stat sb;

	n = 0;
	RB_FOREACH(s, sessions, &sessions) {
		if (s->attached != 0) {
			n++;
			break;
		}
	}

	if (n != last) {
		last = n;

		if (stat(socket_path, &sb) != 0)
			return;
		mode = sb.st_mode & ACCESSPERMS;
		if (n != 0) {
			if (mode & S_IRUSR)
				mode |= S_IXUSR;
			if (mode & S_IRGRP)
				mode |= S_IXGRP;
			if (mode & S_IROTH)
				mode |= S_IROTH;
		} else
			mode &= ~(S_IXUSR|S_IXGRP|S_IXOTH);
		chmod(socket_path, mode);
	}
}

On a UNIX socket the “execute” bit means “may connect”. tmux adds it while a session is attached and removes it when nothing is attached, so an idle server isn’t accepting connections from a group that has access to the directory.

The stat()/chmod() pair follows symlinks, which is a small sharp edge when -S points into a world-writable directory.

What this means in practice

The threat model is simple to state and worth internalising:

Anyone who can connect() to the socket owns the session. There’s no second factor. tmux -S /tmp/x attach as an allowed user gives full command execution, including run-shell, source-file and #() format jobs.
The default socket is group-writable. Being in the right group is equivalent to being the user who started the server. Use -S with a private path if that matters, or set an explicit ACL.
The ACL is coarse. It’s uid or gid, read-only or read-write. There’s no per-command policy, and it doesn’t survive a restart.
Read-only is a genuinely useful downgrade, because it also disables shell jobs in formats — the usual way an untrusted user would try to get code execution out of a status line.

Wrapping up

The design is defensible. tmux assumes the socket directory is a trusted per-user boundary, and it defends that boundary carefully. The lstat() check, the ownership check, the .. rejection and the 0700 directory are all there specifically because /tmp is hostile.

What it doesn’t do is pretend that being able to open the socket is the same as being harmless.

Here’s the thing: the model is “the socket is the credential”. That’s fine for a single-user desktop, and it’s the reason tmux needs no password machinery at all. But the moment you share a tmux server, you’re sharing a shell, and the only knob is server-access -r.

tmux Format Expansion Runs Shell Commands: A Template Language With a Footgun

Jay Hubbert — Mon, 27 Jul 2026 11:00:00 +0000

TL;DR: tmux formats are code, and they execute where they’re expanded. #(command) runs a shell, #{VAR} splices an environment variable in verbatim, and #{E:VAR} re-expands that value as a format — which turns a plain environment variable into shell execution.

tmux formats are strings with #{...} holes in them. The status line, the pane border, display-message, the #{...} interpolation in hook commands — all of them are format strings, and the format language has grown a surprising amount of power: it can run shell commands, read environment variables, and re-expand its own output.

This is the anatomy of that language, and the places where it stops being a templating convenience and starts being a security-relevant primitive.

The pieces

The format language lives in format.c (about 7300 lines). The core syntax handled by format_expand1():

Syntax	Meaning
`#{name}`	Look up a format variable (`window_name`, `pane_pid`, …)
`#{name:modifier}`	Look up with modifiers (`:s/a/b/`, `:t`, `:p`, …)
`#(command)`	Run a shell command and use its output
`##[style]`	Look up a style
`%%`	A literal `%`

Every command that takes a format expands it before doing anything else. run-shell, if-shell, pipe-pane, display-message, send-keys, new-window, split-window, set-option for format options, and the status line itself.

The shell escape hatch

#(command) runs a command. The implementation is format_job_get():

 c
 
 
/* Find a job. */
static char *
format_job_get(struct format_expand_state *es, const char *cmd)
{
	...
	fj0.tag = ft->tag;
	fj0.cmd = cmd;
	if ((fj = RB_FIND(format_job_tree, jobs, &fj0)) == NULL) {
		fj = xcalloc(1, sizeof *fj);
		fj->client = ft->client;
		fj->tag = ft->tag;
		fj->cmd = xstrdup(cmd);

		RB_INSERT(format_job_tree, jobs, fj);
	}

	format_copy_state(&next, es, FORMAT_EXPAND_NOJOBS|
	 FORMAT_EXPAND_NOCYCLE);
	next.flags &= ~FORMAT_EXPAND_TIME;

	expanded = format_expand1(&next, cmd);
	...
	if (force || (fj->job == NULL && fj->last != t)) {
		fj->job = job_run(expanded, 0, NULL, NULL, NULL,
		 server_client_get_cwd(ft->client, NULL), format_job_update,
		 format_job_complete, NULL, fj, JOB_NOWAIT, -1, -1);

Four things worth noticing:

The command is format-expanded first (format_expand1(&next, cmd)), so a job command can itself contain #{...} substitutions.
The expansion is done with FORMAT_EXPAND_NOJOBS, so jobs don’t recurse into more jobs.
Results are cached per client in a red-black tree keyed on the command string and the format tag, and the cache is refreshed at most once per second unless FORMAT_FORCE is set. A status line with #(date) doesn’t fork a shell sixty times a second.
job_run() with JOB_NOWAIT means the job runs in the background and the previous result is returned until the new one lands. That’s why a slow command in a status line shows stale output for a second rather than blocking the redraw.

That last point is genuinely nice design. The status line stays responsive even when your format is running curl.

The environment variable fallback

This is the subtle one. If a format key is not a known format and not an option, tmux falls back to looking it up as an environment variable (format.c):

 c
 
 
	if (~modifiers & FORMAT_TIMESTRING) {
		envent = NULL;
		if (ft->s != NULL)
			envent = environ_find(ft->s->environ, key);
		if (envent == NULL)
			envent = environ_find(global_environ, key);
		if (envent != NULL && envent->value != NULL) {
			found = xstrdup(envent->value);
			goto found;
		}
	}

So #{HOME} in a format expands to the environment variable HOME. The session environment is consulted first, then the global environment.

That means an environment variable can be printed into a status line, into a control-mode notification, or into the argument of run-shell:

tmux

set -g status-right '#(echo $SECRET)'

The environment variable’s value is inserted verbatim, with no escaping. Whatever ends up in the status line ends up on the user’s screen (and, if the client is a control-mode client, on the wire).

Re-expansion: the `E` and `T` modifiers

The E modifier expands the value again as a format (format.c):

 c
 
 
done:
	/* Expand again if required. */
	if (modifiers & FORMAT_EXPAND) {
		new = format_expand1(es, value);
		free(value);
		value = new;
	} else if (modifiers & FORMAT_EXPANDTIME) {
		format_copy_state(&next, es, FORMAT_EXPAND_TIME);
		new = format_expand1(&next, value);
		free(value);
		value = new;
	}

#{E:SOMEVAR} takes the value of SOMEVAR and parses it as a format string. #{T:SOMEVAR} does the same with time formats enabled.

This is the classic escalation path. If an attacker can set an environment variable whose value contains #{...} or #(cmd), and something expands that variable with the E modifier, the value becomes live format text — and #(cmd) is live shell execution.

The E modifier isn’t enabled by default for every consumer, but it is available to anyone who can write a format string. That includes anyone who can write a tmux.conf or a hook.

`${VAR}` in the command language

Formats aren’t the only expansion mechanism. The tmux command parser also expands environment variables, and it does so by raw string splicing. From cmd-parse.y:

 c
 
 
	envent = environ_find(global_environ, name);
	if (envent != NULL && envent->value != NULL) {
		value = envent->value;
		log_debug("%s: %s -> %s", __func__, name, value);
		yylex_append(buf, len, value, strlen(value));
	}

The value is appended to the token buffer as-is. It is not re-quoted, not re-escaped and not re-scanned. So a global environment variable whose value contains a quote, a semicolon or a space changes the meaning of the command being parsed.

set-environment -g writes to the global environment, and the global environment is what the parser reads. That’s a genuine injection path from “can set a global environment variable” to “can run arbitrary tmux commands, including run-shell”.

The parser’s quoting rules are subtle and have been fixed several times. cmd_template_replace() in cmd.c documents the intended behaviour:

 c
 
 
/*
 * Replace the first %% or any %idx in template by s. %% is intended for use in
 * single quotes, so ' is escaped. %%% and %idx% are for double quotes, so a
 * list of special characters is escaped. %idx is left unescaped.
 */

with the double-quote set "\"\\$;~" and single quotes doubled. The %% behaviour was tightened in commit a177d0f5 — “Change %% to escape single quotes … to avoid a single quote being able to terminate quoted sections of commands” — because a single quote in the substituted value could otherwise close a quoted section early.

Hooks: expand, then parse

Hooks take the union of formats and commands. hooks_parse() in hooks.c:

 c
 
 
/* Parse a hook command. */
static struct cmd_parse_result *
hooks_parse(struct hooks_data *hd, struct cmd_find_state *fs,
 const char *value)
{
	struct cmd_parse_result	*pr;
	struct format_tree		*ft;
	char			*expanded;

	if (!hd->expand)
		return (cmd_parse_from_string(value, NULL));

	ft = format_create_defaults(NULL, hd->client, fs->s, fs->wl, fs->wp);
	if (hd->formats != NULL)
		format_merge(ft, hd->formats);
	expanded = format_expand(ft, value);
	format_free(ft);

	pr = cmd_parse_from_string(expanded, NULL);
	free(expanded);
	return (pr);
}

The hook command text is format-expanded and then parsed as tmux commands. For monitor-based hooks, the expansion includes the monitored value — a window name or a pane title — which is attacker-influenced text if some other user can rename a window.

hooks.c builds the format tree with FORMAT_NOJOBS, so the expansion itself won’t run a shell job. But the result is still parsed as commands, so a monitored value containing ; or a newline that survives sanitisation is a problem.

This is why the sanitisation of names matters, and it’s the subject of How tmux Sanitises Window Names Against Injection.

The read-only escape hatch

For clients that are read-only (via server-access -r), shell jobs in formats are switched off entirely:

 c
 
 
	if (c != NULL && (c->flags & CLIENT_READONLY))
		ft->flags |= FORMAT_NOJOBS;

and format_expand1() honours the flag:

 c
 
			if ((ft->flags & FORMAT_NOJOBS) ||

so #(cmd) expands to nothing at all. This is the single most important mitigation for a shared tmux server: a read-only client cannot get code execution through the status line, through display-message, or through any format-consuming command.

Summary of the attack surface

Primitive	Where it comes from	Consequence
`#(cmd)`	any format string	shell execution as the server user
`#{VAR}`	environment variable	value injected verbatim into output
`#{E:VAR}`	environment variable	value reinterpreted as format, so `#(cmd)` inside it runs
`${VAR}` in the parser	global environment	raw splice into the command being parsed
hook expansion	monitored value	user text parsed as tmux commands
`%%` / `%1` substitution	command arguments	quoting subtleties, historically exploitable

Wrapping up

The unifying theme: tmux formats are code, and they execute where they are expanded.

Every mitigation lives in the same family — decide early whether the client is trusted, and refuse to expand untrusted text into a format or a command.

Two things to internalize. First, never let untrusted text reach a format that uses E or T; that modifier turns a data value into code. Second, if you’re running a shared tmux server, server-access -r is the single switch that turns off the worst of it.

Security on Opensource internals

tmux Sanitises Window Names Against Injection

The function

Why vis(3) and not a hand-rolled check

Where it is applied

The history

What is not defended

Wrapping up

tmux Control Mode Is an Unauthenticated Command Channel

What control mode looks like

Reading commands

The reply framing

Where the protocol gets interesting: the raw sink

A note on window names

DoS protections

Using it responsibly

Wrapping up

tmux Secures its UNIX Socket

The socket is the boundary

The 0700 directory under /tmp

One rough edge: the -L label

The ACL: real peer credentials

Read-only is enforced in two places

The ACL is only consulted at accept time

The execute bit dance

What this means in practice

Wrapping up

tmux Format Expansion Runs Shell Commands: A Template Language With a Footgun

The pieces

The shell escape hatch

The environment variable fallback

Re-expansion: the E and T modifiers

${VAR} in the command language

Hooks: expand, then parse

The read-only escape hatch

Summary of the attack surface

Wrapping up

Why `vis(3)` and not a hand-rolled check

One rough edge: the `-L` label

Re-expansion: the `E` and `T` modifiers

`${VAR}` in the command language