1byobu(1) byobu byobu(1)
2
6 byobu - wrapper script for seeding a user's byobu configuration and
7 launching screen
8
11 byobu [screen options]
12 Options to byobu are simply passed through screen(1).
14
17 byobu is a script that launches GNU screen in the byobu configuration.
18 This enables the display of system information and status notifications
19 within two lines at the bottom of the screen session. It also enables
20 multiple tabbed terminal sessions, accessible through simple key‐
21 strokes.
22 Note that BYOBU_CONFIG_DIR=$HOME/.byobu.
24
27 byobu supports a number of unique and interesting status notifications
28 across the lowest two lines in the screen. Each status notification
29 item is independently configurable, enabled and disabled by the config‐
30 uration utility. The guide below helps identify each status item (in
31 alphabetical order):
32 apport - symbol displayed if there are pending crash reports; {!} sym‐
34 bol displayed on the lower bar toward the left, in black on an orange
35 background
36 arch - system architecture; displayed on the lower bar toward the left,
38 in the default text color on the default background color
39 battery - battery information; display on the lower bar toward the
41 right; |-| indicates discharging, |+| indicates charging, |=| indicates
42 fully charged; when charging or discharging, the current battery
43 capacity as a percentage is displayed; the colours green, yellow, and
44 red are used to give further indication of the battery's charge state;
45 you may override the detected battery by setting BAT‐
46 TERY=/proc/acpi/battery/BAT0 in $BYOBU_CONFIG_DIR/statusrc
47 cpu_count - the number of cpu's or cores on the system; displayed in
49 the lower bar toward the right in the default text color on the default
50 background, followed by a trailing 'x'
51 cpu_freq - the current frequency of the cpu in GHz; displayed in the
53 lower bar toward the right in white text on a light blue background
54 cpu_temp - the cpu temperature in Celsius (default) or Fahrenheit, con‐
56 figure TEMP=F or TEMP=C in $BYOBU_CONFIG_DIR/statusrc; displayed in the
57 lower bar toward the right in yellow text on a black background; you
58 may override the detected cpu temperature device by setting MONI‐
59 TORED_TEMP=/proc/acpi/whatever in $BYOBU_CONFIG_DIR/statusrc
60 custom - user defined custom scripts; must be executable programs of
62 any kind in $BYOBU_CONFIG_DIR/bin; must be named N_NAME, where N is the
63 frequency in seconds to refresh the status indicator, and NAME is the
64 name of the script; N should not be less than 5 seconds; the script
65 should echo a small amount of text to standard out, standard error is
66 discarded; the indicator will be displayed in the lower panel, in
67 inverted colors to your current background/foreground scheme, unless
68 you manually specify the colors in your script's output; BEWARE, cpu-
69 intensive custom scripts may impact your overall system performance and
70 could upset your system administrator!
71 Example: $BYOBU_CONFIG_DIR/bin/1000_uname
72 #!/bin/sh
73 printf "\005{= bw}%s\005{-}" "$(uname -r)"
74 date - the system date in YYYY-MM-DD formate; displayed in the lower on
76 the far right in the default text color on the default background
77 disk - total disk space available and total used on / directory; dis‐
79 played in the lower bar on the far right in white text on a light pur‐
80 ple background; override the default directory by specifying an alter‐
81 nate mount point with MONITORED_DISK=/wherever in $BYOBU_CON‐
82 FIG_DIR/statusrc
83 disk_io - instantaneous read/write througput in kB/s or MB/s over the
85 last 3 seconds; displayed in the lower bar toward the right in white
86 text on a light purple background with a leading '<' sign indicating
87 'read speed' and '>' sign indicating 'write speed'; override the
88 default monitored disk by specifying an alternate device with MONI‐
89 TORED_DISK=/dev/sdb, and override the default DISK_IO_THRESHOLD=50
90 (kB/s) in $BYOBU_CONFIG_DIR/statusrc
91 ec2_cost - an estimation of the cost of the current boot of the system
93 in terms of the Amazon EC2 billing model; displayed in the lower bar
94 toward the right in green text on a black background; there is a lead‐
95 ing '~' to indicate that this is an estimation, and the monetary units
96 are US Dollars '$'
97 raid - note very prominently if there is a RAID failure detected, in
99 red blinking text on a white background; the term 'RAID' notes that
100 there is something wrong with the RAID, and if there is a
101 rebuild/resync in progress, the percent complete is also shown
102 rcs_cost - an estimation of the cost of the current boot of the system
104 in terms of the Rackspace Cloud Server billing model; displayed in the
105 lower bar toward the right in green text on a black background; there
106 is a leading '~' to indicate that this is an estimation, and the mone‐
107 tary units are US Dollars '$'
108 fan_speed - cpu or system fan speed as reported by lm-sensors; dis‐
110 played in the lower bar toward the right in black text on a grey back‐
111 ground; there is a trailing 'rpm' for units
112 hostname - the hostname of the system; displayed in the upper bar on
114 the far right in bold black text on a grey background; there is a lead‐
115 ing '@' symbol if the username status is also enabled
116 ip_address - the IPv4 address of the system in dotted decimal form;
118 displayed in the upper bar on the far right in bold black text on a
119 grey background; you can override and display your IPv6 address by
120 setting 'IPV6=1' in $BYOBU_CONFIG_DIR/statusrc
121 load_average - the system load average over the last 1 minute; dis‐
123 played in the lower bar toward the right in black text on a yellow
124 background
125 logo - an approximation of the current operating system's logo; dis‐
127 played in the lower bar on the far left; you may customize this logo by
128 setting a chosen logo in $BYOBU_CONFIG_DIR/logo, or you may override
129 this with LOGO=:-D in $BYOBU_CONFIG_DIR/statusrc
130 mail - system mail for the current user; the letter '[M]' is displayed
132 in the lower bar toward the left in black text on a grey background
133 mem_available - total memory available in the system; displayed in the
135 lower bar toward the right in white text on a green background
136 mem_used - total memory used in the system as a percentage of the total
138 memory available; displayed in the lower bar toward the right in white
139 text on a green background with a trailing '%' sign
140 menu - a simple indicator directing new users to use the F9 keybinding
142 to access the byobu menu
143 network - instantaneous upload/download bandwidth in [GMk]bps over the
145 last 3 seconds; nothing is displayed if traffic is 0; displayed in the
146 lower bar toward the left in white text on a purple background with a
147 leading '^' sign indicating 'up' and 'v' sign indicating 'down'; over‐
148 ride the default interface by specifying an alternate interface with
149 MONITORED_NETWORK=eth1, and override the default units (bits) with NET‐
150 WORK_UNITS=bytes, and override the default NETWORK_THRESHOLD=20 (kbps)
151 in $BYOBU_CONFIG_DIR/statusrc
152 notify_osd - Send on-screen notification messages to screen's notifica‐
154 tion buffer
155 processes - total number of processes running on the system; displayed
157 in the lower bar in white text on a dark yellow background with a
158 trailing '&' indicating 'background processes'
159 reboot_required - symbol present if a reboot is required following a
161 system update; displayed in the lower bar white text on a blue back‐
162 ground by the symbol '(R)'; additionally, reboot_required will print
163 '<F5>' in white text on a blue background, if Byobu requires you to
164 reload your profile to affect some changes.
165 release - distribution and version information about the release run‐
167 ning on the current system as reported by lsb_release(1) or /etc/issue;
168 displayed in the lower bar in bold black text toward the left on a grey
169 background; you may override the detected release with DISTRO=Whatever
170 in $BYOBU_CONFIG_DIR/statusrc
171 services - users can configure a list of services to monitor, define
173 the SERVICES variable in $BYOBU_CONFIG_DIR/statusrc, a whitespace sepa‐
174 rated of services, each service should include the init name of the
175 service, then a pipe, and then an abbreviated name or symbol to display
176 when running (e.g. SERVICES="ssh|ssh apache2|http"); displayed in the
177 lower bar toward the center in cyan on a white background
178 swap - total swap space and total used as a percentage of the total
180 available; displayed in the lower bar toward the right in white text on
181 a light green background with a trailing '%' sign
182 time - the system time in HH:MM:SS format; displayed in the lower bar
184 on the far right in the default text and default background colors
185 time_binary - only for the hard core geek, the local system time in
187 binary; requires UTF8 support in a VERY recent version of GNU Screen;
188 you must additionally set "UTF8=1" in $BYOBU_CONFIG_DIR/statusrc; dis‐
189 played in the lower bar on the far right in the default text and back‐
190 ground colors
191 time_utc - the UTC system time in HH:MMformat; displayed in the lower
193 bar on the far right in dark text on a light background
194 updates_available - the number of updates available on the system; dis‐
196 played in the lower bar toward the right in white text on a red back‐
197 ground with a trailing '!' sign; if any updates are marked 'security
198 updates', then there will be a total of two trailing exclamation
199 points, '!!'
200 uptime - the total system uptime since last boot; displayed in the
202 lower bar toward the right in blue text on a grey background
203 users - the number of remote users logged into the system via sshd,
205 empty if 0 users; displayed in the lower bar toward the right in red
206 text on a grey background with a trailing '#' sign
207 whoami - the name of the user who owns the screen session; displayed in
209 the upper bar toward the far right in bold black text on a grey back‐
210 ground
211 wifi_quality - the connection rate and signal quality of the wifi con‐
213 nection; displayed in the lower bar toward the right in black text on a
214 cyan background; the connection rate is in 'Mb/s' and the signal qual‐
215 ity is as a percentage with a trailing '%'; override the default inter‐
216 face by specifying an alternate interface with MONITORED_NETWORK=wlan0
217 in $BYOBU_CONFIG_DIR/statusrc
218
221 Byobu name screen sessions "byobu", if unspecified. To hide sessions
222 from byobu-select-session(1), prepend a "." to the beginning of the
223 session name, like:
224 byobu -S .hidden
226
229 Each open window in the screen session is displayed in the upper bar
230 toward the far left. These are numbered, and include indicators as to
231 activity in the window (see "activity" in screen(1) for symbol defini‐
232 tions). The current active window is highlighted by inverting the
233 background/text from the rest of the window bar.
234 Users can create a list of windows to launch at startup in $BYOBU_CON‐
236 FIG_DIR/windows. This file is the same syntax as ~/.screenrc, each
237 line specifying a window using the "screen" command, as described in
238 screen(1).
239 User can also launch Byobu with unique window sets. Users can store
241 these as $BYOBU_CONFIG_DIR/windows.[NAME], and launch Byobu with the
242 environment variable BYOBU_WINDOWS.
243 For example:
245 $ cat $BYOBU_CONFIG_DIR/windows.ssh_sessions
246 screen -t localhost bash
247 screen -t aussie ssh root@aussie
248 screen -t beagle ssh root@beagle
249 screen -t collie ssh root@collie
250 $ BYOBU_WINDOWS=ssh_sessions byobu
251
254 byobu uses binary for capacity measurements of KB, MB, GB, and TB.
255 This means multiples of 1024 rather than multiples of 1000, in accor‐
256 dance with JEDEC Standard 100B.01 for disk and memory capacity measure‐
257 ments. See:
258 * http://en.wikipedia.org/wiki/JEDEC_memory_standards
259 byobu uses decimal for measurements of network data transfer, meaning
261 multiple of 1000, rather than 1024. See:
262 * http://en.wikipedia.org/wiki/Data_rate_units
263
266 byobu keybindings can be user defined in /usr/share/byobu/keybindings/
267 (or within .screenrc if byobu-export was used). The common key bindings
268 are:
269 F2 - Create a new window
271 F3 - Move to previous window
273 F4 - Move to next window
275 F5 - Reload profile
277 F6 - Detach from this session
279 F7 - Enter copy/scrollback mode
281 F8 - Re-title a window
283 F9 - Configuration Menu
285 F12 - Lock this terminal
287 shift-F2 - Split the screen horizontally
289 ctrl-F2 - Split the screen vertically
291 shift-F3 - Shift the focus to the previous split region
293 shift-F4 - Shift the focus to the next split region
295 shift-F5 - Join all splits
297 ctrl-F6 - Remove this split
299 ctrl-F5 - Reconnect GPG and SSH sockets
301 shift-F6 - Detach, but do not logout
303 alt-pgup - Enter scrollback mode
305 alt-pgdn - Enter scrollback mode
307 Ctrl-a $ - show detailed status
309 Ctrl-a R - Reload profile
311 Ctrl-a ! - Toggle key bindings on and off
313 Ctrl-a k - Kill the current window
315 Ctrl-a ~ - Save the current window's scrollback buffer
317
320 For Byobu colors to work properly, older versions of GNU Screen require
321 a 1-line patch to adjust MAX_WINMSG_REND in screen.c. The change is in
322 GNU Screen's upstream source control system as of 2010-01-26, but GNU
323 Screen has not released a new upstream version in several years. You
324 can disable colors entirely by setting MONOCHROME=1 in $BYOBU_CON‐
325 FIG_DIR/statusrc. For more information, see:
326 * http://savannah.gnu.org/bugs/?22146
327 PuTTY users have reported that the F2, F3, and F4 shortcut keys are not
329 working properly. PuTTY sends the same escape sequences as the linux
330 console for F1-F4 by default. You can fix this problem in the PuTTY
331 config, Terminal -> Keyboard -> Function keys: Xterm R6. See:
332 http://www.mail-archive.com/screen-users@gnu.org/msg01525.html
333 Apple Mac OSX terminal users have reported 'flashing text'. You can
335 fix this in the advanced settings of the terminal application, with
336 'Declare Terminal As: xterm-color'.
337 Apple Mac keyboard users may need to specify a vt100 terminal by adding
339 this to your OSX profile, in order to get Byobu's function keys and
340 colors to work:
341 alias ssh='TERM=vt100 ssh'
342 Users of a non-UTF8 locale (such as cs_CZ charset ISO-8859-2), may need
344 to add "defutf8 off" to ~/.screenrc, if some characters are rendering
345 as "?".
346 Users who customize their PS1 prompt need to put this setting in
348 ~/.bashrc, rather than ~/.profile, in order for it to work correctly
349 with Byobu.
350
353 screen(1), byobu-config(1), byobu-export(1), byobu-status(1), byobu-
354 status-detail(1), byobu-enable(1), byobu-launch(1)
355 http://launchpad.net/byobu
356
359 This manpage and the utility were written by Dustin Kirkland <kirk‐
360 land@ubuntu.com> for Ubuntu systems (but may be used by others). Per‐
361 mission is granted to copy, distribute and/or modify this document and
362 the utility under the terms of the GNU General Public License, Version
363 3 published by the Free Software Foundation.
364 The complete text of the GNU General Public License can be found in
366 /usr/share/common-licenses/GPL on Debian/Ubuntu systems, or in
367 /usr/share/doc/fedora-release-*/GPL on Fedora systems, or on the web at
368 http://www.gnu.org/licenses/gpl.txt.
369byobu 19 June 2009 byobu(1)