{
    "content": [
        {
            "type": "text",
            "text": "# byobu(1) (man)\n\n**Summary:** byobu  -  wrapper  script for seeding a user's byobu configuration and launching a text based window manager (either screen or tmux)\n\n**Synopsis:** byobu [options]\nbyobu-screen [screen options]\nbyobu-tmux [tmux options]\nOptions to byobu are simply passed through screen(1) or tmux(1).\n\n## See Also\n\n- screen(1)\n- byobu-config(1)\n- byobu-export(1)\n- byobu-status(1)\n- byobu-status-detail(1)\n\n## Section Outline\n\n- **NAME** (4 lines)\n- **SYNOPSIS** (9 lines)\n- **DESCRIPTION** (11 lines)\n- **BACKGROUND COLORS** (6 lines)\n- **STATUS NOTIFICATIONS** (180 lines)\n- **SESSIONS** (6 lines)\n- **WINDOWS** (39 lines)\n- **UNITS OF MEASURE** (10 lines)\n- **KEYBINDINGS** (52 lines) — 1 subsections\n  - SCROLLBACK, COPY, PASTE MODES (8 lines)\n- **BUGS** (41 lines)\n- **SEE ALSO** (1 lines) — 1 subsections\n  - enable(1), byobu-launch(1), byobu-select-backend(1), tmux(1) (3 lines)\n- **AUTHOR** (12 lines)\n\n## Full Content\n\n### NAME\n\nbyobu  -  wrapper  script for seeding a user's byobu configuration and launching a text based\nwindow manager (either screen or tmux)\n\n### SYNOPSIS\n\nbyobu [options]\n\nbyobu-screen [screen options]\n\nbyobu-tmux [tmux options]\n\nOptions to byobu are simply passed through screen(1) or tmux(1).\n\n### DESCRIPTION\n\nbyobu is a script that launches a text based window manager (either screen(1) or tmux(1))  in\nthe byobu configuration.  This enables the display of system information and status notifica‐\ntions within two lines at the bottom of the screen session. It also enables  multiple  tabbed\nterminal sessions, accessible through simple keystrokes.\n\nbyobu  currently  defaults to using tmux(1) (if present) as the backend, however, this can be\noverridden with the byobu-select-backend(1) utility.\n\nNote that BYOBUCONFIGDIR=$XDGCONFIGHOME/byobu if defined, and $HOME/.byobu otherwise.\n\n### BACKGROUND COLORS\n\nThe background colors of the byobu  status  lines  can  be  adjusted  by  editing  the  files\n$HOME/.byobu/color (for byobu-screen) and $HOME/.byobu/color.tmux (for byobu-tmux).  The com‐\nmand Ctrl-Shift-F5 will change the background to a randomly selected color  when  running  in\nbyobu-tmux mode.  Simply remove those files to return to the default color configuration.\n\n### STATUS NOTIFICATIONS\n\nbyobu  supports a number of unique and interesting status notifications across the lowest two\nlines in the screen.  Each status notification item is  independently  configurable,  enabled\nand  disabled  by the configuration utility.  The guide below helps identify each status item\n(in alphabetical order):\n\napport - symbol displayed if there are pending crash reports; {!}  symbol  displayed  on  the\nlower bar toward the left, in black on an orange background\n\narch  -  system architecture; displayed on the lower bar toward the left, in the default text\ncolor on the default background color\n\nbattery - battery information; display on the lower bar toward the right;  -  indicates  dis‐\ncharging, + indicates charging, = indicates fully charged;  when charging or discharging, the\ncurrent battery capacity as a percentage is displayed;  the colours green,  yellow,  and  red\nare  used  to give further indication of the battery's charge state; you may override the de‐\ntected battery by setting BATTERY=/proc/acpi/battery/BAT0 in $BYOBUCONFIGDIR/statusrc\n\ncpucount - the number of cpu's or cores on the system; displayed in the lower bar toward the\nright in the default text color on the default background, followed by a trailing 'x'\n\ncpufreq  -  the  current  frequency of the cpu in GHz; displayed in the lower bar toward the\nright in white text on a light blue background\n\ncputemp - the cpu temperature in Celsius (default) or Fahrenheit, configure TEMP=F or TEMP=C\nin  $BYOBUCONFIGDIR/statusrc; displayed in the lower bar toward the right in yellow text on\na black background; you may override the detected cpu temperature  device  by  setting  MONI‐\nTOREDTEMP=/proc/acpi/whatever in $BYOBUCONFIGDIR/statusrc\n\ncustom  - user defined custom scripts; must be executable programs of any kind in $BYOBUCON‐\nFIGDIR/bin; must be named NNAME, where N is the frequency in seconds to refresh the  status\nindicator,  and  NAME  is  the  name  of the script; N should not be less than 5 seconds; the\nscript should echo a small amount of text to standard out, standard error is  discarded;  the\nindicator  will be displayed in the lower panel, in default colors, unless you manually spec‐\nify the colors in your script's output; BEWARE, cpu-intensive custom scripts may impact  your\noverall  system performance and could upset your system administrator!  In fact, you can eas‐\nily copy and modify any status  script  usually  found  in  /usr/lib/byobu/*  to  your  local\n$HOME/.byobu/ directory.\nExample: $BYOBUCONFIGDIR/bin/1000uname\n#!/bin/sh\nprintf \"\\005{= bw}%s\\005{-}\" \"$(uname -r)\"\n\n\ndate - the system date in YYYY-MM-DD format, or you can set this to any valid strftime(3) you\nlike in $BYOBUCONFIGDIR/datetime; displayed in the lower on the far right  in  the  default\ntext color on the default background\n\ndisk  -  total disk space available and total used on / directory; displayed in the lower bar\non the far right in white text on a light purple background; override the  default  directory\nby   specifying  an  alternate  mount  point  with  MONITOREDDISK=/wherever  in  $BYOBUCON‐\nFIGDIR/statusrc\n\ndiskio - instantaneous read/write througput in kB/s or MB/s over the last  3  seconds;  dis‐\nplayed  in  the  lower bar toward the right in white text on a light purple background with a\nleading '<' sign indicating 'read speed' and '>' sign indicating 'write speed'; override  the\ndefault  monitored  disk  by specifying an alternate device with MONITOREDDISK=/dev/sdb, and\noverride the default DISKIOTHRESHOLD=50 (kB/s) in $BYOBUCONFIGDIR/statusrc\n\ndistro - OS/distribution name of the release running on the current  system  as  reported  by\nlsbrelease(1)  or  /etc/issue; displayed in the lower bar in bold black text toward the left\non a grey background; you may override the detected  release  with  DISTRO=Whatever  in  $BY‐\nOBUCONFIGDIR/statusrc\n\nentropy - a count of the system's current entropy in bytes; displayed in the lower bar toward\nthe right in yellow text on a dark grey background; there is a leading 'e' to  indicate  'en‐\ntropy'\n\nraid  -  note very prominently if there is a RAID failure detected, in red blinking text on a\nwhite background; the term 'RAID' notes that there is something wrong with the RAID,  and  if\nthere is a rebuild/resync in progress, the percent complete is also shown\n\nfanspeed - cpu or system fan speed as reported by lm-sensors; displayed in the lower bar to‐\nward the right in black text on a grey background; there is a trailing 'rpm' for  units;  you\nmay  override  the  detected  fan  by setting FAN=/sys/path/to/your/fan1input in $BYOBUCON‐\nFIGDIR/statusrc\n\nhostname - the hostname of the system; displayed in the upper bar on the far  right  in  bold\nblack text on a grey background; there is a leading '@' symbol if the username status is also\nenabled\n\nipaddress - the IPv4 address of the system in dotted decimal form; displayed  in  the  upper\nbar  on  the far right in bold black text on a grey background;  you can override and display\nyour IPv6 address by setting 'IPV6=1', and you can show your external ip address  by  setting\n'IPEXTERNAL=1' in $BYOBUCONFIGDIR/statusrc\n\nipaddress4  -  the IPv4 address of the system in dotted decimal form; displayed in the upper\nbar on the far right in bold black text on a grey background;  you can show your external  ip\naddress by setting 'IPEXTERNAL=1' in $BYOBUCONFIGDIR/statusrc\n\nipaddress6  - the IPv6 address of the system; displayed in the upper bar on the far right in\nbold black text on a grey background;  you can show  your  external  ip  address  by  setting\n'IPEXTERNAL=1' in $BYOBUCONFIGDIR/statusrc\n\nloadaverage - the system load average over the last 1 minute; displayed in the lower bar to‐\nward the right in black text on a yellow background\n\nlogo - an approximation of the current operating system's logo; displayed in the lower bar on\nthe  far  left;  you  may  customize this logo by setting a chosen logo with LOGO=:-D in $BY‐\nOBUCONFIGDIR/statusrc\n\nmail - system mail for the current user; the letter '[M]' is displayed in the lower  bar  to‐\nward the left in black text on a grey background\n\nmemory - total memory available and used percentage in the system; displayed in the lower bar\ntoward the right in white text on a green background\n\nmenu - a simple indicator directing new users to use the F9 keybinding to  access  the  byobu\nmenu\n\nnetwork  - instantaneous upload/download bandwidth in [GMk]bps over the last 3 seconds; noth‐\ning is displayed if traffic is 0; displayed in the lower bar toward the left in white text on\na  purple  background with a leading '^' sign indicating 'up' and 'v' sign indicating 'down';\noverride the default interface by  specifying  an  alternate  interface  with  MONITOREDNET‐\nWORK=eth1,  and  override the default units (bits) with NETWORKUNITS=bytes, and override the\ndefault NETWORKTHRESHOLD=20 (kbps) in $BYOBUCONFIGDIR/statusrc\n\nnotifyosd - Send on-screen notification messages to screen's notification buffer\n\nprocesses - total number of processes running on the system; displayed in the  lower  bar  in\nwhite text on a dark yellow background with a trailing '&' indicating 'background processes'\n\nrebootrequired - symbol present if a reboot is required following a system update; displayed\nin the lower bar white text on a blue background  by  the  symbol  '(R)';  additionally,  re‐\nbootrequired  will print '<F5>' in white text on a blue background, if Byobu requires you to\nreload your profile to affect some changes; it will also detect if your system  is  currently\nin  powernap(8)  state and if so print '.zZ'; if your system is currently performing an unat‐‐\ntended-upgrade(1) you will see a white warning sign on a red background.\n\nrelease - OS/distribution name of the release running on the current system  as  reported  by\nlsbrelease(1)  or  /etc/issue; displayed in the lower bar in bold black text toward the left\non a grey background; you may override the detected release  with  RELEASE=Whatever  in  $BY‐\nOBUCONFIGDIR/statusrc;  you  may also abbreviate the release string to N characters by set‐\nting RELEASEABBREVIATED=N in $BYOBUCONFIGDIR/statusrc\n\nservices - users can configure a list of services to monitor, define the SERVICES variable in\n$BYOBUCONFIGDIR/statusrc,  a  whitespace separated of services, each service should include\nthe init name of the service, then a pipe, and then an abbreviated name or symbol to  display\nwhen  running  (e.g.  SERVICES=\"ssh|ssh apache2|http\"); displayed in the lower bar toward the\ncenter in cyan on a white background\n\nsession - byobu session name (only supported in byobu-tmux(1)); displayed in the lower bar on\nthe left in underlined black text on a white background\n\nswap  -  total swap space and total used as a percentage of the total available; displayed in\nthe lower bar toward the right in black text on a light green background with a trailing  '%'\nsign\n\ntime  -  the  system  time  in HH:MM:SS format (by default), or you can set this to any valid\nstrftime(3) you like in $BYOBUCONFIGDIR/datetime; displayed in the lower  bar  on  the  far\nright in the default text and default background colors\n\ntimebinary  -  only  for the hard core geek, the local system time in binary; requires UTF-8\nsupport in a VERY recent version of GNU Screen; displayed in the lower bar on the  far  right\nin the default text and background colors\n\ntimeutc  -  the UTC system time in HH:MM format; displayed in the lower bar on the far right\nin dark text on a light background\n\nupdatesavailable - the number of updates available on the system; displayed in the lower bar\ntoward  the  right in white text on a red background with a trailing '!' sign; if any updates\nare marked 'security updates', then there will be a total of two trailing exclamation points,\n'!!'\n\nuptime - the total system uptime since last boot; displayed in the lower bar toward the right\nin blue text on a grey background\n\nusers - the number of remote users logged into the system via sshd, empty if  0  users;  dis‐\nplayed in the lower bar toward the right in red text on a grey background with a trailing '#'\nsign; set USERSDISTINCT=1 to instead count the number of distinct users logged into the sys‐\ntem (rather than open ssh sessions)\n\nwhoami  - the name of the user who owns the screen session; displayed in the upper bar toward\nthe far right in bold black text on a grey background\n\nwifiquality - the connection rate and signal quality of the wifi  connection;  displayed  in\nthe  lower bar toward the right in black text on a cyan background; the connection rate is in\n'Mb/s' and the signal quality is as a percentage with a trailing '%';  override  the  default\ninterface  by  specifying  an alternate interface with MONITOREDNETWORK=wlan0 in $BYOBUCON‐\nFIGDIR/statusrc\n\n### SESSIONS\n\nByobu name screen sessions \"byobu\", if unspecified.  To hide sessions from  byobu-select-ses‐‐\nsion(1), prepend a \".\" to the beginning of the session name, like:\n\nbyobu -S .hidden\n\n### WINDOWS\n\nEach  open  window  in  the screen session is displayed in the upper bar toward the far left.\nThese are numbered, and include indicators as to activity in the window  (see  \"activity\"  in\nscreen(1)  and  tmux(1) for symbol definitions).  The current active window is highlighted by\ninverting the background/text from the rest of the window bar.\n\nUsers can create a list of windows to launch at startup in $BYOBUCONFIGDIR/windows and $BY‐\nOBUCONFIGDIR/windows.tmux.  This file is the same syntax as ~/.screenrc and ~/.tmuxrc, each\nline specifying a window, as described in screen(1) or tmux(1).\n\nUser can also launch Byobu with unique window sets.  Users can  store  these  as  $BYOBUCON‐\nFIGDIR/windows.[NAME]  and  $BYOBUCONFIGDIR/windows.tmux.[NAME], and launch Byobu with the\nenvironment variable BYOBUWINDOWS=NAME.\n\nFor example:\n$ cat $BYOBUCONFIGDIR/windows.sshsessions\nscreen -t localhost bash\nscreen -t aussie ssh root@aussie\nscreen -t beagle ssh root@beagle\nscreen -t collie ssh root@collie\n\nThen:\n$ BYOBUWINDOWS=sshsessions byobu\n\nFor example:\n$ cat $BYOBUCONFIGDIR/windows.tmux.split4\nnew-session 'bash' ;\nnew-window -n term1 ;\nnew-window -n term2 ;\nnew-window -n ssh ssh 10.9.8.7 ;\nsplit-window ;\nsplit-window ;\nsplit-window ;\nselect-layout tiled ;\nselect-pane -t 0\n\nThen:\n$ BYOBUWINDOWS=split4 byobu\n\n### UNITS OF MEASURE\n\nbyobu uses binary for capacity measurements of KB, MB, GB, and TB.  This means  multiples  of\n1024  rather than multiples of 1000, in accordance with JEDEC Standard 100B.01 for memory ca‐\npacity measurements.  See:\n* http://en.wikipedia.org/wiki/JEDECmemorystandards\n\nbyobu uses decimal for measurements of network  data  transfer,  meaning  multiple  of  1000,\nrather than 1024.  See:\n* http://en.wikipedia.org/wiki/Datarateunits\n\n### KEYBINDINGS\n\nbyobu  keybindings  can be user defined in /usr/share/byobu/keybindings/ (or within .screenrc\nif byobu-export was used). The common key bindings are:\n\nF2 - Create a new window\n\nF3 - Move to previous window\n\nF4 - Move to next window\n\nF5 - Reload profile\n\nF6 - Detach from this session\n\nF7 - Enter copy/scrollback mode\n\nF8 - Re-title a window\n\nF9 - Configuration Menu\n\nF12 -  Lock this terminal\n\nshift-F2 - Split the screen horizontally\n\nctrl-F2 - Split the screen vertically\n\nshift-F3 - Shift the focus to the previous split region\n\nshift-F4 - Shift the focus to the next split region\n\nshift-F5 - Join all splits\n\nctrl-F6 - Remove this split\n\nctrl-F5 - Reconnect GPG and SSH sockets\n\nshift-F6 - Detach, but do not logout\n\nalt-pgup - Enter scrollback mode\n\nalt-pgdn - Enter scrollback mode\n\nCtrl-a $ - show detailed status\n\nCtrl-a R - Reload profile\n\nCtrl-a ! - Toggle key bindings on and off\n\nCtrl-a k - Kill the current window\n\nCtrl-a ~ - Save the current window's scrollback buffer\n\n#### SCROLLBACK, COPY, PASTE MODES\n\nEach window in Byobu has up to 10,000 lines of scrollback history, which you  can  enter  and\nnavigate  using  the alt-pgup and alt-pgdn keys.  Exit this scrollback mode by hitting enter.\nYou can also easily copy and paste text from scrollback mode.  To do so, enter scrollback us‐\ning   alt-pgup   or   alt-pgdn,   press   the   spacebar  to  start  highlighting  text,  use\nup/down/left/right/pgup/pgdn to select the text, and press enter to copy the text.   You  can\nthen paste the text using alt-insert or ctrl-a-].\n\n### BUGS\n\nFor Byobu colors to work properly, older versions of GNU Screen require a 1-line patch to ad‐\njust MAXWINMSGREND in screen.c.  The change is in GNU Screen's upstream source control sys‐\ntem  as  of  2010-01-26,  but  GNU  Screen has not released a new upstream version in several\nyears.  You can disable colors entirely by  setting  MONOCHROME=1  in  $BYOBUCONFIGDIR/sta‐\ntusrc.  For more information, see:\n* http://savannah.gnu.org/bugs/?22146\n\nPuTTY  users  have  reported  that the F2, F3, and F4 shortcut keys are not working properly.\nPuTTY sends the same escape sequences as the linux console for F1-F4 by default.  You can fix\nthis  problem  in  the  PuTTY  config, Terminal -> Keyboard -> Function keys: Xterm R6.  See:\nhttp://www.mail-archive.com/screen-users@gnu.org/msg01525.html\n\nPuTTY users should configure enable UTF-8 characters in order to fix status  refresh  issues.\nYou can fix this problem in the PuTTY configuration, Window -> Translation: select UTF-8.\n\nPuTTY  users  should avoid resizing their window to one character tall, as this can sometimes\ncrash byobu-screen.\n\nApple Mac OSX terminal users have reported 'flashing text'.  You can fix this in the advanced\nsettings of the terminal application, with 'Declare Terminal As: xterm-color'.\n\nApple Mac keyboard users may need to specify a vt100 terminal by adding this to your OSX pro‐\nfile, in order to get Byobu's function keys and colors to work:\nalias ssh='TERM=vt100 ssh'\n\nUsers of a non-UTF-8 locale (such as csCZ charset ISO-8859-2), may need to add \"defutf8 off\"\nto ~/.screenrc, if some characters are rendering as \"?\".\n\nUsers  who  customize  their  PS1  prompt  need to put this setting in ~/.bashrc, rather than\n~/.profile, in order for it to work correctly with Byobu.\n\nIf you run byobu(1) under sudo(8), you must use the -H option, such that the user's $HOME di‐\nrectory environment variable is set properly.  Otherwise, byobu(1) will create a bunch of di‐\nrectories in the $SUDOUSER's $HOME, but will be owned by root.  To prevent this from happen‐\ning, byobu(1) will simply refuse to run if $USER does not own $HOME.\n\nByobu  requires  a  suitable ulimit(3) values to run.  If you get an error at startup saying,\n'pipe: too many open files', then check your ulimit -a values, as your \"open files\"  or  \"max\nuser processes\" are too low.  In this case, you will probably need to run simple screen(1)\n\n### SEE ALSO\n\nscreen(1),  byobu-config(1), byobu-export(1), byobu-status(1), byobu-status-detail(1), byobu-\n\n#### enable(1), byobu-launch(1), byobu-select-backend(1), tmux(1)\n\nhttp://byobu.org\n\n### AUTHOR\n\nThis manpage and the utility were written by Dustin Kirkland <kirkland@byobu.org> for  Ubuntu\nsystems (but may be used by others).  Permission is granted to copy, distribute and/or modify\nthis document and the utility under the terms of the GNU General Public  License,  Version  3\npublished by the Free Software Foundation.\n\nThe  complete  text  of  the GNU General Public License can be found in /usr/share/common-li‐\ncenses/GPL on Debian/Ubuntu systems, or in /usr/share/doc/fedora-release-*/GPL on Fedora sys‐\ntems, or on the web at http://www.gnu.org/licenses/gpl.txt.\n\n\n\nbyobu                                       19 June 2009                                    byobu(1)\n\n"
        }
    ],
    "structuredContent": {
        "command": "byobu",
        "section": "1",
        "mode": "man",
        "summary": "byobu  -  wrapper  script for seeding a user's byobu configuration and launching a text based window manager (either screen or tmux)",
        "synopsis": "byobu [options]\nbyobu-screen [screen options]\nbyobu-tmux [tmux options]\nOptions to byobu are simply passed through screen(1) or tmux(1).",
        "flags": [],
        "examples": [],
        "see_also": [
            {
                "name": "screen",
                "section": "1",
                "url": "https://www.chedong.com/phpMan.php/man/screen/1/json"
            },
            {
                "name": "byobu-config",
                "section": "1",
                "url": "https://www.chedong.com/phpMan.php/man/byobu-config/1/json"
            },
            {
                "name": "byobu-export",
                "section": "1",
                "url": "https://www.chedong.com/phpMan.php/man/byobu-export/1/json"
            },
            {
                "name": "byobu-status",
                "section": "1",
                "url": "https://www.chedong.com/phpMan.php/man/byobu-status/1/json"
            },
            {
                "name": "byobu-status-detail",
                "section": "1",
                "url": "https://www.chedong.com/phpMan.php/man/byobu-status-detail/1/json"
            }
        ],
        "section_outline": [
            {
                "name": "NAME",
                "lines": 4,
                "subsections": []
            },
            {
                "name": "SYNOPSIS",
                "lines": 9,
                "subsections": []
            },
            {
                "name": "DESCRIPTION",
                "lines": 11,
                "subsections": []
            },
            {
                "name": "BACKGROUND COLORS",
                "lines": 6,
                "subsections": []
            },
            {
                "name": "STATUS NOTIFICATIONS",
                "lines": 180,
                "subsections": []
            },
            {
                "name": "SESSIONS",
                "lines": 6,
                "subsections": []
            },
            {
                "name": "WINDOWS",
                "lines": 39,
                "subsections": []
            },
            {
                "name": "UNITS OF MEASURE",
                "lines": 10,
                "subsections": []
            },
            {
                "name": "KEYBINDINGS",
                "lines": 52,
                "subsections": [
                    {
                        "name": "SCROLLBACK, COPY, PASTE MODES",
                        "lines": 8
                    }
                ]
            },
            {
                "name": "BUGS",
                "lines": 41,
                "subsections": []
            },
            {
                "name": "SEE ALSO",
                "lines": 1,
                "subsections": [
                    {
                        "name": "enable(1), byobu-launch(1), byobu-select-backend(1), tmux(1)",
                        "lines": 3
                    }
                ]
            },
            {
                "name": "AUTHOR",
                "lines": 12,
                "subsections": []
            }
        ]
    }
}