Introduction to Byobu: A Window Manager and Terminal Multiplexer

A complete guide on how to use byobu

Dustinkirkland, CC BY-SA 3.0 <https://creativecommons.org/licenses/by-sa/3.0>, via Wikimedia Commons

Byobu (pronounced like this) is a Japanese term for decorative, multi-panel screens that serve as folding room dividers. Byobu is also an open source software project, which is a text-based window manager and terminal multiplexer. A Terminal Multiplexer (short for tmux) manages multiple terminal sessions simultaneously.

GNU Screen is a terminal multiplexer that is used on Unix-like operating system. Tmux is another terminal multiplexer that includes most features of GNU Screen. Byobu is an enhancement for GNU Screen or tmux, used with the Linux operating system. Byobu has the following features:

It supports status notifications.
It saves the state on a remote server.
It manages the terminal windows.

Let’s install byobu and explore these features.

Intall Byobu

On macOS, byobu can be installed with brew:

% brew install byobu

The installation output recommends to set BYOBU_PREFIX in the profile:

export BYOBU_PREFIX=/usr/local

In a terminal window, type the following command, and the specific window starts a byobu session.

% byobu

Type the following command, and any newly opened terminal window starts a byobu session automatically.

% byobu-enable

The Byobu window manager will be launched automatically at each text login.

To disable this behavior later, just run:
  byobu-disable

As the output specified, the automatic byobu session can be disabled by byobu-disable.

The rest of this article does not use the automatic byobu session.

Status Notifications

Here is a normal terminal window:

As soon as byobu is on, there are some changes:

The title of the terminal window provides more information about the user and the system IP address.
The bottom of the terminal window shows a number of colorful status information.

logo — the operating system’s logo, which is an Apple logo.
arch — the system architecture, which is macOS 11.4.
windows — each open window is numbered, and the current active window is highlighted and indicated by an asterisk.
apport —the symbol displayed if there are pending crash reports, which is 23!.
uptime — the total system uptime since last boot, which is 3d20h.
load_average — the system load average over the last 1 minute, which indicates 2.56 CPU resources are used.
cpu_count — the number of CPU or cores on the system, which is 12. Since 2.56 out of 12 CPUs are used, the system is about 21% utilized.
cpu_freq — the current frequency of each CPU, which is 2.6GHz.
memory — the total memory available (16.6G) and used percentage (63%) in the system.
ip_address — the IPv4 address of the system (192.168.1.228) that can be configured to show the IPv6 address.
date — the system date, which is 2022–01–08.
time — the system time, which is 10:03:25.

3. The status information can be toggled by Shift-F5.

whoami — the name of the user who owns the screen session.

4. The status at the bottom automatically refreshes at reasonable intervals. Clicking F5 reloads profile and refreshes status.

Remote Server State Is Saved

Byobu handles ssh sessions differently from normal terminal windows. Let’s compare the differences.

Normal Terminal Window

We have a remote server that is installed with Create React App. We ssh to the server with a normal terminal window, and execute npm start. The remote desktop shows Create React App runs at localhost://3000.

We execute a command to kill -9 <ssh process id>, and the remote process exits along with the ssh session.

Byobu Terminal Window

We run the same use case using a byobu terminal window. Execute npm start, and the remote desktop shows Create React App runs at localhost://3000.

We execute a command to kill -9 <ssh process id>, and the remote desktop shows the process continue running, regardless of that the ssh session has exited.

Generally speaking, we can use byobu to connect, disconnect, reconnect, and even let other users to access it. The session continues to be alive independent of whether the byobu terminal window exists or not.

Manage Terminal Windows

Byobu is a text-based window manager and terminal multiplexer. It manages multiple windows and multiple sessions.

Clicking Shift-F1, we see the byobu usage:

We add line 45 to show how to exit the current window, session, or byobu itself.

There might be multiple ways to accomplish the same thing. For example, line 7 and line 8 show different ways to move focus among windows.

Some key combinations may not work on a specific platform, due to key binding conflicts on the platform. For example, we are not able to use Ctrl-6 to exit on macOS.

Tabs on a normal terminal window

We can create tabs on a normal terminal window. Clicking Cmd-t can generate a new tab. Tabs coexist on a terminal window, but we can only view one tab at a time.

Create a new byobu window

For a byobu terminal window, clicking F2 starts a new window, which is similar to a terminal window’s tab. Byobu windows coexist on a byobu terminal window, but we can only view one tab at a time.

By clicking F2 3 times, we have 4 byobu windows (including the original one). They are named 0, 1, 2, and 3. The last one (numbered 3) is active.

By clicking F3 or F4, we can move focus back or forth on different windows.

By clicking F8, we can rename the current window. We rename window 2 to second, and window 3 to third. Now 4 windows are named 0, 1, second, and third.

Create a new byobu session

Launch another terminal window, and turn it into a byobu terminal window (typing byobu). The new terminal window mirrors the last byobu terminal window. We type in one terminal window, and it displays on both terminal windows.

It is because the two terminal windows share the same session. What if each terminal window needs to have a separate session?

We can create a new session. The byobu menu says that Ctrl-Shift-F2 will do the trick, but it does not work on macOS.

Instead, we can use a command to achieve it. byobu new creates an unname session. byobu new -s <session-name> creates a named session.

Type byobu new -s newSession to create a second byobu terminal window. And now, two byobu terminal windows are independent.

In addition, we see a new status notification for sessions.

session — each byobu session displays a session name, or a session number if it is unnamed.

When we have more than one byobu session, typing byobu asks which session to attach to. We have 4 choices:

Attach to the existing tmux of the session, 1, which has 4 windows.
Attach to the existing tmux of the session, newSession, which has 1 window.
Create a new byobu session.
Run a shell without byobu.

These choices can also be invoked by the command, byobu-select-session.

Create split byobu windows

So far, we view one byobu window at a time, similar to a terminal window’s tabs. One of the cool features is to create multiple split byobu windows that can be viewed simultaneously.

Clicking Shift-F2 2 times, and we get 3 horizontally split byobu windows.

We can use Shift-Left/Shift-Right/Shift-Up/Shift-Down to move focus among splits. In each active window, we can perform work. It is wonderful that we can view these windows simultaneously.

It works perfect until we try to use Ctrl-F2 to create a vertical split. It does not work on macOS. Also, it is a little rough to adjust window sizes. We would like to have the mouse support for split byobu windows.

What should we do?

Creating the file, ~/.byobu/.tmux.conf, resolves all our problems.

Line 1 sets up key binding prefix to the back tick (`).

Line 2 enables mouse support.

Line 3 sets the terminal color.

Link 4 binds key `r to refresh the configuration file.

Link 5 binds key `- to create a vertical split.

Link 6 binds key `| to create a horizontal split.

With this magic configuration, we are free to create splits and use mouse to select and resize splits.

Shift-F11 zooms into a split, and the same command zooms out of a split.

What else?

Can we join split windows?

Yes, the easiest way is to exit the unwanted windows (Ctrl-d).

Conclusion

We have shown cool features of byobu, a text-based window manager, and terminal multiplexer. It helps us to keep the remote desktop session, even after the ssh session exists. Also, the window splits present a global view of multiple pieces of the current work, which is helpful in today’s microservices cloud environment.

You can go to the byobu official site to check out more details.

Thanks for reading. I hope this was helpful. If you are interested, check out my other Medium articles.

Note: Thanks, Urian Chang and Marc Mercer, for contributing byobu commands and configurations.