byobu

table of Contents

1. overview
2. module description – what the module does and why it is useful
3. setup – the basics of getting started with byobu
   • what byobu affects
   • setup requirements
   • beginning with byobu
4. usage – configuration options and additional functionality
5. reference – an under-the-hood peek at what the module is doing and how
   • classes
   • parameters
   • variables
6. limitations – OS compatibility, known issues, etc.
7. links – external references
8. index (alphabetical parameter list)
9. intellectual property rights

overview

Install byobu(1) and (your favorite terminal multiplexer) screen(1) (default) or tmux(1) (meanwhile the normally distributed default).

module description

This module installs byobu and your selected terminal multiplexer which is either screen(1) (default) or tmux(1). It optionally lets you configure it by overwriting various /usr/share/byobu/… and /usr/lib/byobu/… files since any more specific configuration can't be handled via /etc/byobu/*.

setup

what byobu affects

• package: byobu (default: ensure => present)
• package: screen (default: ensure => present)
• package: tmux (optional)
• file: /etc/byobu/backend (fill with byobu_terminal_multiplexer)
• file: /usr/lib/byobu/arch (optional)
• file: /usr/lib/byobu/hostname (optional)
• file: /usr/share/byobu/keybindings/common (optional)
• file: /usr/share/byobu/keybindings/f-keys.screen (optional)
• file: /usr/share/byobu/keybindings/f-keys.tmux (optional)
• file: /usr/share/byobu/status/status (optional)
• file: /var/cache/debconf/byobu.preseed
• /var/cache/debconf/config.dat (optionally, modified by executing debconf-set-selections(1))

setup requirements

The future parser is required. (instructions for PP 3.8 users)

The templates use the variable $server_facts. In Puppet 4.x you had to enable that variable via the trusted_server_facts setting.

beginning with byobu

Install screen(1) and then byobu(1) and don't set up “launch by default” (automatic start of byobu at login):

class { 'byobu':
}

usage

installing

See also § beginning with byobu.

This is how I set up my byobu(1):

class terminal_multiplexer {
    class { 'byobu':
        byobu_terminal_multiplexer    => 'screen',
        byobu_launch_by_default       => false,
        launch_by_default_ensure_set  => ($facts['os']['family'] == 'Debian'),
        let_screen_and_tmux_coexist   => false,
        purge_instead_of_remove       => true,
        # we've got unattended-upgrade(8) for this
        latest_instead_of_present     => false,
        overwrite_usr_config          => true,
        overwrite_various_status      => true,
        byobu_control_a_behavior      => 'screen',
        status_screen_upper_left      => {
            'color'                         => true,
        },
        status_screen_upper_right     => {
            'color'                         => true,
            'menu'                          => false,
            'date'                          => true,
            'time'                          => true,
            'time_utc'                      => false,
        },
        status_screen_lower_left      => {
            'color'                         => true,
            'logo'                          => false,
            'distro'                        => false,
            'release'                       => false,
            'arch'                          => true,
            'reboot_required'               => true,
            'updates_available'             => true,
            'services'                      => true,
            'users'                         => true,
            'mail'                          => false,
            'uptime'                        => true,
            'processes'                     => false,
            'disk'                          => false,
            'raid'                          => false,
            'disk_io'                       => true,
        },
        status_screen_lower_right     => {
            'color'                         => true,
            'custom'                        => true,
            'entropy'                       => false,
            'apport'                        => false,
            'ec2_cost'                      => false,
            'rcs_cost'                      => false,
            'battery'                       => true,
            'swap'                          => false,
            'memory'                        => false,
            'fan_speed'                     => false,
            'cpu_temp'                      => true,
            'cpu_count'                     => true,
            'cpu_freq'                      => true,
            'load_average'                  => true,
            'wifi_quality'                  => true,
            'network'                       => true,
            'ip_address'                    => true,
            'whoami'                        => true,
            'hostname'                      => true,
        },
    }
}

Some examples are included in examples/.

uninstalling

Remove byobu(1), tmux(1) and screen(1) and /var/cache/debconf/byobu.preseed:

class { 'byobu':
    let_screen_and_tmux_coexist => false,  # yes, this says /false/
    byobu_version               => absent,
    screen_version              => absent,
    tmux_version                => absent,
}

Purge byobu(1) and tmux(1) and remove /var/cache/debconf/byobu.preseed, but leave screen(1) as it is, installed or un-installed.

class { 'byobu':
    byobu_terminal_multiplexer => 'tmux',
    byobu_version              => purged,
    tmux_version               => purged,
}

reference

classes

public classes

• byobu: the basis class
• byobu::params: default values for byobu

private classes

• byobu::install: installs byobu(1) optionally with the desired terminal multiplexer
• byobu::config: configures byobu(1)

parameters

For an alphabetical list, see § index.

byobu_terminal_multiplexer

Byobu works with both good ole screen(1) and the younger tmux(1).

Specifying none of them lets the installer automatically choose one of them. [Meanwhile the distributed default selection is tmux(1).] Also by specifying none of them screen_version and tmux_version won't have any effect either.

If overwrite_usr_config is true then this parameter also determines the default keybinding set (f-keys.screen or f-keys.tmux) sourced in /usr/share/byobu/keybindings/common. The distributed default would be f-keys.screen for both screen(1) and tmux(1).

• considered values: 'screen' and 'tmux'
• allowed values: 'screen', 'tmux' and undef
• default: 'screen'

let_screen_and_tmux_coexist

You may or may not want to let the users on your system choose which terminal multiplexer to use with byobu(1).

If you set this parameter to true, only the package determined by byobu_terminal_multiplexer will be managed by this module. Thus the other terminal multiplexer – which maybe is installed on the specific machine – won't be removed.

If you set this parameter to false, and for instance byobu_terminal_multiplexer is set to 'screen', then tmux(1) is gonna be removed (or purged in case of purge_instead_of_remove).

• considered values: true and false
• allowed values: true and false
• default: true

byobu_control_a_behavior

This parameter only has an effect if overwrite_usr_config is set to true.

Normally, byobu(1) asks the user once he pressed ^a his first time, whether he wants to use ^a as the normal screen(1)-escape sequence, or as the emacs(1)-“editor” sequence for jumping to the begin of a line. This behavior is achieved by binding ^a to call /usr/bin/byobu-ctrl-a, which then installs an override of the global ^a setting (to run byobu-ctrl-a(1)) with the desired behavior on a per-user-basis (by re-mapping ^a in ~/.byobu/keybindings).

By setting this parameter to either 'screen' or 'emacs' the users won't have this opportunity except by manually invoking byobu-ctrl-a(1).

By setting this to any other value the distributed default to ask the user is established (again, provdided overwrite_usr_config is true, otherwise we don't change anything).

And yes, you can use screen(1)'s control-A behavior in tmux(1). There's no connection between them.

• considered values: 'screen' and 'emacs' (provided that overwrite_usr_config is true)
• allowed values: 'screen', 'emacs' and undef
• default: 'screen'

byobu_launch_by_default

Install byobu-launcher(1) in /etc/profile.d/ or don't. This setting is managed via debconf(7) and the package installation responsefile. The byobu module does not manage any File resources in /etc/profile.d/.

• considered values: false and true
• allowed values: false and true
• default: false

launch_by_default_ensure_set

This parameter ensures that the desired value determined by byobu_launch_by_default isn't set only during an installation of byobu(1) facilitated by puppet, but also on systems, which got byobu(1) already installed. Those may have set an other value than you wish.

This triggers runs of debconf-set-selection(1) and dpkg-reconfigure(8) accordingly.

• considered values: false and true
• allowed values: false and true
• default: false

purge_instead_of_remove

Setting this to true ensures packages which are going to be removed (by this module) to be purged instead of just being absent.

This doesn't have an effect, if for the package, which shall be removed, the corresponding variable byobu_version, screen_version or tmux_version has a defined value.

• considered values: false and true (unless explicitely forced version)
• allowed values: false and true
• default: false

latest_instead_of_present

Setting this to true ensures packages, which are going to be installed, to be latest instead of just present.

This doesn't have an effect, if for the package, which shall be installed, the corresponding variable byobu_version, screen_version or tmux_version has a defined value.

• considered values: false and true (unless a version's been specified)
• allowed values: false and true
• default: false

overwrite_usr_config

Unfortunately byobu(1) doesn't give any chance for further system-wide configuration in the /etc/byobu/ directory except for selecting the default backend ('screen' or 'tmux').

This forces me to overwrite some configuration files in /usr/share/byobu/ which ain't best practice at all. Either that's been done so to reduce complexity or it's the philosophy of byobu(1) to supply a uniform environment on all machines. I dunno. But I won't start distributing my own byobu version just because of four or five files, eh?

If you wanna enable various module's features set this to true. Which features are affected stands at the corresponding parameter.

• considered values: false and true
• allowed values: false and true
• default: false

overwrite_various_status

• Some status notifications, others don't, print a final space at the end of the status string. E. g. whoami doesn't but hostname. If you want hostname at the bottom right corner there'd be a blank space. Please lookup, whether your use case is covered.

Set this parameter to true to overwrite some status notification scripts located at /usr/lib/byobu/.

• considered values: false and true
• allowed values: false and true
• default: false

byobu_version

Value for the ensure attribute of the package 'byobu'.

• default: undef

screen_version

Value for the ensure attribute of the package 'screen'.

This parameter only has an effect, if 'screen' is about to be installed or removed at all. Compare description of tmux_version below.

• default: undef

tmux_version

Value for the ensure attribute of the package 'tmux'.

If you wanna install both tmux(1) and screen(1), while the value for byobu_terminal_multiplexer stays 'screen', you've got to set let_screen_and_tmux_coexist to false and tmux_version to present, latest, or some version string. Yeah, that's quite unintuitive, I know.

• default: undef

status_screen_upper_left

→ status_tmux_left

default:

{
    'color'                         => true,
}

status_screen_upper_right

→ status_tmux_left

default:

{
    'color'                         => true,
    'whoami'                        => true,
    'hostname'                      => true,
    'ip_address'                    => true,
    'menu'                          => true,
}

status_screen_lower_left

→ status_tmux_left

default:

{
    'color'                         => true,
    'logo'                          => true,
    'distro'                        => true,
    'release'                       => true,
    'arch'                          => false,
}

status_screen_lower_right

→ status_tmux_left

default:

{
    'color'                         => true,
    'network'                       => true,
    'disk_io'                       => false,
    'custom'                        => true,
    'entropy'                       => false,
    'raid'                          => true,
    'reboot_required'               => true,
    'updates_available'             => true,
    'apport'                        => false,
    'services'                      => false,
    'mail'                          => false,
    'users'                         => true,
    'uptime'                        => true,
    'ec2_cost'                      => false,
    'rcs_cost'                      => false,
    'fan_speed'                     => false,
    'cpu_temp'                      => false,
    'battery'                       => true,
    'wifi_quality'                  => true,
    'processes'                     => false,
    'load_average'                  => true,
    'cpu_count'                     => true,
    'cpu_freq'                      => true,
    'memory'                        => true,
    'swap'                          => false,
    'disk'                          => false,
    'time_utc'                      => false,
    'date'                          => true,
    'time'                          => true,
}

status_tmux_left

Select default status notification for the specific position.

A hash literal is expected like this:

status_screen_upper_right      = {
    'color'                         => true,
    'whoami'                        => true,
    'hostname'                      => true,
    'menu'                          => false,
}

Where the key is the name of the status notification and the value specifies whether it is enabled or disabled. Possible status notifications are usually located at /usr/lib/byobu/.

Note: All available status notifications shall be mentioned, even though they're disabled. This determines the position of the proper status notification, if the individual users decides to enable any of them. That said, listing of all possible status notifications is neither checked or enforced (by this module, and byobu(1) itself seems not to care either).

The status_* parameters only take effect, if overwrite_usr_config is true.

default:

{
    'logo'                          => true,
    'distro'                        => false,
    'release'                       => true,
    'arch'                          => false,
}

status_tmux_right

Since there can be as many tmux_right lines in ~/.byobu/status as you want, this has to be represented somehow, too.

Thus the expected structure of this parameter looks like this:

status_tmux_right              = [
    {
        'time_utc'                      => false,
        'date'                          => true,
        'time'                          => true,
    },
    {
        'time_utc'                      => true,
    },
]

The notes for all the other status parameters are valid here, too.

default:

[
    {
        'network'                       => false,
        'disk_io'                       => false,
        'custom'                        => false,
        'entropy'                       => false,
        'raid'                          => true,
        'reboot_required'               => true,
        'updates_available'             => true,
        'apport'                        => false,
        'services'                      => false,
        'mail'                          => false,
        'users'                         => false,
        'uptime'                        => true,
        'ec2_cost'                      => false,
        'rcs_cost'                      => false,
        'fan_speed'                     => false,
        'cpu_temp'                      => false,
        'battery'                       => false,
        'wifi_quality'                  => false,
        'processes'                     => false,
        'load_average'                  => true,
        'cpu_count'                     => true,
        'cpu_freq'                      => true,
        'memory'                        => true,
        'swap'                          => false,
        'disk'                          => false,
        'whoami'                        => false,
        'hostname'                      => false,
        'ip_address'                    => false,
        'time_utc'                      => false,
        'date'                          => true,
        'time'                          => true,
    }
]

variables

Nothing expected.

limitations

• This module's been used with stable Debian and Ubuntu releases. See metadata.json for more details.
• Some functionality relies on debconf(7).
• Hashes weren't always sorted in ruby. If you're using a pretty old ruby version, hashes might be shuffled each puppet run. This especially concerned the status_* parameters. Upgrade your ruby version, if you're experiencing that File['byobu_status'] changes each puppet run, though you didn't change your manifests.
• If you used once overwrite_usr_config and/or overwrite_various_status and later decide not use their functionality, changes won't (can't) be rolled back. You'd have to reinstall byobu(1) in order to restore the original configuration.

links

• byobu.co – byobu project page (covers BTW, how “byobu” is pronounced)

index

alphabetical parameter list

• byobu_control_a_behavior
• byobu_launch_by_default
• byobu_terminal_multiplexer
• byobu_version
• latest_instead_of_present
• launch_by_default_ensure_set
• let_screen_and_tmux_coexist
• overwrite_usr_config
• overwrite_various_status
• purge_instead_of_remove
• screen_version
• status_screen_lower_left
• status_screen_lower_right
• status_screen_upper_left
• status_screen_upper_right
• status_tmux_left
• status_tmux_right
• tmux_version

intellectual property rights

Default IPR.

2018-02-11 Kai Burghardt <wizEATkaiburghardt.de>

* edited a couple comments
* use $server_facts[environment] instead of $environment
* populated with `puppet module generate` stuff
* extended version requirements specified in metadata.json
* some edits in readme.md

2016-12-04 Kai Burghardt <wizAEDkaiburghardt.de>

* added lint exception statements
* retrieved more recent versions of status source code
* tweaked vim modelines
* confirmed functionality under Debian "Jessie" 8.6 

2016-09-07 Kai Burghardt <wizAETkaiburghardt.de>

* fixed errors in readme.md
* conditional preseed (on Debian platforms only)
* corrected variable name misspelling
* added some explanatory comments into source code

2016-09-04 Kai Burghardt <wizETTkaiburghardt.de>

* initial public release
* exported documentation from init.pp to readme.md and markdowned it
* added datatype restrictions to init.pp
* gathered examples into examples/ directory
* status_tmux_right datatype changed to Hash
* no presets anymore