High-resolution text console with uvesafb and Debian

While you may rarely use the console on your server, it’s nice to have a high-resolution display just to see that many more columns and rows. Linux’s vesa module (via the vga= parameter) has been around for a while and made this possible, provided you kept up with what VGA mode number to use and don’t mind the spotty hardware compatibility.

While KMS is the way to do this in the future, it doesn’t help us with the drivers and hardware we have now. A new kernel module, uvesafb, mainlined in 2.6.24, is another, new option. In addition to specifying modes in a more user-friendly way (e.g. 1280x1024-32 for 32-bit color, with a 1280x1024 resolution), hardware compatibility is better—in particular, you can now get a high-resolution text console with NVIDIA display adapters.

In the following, I describe how to use uvesafb on Debian and derivative distributions (e.g. Ubuntu). The instructions assume kernel 2.6.27 or higher (Debian 6.0 (squeeze) and Ubuntu 8.10 (Intrepid Ibex), or later).

Presumably, you want to use uvesafb because the normal vesa framebuffer does not work. Make sure you don’t have any vga= options anywhere, as these will force the initialization of the vesa framebuffer which will prevent the use of uvesafb.

grep vga /proc/cmdline
grep -ir vga /etc/modprobe.d/

Should yield no results. If you do have a vga= option somewhere, you’ll need to remove it. Removing it is outside the scope of this HOWTO, but you probably want to check your bootloader’s configuration and the files in /etc/modprobe.d/.

Before you can use uvesafb, you need to install a user space helper, v86d:

sudo aptitude install v86d

Next, make sure the uvesafb module is included into your initrd. Add it to the end of /etc/initramfs-tools/modules:

sudo sh -c "echo uvesafb >> /etc/initramfs-tools/modules"

Configure what mode you want uvesafb to use. To see what modes are available, load the uvesafb module and examine sysfs:

sudo modprobe uvesafb
cat /sys/bus/platform/drivers/uvesafb/uvesafb.0/vbe_modes

All the monitors I use can display at least 1280x1024, so I decided to go with 1280x1024-32, which is passed to uvesafb through the mode_option= parameter. The typical way to do this on Debian-based distributions is to place a file into /etc/modprobe.d/:

sudo sh -c "echo options uvesafb mode_option=1280x1024-32 scroll=ywrap > /etc/modprobe.d/uvesafb.conf"

Last, rebuild your initrd to make sure it contains all the changes we’ve made:

sudo update-initramfs -k all -u

You’ll need to do this every time you want to use a different mode. Reboot, and you’ll be rocking with a high-resolution text console!

Correction: “vga” isn’t a kernel parameter, it’s an instruction to your bootloader (e.g. LILO, GRUB) to set a mode on startup. Thanks garygolden on the Debian User Forums. The distinction changes nothing in getting uvesafb to work.