Tmux Deployment & Usage Guide

A terminal multiplexer that enables multiple terminal sessions to be accessed and controlled from a single screen.

1. Prerequisites

Build Requirements

C Compiler: GCC or Clang with C99 support
Autotools: autoconf (≥2.69), automake, pkg-config
Lex/Yacc: bison or byacc (for command parsing)
Libraries:
- libevent 2.0+ (development headers)
- ncurses 5.7+ or ncursesw (wide character support)
- utempter (optional, for utmp/wtmp management)

Platform-Specific Dependencies

Debian/Ubuntu:

sudo apt-get install build-essential autoconf automake pkg-config \
    libevent-dev ncurses-dev bison

RHEL/CentOS/Fedora:

sudo dnf install gcc make autoconf automake pkgconfig \
    libevent-devel ncurses-devel bison

macOS:

brew install autoconf automake pkg-config libevent ncurses bison
export PATH="$(brew --prefix bison)/bin:$PATH"

2. Installation

From Source (Latest Development)

# Clone repository
git clone https://github.com/tmux/tmux.git
cd tmux

# Generate configure script (required for git builds)
sh autogen.sh

# Configure build
./configure --prefix=/usr/local

# Compile
make

# Install system-wide
sudo make install

From Release Tarball

wget https://github.com/tmux/tmux/releases/download/3.3a/tmux-3.3a.tar.gz
tar -zxf tmux-3.3a.tar.gz
cd tmux-3.3a
./configure && make && sudo make install

Verification

tmux -V
# Output: tmux 3.4 (or version installed)

3. Configuration

Configuration File

Tmux reads configuration from ~/.tmux.conf (or ~/.config/tmux/tmux.conf if XDG directories are used).

Create basic configuration:

cat > ~/.tmux.conf << 'EOF'
# Change prefix from Ctrl-b to Ctrl-a
unbind C-b
set -g prefix C-a
bind C-a send-prefix

# Enable mouse support
set -g mouse on

# Set terminal colors
set -g default-terminal "screen-256color"

# Status bar customization
set -g status-bg colour235
set -g status-fg white

# Vim-style pane navigation
bind h select-pane -L
bind j select-pane -D
bind k select-pane -U
bind l select-pane -R
EOF

Environment Variables

Variable	Description
`TMUX`	Socket path (set automatically inside tmux)
`TMUX_TMPDIR`	Directory for tmux sockets (default: `/tmp`)
`TERM`	Terminal type for new windows
`SHELL`	Default shell for new windows

Systemd/SSH socket directory fix:

# If /tmp is namespaced (systemd), set persistent directory
export TMUX_TMPDIR=~/.tmux_tmp
mkdir -p ~/.tmux_tmp

4. Build & Run

Development Build (Debug Symbols)

./configure CFLAGS="-g -O0" --prefix=$HOME/tmux-dev
make
make install

# Run without installing
./tmux

Static Build (Portable Binary)

./configure --enable-static \
    LDFLAGS="-static" \
    LIBEVENT_CFLAGS="-I/usr/local/include" \
    LIBEVENT_LIBS="-L/usr/local/lib -levent"
make

Basic Usage

Start new session:

tmux new-session -s mysession
# Or: tmux new -s mysession

Detach from session:

Press Ctrl-b then d

List sessions:

tmux ls

Attach to existing session:

tmux attach -t mysession
# Or: tmux a -t mysession

Kill session:

tmux kill-session -t mysession

Key Bindings (Default Prefix: `Ctrl-b`)

Key	Action
`c`	Create new window
`n`	Next window
`p`	Previous window
`0-9`	Select window by number
`%`	Split pane horizontally
`"`	Split pane vertically
`o`	Switch to next pane
`?`	Show key bindings
`:`	Command prompt

5. Deployment

Distribution Packaging

Since tmux is a client-side terminal application, "deployment" typically means system-wide installation or distribution packaging.

Create Debian Package:

sudo apt-get install checkinstall
./configure
make
sudo checkinstall --pkgname=tmux --pkgversion="3.4-git"

Create RPM Package:

./configure
make dist
rpmbuild -tb tmux-3.4.tar.gz

Server Environment Deployment

For multi-user server environments:

Install globally:
```
sudo make install
```

Set system-wide configuration (/etc/tmux.conf):

# Restrict permissions
set -g lock-command "vlock"
set -g lock-after-time 300

Socket Management (for shared sessions):

# Create shared socket directory
sudo mkdir -p /var/tmux
sudo chmod 1777 /var/tmux

# Start shared session
tmux -S /var/tmux/shared new -s shared

# Users attach with
tmux -S /var/tmux/shared attach

Container/Docker Usage

FROM alpine:latest
RUN apk add --no-cache tmux
ENTRYPOINT ["tmux"]

docker run -it --rm tmux-image

6. Troubleshooting

Build Issues

Error: libevent not found

# Install libevent development headers
sudo apt-get install libevent-dev  # Debian/Ubuntu
sudo dnf install libevent-devel    # RHEL/Fedora

# If installed in non-standard location:
./configure CFLAGS="-I/usr/local/include" LDFLAGS="-L/usr/local/lib"

Error: ncurses not found or ncursesw not found

# Install wide-character ncurses
sudo apt-get install libncursesw5-dev
# Or force narrow ncurses:
./configure --with-ncurses

Error: aclocal-1.16: command not found

# Regenerate build scripts for your automake version
autoreconf -fi

Runtime Issues

Sessions disappear after logout

Cause: Systemd or TMPFS cleaning /tmp
Solution: Set TMUX_TMPDIR to persistent directory (see Configuration section)

Colors not working correctly

# In ~/.tmux.conf
set -g default-terminal "tmux-256color"
# Or fallback to screen-256color if terminfo missing

High CPU usage

Check for rapid status interval: set -g status-interval 5 (seconds)
Disable aggressive resize if causing loops: set -g aggressive-resize off

Permission denied on socket

# Fix socket permissions
chmod 700 ~/.tmux_tmp
# Or remove stale sockets
rm -rf /tmp/tmux-*

Unicode/UTF-8 characters display incorrectly

# Ensure locale is set
export LANG=en_US.UTF-8
# Use ncursesw (wide character support) during build
./configure --enable-utf8proc  # Optional: use utf8proc library

How to Deploy & Use tmux/tmux