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.
- Using the keyboard:
- Use the
Home
orEnd
keys to jump to the top or to the end of a page. - Use
PgUp
orPgDn
to advance a whole page (window size) minus one step. - Use the arrow keys to move the view a step in that direction.
- You can also use the
Space
key asPgDn
andb
as PgUp.
- Use the
- Using the mouse or pointing device:
- Rotate the mouse wheel to move one step in that direction. Hold Shift to move one page instead.
- Keep the middle button (or mouse wheel button) pressed while dragging to scroll the page precisely.
- Using the scrollbar:
- Drag the thumb in the scrollbar on the side up or down to scroll the page.
- Left-click or right-click on the scrollbar above or below the thumb to move one page in that direction.
- Middle-click on the scrollbar above or below the thumb to jump to that specific position of the page.
- Click the scrollbar arrows to move the view one step in that direction.
- Rotate the mouse wheel over the vertical scrollbar to move one page in that direction.
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.
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).
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.
Navigation
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
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:
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
.
Web search
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:
- There is an option in the Tools menu to disable automatic image loading.
An image's alt text (or
[IMG]
placeholder) will appear in the page. - If you want to load an individual image, left click on its text.
- You can set "no images" as the default mode in dillorc.
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.
- "
#option=...
" shows the built-in default. - "
# option=...
" is an additional example. - "
option=...
" overrides the built-in value.
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:
- Line 1: Comment line begins with
#
. - Line 2: Deny all cookies from all domains not otherwise specified (this is the default).
- Line 3: Accept all cookies from fltk.org, and save them to disk when the cookie plugin exits.
- Line 4: Accept all cookies from all subdomains of example.com, but do not save them when the cookie plugin exits.
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:
- "
*
" to match any domain - "
example.com
" to match the specific host example.com - "
.example.com
" to match example.com and any of its subdomains
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 (
) 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.
- Modifiers recognized: Shift, Ctrl, Alt, Meta (on Mac OS X use "Meta" for Command).
- Key names recognized: Backspace, Delete, Down, End, Esc, F1 through F12, Home, Insert, Left, Menu, PageDown, PageUp, Print, Return, Right, Space, Tab, Up.
- Multimedia keys: Back, Favorites, Forward, HomePage, Mail, MediaNext, MediaPlay, MediaPrev, MediaStop, Refresh, Search, Sleep, Stop, VolumeDown, VolumeMute, VolumeUp.
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 |