Byobu is a light, powerful, text-based window manager based on GNU Screen. Using Byobu, you can quickly create and move between different windows over a single SSH connection or TTY terminal, monitor dozens of important statistics about your system, detach and reattach to sessions later while your programs continue to run in the background.

Quick Start Guide

Enable/Disable

Byobu can be configured to run by default at every text login (SSH or TTY). That behavior can be toggled with the byobu-enable and byobu-disable commands.

byobu-enable

and

byobu-disable

Note that you can also ssh to a host and not launch Byobu at login any time with:

ssh -t remotehost bash

Status and Caption Lines

Byobu displays two lines at the bottom of your screen. The upper one is the Caption line, and the lower one is the Hard Status.

The Caption line shows your open windows, and highlights the one upon which you are focused, and optionally displays your user name, host name, IP address, and a hint that there is a Menu available if you press F9.

The Hard Status line consists of color coded output and symbols with configurable and dynamically updated facts, statistics, and information about the local system. See the Status Notifications section below for more information.

Some users may find the Hard Status line distracting. The byobu-quiet command will disable the display of the Hard Status. Append --undo to revert this configuration change.

Some other users may find both the Hard Status and Caption distracting. In this case, the byobu-silent command will disable both lines. Again, append --undo to revert the change.

Key Bindings

Byobu is a configuration layer on top of GNU Screen. As such, all of GNU Screen's keybindings work in Byobu exactly as in Screen.

Moreover, Byobu provides a comprehensive, advanced set of commands bound to the F-keys on most keyboards.

F2

Create a new window

F3

Move to the previous window

F4

Move to the next window

F5

Refresh all status notifications

F6

Detach from the session and logout

Shift-F6

Detach from the session, but do not logout

F7

Enter scrollback/search mode

F8

Rename the current window

F9

Launch the Byobu Configuration Menu

F12

GNU Screen's Escape Key

Alt-Pageup

Scroll back through this window's history

Alt-Pagedown

Scroll forward through this window's history

Shift-F2

Split the screen horizontally

Ctrl-F2

Split the screen vertically

Shift-F3

Move focus to the next split

Shift-F4

Move focus to the previous split

Shift-F5

Collapse all splits

Ctrl-F5

Reconnect any SSH/GPG sockets or agents

Shift-F12

Toggle all of Byobu's keybindings on or off

Advanced Features

Screen's Escape Key

Traditionally, GNU Screen's escape key sequence is ctrl-a. However, this conflicts with GNU Emacs' use of ctrl-a, which brings the cursor to the beginning of the line. GNU Screen can be configured to use a different sequence for its escape, but to do this by default confuses some traditional GNU Screen users.

Therefore, Byobu will prompt the user the first time they press ctrl-a.

Configure Byobu's ctrl-a behavior...
When you press ctrl-a in Byobu, do you want it to operate in:
(1) Emacs mode (go to beginning of line)
(2) Screen mode (screen's default escape sequence)
Note that:
- F12 also operates as Screen escape in Byobu
- You can press F9 and choose your escape character
- You can run 'byobu-ctrl-a' at any time to change your selection
Select [1 or 2]:

GNU Emacs aficionados can choose option (1), and their ctrl-a will behave in Emacs mode thereafter. These users can press F9, and then choose a different escape character, if they wish, or they can simply use Byobu's default, F12 and ctrl-^.

Users who choose option (2) can use either ctrl-a or F12 as their escape key.

Actually, we can use ctrl-a a to move to the beginning of the line.

Status Notifications

Byobu provides nearly 40 different status notifications that can be toggled on or off, and in some cases, configured. The Byobu manual contains authoritative descriptions of each and every notification.

Toggling Notifications

Each notification can be toggled from the Byobu Configuration Menu, using:

F9 -> Toggle status notifications -> (make selections) -> Apply

Alternatively, notifications can be toggled by editing the file ~/.byobu/status.

Configuring Notifications

Some notifications have configurable options, such as choosing the ethernet interface or disk to monitor, or displaying units in Celsius or Fahrenheit. These values can be set in ~/.byobu/statusrc. To see the the list of configurable variables, see the bottom of /etc/byobu/statusrc, and the Byobu manual.

Custom Status Notifications

Beyond the bundled notifications, it is quite easy to write your own custom notification to monitor anything you want on your system.

Simply create the Byobu custom binary directory:

mkdir -p $HOME/.byobu/bin

And create a script in that directory named NN_foo, where NN is the frequency in seconds that you want to run your script, and foo is some description of your status item. Make sure that the script is executable.

Color Configuration

The background color of the Caption and Status lines at the bottom of Byobu can be changed in the Configuration Menu

F9 -> Change Byobu's background color

F9 -> Change Byobu's foreground color

The variety of the colors in the status notifications can be flattened by adding MONOCHROME=1 in ~/.byobu/colors.

Window Sets

Users can create a list of windows to launch at startup in $DATA/windows. This file is the same syntax as ~/.screenrc, each line specifying a window using the "screen" command, as described in Screen's manual.

User can also launch Byobu with unique window sets. Users can store these as $DATA/windows.[NAME], and launch Byobu with the environment variable BYOBU_WINDOWS.