Dillo User Manual

Welcome to the user manual of the Dillo browser. The manual is divided into sections but is written in a single page to allow search by keywords. Generated for version v3.1.1-120-g540bad94.

Table of contents:

Introduction

Dillo is a web browser designed to be fast, use few resources and support slow and unreliable networks on resource-constrained machines. It can load local and remote files via HTTP, HTTPS and FTP. Other protocols like Gemini, Gopher, IPFS and others are available as plugins.

Dillo supports a subset of HTML 4.01 and CSS 2.1 but it doesn't support JavaScript and only implements some elements of HTML 5 and CSS 3. It also renders plain text documents and images in PNG, JPG, GIF, SVG and WebP formats.

Reading

In this section we cover the basics to read a web page, scrolling and finding or copying text.

Basics

The graphical interface is designed to be used with a mouse or pointing device. At the top of the browser window you have the location bar and the main buttons to control the browser. You can leave the mouse for a brief moment over any part of the menu to show a tooltip with more information.

Dillo has context sensitive menus, which are opened with the right mouse button, available on pages, links, images, forms, the Back and Forward buttons, and the bug meter. They show different actions to be performed specific to the element. For example, to save a page you can right-click on the page and select "Save page as...". Or to copy a link URL you can right-click on a link and select "Copy link location".

Dillo can hide all panels and use the whole window area to display the page. To switch between modes use the ESC key. You can also choose the control panel size by going to the Tools button and selecting a different one under "Panel size".

You can open this manual from Dillo by clicking on the top right "?" button. It doesn't require a network connection.

Scrolling

There are several methods to move or scroll the view of the current page.

You can control the size of a step by setting the scroll_step option in the dillorc configuration file. By default it will scroll 100 pixels per step. The vertical scrollbar can be positioned on the left side setting the scrollbar_on_left option to YES, by default it is on the right side.

The vertical scrollbar has another mode of operation to navigate full pages that can be enabled by setting the scrollbar_page_mode option to YES or temporarily by holding the Shift key. When this mode is active, left-clicking anywhere on the scrollbar will scroll down one page and right-clicking will scroll up one page. Middle clicking on the scrollbar will move the thumb to that position, which can also be dragged. The Shift key can also be used to temporarily disable this mode if it was enabled in the configuration.

Find text

To find text in a document right-click to open the Page menu and select Find text or press Ctrl+F on the keyboard. Then type the substring that you want to find and click Next (or the Enter key).

Dillo will scroll the page and highlight found text starting from the top. To find a word (not a substring) use spaces around it to limit the search to matching words only.

To close the find bar you can click on the red X on the bottom right or press ESC.

Copy and paste

To copy some text just hold down the left mouse button and move to select the area to copy. To paste, go to the target application and press the middle mouse button.

If you want to select more than one screen, hold the mouse left button down and scroll with PgUp, PgDn or the arrow keys.

If you want to paste an URL into Dillo, do it on the "clear-URL" button (the "X" next to the location bar).

Zoom

You can increase or decrease the size of the elements of a page by changing the zoom factor. Use Ctrl + to increase the size, Ctrl - to decrease it and Ctrl 0 to reset the value to 100%.

The initial zoom factor is specified by the zoom_factor option in the dillorc configuration file. When a new tab or window is opened, the current zoom factor value is inherited.

This section focuses on how to navigate to other pages by following hyperlinks, using bookmarks, typing or pasting a new URL or using the history.

Hyperlinks (or just links) allow you to navigate to other pages by clicking them. They change the cursor to a hand to indicate that an element can be clicked with the left button:

hand shaped cursor

Links to other pages usually appear in blue and underlined by default and once they are visited they change to purple. However, this is not always the case, so using the mouse cursor shape is the best indicator of a link.

When you follow a link by clicking on it, the previous pages will be remembered in case you want to go back to them. Use the Back and Forward buttons on the top bar to navigate among history pages.

History

When you follow several links across different web pages, they are remembered in case you can to go back. Use the "Back" and "Forward" buttons of the panel to go to the previous or next page.

You can also right-click on the Back or Forward buttons to open a menu with the list of previous or next pages available, so you can jump directly to them. Use the left button to open them in the current tab or the middle button to open them in a new tab.

The , (comma) and . (dot) keys can be used to jump backwards or forward (mnemonic: those keys are usually labeled "<" and ">").

Location bar

The location bar on the top displays the URL of the current page loaded and can be used to access other pages by typing the new URL or by pasting it and pressing Enter.

The red x on the left clears the location bar content when left clicked. Then you can type or paste a new address from the clipboard by middle clicking on the location bar. As these two actions are usually performed together, you can simply middle-click on the x button to go to the URL in the clipboard.

You can also select the location bar content from the keyboard by pressing Ctrl+L.

Several search engines are available by pressing the magnifying glass icon next to the location bar or by pressing Ctrl+S. The search engines are configured in Dillorc with the option search_url. Use it multiple times to define multiple search engines.

The location bar can also be used to search the web by using a special prefix for each search engine. For example, the following line:

search_url="dd DuckDuckGo http://duckduckgo.com/lite/?kp=-1&kd=-1&q=%s"

Defines the "DuckDuckGo" search engine with the prefix "dd", so you can type in the location bar "dd dillo browser" to search with DuckDuckGo for the keywords "dillo browser".

Tabs

Dillo can open different web pages into tabs. To open a link in a new tab click the middle button instead of the left button. The same applies to buttons to submit a form. A new tab can also be opened from the File menu or using the shortcut Ctrl+T.

By default the new tab will be automatically focused. If you want to change this behaviour, adjust the following options in the dillorc configuration file: 

middle_click_opens_new_tab
focus_new_tab

Press Shift to temporarily reverse the focusing behaviour while middle-clicking on a link.

To close a tab press the X button on the top right (only visible with multiple tabs). You can also close the tab by clicking with the right button on the tab label. The middle button can be used instead by setting the option: 

right_click_closes_tab=NO

Use the new_tab_page option to control which page is loaded in a newly opened tab, by default is an empty page. To open the bookmarks page set the following line in dillorc: 

new_tab_page="dpi:/bm/"

Bookmarks

Dillo can save URLs of web pages as bookmarks so you can open them later. To bookmark the current page, open the Page menu by right-clicking on the page and select "Bookmark this page" (it also works over a link).

To see or edit the bookmarks, click on the Bookmarks button on the panel or press Ctrl+B.

Bookmarks are handled by a built-in Dillo plugin named bm (read more about plugins in the Plugins section) and are synchronized across all instances of the browser. The list of bookmarks can also be shown by opening the URL dpi:/bm/.

The bookmarks are stored in a simple plain text file named bm.txt (see the details of this file in the bm.txt section). You can edit the file directly to change the bookmarks.

Privacy and network

The default privacy policy in Dillo attempts to keep the user safe from tracking, even if this policy breaks a lot of website functionality. In this section you can add exceptions or relax the configuration at your own risk.

HTTPS

Dillo has support for HTTPS, allowing secure connections to remote websites. Use the protocol "https:" to specify the use of HTTPS. When a problem is encountered with the remote certificate, a warning dialog explains the details and allows you to choose what to do: continue loading the website or cancel.

By default Dillo looks for a TLS library at build time, which can be OpenSSL or mbedTLS. You can see which library is being used by looking at the console when it starts: 

$ dillo
dillo_dns_init: Here we go! (threaded)
TLS library: OpenSSL 3.2.1 30 Jan 2024
...

Cookies

Due to privacy concerns, cookies are disabled by default unless explicitly enabled in the configuration.

Support for cookies is implemented using a built-in plugin that shares them between several instances of Dillo and follows the RFC 6265 specification. Current cookie limits are 20 per domain and 1200 in total.

Cookies are configured by the cookiesrc configuration file. See the Cookiesrc section to see how to enable cookies for some domains or accept them by default.

Proxy

Dillo can use a HTTP proxy by setting the environment variable http_proxy or the configuration option with the same name. All HTTP and HTTPS traffic will be sent through the proxy.

Note: Plugins may not implement proxy support.

Ad blocking

Dillo has the ability to block content when loading a page based on the domain the embeded content is being loaded from. You can control how Dillo handles automatic requests for resources (like images and style sheets) that aren't at the same domain as the original page.

See the domainrc configuration file to find out how to specify which domains are blocked or allowed.

Downloads

Downloads are made using wget with a FLTK-based GUI wrapper, through the Dillo plugin (dpi) framework. If you close the browser window, downloads will continue.

Images-off mode

You can browse without images now:

Configuration

Dillo has several configuration files that control the behavior of the browser. Each configuration file is searched first in the ~/.dillo directory and, if not found, in the default system configuration directory (typically /etc/dillo).

Most configuration files can include comments by starting a line with the "#" symbol. Their specific syntax is described in the following sections.

Dillorc

The main configuration of Dillo is controled by the dillorc file. The list of all available options can be found in the system configuration file, typically /etc/dillo/dillorc. You may want to copy it into ~/.dillo/dillorc and edit it to suit your needs.

The file is commented to describe what each option does. The default value for each option as well as other interesting values are also available as comments:

The search_url option can be specified multiple times: 

search_url="dd DuckDuckGo (https) https://duckduckgo.com/lite/?kp=-1&q=%s"
search_url="Wikipedia http://www.wikipedia.org/w/index.php?search=%s&go=Go"

Cookiesrc

Cookies are configured in the ~/.dillo/cookiesrc file by using rules, with one rule per line. The rule syntax is very simple, first specify the host and then the action, separated by white spaces. Comment lines start with # as the first character and the whole line is ignored.

The host can be in the form example.com to match only that domain or .example.com to match all subdomains of example.com. The special word DEFAULT specifies the default policy, when no other match occurs.

The action can be: DENY to ignore cookies, ACCEPT_SESSION to only accept session cookies but don't save them to disk and ACCEPT to accept and store cookies in disk (this will allow sites to track you over time).

When the cookies plugin exits, only the accepted cookies by ACCEPT are saved to ~/.dillo/cookies.txt, and ACCEPT_SESSION cookies are forgotten. The cookies plugin normally exits after a period of inactivity, but you can force it to exit with the command dpidc stop.

Here is an example cookiesrc file: 

# host        action
DEFAULT       DENY
fltk.org      ACCEPT
.example.com  ACCEPT_SESSION

Which is parsed as follows:

Dillo is especially concerned about privacy and security issues. Our advice is to avoid cookies whenever possible and at most set ACCEPT_SESSION to specific trusted sites.

Domainrc

With the ~/.dillo/domainrc file, you can control how Dillo handles automatic requests for resources (like images and style sheets) that aren't at the same domain as the original page.

The file contains one rule per line. Comments are specified by starting the line with the # symbol. The default rule is either default accept or default deny and will cause Dillo to, respectively, accept all requests by default or deny all requests by default.

Depending on the default rule, the next rules behave as exceptions by denying specific connections or allowing specific connections, respectively.

Exceptions to the default rule are written in the format source destination, and match request from the source domain to the destination domain. The source and destination domains can be specified in three ways:

Here is an example: 

# Accept all requests by default
default accept
# But block some ad-sites and trackers from any domain
* .doubleclick.net
* .googleadservices.com
* .quantserve.com

Style.css

Custom CSS styles can be placed in the ~/.dillo/style.css file to set default web page styles. To override page styles add the "!important" flag.

Dpidrc

The configuration for plugins is placed in the ~/.dillo/dpidrc file.

Plugins are searched in the ~/.dillo/dpi/ directory first, and then in the system directory if not found. The dpi_dir option sets the system dpi directory and must be specified once. Here is an example:

dpi_dir=/usr/lib/dillo/dpi

By default, plugins will receive requests at the URL dpi:/name/, for example bookmarks are available at dpi:/bm/.

Plugins can also be associated with a protocol (like "file:"). When a request is made using the given protocol the associated plugin is used to process the request. The rest of the file assigns a plugin to a protocol, one per line. The syntax is proto.name=path-to-plugin.dpi. The path of the plugin is relative to the dpi directory. Here are protocols used by the built-in plugins:

proto.file=file/file.dpi
proto.ftp=ftp/ftp.filter.dpi
proto.data=datauri/datauri.filter.dpi

Here ( red dot ) is an example image using the data: protocol used to define a PNG image inline in a HTML document.

bm.txt

Web page URLs can be saved as bookmarks so they can be accessed in the future. Bookmarks are stored in a plain text file located at ~/.dillo/bm.txt. The file can be modified by using the Book button in the toolbar and the context menu on a page or link, but they can also be edited manually. Bookmarks are organized into sections and are given a description (usually the page title).

The syntax of the bm.txt file is described as follows:

First, the sections are defined at the beginning, prefixed with a :sN: identifier, along with the description of the section:

:s0: News
:s1: Blog

Then every bookmark is added in a single line, by writing the section identifier, the URL and a description:

s0 https://slashdot.org Slashdot
s0 https://news.ycombinator.com/ Hacker News
s1 https://100r.co/site/log.html 100 Rabbits Log

The bm.txt file is designed to be easily read by humans and is suitable to be kept updated among machines by using a version control tool.

Keysrc

The mapping of keys in Dillo is contolled by the ~/.dillo/keysrc file. The format is "key = action" or "<modifier>key = action". Lines that begin with a "#" are comments. The commented-out bindings below show the defaults built into Dillo.

If Dillo is running under X11, keys whose names are not recognized can be specified using their keysym value in hexadecimal. Use xev to get the keysym, for example: 

0x1008ff27 = forward

The action "nop" (no operation) can be used to remove a binding.

Example file:

# "close-all" closes all tabs/windows and exits.
<ctrl>q = close-all

# "left-tab" and "right-tab" switch to the left/right of the current tab.
<ctrl><shift>tab = left-tab

# Use HJKL to move around
k = line-up
j = line-down
h = left
l = right

Advanced usage

These sections focus on advanced topics and are recommended for experienced users of Dillo.

Plugins

The functionality of Dillo can be extended by using plugins, which can translate other formats to HTML, implement new protocols or provide a custom service.

Plugins can be written in any programming language and they interact with the browser using the DPI protocol. A list of plugins is available on the Dillo website. Some plugins are just a few lines of shell script, so you are encouraged to read them to learn how to write your own plugins. Plugins are searched by looking for files that end with the .dpi extension (or .dpi.exe in Windows) in ~/.dillo/dpi and dpi_dir (see the Dpidrc configuration section).

There are two types of plugins: filters and servers. Filters are executed for each request like a UNIX pipe, they read from the standard input and write to the standard output. The name of filter plugin programs must end in .filter.dpi. On the other hand, servers listen on a socket for new requests. They can process several requests at the same time, preventing the overhead of spawning multiple processes and they can easily share information among requests.

You can install plugins from any third party, but you should always review the source before running code written by others. To install a new plugin, copy the files to ~/.dillo/dpi/name/ and then associate the name protocol to the program that must run in the ~/.dillo/dpidrc file. Plugins may have other software dependencies required for it to work.

Here is an example of how to manually install the Gemini protocol plugin (it comes with a Makefile that automates the process, so this is not necessary), which is a filter plugin written in shell script:

$ mkdir -p ~/.dillo/dpi/gemini
$ cp gemini.filter.dpi ~/.dillo/dpi/gemini/
$ chmod +x ~/.dillo/dpi/gemini/gemini.filter.dpi
$ echo "proto.gemini=gemini/gemini.filter.dpi" >> ~/.dillo/dpidrc
$ dpidc stop

Now, when a request is made to an URL that begins with the gemini: protocol, it will be processed by the gemini/gemini.filter.dpi program, and the output will be displayed by Dillo.

Bug Meter

Dillo includes a bug meter which shows the number of detected bugs inside the page. The bugs are caught at parsing time, so the error messages also show the line where they occur and provide a hint of what was expected instead.

The primary purpose of the bug meter is to help webmasters and page authors to polish the contents of their sites with a view to making them compliant with HTML standards.

The bug meter is located at the lower right corner of Dillo. Use the left-click to see the messages, right-click for a menu to open other HTML validators.

Keyboard shortcuts

Most actions can be issued by using a keyboard shortcut. The key bindings can be changed in the ~/.dillo/keysrc file (see the keysrc section). The list of default bindings is given in the following table.

Shortcut Mnemonic Function
Ctrl-L Location Enter a new URL
Ctrl-F Find Find text
Ctrl-S Search Search the web
Ctrl-R Reload Reload current page
Ctrl-N New New browser window
Ctrl-T Tab New tab
Ctrl-W Window Quit tab/window
Ctrl-O Open Open file
Ctrl-U View source
Ctrl-B Bookmarks View bookmarks
Ctrl-Q Quit Quit dillo
Ctrl-+ or Ctrl-= Bigger Zoom in
Ctrl-- Smaller Zoom out
Ctrl-0 100% Reset zoom to 100%
Back or "," < Previous page
Shift-Back or "." > Next page
Alt-F File File menu
Ctrl-Tab or
Ctrl-PageDown 		Tab Next tab
Ctrl-Shift-Tab or
Ctrl-PageUp 		Tab Previous tab
Esc escape Close dialog, Close findbar,
Hide/show control panels