Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
byobu(1)			     byobu			      byobu(1)

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

SYNOPSIS
       byobu [options]

       byobu-screen [screen options]

       byobu-tmux [tmux	options]

       Options to byobu	are simply passed through screen(1) or tmux(1).

DESCRIPTION
       byobu is	a script that launches a text  based  window  manager  (either
       screen(1)  or  tmux(1))	in  the	byobu configuration.  This enables the
       display of system information and status	notifications within two lines
       at  the	bottom	of the screen session. It also enables multiple	tabbed
       terminal	sessions, accessible through simple keystrokes.

       byobu currently defaults	to using tmux(1) (if present) as the  backend,
       however,	 this can be overridden	with the byobu-select-backend(1) util-
       ity.

       Note  that  BYOBU_CONFIG_DIR=$XDG_CONFIG_HOME/byobu  if	defined,   and
       $HOME/.byobu otherwise.

BACKGROUND COLORS
       The  background	colors	of  the	 byobu status lines can	be adjusted by
       editing the files $HOME/.byobu/color (for byobu-screen) and  $HOME/.by-
       obu/color.tmux (for byobu-tmux).	 The command Ctrl-Shift-F5 will	change
       the background to a randomly selected color when	running	in  byobu-tmux
       mode.  Simply remove those files	to return to the default color config-
       uration.

STATUS NOTIFICATIONS
       byobu supports a	number of unique and interesting status	 notifications
       across  the  lowest  two	lines in the screen.  Each status notification
       item is independently configurable, enabled and disabled	by the config-
       uration	utility.   The guide below helps identify each status item (in
       alphabetical order):

       apport -	symbol displayed if there are pending crash reports; {!}  sym-
       bol  displayed  on the lower bar	toward the left, in black on an	orange
       background

       arch - system architecture; displayed on	the lower bar toward the left,
       in the default text color on the	default	background color

       battery	-  battery  information;  display  on the lower	bar toward the
       right; -	indicates discharging, + indicates charging, = indicates fully
       charged;	 when charging or discharging, the current battery capacity as
       a percentage is displayed;  the colours green, yellow, and red are used
       to give further indication of the battery's charge state; you may over-
       ride the	detected battery by setting BATTERY=/proc/acpi/battery/BAT0 in
       $BYOBU_CONFIG_DIR/statusrc

       cpu_count  -  the  number of cpu's or cores on the system; displayed in
       the lower bar toward the	right in the default text color	on the default
       background, followed by a trailing 'x'

       cpu_freq	 -  the	 current frequency of the cpu in GHz; displayed	in the
       lower bar toward	the right in white text	on a light blue	background

       cpu_temp	- the cpu temperature in Celsius (default) or Fahrenheit, con-
       figure TEMP=F or	TEMP=C in $BYOBU_CONFIG_DIR/statusrc; displayed	in the
       lower bar toward	the right in yellow text on a  black  background;  you
       may  override  the  detected  cpu  temperature  device by setting MONI-
       TORED_TEMP=/proc/acpi/whatever in $BYOBU_CONFIG_DIR/statusrc

       custom -	user defined custom scripts; must be  executable  programs  of
       any kind	in $BYOBU_CONFIG_DIR/bin; must be named	N_NAME,	where N	is the
       frequency in seconds to refresh the status indicator, and NAME  is  the
       name  of	 the  script;  N should	not be less than 5 seconds; the	script
       should echo a small amount of text to standard out, standard  error  is
       discarded;  the	indicator will be displayed in the lower panel,	in de-
       fault colors, unless you	manually specify the colors in	your  script's
       output;	BEWARE,	 cpu-intensive	custom scripts may impact your overall
       system performance and could upset your system administrator!  In fact,
       you  can	 easily	 copy  and  modify  any	status script usually found in
       /usr/lib/byobu/*	to your	local $HOME/.byobu/ directory.
	 Example: $BYOBU_CONFIG_DIR/bin/1000_uname
	   #!/bin/sh
	   printf "\005{= bw}%s\005{-}"	"$(uname -r)"

       date - the system date in YYYY-MM-DD format, or you can set this	to any
       valid  strftime(3) you like in $BYOBU_CONFIG_DIR/datetime; displayed in
       the lower on the	far right in the default text  color  on  the  default
       background

       disk  -	total disk space available and total used on / directory; dis-
       played in the lower bar on the far right	in white text on a light  pur-
       ple  background;	override the default directory by specifying an	alter-
       nate  mount  point   with   MONITORED_DISK=/wherever   in   $BYOBU_CON-
       FIG_DIR/statusrc

       disk_io	-  instantaneous read/write througput in kB/s or MB/s over the
       last 3 seconds; displayed in the	lower bar toward the  right  in	 white
       text  on	 a  light purple background with a leading '<' sign indicating
       'read speed' and	'>' sign indicating 'write speed';  override  the  de-
       fault  monitored	 disk  by  specifying  an  alternate device with MONI-
       TORED_DISK=/dev/sdb,  and  override  the	 default  DISK_IO_THRESHOLD=50
       (kB/s) in $BYOBU_CONFIG_DIR/statusrc

       distro  -  OS/distribution  name	 of the	release	running	on the current
       system as reported by lsb_release(1) or /etc/issue;  displayed  in  the
       lower  bar in bold black	text toward the	left on	a grey background; you
       may override the	detected release with DISTRO=Whatever  in  $BYOBU_CON-
       FIG_DIR/statusrc

       ec2_cost	 - an estimation of the	cost of	the current boot of the	system
       in terms	of the Amazon EC2 billing model; displayed in  the  lower  bar
       toward  the  right  in  green  text on a	black background; the monetary
       units are US Dollars '$'; this plugin only works	when an	AWS-compatible
       metadata	server is available at http://169.254.169.254

       entropy	-  a count of the system's current entropy in bytes; displayed
       in the lower bar	toward the right in yellow text	on a dark  grey	 back-
       ground; there is	a leading 'e' to indicate 'entropy'

       raid  -	note  very prominently if there	is a RAID failure detected, in
       red blinking text on a white background;	the  term  'RAID'  notes  that
       there  is  something  wrong  with  the  RAID,  and  if  there  is a re-
       build/resync in progress, the percent complete is also shown

       rcs_cost	- an estimation	of the cost of the current boot	of the	system
       in  terms of the	Rackspace Cloud	Server billing model; displayed	in the
       lower bar toward	the right in green text	on a black  background;	 there
       is  a leading '~' to indicate that this is an estimation, and the mone-
       tary units are US Dollars '$'

       fan_speed - cpu or system fan speed as  reported	 by  lm-sensors;  dis-
       played  in the lower bar	toward the right in black text on a grey back-
       ground; there is	a trailing 'rpm' for units; you	may override  the  de-
       tected  fan  by setting FAN=/sys/path/to/your/fan1_input	in $BYOBU_CON-
       FIG_DIR/statusrc

       hostname	- the hostname of the system; displayed	in the	upper  bar  on
       the far right in	bold black text	on a grey background; there is a lead-
       ing '@' symbol if the username status is	also enabled

       ip_address - the	IPv4 address of	the system  in	dotted	decimal	 form;
       displayed  in  the  upper  bar on the far right in bold black text on a
       grey background;	 you can override and display  your  IPv6  address  by
       setting	'IPV6=1', and you can show your	external ip address by setting
       'IP_EXTERNAL=1' in $BYOBU_CONFIG_DIR/statusrc

       ip_address4 - the IPv4 address of the system in	dotted	decimal	 form;
       displayed  in  the  upper  bar on the far right in bold black text on a
       grey background;	 you can show your  external  ip  address  by  setting
       'IP_EXTERNAL=1' in $BYOBU_CONFIG_DIR/statusrc

       ip_address6  -  the  IPv6 address of the	system;	displayed in the upper
       bar on the far right in bold black text on a grey background;  you  can
       show your external ip address by	setting	'IP_EXTERNAL=1'	in $BYOBU_CON-
       FIG_DIR/statusrc

       load_average - the system load average over the	last  1	 minute;  dis-
       played  in  the	lower  bar  toward the right in	black text on a	yellow
       background

       logo - an approximation of the current operating	 system's  logo;  dis-
       played in the lower bar on the far left;	you may	customize this logo by
       setting a chosen	logo in	$BYOBU_CONFIG_DIR/logo,	or  you	 may  override
       this with LOGO=:-D in $BYOBU_CONFIG_DIR/statusrc

       mail  - system mail for the current user; the letter '[M]' is displayed
       in the lower bar	toward the left	in black text on a grey	background

       memory -	total memory available and used	percentage in the system; dis-
       played in the lower bar toward the right	in white text on a green back-
       ground

       menu - a	simple indicator directing new users to	use the	F9  keybinding
       to access the byobu menu

       network	- instantaneous	upload/download	bandwidth in [GMk]bps over the
       last 3 seconds; nothing is displayed if traffic is 0; displayed in  the
       lower  bar  toward the left in white text on a purple background	with a
       leading '^' sign	indicating 'up'	and 'v'	sign indicating	'down';	 over-
       ride  the  default  interface by	specifying an alternate	interface with
       MONITORED_NETWORK=eth1, and override the	default	units (bits) with NET-
       WORK_UNITS=bytes,  and override the default NETWORK_THRESHOLD=20	(kbps)
       in $BYOBU_CONFIG_DIR/statusrc

       notify_osd - Send on-screen notification	messages to screen's notifica-
       tion buffer

       processes  - total number of processes running on the system; displayed
       in the lower bar	in white text on  a  dark  yellow  background  with  a
       trailing	'&' indicating 'background processes'

       reboot_required	-  symbol  present if a	reboot is required following a
       system update; displayed	in the lower bar white text on	a  blue	 back-
       ground  by  the	symbol '(R)'; additionally, reboot_required will print
       '<F5>' in white text on a blue background, if  Byobu  requires  you  to
       reload your profile to affect some changes; it will also	detect if your
       system is currently in powernap(8) state	and if so print	'.zZ'; if your
       system  is currently performing an unattended-upgrade(1)	you will see a
       white warning sign on a red background.

       release - OS/distribution name of the release running  on  the  current
       system  as  reported  by	lsb_release(1) or /etc/issue; displayed	in the
       lower bar in bold black text toward the left on a grey background;  you
       may  override the detected release with RELEASE=Whatever	in $BYOBU_CON-
       FIG_DIR/statusrc; you may also abbreviate the release string to N char-
       acters by setting RELEASE_ABBREVIATED=N in $BYOBU_CONFIG_DIR/statusrc

       services	 -  users  can configure a list	of services to monitor,	define
       the SERVICES variable in	$BYOBU_CONFIG_DIR/statusrc, a whitespace sepa-
       rated  of  services,  each  service should include the init name	of the
       service,	then a pipe, and then an abbreviated name or symbol to display
       when  running  (e.g. SERVICES="ssh|ssh apache2|http"); displayed	in the
       lower bar toward	the center in cyan on a	white background

       session - byobu session name (only supported  in	 byobu-tmux(1));  dis-
       played in the lower bar on the left in underlined black text on a white
       background

       swap - total swap space and total used as a  percentage	of  the	 total
       available; displayed in the lower bar toward the	right in black text on
       a light green background	with a trailing	'%' sign

       time - the system time in HH:MM:SS format (by default), or you can  set
       this  to	 any valid strftime(3) you like	in $BYOBU_CONFIG_DIR/datetime;
       displayed in the	lower bar on the far right in the default text and de-
       fault background	colors

       time_binary - only for the hard core geek, the local system time	in bi-
       nary; requires UTF-8 support in a VERY recent version  of  GNU  Screen;
       displayed  in  the  lower  bar on the far right in the default text and
       background colors

       time_utc	- the UTC system time in HH:MM format; displayed in the	 lower
       bar on the far right in dark text on a light background

       updates_available - the number of updates available on the system; dis-
       played in the lower bar toward the right	in white text on a  red	 back-
       ground  with  a	trailing '!' sign; if any updates are marked 'security
       updates', then there will  be  a	 total	of  two	 trailing  exclamation
       points, '!!'

       uptime  -  the  total  system  uptime since last	boot; displayed	in the
       lower bar toward	the right in blue text on a grey background

       users - the number of remote users logged into  the  system  via	 sshd,
       empty  if  0  users; displayed in the lower bar toward the right	in red
       text on a grey background with a	 trailing  '#'	sign;  set  USERS_DIS-
       TINCT=1	to  instead count the number of	distinct users logged into the
       system (rather than open	ssh sessions)

       whoami -	the name of the	user who owns the screen session; displayed in
       the  upper  bar toward the far right in bold black text on a grey back-
       ground

       wifi_quality - the connection rate and signal quality of	the wifi  con-
       nection;	displayed in the lower bar toward the right in black text on a
       cyan background;	the connection rate is in 'Mb/s' and the signal	 qual-
       ity is as a percentage with a trailing '%'; override the	default	inter-
       face by specifying an alternate interface with  MONITORED_NETWORK=wlan0
       in $BYOBU_CONFIG_DIR/statusrc

SESSIONS
       Byobu  name  screen sessions "byobu", if	unspecified.  To hide sessions
       from byobu-select-session(1), prepend a "." to  the  beginning  of  the
       session name, like:

	byobu -S .hidden

WINDOWS
       Each  open  window  in the screen session is displayed in the upper bar
       toward the far left.  These are numbered, and include indicators	as  to
       activity	 in  the  window  (see "activity" in screen(1) and tmux(1) for
       symbol definitions).  The current active	window is highlighted  by  in-
       verting the background/text from	the rest of the	window bar.

       Users  can create a list	of windows to launch at	startup	in $BYOBU_CON-
       FIG_DIR/windows and $BYOBU_CONFIG_DIR/windows.tmux.  This file  is  the
       same  syntax  as	~/.screenrc and	~/.tmuxrc, each	line specifying	a win-
       dow, as described in screen(1) or tmux(1).

       User can	also launch Byobu with unique window sets.   Users  can	 store
       these  as  $BYOBU_CONFIG_DIR/windows.[NAME]  and	$BYOBU_CONFIG_DIR/win-
       dows.tmux.[NAME], and launch Byobu with the  environment	 variable  BY-
       OBU_WINDOWS=NAME.

       For example:
	 $ cat $BYOBU_CONFIG_DIR/windows.ssh_sessions
	 screen	-t localhost bash
	 screen	-t aussie ssh root@aussie
	 screen	-t beagle ssh root@beagle
	 screen	-t collie ssh root@collie

       Then:
	 $ BYOBU_WINDOWS=ssh_sessions byobu

       For example:
	 $ cat $BYOBU_CONFIG_DIR/windows.tmux.split4
	 new-session 'bash' ;
	 new-window -n term1 ;
	 new-window -n term2 ;
	 new-window -n ssh ssh 10.9.8.7	;
	 split-window ;
	 split-window ;
	 split-window ;
	 select-layout tiled ;
	 select-pane -t	0

       Then:
	 $ BYOBU_WINDOWS=split4	byobu

UNITS OF MEASURE
       byobu  uses  binary  for	 capacity  measurements	of KB, MB, GB, and TB.
       This means multiples of 1024 rather than	multiples of 1000,  in	accor-
       dance  with  JEDEC  Standard  100B.01 for memory	capacity measurements.
       See:
	* http://en.wikipedia.org/wiki/JEDEC_memory_standards

       byobu uses decimal for measurements of network data  transfer,  meaning
       multiple	of 1000, rather	than 1024.  See:
	* http://en.wikipedia.org/wiki/Data_rate_units

KEYBINDINGS
       byobu  keybindings can be user defined in /usr/share/byobu/keybindings/
       (or within .screenrc if byobu-export was	used). The common key bindings
       are:

       F2 - Create a new window

       F3 - Move to previous window

       F4 - Move to next window

       F5 - Reload profile

       F6 - Detach from	this session

       F7 - Enter copy/scrollback mode

       F8 - Re-title a window

       F9 - Configuration Menu

       F12 -  Lock this	terminal

       shift-F2	- Split	the screen horizontally

       ctrl-F2 - Split the screen vertically

       shift-F3	- Shift	the focus to the previous split	region

       shift-F4	- Shift	the focus to the next split region

       shift-F5	- Join all splits

       ctrl-F6 - Remove	this split

       ctrl-F5 - Reconnect GPG and SSH sockets

       shift-F6	- Detach, but do not logout

       alt-pgup	- Enter	scrollback mode

       alt-pgdn	- Enter	scrollback mode

       Ctrl-a $	- show detailed	status

       Ctrl-a R	- Reload profile

       Ctrl-a !	- Toggle key bindings on and off

       Ctrl-a k	- Kill the current window

       Ctrl-a ~	- Save the current window's scrollback buffer

SCROLLBACK, COPY, PASTE	MODES
       Each  window  in	 Byobu	has  up	to 10,000 lines	of scrollback history,
       which you can enter and navigate	using the alt-pgup and alt-pgdn	 keys.
       Exit  this  scrollback mode by hitting enter.  You can also easily copy
       and paste text from scrollback mode.  To	do so, enter scrollback	 using
       alt-pgup	 or  alt-pgdn,	press the spacebar to start highlighting text,
       use up/down/left/right/pgup/pgdn	to select the text, and	press enter to
       copy  the  text.	 You can then paste the	text using alt-insert or ctrl-
       a-].

BUGS
       For Byobu colors	to work	properly, older	versions of GNU	Screen require
       a 1-line	patch to adjust	MAX_WINMSG_REND	in screen.c.  The change is in
       GNU Screen's upstream source control system as of 2010-01-26,  but  GNU
       Screen  has  not	released a new upstream	version	in several years.  You
       can disable colors entirely  by	setting	 MONOCHROME=1  in  $BYOBU_CON-
       FIG_DIR/statusrc.  For more information,	see:
	* http://savannah.gnu.org/bugs/?22146

       PuTTY users have	reported that the F2, F3, and F4 shortcut keys are not
       working properly.  PuTTY	sends the same escape sequences	as  the	 linux
       console	for  F1-F4  by default.	 You can fix this problem in the PuTTY
       config,	Terminal  ->  Keyboard	->  Function  keys:  Xterm  R6.	  See:
       http://www.mail-archive.com/screen-users@gnu.org/msg01525.html

       PuTTY  users  should  configure enable UTF-8 characters in order	to fix
       status refresh issues.  You can fix this	problem	in the PuTTY  configu-
       ration, Window -> Translation: select UTF-8.

       PuTTY  users  should avoid resizing their window	to one character tall,
       as this can sometimes crash byobu-screen.

       Apple Mac OSX terminal users have reported 'flashing  text'.   You  can
       fix  this  in  the  advanced settings of	the terminal application, with
       'Declare	Terminal As: xterm-color'.

       Apple Mac keyboard users	may need to specify a vt100 terminal by	adding
       this  to	 your  OSX  profile, in	order to get Byobu's function keys and
       colors to work:
	 alias ssh='TERM=vt100 ssh'

       Users of	a non-UTF-8 locale (such as  cs_CZ  charset  ISO-8859-2),  may
       need  to	 add "defutf8 off" to ~/.screenrc, if some characters are ren-
       dering as "?".

       Users who customize their PS1  prompt  need  to	put  this  setting  in
       ~/.bashrc,  rather  than	 ~/.profile, in	order for it to	work correctly
       with Byobu.

       If you run byobu(1) under sudo(8), you must use	the  -H	 option,  such
       that  the  user's $HOME directory environment variable is set properly.
       Otherwise,  byobu(1)  will  create  a  bunch  of	 directories  in   the
       $SUDO_USER's  $HOME,  but  will be owned	by root.  To prevent this from
       happening, byobu(1) will	simply refuse to run if	 $USER	does  not  own
       $HOME.

       Byobu requires a	suitable ulimit(3) values to run.  If you get an error
       at startup saying, 'pipe: too many open files', then check your	ulimit
       -a  values,  as	your "open files" or "max user processes" are too low.
       In this case, you will probably need to run simple screen(1)

SEE ALSO
       screen(1), byobu-config(1),  byobu-export(1),  byobu-status(1),	byobu-
       status-detail(1),  byobu-enable(1), byobu-launch(1), byobu-select-back-
       end(1), tmux(1)
       http://byobu.org

AUTHOR
       This manpage and	the utility were written  by  Dustin  Kirkland	<kirk-
       land@byobu.org>	for  Ubuntu systems (but may be	used by	others).  Per-
       mission is granted to copy, distribute and/or modify this document  and
       the  utility under the terms of the GNU General Public License, Version
       3 published by the Free Software	Foundation.

       The complete text of the	GNU General Public License  can	 be  found  in
       /usr/share/common-licenses/GPL	on   Debian/Ubuntu   systems,	or  in
       /usr/share/doc/fedora-release-*/GPL on Fedora systems, or on the	web at
       http://www.gnu.org/licenses/gpl.txt.

byobu				 19 June 2009			      byobu(1)

NAME | SYNOPSIS | DESCRIPTION | BACKGROUND COLORS | STATUS NOTIFICATIONS | SESSIONS | WINDOWS | UNITS OF MEASURE | KEYBINDINGS | SCROLLBACK, COPY, PASTE MODES | BUGS | SEE ALSO | AUTHOR

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=byobu&sektion=1&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help