1byobu(1)                             byobu                            byobu(1)
2
3
4

NAME

6       byobu  -  wrapper  script  for seeding a user's byobu configuration and
7       launching a text based window manager (either screen or tmux)
8
9

SYNOPSIS

11       byobu [options]
12
13       byobu-screen [screen options]
14
15       byobu-tmux [tmux options]
16
17       Options to byobu are simply passed through screen(1) or tmux(1).
18
19

DESCRIPTION

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
27       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
31       Note  that  BYOBU_CONFIG_DIR=$XDG_CONFIG_HOME/byobu  if  defined,   and
32       $HOME/.byobu otherwise.
33
34

BACKGROUND COLORS

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
43

STATUS NOTIFICATIONS

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
51       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
55       arch - system architecture; displayed on the lower bar toward the left,
56       in the default text color on the default background color
57
58       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
66       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
70       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
73       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
79       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
94
95       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
100       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
106       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
114       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
120       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
124       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
129       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
135       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
139       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
145       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
150       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
155       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
159       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
163       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
166       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
170       menu  - a simple indicator directing new users to use the F9 keybinding
171       to access the byobu menu
172
173       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
182       notify_osd - Send on-screen notification messages to screen's notifica‐
183       tion buffer
184
185       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
189       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
198       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
205       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
212       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
216       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
220       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
225       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
230       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
233       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
239       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
242       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
248       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
252       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
259

SESSIONS

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
265        byobu -S .hidden
266
267

WINDOWS

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
275       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
280       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
285       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
292       Then:
293         $ BYOBU_WINDOWS=ssh_sessions byobu
294
295       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
307       Then:
308         $ BYOBU_WINDOWS=split4 byobu
309
310

UNITS OF MEASURE

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
318       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
322

KEYBINDINGS

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
328       F2 - Create a new window
329
330       F3 - Move to previous window
331
332       F4 - Move to next window
333
334       F5 - Reload profile
335
336       F6 - Detach from this session
337
338       F7 - Enter copy/scrollback mode
339
340       F8 - Re-title a window
341
342       F9 - Configuration Menu
343
344       F12 -  Lock this terminal
345
346       shift-F2 - Split the screen horizontally
347
348       ctrl-F2 - Split the screen vertically
349
350       shift-F3 - Shift the focus to the previous split region
351
352       shift-F4 - Shift the focus to the next split region
353
354       shift-F5 - Join all splits
355
356       ctrl-F6 - Remove this split
357
358       ctrl-F5 - Reconnect GPG and SSH sockets
359
360       shift-F6 - Detach, but do not logout
361
362       alt-pgup - Enter scrollback mode
363
364       alt-pgdn - Enter scrollback mode
365
366       Ctrl-a $ - show detailed status
367
368       Ctrl-a R - Reload profile
369
370       Ctrl-a ! - Toggle key bindings on and off
371
372       Ctrl-a k - Kill the current window
373
374       Ctrl-a ~ - Save the current window's scrollback buffer
375
376

SCROLLBACK, COPY, PASTE MODES

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
387

BUGS

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
397       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
403       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
407       PuTTY users should avoid resizing their window to one  character  tall,
408       as this can sometimes crash byobu-screen.
409
410       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
414       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
419       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
423       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
427       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
434       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
439

SEE ALSO

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
446

AUTHOR

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
454       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.
458
459
460
461byobu                            19 June 2009                         byobu(1)
Impressum