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.

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.

cat > $HOME/.byobu/bin/10_vms <<EOF
#!/bin/sh
echo "VMs:\$(pgrep -c kvm)"
EOF
cat $HOME/.byobu/bin/10_vms

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.

For example:

$ cat $DATA/windows.ssh_sessions
screen -t localhost bash
screen -t aussie ssh root@aussie
screen -t beagle ssh root@beagle
screen -t collie ssh root@collie
$ BYOBU_WINDOWS=ssh_sessions byobu

More Information

• Byobu's Manual

• GNU Screen's Manual

• Byobu's Webpage

• Announcements, Tips, and Tricks