byobu

       launching a text based window manager (either screen or tmux)


SYNOPSIS
       byobu [screen 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 overriden with the byobu-select-backend(1) util-
       ity.

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


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'

       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
       inverted  colors  to  your current background/foreground scheme, 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!
         Example: $BYOBU_CONFIG_DIR/bin/1000_uname
           #!/bin/sh
           printf "\005{= bw}%s\005{-}" "$(uname -r)"

       date - the system date in YYYY-MM-DD formate; 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
       default  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; there is a lead-
       ing '~' to indicate that this is an estimation, and the monetary  units
       are  US  Dollars  '$';  if  not running in EC2, this plugin is disabled
       unless EC2_ESTIMATE=1 in ~/.byobu/statusrc

       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
       rebuild/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-
       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 in the system; displayed in
       the lower bar toward the right in white text on a green background

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

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

       time - the system time in HH:MM:SS format; displayed in the  lower  bar
       on the far right in the default text and default background colors

       time_binary  -  only  for  the hard core geek, the local system time in
       binary; requires UTF8 support in a VERY recent version of  GNU  Screen;
       you  must additionally set "UTF8=1" in $BYOBU_CONFIG_DIR/statusrc; dis-
       played in the lower bar on the far right in the default text and  back-
       ground colors

       time_utc  -  the UTC system time in HH:MMformat; 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

       screen(1).

       User  can  also  launch Byobu with unique window sets.  Users can store
       these as $BYOBU_CONFIG_DIR/windows.[NAME], and launch  Byobu  with  the
       environment variable BYOBU_WINDOWS.

       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
         $ BYOBU_WINDOWS=ssh_sessions 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 disk and memory capacity measure-
       ments.  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

       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

       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-UTF8 locale (such as cs_CZ charset ISO-8859-2), may need
       to add "defutf8 off" to ~/.screenrc, if some characters  are  rendering
       as "?".

       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://launchpad.net/byobu


AUTHOR
       This  manpage  and  the  utility were written by Dustin Kirkland <kirk-
       land@ubuntu.com> 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)
Man Pages Copyright Respective Owners. Site Copyright (C) 1994 - 2017 Hurricane Electric. All Rights Reserved.