How to customize i3status on Linux

I3 is one of the most used tiling window managers on Linux. A tiling window manager arranges windows in a non-overlapping way: this allows us to use screen space efficiently, but can require a little bit of time to get used to.

The i3 window manager on Linux is usually installed together with the i3status utility, which can be used to populate supported status bars with information such as memory or CPU usage. In this tutorial we see how to customize i3status and use some of its modules.

In this tutorial you will learn:

• What are the i3status configuration files
• How to customize i3status
• How to use the “disk” module
• How to use the “cpu_usage” module
• How to use the “ethernet” and “wireless” modules
• How to use the “battery” module
• How to use the “memory” module

Software requirements and conventions used

Software Requirements and Linux Command Line Conventions

Category	Requirements, Conventions or Software Version Used
System	Distribution-independent
Software	i3status
Other	None
Conventions	# – requires given linux-commands to be executed with root privileges either directly as a root user or by use of sudo command $ – requires given linux-commands to be executed as a regular non-privileged user

Introduction

During the curse of this tutorial I will assume you already have installed the i3 window manager and have the i3status utility running together with the i3bar, which is the default status bar which comes with i3. Although i3status usually comes with a default configuration, for the sake of clarity we will start from scratch, and populate it with the instructions explained in the tutorial.

The i3status configuration file

To customize i3status we need to operate on its configuration file. The existence of the following files is checked, in order:

1. ~/.config/i3status/config
2. /etc/xdg/i3status/config
3. ~/.i3status.conf
4. /etc/i3status.conf

---

---

We can also use a custom file: all we have to do is to pass its path as argument to the -c option when we invoke i3status. For the sake of this tutorial we will use the ~/.config/i3status/config file,  in order to create a configuration valid only for our specific user. To make changes to the configuration file effective, all we have do to is to reload the i3 window manager: we can usually do this via the “Mod+Shift+R” keys combination.

The “general” section

The first thing we want to define in our i3status configuration file is the “general” section. In this section we can declare what colors should be used (if any) for the various states, and how often i3status should update  the information printed to the status bar. Let’s see an example. In the ~/.config/i3status/config file, we write:

general {
  colors = true
  color_good = "#a3be8c"
  color_degraded = "#ebcb8b"
  color_bad = "#bf616a"
  interval = 1
  separator = "|"
}

The “general” section is delimited by using curly braces. In it, we declared that we want to use colors (via the colors = true directive) and defined which colors should be associated with the the good, degraded and bad status. Status thresholds can be defined inside some modules, and can be used to highlight, for example, a poor wireless connection or a high CPU usage. The colors are defined by using the RGB hexadecimal notation, just as we would do in a css file. Next, with the interval directive, we defined the interval of time in seconds after i3status must update information in the status bar. Finally, with the separator directive, we defined the character to use as a separator between the information printed by the various modules we are about to see.

Using modules

The i3status utility provides a series of modules we can use to retrieve some useful information. Those we will discuss about in this tutorial are:

• Disk: used to print the used, free and total space of a filesystem
• Wireless: displays information about a wireless network interface connection
• Ethernet: displays information about an ethernet interface connection
• Battery: gets the status of batteries
• CPU usage: displays information about the CPU usage
• Memory: displays information about memory usage

Modules can be configured using the appropriate directives enclosed in curly braces. Let’s see some examples.

The Disk module

Let’s start with the “Disk” module. As we already said, this module can be used to display information about the total, used and free space of a given filesystem. Suppose we want to check the percentage of used space in the “/” filesystem. Here is what we could write:

disk "/" {
  format = "/: %percentage_used"
}

---

---

We define how the status should be printed in the status bar, by using the format directive. The %percentage_used placeholder will be substituted by the actual percentage of used space. Another placeholders we can use, for example is %percentage_free, which is rendered as the percentage of free space in the filesystem (for the complete placeholder list take a look at the i3status manual). After we configure a module, for its content to be included in the output of i3status, we must add it to the order list, after the “general section”. Here is how the configuration file looks like at this point:

general {
  colors = true
  color_good = "#a3be8c"
  color_bad  = "#bf616a"
  color_degraded = "#ebcb8b"
  interval = 1
  separator = "|"
}

order += "disk /"

disk "/" {
  format = "/: %percentage_used"
}

After we reload i3, information are displayed in the i3bar:

The cpu_usage module

The “cpu_usage” module can be used to display CPUs usage in percentage format via the %usage placeholder:

cpu_usage {
  format = "Cpu: %usage"
}

As we mentioned before, it is possible to define the degraded and bad thresholds: when the percentage reaches a threshold, it will be printed using the corresponding color defined in the general section. By default this thresholds are 90 and 95, respectively, but they can be changed via the degraded_threshold and max_threshold directives. In case we want to track the percentage relative to a specific CPU, we can specify it with the %cpu<N> sintax, where N is the number of the CPU starting from 0:

cpu_usage {
  format = "CPU_0: %cpu0 CPU_1: %cpu1 CPU_2: %cpu2 CPU_3: %cpu3"
  degraded_threshold = 90
  max_threshold = 95
}

To add the result of the module to the i3status output we add it to the order:

order += "disk /"
order += "cpu_usage"

Here is how the status changes:

The ethernet and wireless modules

With the “ethernet” and “wireless” modules we can get information about corresponding network connections. With the ethernet module we pass the name of a network interface and let i3status print the IP address assigned to it, and, if available, the link speed. Here is an example of the module usage:

ethernet enp0s31f6 {
  format_up = "ETH: %ip (%speed)"
  format_down = "ETH: down"
}

---

---

With the format_up directive we specify what must be displayed when the connection is up: the %ip placeholder is substituted by the IP address assigned to the interface, and %speed with the link speed. With format_down, instead, we set what must be displayed in case the connection is down. If we don’t want to “hard-code” an interface name, we can use the _first_ special value: when we do so, the first non-loopback, non-wireless interface will be used.

The “wireless” module work similarly. In this case we specify the name of a wireless interface, or, again, use the _first_, which, in this case, will be substituted by the name of the first wireless network interface. Among the other things, we can retrieve information about the %quality, %ssid and %ip of the connection. Here is an example of the module usage:

wireless __first__ {
  format_up = "WLS: (%quality at %ssid) %ip"
  format_down  = "WLS: down"
}

Here is how the status bar appears after we add the “ethernet” and “wireless” modules to the order:

The “battery” module

The “battery” module can be used to retrieve information about a battery, such as its status, and its charge percentage. Those information are exposed in the /sys/class/power_supply/BAT<n>/uevent file (n is the number of the battery, since some machines may have more than one). Supposing we want the percentage of the battery to be displayed, and the “color_bad” to be used to print it when the percentage is 10% or lower, we would write:

battery 0 {
  format = "BAT0: %percentage"
  last_full_capacity = true
  threshold_type=percentage
  low_threshold=10
}

We passed the battery number after the module name, and we used the format directive to set what information should be displayed in the status bar. With the last_full_capacity directive we declare that we want the percentage to be calculated relatively to the current capacity of the battery and not to its full capacity by design. Next, we used the threshold_type directive to explicitly state that the threshold should be intended as a percentage value, and then we set the low_threshold to 10.

What if we have more than one battery on our machine? Batteries are numbered progressively starting from 0, and we can use the “path” directive to explicitly set the path of the “uevent” file:

battery 1 {
  path=/sys/class/power_supply/%d/uevent
  format = "BAT1: %percentage"
  last_full_capacity = true
  threshold_type=percentage
  low_threshold=10
}

Inside the module configuration the first %d placeholder is substituted by the battery number passed next to the module name. In case we want to obtain an aggregate of all the existing batteries, all we have to do, is to replace the battery number with “all”:

battery all {
  path=/sys/class/power_supply/%d/uevent
  format = "BAT AGGR: %percentage"
  last_full_capacity = true
  threshold_type=percentage
  low_threshold=10
}

Here is the result of adding the above configurations to the i3status order:

The “memory” module

The “memory” module allow us to keep track of the ram usage by querying /proc/meminfo. We can make i3status display the total, used, free and available system memory by using the corresponding placeholders. There are two methods which can be used to calculate the available/used memory: “memeavailable” and “classical”. The former is obtained by subtracting the “MemAvailable” from the total memory, and corresponds to the value returned by the free command; the latter calculates the available memory by subtracting the buffers, cache and “free” memory from the total memory, and corresponds to the value returned by the gnome system monitor. To display the used/total memory in percentage we can write:

memory {
  memory_used_method = classical
  format="Memory: %used/%total"
}

Here is the result of including the module in i3status:

Conclusions

In this article we learned how to customize i3status, an utility which comes with the i3 window manager and can be used to generate and print information in status bars like i3bar. We saw how to configure it and how to use some of the available modules. For a complete overview of i3status functionalities, please take a look at the utility manual.