This document provides usage instructions for the Framebuffer version of NetSurf.

Framebuffer NetSurf has been tested on Ubuntu and Debian.


What it is

The NetSurf framebuffer front end is primarily intended for kiosk and embedded applications where there is insufficient Operating System support for a full graphical windowing environment.

The framebuffer frontend features:

What it is not

The framebuffer frontend is not a replacement for full native ports. It lacks functionality and flexibility compared to such implementations.

Limitations include:

In addition it should be noted support for some libnsfb surfaces has been implemented purely for debugging functionality (SDL especially) and is not intended to replace native surface handlers.

If a high level windowing system is available then a native NetSurf frontend is almost certainly a better choice than attempting to use the framebuffer frontend.

If there is a graphical environment which supports GTK then using the GTK frontend is a vastly superior choice. The framebuffer frontend will appear exceptionally limited on such capable systems.


The framebuffer frontend is executed with the nsfb command. This command takes parameters to control the operation of the browser. The 'Configuring' section describes the available options in detail.

The selection of the display surface is controlled with the -f switch, the available display surfaces can be shown by passing '?' as the parameter.

$ ./nsfb -f ? ./nsfb: Valid surface names are: ./nsfb: ram ./nsfb: sdl ./nsfb: x ./nsfb: vnc ./nsfb: wld

The avilable surfaces are dependant on what was compiled into the nsfb library.

Common issues


Several resources are set at compile time and are not changeable at run time such as the icon bitmaps, the font system to use and what default surface to use. Refer to the BUILDING-Framebuffer document for details.

As with any NetSurf frontend run-time configuration is read from a "Choices" file. This file is a simple key:value list and by default is located in "${HOME}/.netsurf/Choices".

The standard core user options are available. In addition to the core options there are a number of values to control specific aspects of the framebuffer version.

Toolkit Options

The trivial toolkit has some configuration parameters allowing the user to alter specific aspects of the UI. All the sizes are in surface pixels however that is mapped.

fb_furniture_size This is the size allowed for the scroll bar elements.

fb_toolbar_size The height of the toolbar.

fb_toolbar_layout The layout of the toolbar, layout uses a string to define buttons type and position each character adds an element to the toolbar:

b - Move back in history l - Display the local history f - Move forward in history s - stop fetching content r - refresh content u - url bar expands to fit remaining space t - throbber/activity indicator c - close the current window q - Disable The toolbar altogether

If the option contains only the q specifier the toolbar is disabled altogether (this was previously the empty string but that was difficult to configure correctly).

The default layout is "blfsrutc" there should be no more than a single url bar entry.

fb_osk Whether the on screen keyboard should be enabled for input.

Framebuffer Surface

There are four command line switches which override compiled in defaults these are:

-f <handler> Selects a surface handler to pass to libnsfb instead of the default. (e.g. x, sdl, mem, linux)

-b <depth> Selects the pixel depth to pass to libnsfb instead of the compiled in default. (one of 8, 16, 24, 32)

-w <width> Selects the surface width to pass to libnsfb instead of the compiled in default.

-h <height> Selects the surface height to pass to libnsfb instead of the compiled in default.

The libnsfb surface parameters are controlled with:

fb_refresh - The refresh rate (for physical displays) fb_depth - The depth (in bits per pixel) of the surface fb_device - The path to the device (for physical displays) fb_input_devpath - The path to the input devices (for linux input layer) fb_input_glob - The input device selection glob (for linux input layer) window_width - The width of the framebuffer window_height - The height of the framebuffer

The defaults are for 800 by 600 pixels at 16bpp and 70Hz refresh rate.

The documentation of libnsfb should be consulted for further information about supported surfaces and their configuration.


If the compile time option is set to use the freetype font system then several configuration options are available. If the simple bitmap glyphs are used none of these options apply.

Font faces are provided for the css default styles of sans serif, serif, monospace, cursive and fantasy. Only the sans serif non-italic normal weight font is required to exist, If any of the other faces are missing the sans serif font will be used instead.

The compiled in default font file paths are specified within the build time Makefile.config. The default faces is the truetype DejaVu font set in the directory /usr/share/fonts/truetype/ttf-dejavu/

The font glyphs are, by default, rendered as 256 level transparency which gives excellent visual results even on small font sizes.

The font selection may be changed by placing truetype font files in the resources path. The resource files will be the generic names sans_serif.ttf, sans_serif_bold.ttf etc.

The font system is configured at run-time by several options:

fb_font_monochrome This option causes the renderer to use monochrome glyph rendering. This method of rendering is much less visually appealing and while faster to plot it is slower to render.

fb_font_cachesize This option sets the number of kilobytes of memory set aside for caching the rendered glyphs. This caching significantly improves the performance of using the freetype rendering system. It is set to 2048 by default (2 Megabytes of memory) which impiracle testing shows to be a suitable value for the seven default faces.

The remaining options control the files to be used for font faces. The font file name options will override both the compiled in paths and files found in the resource path.

fb_face_sans_serif - The sans serif face fb_face_sans_serif_bold - The bold sans serif face fb_face_sans_serif_italic - The italic sans serif face fb_face_sans_serif_italic_bold - The bold italic sans serif face. fb_face_serif - The serif font fb_face_serif_bold - The bold serif font fb_face_monospace - The monospaced font fb_face_monospace_bold - The bold monospaced font fb_face_cursive - The cursive font fb_face_fantasy - The fantasy font