tmux session logging lets you record the entire output of your terminal sessions to a file, which is incredibly useful for debugging, auditing, or just sharing your work.
Let’s see it in action. Imagine you’re setting up a new server and want to document every command you run.
# Start a new tmux session named 'server-setup'
tmux new-session -s server-setup
# Inside the tmux session, start logging to a file
# Press Ctrl+b then : to enter command mode, then type:
# capture-pane -S -3000 ; save-buffer /tmp/server-setup.log
# This command scrolls back 3000 lines and saves the buffer.
# For continuous logging, use:
# Ctrl+b then : then set-option logger-start-time on
# Ctrl+b then : then set-option logger-file /tmp/server-setup.log
# Ctrl+b then : then set-option logger-base-path /tmp
# Ctrl+b then : then set-option logger-strftime "%Y-%m-%d_%H-%M-%S"
# Ctrl+b then : then set-option logger-rotate on
# Ctrl+b then : then set-option logger-base-name "server-setup-log"
# Ctrl+b then : then set-option logger-max-lines 10000
# Ctrl+b then : then run-shell 'tmux attach-session -t server-setup' # Reattach to see changes if needed
Now, as you type commands and see output in your server-setup tmux session, all of it is being appended to /tmp/server-setup.log. If the file gets too large, or if you want to manage space, logger-rotate on will automatically create new log files with timestamps, like server-setup-log_2023-10-27_10-30-00.log.
The core problem tmux logging solves is the ephemeral nature of terminal output. Without logging, if you close a session or scroll too far, the history is lost. Logging makes that history persistent and searchable.
Internally, tmux operates by managing panes and windows. When you enable logging, tmux essentially captures the buffer associated with a specific pane and writes its contents to a file. The set-option commands configure how this capture happens:
logger-start-time on: This is crucial. It tells tmux to begin logging automatically when a new pane is created or when logging is enabled. Without this, you might only capture what’s already in the buffer.logger-file /tmp/server-setup.log: Specifies the initial file. Iflogger-rotateis off, all output goes here.logger-base-path /tmp: Sets the directory where rotated logs will be placed.logger-strftime "%Y-%m-%d_%H-%M-%S": This defines the timestamp format used for rotated log filenames.logger-rotate on: This is the magic for managing log size. When a log file reaches a certain threshold (or based on time, though less common), it’s closed, timestamped, and a new one is started.logger-base-name "server-setup-log": The prefix for your rotated log files.logger-max-lines 10000: Limits the number of lines in a single log file before rotation occurs, iflogger-rotateis enabled.
The capture-pane command is more of a manual snapshot. It grabs the current contents of the active pane’s buffer (including scrollback history up to the specified number of lines, -S -3000 meaning 3000 lines from the start of the buffer) and writes it to a file. This is useful for capturing a specific state rather than continuous recording.
The most surprising thing about tmux logging is how it interacts with scrollback buffers. When you enable continuous logging (logger-start-time on), tmux doesn’t just log what’s currently visible. It logs everything that ever passes through that pane’s buffer, including what scrolls off the screen. This means you can enable logging after a problem has occurred and still capture the output that led up to it, provided it hasn’t been completely overwritten by new output and the pane’s buffer is large enough.
The next concept you’ll likely explore is how to manage and search these log files efficiently, perhaps using tools like grep or less directly on the log files, or by integrating tmux logging with other monitoring systems.