Byobu is a text based window manager and if you haven’t used it before you’ll probably think it’s the best thing you’ve never used. In this quick start guide I’ll show you how to install it and get started with some basic functionality. I’ll be starting with a basic Ubuntu 14.04 server installation but this should work with any recent Ubuntu version. 

To install Byobu you simply need to run the following:

sudo apt-get install byobu

Then enable and start it with:

byobu-enable

You may find at this point that your terminal becomes corrupted, if that’s the case you can type “exit” to leave byobu. If after logging out and back in it’s still corrupted you can enter “byobu-disable” to turn byobu off while you work on a solution.

Byobu Scrolling Status Bar Problem

When accessing Byobu over Putty (e.g. from Windows machine) I find that the status bar that should be fixed at the bottom of the window repeats all the way up the screen. Here are two solutions.

Solution 1

Putty assumes that the remote character set it will be receiving is ISO-8859-1 which is normally a fairly safe bet. Typically even if the remote machine is set to some other character set nothing too bad will happen especially if the remote machine is using a western character set. Ubuntu actually sends UTF-8 though and Byobu makes use of some of the additional characters to paint the screen. In order for Putty to correctly understand this is needs to be told to expect UTF-8.

Under “Window > Translation > Remote character set” select UTF-8 in the drop down, save the settings and log back in.

Solution 2

If for some reason you can’t modify your Putty settings you can avoid this problem by switching the Byobu backend from tmux to screen like this:

$ byobu-select-backend
Select the byobu backend:
  1. tmux
  2. screen
Choose 1-2 [1]: 2

While this solution works I’m not sure if there are any ramifications to it. I’d guess you would limit the display to just ISO-8859-1 characters.

Enabling the Function Keys

Note: none of these solutions make the modifier keys (shift, alt and ctrl) work with the function keys through Putty. As far as I can tell Putty is incapable of sending the correct escape sequences for modified function keys there’s seems to be a wish list entry for the functionality but Putty hasn’t seen significant development effort for a while so I’m guessing it’s never going to happen. There are ways around this issue though and getting the functions keys working is a good start.

Solution 1

Byobu is largely driven by the function keys but by default Putty doesn’t send the function keys to the terminal or at least the default behaviour isn’t useful (F9 seems to work but the others don’t). To enable the function keys under “Terminal > Keyboard > The Function keys and keypad” select “Xterm R6”. Save your settings and log back in.

Solution 2

An alternative way to enable the function keys is to tell Putty the terminal type should be “putty-256color”. To get to this setting select “Connection > Data > Terminal-type string”. I don’t know whether this is better or worse than solution 1. The default value of the terminal type is xterm.

Overview of the Byobu Screen

The basic Byobu screen shows a range of basic statistics about your machine as well as giving you an overview of the windows you have open at the moment. The screenshot below shows the basic display, I’ve opened a second window in order to show how multiple windows are displayed.

If you don’t like the status bar hand in your geek badge as you leave you can make it less in your face with the byobu-quiet and byobu-silent commands.

Basic Commands

Windows

One of the best things about Byobu is that you can have multiple windows open at the same time and switch between them quickly. This means, for example, you can have a window tailing a log file while you work on reconfiguring an application in another window. This is certainly a lot less cluttered than tying to have multiple sessions open and it means you only need to shell in once.

• F2 : Creates a new window.
• F3 : Moves to the next window.
• F4 : Moves to the previous window.
• F8 : Renames the current window. Windows start with no name.

Sessions

A feature I love about Byobu is the ability to detach a session and come back to it. Since Byobu runs as a separate application to the terminal unless you exit it will keep running to detach your current session just press F6. When you next shell back in you’ll be back where you left it.

Splitting Windows

If you are accessing Byobu though a regular Linux terminal you have all manner of nice toys to play with for splitting and organizing windows right out the box (there’s a link below to a good description of the keybindings). If you are accessing Byobu through Putty though things are no where nearly as straight forward because almost all of the nice to have features require one of the modifier keys to be pressed along with a function key and Putty can’t handle this.

All is not lost though as it’s refreshingly simple to modify the keybindings for Byobu and you can get most things working easily and in a way that is unlikely to clash with other applications. From inside a Byobu session (you’ll see why in a moment) opek the f-key binding definition file like this:

cd /usr/share/byobu/keybindings
sudo nano f-keys.tmux

Toward the top of the setting you’ll see the split-window bindings which are C-F2 and S-F2. Copy these lines and modify the copies so that the keys you want are bound (or just modify the originals if you want). I went for something like this:

bind-key -n C-F2 display-panes \; split-window -h
bind-key -n C-M-h display-panes \; split-window -h
bind-key -n S-F2 display-panes \; split-window -v
bind-key -n C-M-v display-panes \; split-window -v
bind-key -n C-S-F2 new-session
bind-key -n C-M-s new-session

This gives me:

• Ctrl-Alt-h : horizontal split
• Ctrl-Alt-v : vertical split
• Ctrl-Alt-s : creates a new session

Obviously I could go on and define more bindings but for now that is enough to get me going. If I ever define a whole files worth I’ll publish it and maybe even submit it to the maintainer. Now save your changes and hit F5, you should find your keybindings become active straight away.

Switching between splits can be achieved using F12 followed by one of the arrow keys.

Interestingly Alt+ArrowKey seems to get through Putty fine but Shift+ArrowKey and Ctrl+ArrowKey combinations don’t seem to make it through unscathed. Unfortunately those are the combinations that are used to resize split panels. My alternative keybindings are:

bind-key -n M-S-Up resize-pane -U
bind-key -n C-M-u resize-pane -U
bind-key -n M-S-Down resize-pane -D
bind-key -n C-M-d resize-pane -D
bind-key -n M-S-Left resize-pane -L
bind-key -n C-M-l resize-pane -L
bind-key -n M-S-Right resize-pane -R
bind-key -n C-M-r resize-pane -R

This gives me:

• Ctrl-Alt-u : resize a split pane up
• Ctrl-Alt-d : resize a split pane down
• Ctrl-Alt-l : resize a split pane left
• Ctrl-Alt-r : resize a split pane right

The last one that I’ll define for now is the binding that allows you to send the same command to every panel:

bind-key -n S-F9 command-prompt -p "Send command to all panes:" "run-shell \"$BYOBU_PREFIX/lib/byobu/include/tmux-send-command-to-all-panes '%%'\""
bind-key -n C-M-p command-prompt -p "Send command to all panes:" "run-shell \"$BYOBU_PREFIX/lib/byobu/include/tmux-send-command-to-all-panes '%%'\""

This gives me:

• Ctrl-Alt-p : send a command to all panels

There is also a binding for sending a command to all windows but I don’t think I’d use that – too much risk of unintended consequences for my liking. Sending a command to all panels could potentially come in very useful when updating multiple systems. For example just shell into a different machine in each panel, hit Ctrl-Alt-p and issue apt-get upgrade to have it happen on all machines.

A good overview of the default keybindings can be found here: https://github.com/dustinkirkland/byobu/blob/master/usr/share/doc/byobu/help.tmux.txt