discus

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 discus
   • what discus affects
   • setup requirements
   • beginning with discus
4. usage – configuration options and additional functionality
5. reference – an under-the-hood peek at what the module is doing and how
6. limitations – OS compatibility, etc.
7. development – guide for contributing to the module

overview

This module installs and configures discus(1) – a prettier df(1).

module description

This module installs discus.

setup

what discus affects

• installs discus package
• overwrite /etc/discusrc

setup requirements

This module requires the future parser. (future for PP 3.8 users).

The default template uses $server_facts[environment]. In Puppet 4.x you had to enable trusted_server_facts.

beginning with discus

Just installing discus and overwrite /etc/discusrc with default values.

    class some_tools {
        class { 'discus'
        }
    }

usage

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

    class some_tools {
        class { 'discus':
            latest_instead_of_present     => true,
            discusrc_akabytes             => ['KiB', 'MiB', 'GiB', 'TiB', 'PiB'],
            discusrc_graph_char           => '#',
            discusrc_graph_fill           => '.',
            # unfortunately discus(1) does not exclude tmpfs and alike by itself
            discusrc_skip_list            => [
                    '/dev/',
                    '/dev/pts/',
                    '/dev/hugepages/',
                    '/dev/mqueue/',
                    '/proc/',
                    '/proc/usb/',
                    '/sys/',
                    '/sys/fs/cgroup/',
                    '/sys/fs/cgroup/systemd/',
                    '/sys/fs/pstore/',
                    '/sys/fs/cgroup/perf_event/',
                    '/sys/fs/cgroup/blkio/',
                    '/sys/fs/cgroup/devices/',
                    '/sys/fs/cgroup/memory/',
                    '/sys/fs/cgroup/cpu,cpuacct/',
                    '/sys/fs/cgroup/hugetlb/',
                    '/sys/fs/cgroup/net_cls,net_prio/',
                    '/sys/fs/cgroup/freezer/',
                    '/sys/fs/cgroup/cpuset/',
                    '/proc/sys/fs/binfmt_misc/',
                    '/sys/kernel/debug/',
                    '/sys/kernel/security/',
                    '/sys/fs/fuse/connections/',
                    '/proc/fs/nfsd/',
                    '/run/rpc_pipefs/',
                ],
            discusrc_stat_prog            => '/usr/bin/stat -ft',
            discusrc_color_header         => 'magenta',
            discusrc_color_safe           => 'cyan',
            discusrc_color_warning        => 'bold + yellow',
            discusrc_color_danger         => 'reverse + bold + red',
            discusrc_author               => 'Kai Burghardt <kburgha at gwdg.de>',
        }
    }

Since discusrc can't hold unicode characters, a block display graph can be achieved by the following:

    discusrc_graph_char           => ' ',
    discusrc_graph_fill           => '_',
    discusrc_color_safe           => 'on_green',
    # the asterisk '*' as eighth character is hard coded
    # -> make it _visually_ disappear
    discusrc_color_warning        => 'yellow + on_yellow',
    discusrc_color_danger         => 'on_red'

Note: The graph looks stupid once colors are disabled by -c command line flag.

Both examples are included in examples/.

reference

classes

public classes

• discus: holds the class parameter types and contains the other classes
• discus::params: holds default values (there are also data() and params() functions)

private classes

• discus::install: installs the discus package
• discus::config: distributes the configuration file

parameters

latest_instead_of_present

• abstract: whether packages installed by this module are latest instead of just present

• behavior: Package['discus'] is present by default. Set this parameter to true, to ensure it's latest.

• allowed values: false, true

• default value: false

discusrc_path

• abstract: Where the discusrc goes.

• allowed values: a string the underlying file resource accepts

• default: '/etc/discusrc'

discusrc_mode

• abstract: Optionally what file mode the global discusrc has.

• allowed values: a mode the underlying file resource accepts

• default value: '0644'

discusrc_owner

• abstract: Optionally whom the discusrc belongs to.

• allowed values: a owner string the underlying file resource accepts

• default value: 'root'

discusrc_group

• abstract: Optionally which group the discusrc belongs to.

• allowed values: a group string the underlying file resource accepts

• default value: 'root'

discusrc_template

• abstract: What template to use to render a discusrc

• allowed values: a string

• default: 'discus/discusrc.erb'

discusrc_akabytes

• abstract: An array of strings to label kilo-, mega-, and gigabytes and beyond.

• allowed values: a non-empty array of non-empty strings

• default: ['KB', 'MB', 'GB', 'TB', 'PB', 'EB']

discusrc_color

• abstract: Whether to use colors.

• allowed values: false, true

• default value: true

discusrc_divisor

• abstract: The exponent determing the divisor if smart formatting (dynamically chosing a divisor) is disabled.

• allowed values: a non-negative integer

• default: 1

discusrc_graph

• abstract: Whether to visualize disk usage by a bar graph (true) or to show mount points instead (false).

• allowed values: false, true

• default value: true

discusrc_graph_char

• abstract: The character to print symbolizing used space.

• allowed values: a character

• default: '*'

discusrc_graph_fill

• abstract: The character to print for free space.

• allowed values: a character

• default: '-'

discusrc_mtab

• abstract: Where mtab is located at.

• allowed values: a string

• default: '/etc/mtab'

discusrc_places

• abstract: The number of post decimal point places to show.

• allowed values: an integer

• default value: 2

discusrc_placing

• abstract: This is an internal setting.

discusrc_skip_list

• abstract: Which mounts to ignore.

• allowed values: an array of non-empty strings

• default: ['/dev/pts', '/proc', '/dev', '/proc/usb', '/sys']

discusrc_smart

• abstract: Dynamically choose prefix.

• allowed values: false, true

• default: true

discusrc_stat_prog

• abstract: What program to use if Python's statvfs module's absent.

• allowed values: a string

• default: 'stat -ft'

discusrc_reserved

„Takes into account even the reserved space to root; it will be counted in percentage and in available columns only (used is for real used space).“ This is an internal setting (it was not provided by the discusrc sample).

discusrc_color_header

• abstract: The color for the table header.

• allowed values: a string

• default value: 'blue'

discusrc_color_normal

• abstract: The default color to print everything what's not colored by other terms.

• allowed values: a string

• default value: 'normal'

discusrc_color_safe

• abstract: The color used to print safe amount of used space.

• allowed value: a string

• default value: 'normal'

discusrc_color_warning

• abstract: The color used to print the two characters before the last ones indiciting a disk with less space.

• allowed values: a string

• default value: 'bold + yellow'

discusrc_color_danger

• abstract: The color used to print the last two characters indicating a pretty full disk.

• allowed values: a string

• default value: 'bold + red'

discusrc_author

• abstract: What to print as author comment in the discusrc. It says auth[or] but it's generally considered as a responsibility tag.

• allowed values: a string

• default value: 'Kai Burghardt <wiz at KaiBurghardt.de>'

limitations

• This module's been used with stable Debian and Ubuntu releases.
• It can't uninstall discus(1) or its changes.
• Unfortunately /etc/discusrc can't hold unicode characters since discus treats it as an ASCII file (I've tried PEP0263).
• discus(1) does not color the whole graph bar in one color but only the last few characters once it “realizes” the disk's full (compare /usr/bin/discus [a Python script] itself).
• discus(1) itself does not hold fall-back configuration values. All values originate from discusrc. So ensure those are valid.
• For coloring ANSI coloring escape sequences are used. You cannot change them with this module though the discusrc gives the opportunity.

development

Drop me a line Kai Burghardt <wiz?KaiBurghardt.de> (GnuPG usage advised). This module is primarily targeted for already packaged stable open source Puppet versions.