1byobu(1) byobu byobu(1)
2
6 byobu - wrapper script for seeding a user's byobu configuration and
7 launching a text based window manager (either screen or tmux)
8
11 byobu [options]
12 byobu-screen [screen options]
14 byobu-tmux [tmux options]
16 Options to byobu are simply passed through screen(1) or tmux(1).
18
21 byobu is a script that launches a text based window manager (either
22 screen(1) or tmux(1)) in the byobu configuration. This enables the
23 display of system information and status notifications within two lines
24 at the bottom of the screen session. It also enables multiple tabbed
25 terminal sessions, accessible through simple keystrokes.
26 byobu currently defaults to using tmux(1) (if present) as the backend,
28 however, this can be overridden with the byobu-select-backend(1) util‐
29 ity.
30 Note that BYOBU_CONFIG_DIR=$XDG_CONFIG_HOME/byobu if defined, and
32 $HOME/.byobu otherwise.
33
36 The background colors of the byobu status lines can be adjusted by
37 editing the files $HOME/.byobu/color (for byobu-screen) and
38 $HOME/.byobu/color.tmux (for byobu-tmux). The command Ctrl-Shift-F5
39 will change the background to a randomly selected color when running in
40 byobu-tmux mode. Simply remove those files to return to the default
41 color configuration.
42
45 byobu supports a number of unique and interesting status notifications
46 across the lowest two lines in the screen. Each status notification
47 item is independently configurable, enabled and disabled by the config‐
48 uration utility. The guide below helps identify each status item (in
49 alphabetical order):
50 apport - symbol displayed if there are pending crash reports; {!} sym‐
52 bol displayed on the lower bar toward the left, in black on an orange
53 background
54 arch - system architecture; displayed on the lower bar toward the left,
56 in the default text color on the default background color
57 battery - battery information; display on the lower bar toward the
59 right; - indicates discharging, + indicates charging, = indicates fully
60 charged; when charging or discharging, the current battery capacity as
61 a percentage is displayed; the colours green, yellow, and red are used
62 to give further indication of the battery's charge state; you may over‐
63 ride the detected battery by setting BATTERY=/proc/acpi/battery/BAT0 in
64 $BYOBU_CONFIG_DIR/statusrc
65 cpu_count - the number of cpu's or cores on the system; displayed in
67 the lower bar toward the right in the default text color on the default
68 background, followed by a trailing 'x'
69 cpu_freq - the current frequency of the cpu in GHz; displayed in the
71 lower bar toward the right in white text on a light blue background
72 cpu_temp - the cpu temperature in Celsius (default) or Fahrenheit, con‐
74 figure TEMP=F or TEMP=C in $BYOBU_CONFIG_DIR/statusrc; displayed in the
75 lower bar toward the right in yellow text on a black background; you
76 may override the detected cpu temperature device by setting MONI‐
77 TORED_TEMP=/proc/acpi/whatever in $BYOBU_CONFIG_DIR/statusrc
78 custom - user defined custom scripts; must be executable programs of
80 any kind in $BYOBU_CONFIG_DIR/bin; must be named N_NAME, where N is the
81 frequency in seconds to refresh the status indicator, and NAME is the
82 name of the script; N should not be less than 5 seconds; the script
83 should echo a small amount of text to standard out, standard error is
84 discarded; the indicator will be displayed in the lower panel, in
85 default colors, unless you manually specify the colors in your script's
86 output; BEWARE, cpu-intensive custom scripts may impact your overall
87 system performance and could upset your system administrator! In fact,
88 you can easily copy and modify any status script usually found in
89 /usr/lib/byobu/* to your local $HOME/.byobu/ directory.
90 Example: $BYOBU_CONFIG_DIR/bin/1000_uname
91 #!/bin/sh
92 printf "\005{= bw}%s\005{-}" "$(uname -r)"
93 date - the system date in YYYY-MM-DD format, or you can set this to any
96 valid strftime(3) you like in $BYOBU_CONFIG_DIR/datetime; displayed in
97 the lower on the far right in the default text color on the default
98 background
99 disk - total disk space available and total used on / directory; dis‐
101 played in the lower bar on the far right in white text on a light pur‐
102 ple background; override the default directory by specifying an alter‐
103 nate mount point with MONITORED_DISK=/wherever in $BYOBU_CON‐
104 FIG_DIR/statusrc
105 disk_io - instantaneous read/write througput in kB/s or MB/s over the
107 last 3 seconds; displayed in the lower bar toward the right in white
108 text on a light purple background with a leading '<' sign indicating
109 'read speed' and '>' sign indicating 'write speed'; override the
110 default monitored disk by specifying an alternate device with MONI‐
111 TORED_DISK=/dev/sdb, and override the default DISK_IO_THRESHOLD=50
112 (kB/s) in $BYOBU_CONFIG_DIR/statusrc
113 distro - OS/distribution name of the release running on the current
115 system as reported by lsb_release(1) or /etc/issue; displayed in the
116 lower bar in bold black text toward the left on a grey background; you
117 may override the detected release with DISTRO=Whatever in $BYOBU_CON‐
118 FIG_DIR/statusrc
119 entropy - a count of the system's current entropy in bytes; displayed
121 in the lower bar toward the right in yellow text on a dark grey back‐
122 ground; there is a leading 'e' to indicate 'entropy'
123 raid - note very prominently if there is a RAID failure detected, in
125 red blinking text on a white background; the term 'RAID' notes that
126 there is something wrong with the RAID, and if there is a
127 rebuild/resync in progress, the percent complete is also shown
128 fan_speed - cpu or system fan speed as reported by lm-sensors; dis‐
130 played in the lower bar toward the right in black text on a grey back‐
131 ground; there is a trailing 'rpm' for units; you may override the
132 detected fan by setting FAN=/sys/path/to/your/fan1_input in $BYOBU_CON‐
133 FIG_DIR/statusrc
134 hostname - the hostname of the system; displayed in the upper bar on
136 the far right in bold black text on a grey background; there is a lead‐
137 ing '@' symbol if the username status is also enabled
138 ip_address - the IPv4 address of the system in dotted decimal form;
140 displayed in the upper bar on the far right in bold black text on a
141 grey background; you can override and display your IPv6 address by
142 setting 'IPV6=1', and you can show your external ip address by setting
143 'IP_EXTERNAL=1' in $BYOBU_CONFIG_DIR/statusrc
144 ip_address4 - the IPv4 address of the system in dotted decimal form;
146 displayed in the upper bar on the far right in bold black text on a
147 grey background; you can show your external ip address by setting
148 'IP_EXTERNAL=1' in $BYOBU_CONFIG_DIR/statusrc
149 ip_address6 - the IPv6 address of the system; displayed in the upper
151 bar on the far right in bold black text on a grey background; you can
152 show your external ip address by setting 'IP_EXTERNAL=1' in $BYOBU_CON‐
153 FIG_DIR/statusrc
154 load_average - the system load average over the last 1 minute; dis‐
156 played in the lower bar toward the right in black text on a yellow
157 background
158 logo - an approximation of the current operating system's logo; dis‐
160 played in the lower bar on the far left; you may customize this logo by
161 setting a chosen logo with LOGO=:-D in $BYOBU_CONFIG_DIR/statusrc
162 mail - system mail for the current user; the letter '[M]' is displayed
164 in the lower bar toward the left in black text on a grey background
165 memory - total memory available and used percentage in the system; dis‐
167 played in the lower bar toward the right in white text on a green back‐
168 ground
169 menu - a simple indicator directing new users to use the F9 keybinding
171 to access the byobu menu
172 network - instantaneous upload/download bandwidth in [GMk]bps over the
174 last 3 seconds; nothing is displayed if traffic is 0; displayed in the
175 lower bar toward the left in white text on a purple background with a
176 leading '^' sign indicating 'up' and 'v' sign indicating 'down'; over‐
177 ride the default interface by specifying an alternate interface with
178 MONITORED_NETWORK=eth1, and override the default units (bits) with NET‐
179 WORK_UNITS=bytes, and override the default NETWORK_THRESHOLD=20 (kbps)
180 in $BYOBU_CONFIG_DIR/statusrc
181 notify_osd - Send on-screen notification messages to screen's notifica‐
183 tion buffer
184 processes - total number of processes running on the system; displayed
186 in the lower bar in white text on a dark yellow background with a
187 trailing '&' indicating 'background processes'
188 reboot_required - symbol present if a reboot is required following a
190 system update; displayed in the lower bar white text on a blue back‐
191 ground by the symbol '(R)'; additionally, reboot_required will print
192 '<F5>' in white text on a blue background, if Byobu requires you to
193 reload your profile to affect some changes; it will also detect if your
194 system is currently in powernap(8) state and if so print '.zZ'; if your
195 system is currently performing an unattended-upgrade(1) you will see a
196 white warning sign on a red background.
197 release - OS/distribution name of the release running on the current
199 system as reported by lsb_release(1) or /etc/issue; displayed in the
200 lower bar in bold black text toward the left on a grey background; you
201 may override the detected release with RELEASE=Whatever in $BYOBU_CON‐
202 FIG_DIR/statusrc; you may also abbreviate the release string to N char‐
203 acters by setting RELEASE_ABBREVIATED=N in $BYOBU_CONFIG_DIR/statusrc
204 services - users can configure a list of services to monitor, define
206 the SERVICES variable in $BYOBU_CONFIG_DIR/statusrc, a whitespace sepa‐
207 rated of services, each service should include the init name of the
208 service, then a pipe, and then an abbreviated name or symbol to display
209 when running (e.g. SERVICES="ssh|ssh apache2|http"); displayed in the
210 lower bar toward the center in cyan on a white background
211 session - byobu session name (only supported in byobu-tmux(1)); dis‐
213 played in the lower bar on the left in underlined black text on a white
214 background
215 swap - total swap space and total used as a percentage of the total
217 available; displayed in the lower bar toward the right in black text on
218 a light green background with a trailing '%' sign
219 time - the system time in HH:MM:SS format (by default), or you can set
221 this to any valid strftime(3) you like in $BYOBU_CONFIG_DIR/datetime;
222 displayed in the lower bar on the far right in the default text and
223 default background colors
224 time_binary - only for the hard core geek, the local system time in
226 binary; requires UTF-8 support in a VERY recent version of GNU Screen;
227 displayed in the lower bar on the far right in the default text and
228 background colors
229 time_utc - the UTC system time in HH:MM format; displayed in the lower
231 bar on the far right in dark text on a light background
232 updates_available - the number of updates available on the system; dis‐
234 played in the lower bar toward the right in white text on a red back‐
235 ground with a trailing '!' sign; if any updates are marked 'security
236 updates', then there will be a total of two trailing exclamation
237 points, '!!'
238 uptime - the total system uptime since last boot; displayed in the
240 lower bar toward the right in blue text on a grey background
241 users - the number of remote users logged into the system via sshd,
243 empty if 0 users; displayed in the lower bar toward the right in red
244 text on a grey background with a trailing '#' sign; set USERS_DIS‐
245 TINCT=1 to instead count the number of distinct users logged into the
246 system (rather than open ssh sessions)
247 whoami - the name of the user who owns the screen session; displayed in
249 the upper bar toward the far right in bold black text on a grey back‐
250 ground
251 wifi_quality - the connection rate and signal quality of the wifi con‐
253 nection; displayed in the lower bar toward the right in black text on a
254 cyan background; the connection rate is in 'Mb/s' and the signal qual‐
255 ity is as a percentage with a trailing '%'; override the default inter‐
256 face by specifying an alternate interface with MONITORED_NETWORK=wlan0
257 in $BYOBU_CONFIG_DIR/statusrc
258
261 Byobu name screen sessions "byobu", if unspecified. To hide sessions
262 from byobu-select-session(1), prepend a "." to the beginning of the
263 session name, like:
264 byobu -S .hidden
266
269 Each open window in the screen session is displayed in the upper bar
270 toward the far left. These are numbered, and include indicators as to
271 activity in the window (see "activity" in screen(1) and tmux(1) for
272 symbol definitions). The current active window is highlighted by
273 inverting the background/text from the rest of the window bar.
274 Users can create a list of windows to launch at startup in $BYOBU_CON‐
276 FIG_DIR/windows and $BYOBU_CONFIG_DIR/windows.tmux. This file is the
277 same syntax as ~/.screenrc and ~/.tmuxrc, each line specifying a win‐
278 dow, as described in screen(1) or tmux(1).
279 User can also launch Byobu with unique window sets. Users can store
281 these as $BYOBU_CONFIG_DIR/windows.[NAME] and $BYOBU_CONFIG_DIR/win‐
282 dows.tmux.[NAME], and launch Byobu with the environment variable
283 BYOBU_WINDOWS=NAME.
284 For example:
286 $ cat $BYOBU_CONFIG_DIR/windows.ssh_sessions
287 screen -t localhost bash
288 screen -t aussie ssh root@aussie
289 screen -t beagle ssh root@beagle
290 screen -t collie ssh root@collie
291 Then:
293 $ BYOBU_WINDOWS=ssh_sessions byobu
294 For example:
296 $ cat $BYOBU_CONFIG_DIR/windows.tmux.split4
297 new-session 'bash' ;
298 new-window -n term1 ;
299 new-window -n term2 ;
300 new-window -n ssh ssh 10.9.8.7 ;
301 split-window ;
302 split-window ;
303 split-window ;
304 select-layout tiled ;
305 select-pane -t 0
306 Then:
308 $ BYOBU_WINDOWS=split4 byobu
309
312 byobu uses binary for capacity measurements of KB, MB, GB, and TB.
313 This means multiples of 1024 rather than multiples of 1000, in accor‐
314 dance with JEDEC Standard 100B.01 for memory capacity measurements.
315 See:
316 * http://en.wikipedia.org/wiki/JEDEC_memory_standards
317 byobu uses decimal for measurements of network data transfer, meaning
319 multiple of 1000, rather than 1024. See:
320 * http://en.wikipedia.org/wiki/Data_rate_units
321
324 byobu keybindings can be user defined in /usr/share/byobu/keybindings/
325 (or within .screenrc if byobu-export was used). The common key bindings
326 are:
327 F2 - Create a new window
329 F3 - Move to previous window
331 F4 - Move to next window
333 F5 - Reload profile
335 F6 - Detach from this session
337 F7 - Enter copy/scrollback mode
339 F8 - Re-title a window
341 F9 - Configuration Menu
343 F12 - Lock this terminal
345 shift-F2 - Split the screen horizontally
347 ctrl-F2 - Split the screen vertically
349 shift-F3 - Shift the focus to the previous split region
351 shift-F4 - Shift the focus to the next split region
353 shift-F5 - Join all splits
355 ctrl-F6 - Remove this split
357 ctrl-F5 - Reconnect GPG and SSH sockets
359 shift-F6 - Detach, but do not logout
361 alt-pgup - Enter scrollback mode
363 alt-pgdn - Enter scrollback mode
365 Ctrl-a $ - show detailed status
367 Ctrl-a R - Reload profile
369 Ctrl-a ! - Toggle key bindings on and off
371 Ctrl-a k - Kill the current window
373 Ctrl-a ~ - Save the current window's scrollback buffer
375
378 Each window in Byobu has up to 10,000 lines of scrollback history,
379 which you can enter and navigate using the alt-pgup and alt-pgdn keys.
380 Exit this scrollback mode by hitting enter. You can also easily copy
381 and paste text from scrollback mode. To do so, enter scrollback using
382 alt-pgup or alt-pgdn, press the spacebar to start highlighting text,
383 use up/down/left/right/pgup/pgdn to select the text, and press enter to
384 copy the text. You can then paste the text using alt-insert or ctrl-
385 a-].
386
389 For Byobu colors to work properly, older versions of GNU Screen require
390 a 1-line patch to adjust MAX_WINMSG_REND in screen.c. The change is in
391 GNU Screen's upstream source control system as of 2010-01-26, but GNU
392 Screen has not released a new upstream version in several years. You
393 can disable colors entirely by setting MONOCHROME=1 in $BYOBU_CON‐
394 FIG_DIR/statusrc. For more information, see:
395 * http://savannah.gnu.org/bugs/?22146
396 PuTTY users have reported that the F2, F3, and F4 shortcut keys are not
398 working properly. PuTTY sends the same escape sequences as the linux
399 console for F1-F4 by default. You can fix this problem in the PuTTY
400 config, Terminal -> Keyboard -> Function keys: Xterm R6. See:
401 http://www.mail-archive.com/screen-users@gnu.org/msg01525.html
402 PuTTY users should configure enable UTF-8 characters in order to fix
404 status refresh issues. You can fix this problem in the PuTTY configu‐
405 ration, Window -> Translation: select UTF-8.
406 PuTTY users should avoid resizing their window to one character tall,
408 as this can sometimes crash byobu-screen.
409 Apple Mac OSX terminal users have reported 'flashing text'. You can
411 fix this in the advanced settings of the terminal application, with
412 'Declare Terminal As: xterm-color'.
413 Apple Mac keyboard users may need to specify a vt100 terminal by adding
415 this to your OSX profile, in order to get Byobu's function keys and
416 colors to work:
417 alias ssh='TERM=vt100 ssh'
418 Users of a non-UTF-8 locale (such as cs_CZ charset ISO-8859-2), may
420 need to add "defutf8 off" to ~/.screenrc, if some characters are ren‐
421 dering as "?".
422 Users who customize their PS1 prompt need to put this setting in
424 ~/.bashrc, rather than ~/.profile, in order for it to work correctly
425 with Byobu.
426 If you run byobu(1) under sudo(8), you must use the -H option, such
428 that the user's $HOME directory environment variable is set properly.
429 Otherwise, byobu(1) will create a bunch of directories in the
430 $SUDO_USER's $HOME, but will be owned by root. To prevent this from
431 happening, byobu(1) will simply refuse to run if $USER does not own
432 $HOME.
433 Byobu requires a suitable ulimit(3) values to run. If you get an error
435 at startup saying, 'pipe: too many open files', then check your ulimit
436 -a values, as your "open files" or "max user processes" are too low.
437 In this case, you will probably need to run simple screen(1)
438
441 screen(1), byobu-config(1), byobu-export(1), byobu-status(1), byobu-
442 status-detail(1), byobu-enable(1), byobu-launch(1), byobu-select-back‐
443 end(1), tmux(1)
444 http://byobu.org
445
448 This manpage and the utility were written by Dustin Kirkland <kirk‐
449 land@byobu.org> for Ubuntu systems (but may be used by others). Per‐
450 mission is granted to copy, distribute and/or modify this document and
451 the utility under the terms of the GNU General Public License, Version
452 3 published by the Free Software Foundation.
453 The complete text of the GNU General Public License can be found in
455 /usr/share/common-licenses/GPL on Debian/Ubuntu systems, or in
456 /usr/share/doc/fedora-release-*/GPL on Fedora systems, or on the web at
457 http://www.gnu.org/licenses/gpl.txt.
458byobu 19 June 2009 byobu(1)