XOMBRERO(1) BSD General Commands Manual XOMBRERO(1)NAMExombrero — lightweight web browser
SYNOPSISxombrero [-nSTtV] [-f file] [-s session_name] [url ...]
DESCRIPTIONxombrero is a minimalistic web browser that tries to stay out of the way
so that valuable screen real estate can be used for much more important
stuff. It has sane defaults and does not require one to learn a language
to do any configuration. It was written by hackers for hackers and it
strives to be small, compact, and fast.
xombrero is very simple in its use. Most actions are initiated via key
or mouse bindings. Key bindings are based on those of the vi(1) text
editor, giving web browsing a similar feel to navigating a text document.
The KEY BINDINGS section below documents the various defaults and possi‐
ble customizations.
The options are as follows:
-f file
Specify an alternative configuration file.
-n Open a new tab in a running xombrero for each specified URL.
This option requires enable_socket to be enabled.
-e command
Execute arbitrary command (see the COMMAND MODE section below) in
a running xombrero instance. This option requires enable_socket
to be enabled. Example run: xombrero-e "tabnew openbsd.org";
xombrero-e tabclose; xombrero-e wq.
-S Disable the toolbar.
-s session_name
Open session that was saved with ":session save" command.
-T Disable visualization of tabs.
-t Disable tabs. Pages that would open in tabs open in new windows
instead.
-V Display version and exit.
FAST STARTUP
The following notation is used throughout this page:
C- Control
S- Shift
M1- Meta 1 (sometimes marked Alt)
M2- Meta 2
M3- Meta 3
M4- Meta 4 (sometimes marked Windows)
M5- Meta 2
MB1 Mouse button 1
To browse to a specific address, either use the mouse to click on the
address bar or press F6 to shift the keyboard focus to the address bar.
The address is then entered manually.
The mouse can be used to navigate the page in the traditional manner, or
the keyboard can be used instead. For example, PageUp and PageDown will
scroll up and down the page.
To follow a link, either click on it or use the f key and have xombrero
assign numbers to each link on the page; entering that number on the key‐
board will prompt xombrero to follow the link.
KEY BINDINGSxombrero provides many actions accessed via key or mouse bindings. Most
can be reprogrammed using a keybinding entry in the configuration file.
Each keyboard shortcut requires exactly one entry in the configuration
file. A shortcut can have multiple entries in the configuration file.
The format of the keybinding entry is as follows:
keybinding = (:)action,(!)keystroke(s)
For example, "keybinding = tabnew,C-t" where tabnew is the action and C-t
are the keystrokes.
Actions may be any xombrero command that can be run from the command
prompt. There is one additional action, unbind, which will unbind any
previous actions to that keybinding.
If the action begins with a colon, the action will be entered into the
command prompt instead of being executed. For example, "keybinding =
:session open ,M1-s" will open the command prompt with ":open session "
entered when using the M1-s keybinding.
Keybindings which open the command prompt may also include the string
<uri>, which will be replaced by the current tab's URI. For example,
"keybinding = :open <uri>,F10" will open the command prompt with <uri>
replaced with the current URI.
GTK has some default keybindings for manipulating text inside input
fields, such as the URI or search entry widget, for example C-w deletes a
word. To override these defaults prefix your key with an exclamation mark
(!), like this: "keybinding = tabclose,!C-w". The clearall key word is
special and is meant to reset the key binding list to the GTK+ and WebKit
defaults. This keyword should be the first keybinding entry in the con‐
figuration file.
Shift should be used sparingly since it gets in the way of non-USA key‐
boards. See the accompanying configuration file for examples.
The various bindings are documented below. The relevant keybinding
action is given afterwards, in parentheses.
Command mode
These commands are used to focus or unfocus input on the default input of
a web page.
ESC Go to command mode; unfocus current entry on web page.
(command_mode)
i Go to insert mode; focus on default entry on web page.
(insert_mode)
Search Commands
These commands are used to search for text strings within a web page.
/ Start a search (search)
? Start a backwards search (searchb)
n Next item matching search (searchnext)
N Previous item matching search (searchprev)
Focus Commands
These commands are used to shift the focus of xombrero from one area to
another.
F6 Focus on address bar (focusaddress)
F7 Focus on search entry (focussearch)
Command Aliases
These commands allow the user to map specific actions to specific keys.
F1 Alias for "help"
F2 Alias for "proxy toggle"
F4 Alias for "toplevel toggle"
Prompt Aliases
These commands allow the user to open a prompt. These can be useful when
the -S option is used.
F9 Alias for ":open "
F10 Alias for ":open <uri>"
F11 Alias for ":tabnew "
F12 Alias for ":tabnew <uri>"
Navigation Commands
These commands allow the user to navigate web pages and, to some extent,
control the browser.
F5, C-r, C-l Reload page (reload)
Backspace, M-Left Previous page (goback)
S-BackSpace, M-Right Forward page (goforward)
j, Down Next line on page (scrolldown)
k, Up Previous line on page (scrollup)
G, End Bottom of page (scrollbottom)
gg, Home Top of page (scrolltop)
Space, C-f, PageDown Page down (scrollpagedown)
C-b, PageUp Page up (scrollpageup)
l, Right Page right (scrollright)
h, Left Page left (scrollleft)
$ Page far right (scrollfarright)
0 Page far left (scrollfarleft)
M-f Favorites (fav)
M-j Cookie jar (cookiejar)
M-d Download manager (dl)
C-p Print page (print)
M-h Global history (history)
C-j Toggle JavaScript enabled for FQDN (js)
C-s Toggle source view (togglesrc)
M-c Toggle cookie enabled for FQDN (cookie)
M-p Toggle plugins enabled for FQDN (plugin)
Tab Manipulation
xombrero supports tabbed browsing. That is, web pages may be opened in
separate tabs, allowing the user to quickly move from one page to
another, and back. These commands then are used to create, destroy, and
move between tabs.
C-MB1 Open new tab with the clicked link
C-t Create new tab with focus in URL entry (tabnew)
C-T Create new tab with focus in URL entry as the
last tab in the browser (999tabnew)
C-w Destroy current tab (tabclose)
U Undo close tab (tabundoclose)
C-Left, C-PageUp Go to the previous tab (tabprevious)
C-Right, C-PageDown
Go to the next tab (tabnext)
C-[1..9] Jump to page N (tabnext [1..9])
C-< Jump to first page (tabfirst)
C-> Jump to last page (tablast)
C-minus Zoom out by 4% (focusout)
C-plus, C-equal Zoom in by 4% (focusin)
C-0 Set zoom level to 100% (focusreset)
Yanking and pasting
These commands copy and paste text to and from the clipboard.
p Paste the contents of the clipboard into the address bar
(pasteuricur)
P Paste the contents of the clipboard into a new tab
(pasteurinew)
y Yank the current URL into the clipboard (yankuri)
Hyperlink Following
This allows the user to follow hyperlinks without using a mouse. Enter
the corresponding number to follow the link. Alternatively one can type
the name of the link and when there are no more possibilities xombrero
will follow the link.
f, '.' Highlight all links and prefix them with a number.
(hinting)
F, ',' Highlight all links and prefix them with a number but open
in a new tab. (hinting_newtab)
Exiting
Commands to exit the browser.
C-q Quit (quitall)
Low-Contrast Color Scheme
These commands toggle the page style between the default CSS and a low-
contrast color scheme with light grey text on a dark grey background. If
the userstyle setting is changed, that stylesheet will be used instead of
the low-contrast color scheme.
s Toggle the current tab's style. (userstyle)
S Toggle the global page style mode. Will also affect new
tabs. (userstyle_global)
Insert-mode commands
The following commands are only available when editing an input-field
C-i Edit the contents of the currently active input-element in
an external editor. (editelement)
COMMAND MODE
Command mode works in a similar fashion to the vi(1) editor; it is
entered by typing a colon and exited by pressing Esc. The commands and
their descriptions are listed below.
about, version
Display the About page.
buffers, ls, tabs
Display the currently opened tabs and let the user switch
tabs by typing the tab number or by using the mouse.
ca Display CA certificates.
cert, cert show
Download and display certificates of the domain on current
tab.
cert save
Save certificate into a local store. The next time the
site is visited it is compared against the store. If the
certificate matches, the address bar will be blue; if it
doesn't the bar will be red.
cookie The cookie command is used to manipulate the cookie
whitelist. Used by itself it expands to cookie show all.
cookiejar
Show cookie jar contents.
cookie purge
Remove all cookies from the cookie jar.
cookie save, cookie save fqdn
Save the current fully qualified domain name (FQDN) to the
persistent whitelist. For example, the www.peereboom.us
domain would result in saving www.peereboom.us.
cookie save domain
Save the top level domain name to the persistent whitelist.
For example, the www.peereboom.us domain would result in
saving .peereboom.us.
This action enables cookies if it is currently disabled for
this entry.
cookie show all
Show all persistent and session entries in the cookie
whitelist.
cookie show persistent
Show all persistent entries in the cookie whitelist.
cookie show session
Show all session entries in the cookie whitelist.
cookie toggle domain
Toggle cookie support for the current top level domain.
cookie toggle, cookie toggle fqdn
Toggle cookie support for the current FQDN.
dl Show download manager.
encoding [encoding]
Set the current tab's encoding to encoding and reload the
tab. If encoding is not provided, the current tab's encod‐
ing is displayed.
editsrc
Open the source for the current tab in the editor specified
by the setting external_editor and then check for changes
to the file opened. If it is changed, the page will be
updated.
editelement
If a text-element is currently active (<input> or
<textarea>), it's contents will be opened in the same fash‐
ion as for the command editsrc above
fav Show favorites.
favadd [title]
Add the current page to favorites. The title can be over‐
ridden by specifying title.
favedit
Show favorites list and links to remove entries.
fullscreen, f
Toggle hiding tabs and url entry toolbar.
h, hist, history
Show global history.
help Show help page.
home Go to home URL.
https The https command is used to manipulate the items in the
HTTPS force list. Used by itself it expands to https show
all.
https save, save fqdn
Save the FQDN to the persistent force HTTPS list. For
example, the www.peereboom.us domain would result in saving
www.peereboom.us.
https save domain
Save the top level domain name to the persistent whitelist.
For example, the www.peereboom.us domain would result in
saving .peereboom.us.
https show all
Show all persistent and session entries in the HTTPS force
list.
https show persistent
Show all persistent entries in the HTTPS force list.
https show session
Shows all session entries in the HTTPS force list.
https toggle, https toggle fqdn
Toggle this FQDN in the HTTPS force list.
https toggle domain
Toggle the top level domain in the HTTPS force list.
js The js command is used to manipulate the JavaScript
whitelist. Used by itself it expands to js show all.
js save, save fqdn
Save the FQDN to the persistent whitelist. For example,
the www.peereboom.us domain would result in saving
www.peereboom.us.
js save domain
Save the top level domain name to the persistent whitelist.
For example, the www.peereboom.us domain would result in
saving .peereboom.us.
This action enables JavaScript if it is currently disabled
for this entry.
js show all
Show all persistent and session entries in the JavaScript
whitelist.
js show persistent
Show all persistent entries in the JavaScript whitelist.
js show session
Show all session entries in the JavaScript whitelist.
js toggle, js toggle fqdn
Toggle JavaScript execution for the current FQDN.
js toggle domain
Toggle JavaScript execution for the current top level
domain.
loadimages
If the setting auto_load_images is disabled, load all
images for current site.
open, op, o URL
Open URL.
plugin The plugin command is used to manipulate the plugin
whitelist. Used by itself it expands to plugin show all.
plugin save, save fqdn
Save the FQDN to the persistent whitelist. For example,
the www.peereboom.us domain would result in saving
www.peereboom.us.
plugin save domain
Save the top level domain name to the persistent whitelist.
For example, the www.peereboom.us domain would result in
saving .peereboom.us.
This action enables plugins if they are currently disabled
for this entry.
plugin show all
Show all persistent and session entries in the plugin
whitelist.
plugin show persistent
Show all persistent entries in the plugin whitelist.
plugin show session
Show all session entries in the plugin whitelist.
plugin toggle, plugin toggle fqdn
Toggle plugin execution for the current FQDN.
plugin toggle domain
Toggle plugin execution for the current top level domain.
print Print page.
proxy The proxy command is used to manipulate the currently set
proxy. Used by itself it expands to proxy show.
proxy show
Display the current http_proxy setting.
proxy toggle
Enable or disable the proxy for xombrero. Note that
http_proxy must be set before it can be toggled.
qa, qall, quitall
Quit xombrero.
quit, q
Close current tab and quit xombrero if it is the last tab.
restart
Restart xombrero and reload all current tabs.
run_script [path_to_script]
Run the script path_to_script with the current uri as the
argument. If path_to_script is not provided, the script
specified by the default_script setting is used instead.
script filename
Run an external JavaScript script file in the current tab
context.
session, session show
Display the current session name. By default the session
name is “main_session”. To create a new session use the
session save command. A session is defined as the lifetime
of the browser application.
session delete session_name
Delete session session_name from persistent storage. If
session_name is the current session then the session will
revert to “main_session”.
session open session_name
Close all tabs and open session session_name. Going for‐
ward this session is named session_name.
session save session_name
Save current tabs to session session_name. This will close
the current session and going forward this session is named
session_name.
set The set command is used to inspect, clear or change runtime
options. There are 3 methods to use set. When used by
itself as “:set” the command displays all options as cur‐
rently set.
To set a value use “:set ⟨option⟩=⟨value⟩”. For example,
“:set http_proxy=http://127.0.0.1:8080”.
To clear a value use “:set ⟨option⟩=”. For example, “:set
http_proxy=”.
Note, not all options can be set at runtime.
stats Show blocked cookie statistics. These statistics vary
based on settings and are not persistent.
statustoggle, statust
Toggle status bar.
stop Stop loading the current web page.
tabclose
Close current tab.
tabhide
Hide tabs.
tabnew, tabedit [URL]
Create a new tab and optionally open provided URL.
tabnext
Go to the next tab.
tabonly
Close all tabs except the currently focused one.
tabprevious
Go to the previous tab.
tabshow
Show tabs in GUI.
toplevel, toplevel toggle
Toggle the top level domain name cookie and JS session
whitelist. This is to enable/disable short lived full site
functionality without permanently adding the top level
domain to the persistent whitelist.
urlhide, urlh
Hide url entry and toolbar.
urlshow, urls
Show url entry and toolbar.
userstyle [stylesheet]
Toggle the current tab between using the custom stylesheet
stylesheet and the page's default CSS. If stylesheet is
not provided, the stylesheet specified by the userstyle
setting will be used. This userstyle setting is set by
default to a low-contrast color scheme.
Additional stylesheets may be used in addition to that set
by userstyle by specifying additional keybindings. For
example,
keybinding = userstyle ~/style.css,v
keybinding = userstyle_global ~/style.css,V
will map toggling between ~/style.css to the v and V keys
while keeping the stylesheet specified by userstyle mapped
to the s and S keys.
userstyle_global [stylesheet]
Same as the userstyle command but affects all open tabs and
newly created tabs will use this style.
w Save open tabs to current session. The tabs will be
restored next time the session is opened. See the session
command for additional details.
wq Save open tabs and quit. The tabs will be restored next
time the session is opened. See the session command for
more details.
BUFFER COMMANDS
In addition to shortcuts and commands xombrero provides buffer commands.
Buffer commands are short, multi character vi-like commands, often
requiring an argument. Partial buffer commands are displayed in the buf‐
fer command statusbar element (see statusbar_elems). Pressing Esc or
switching to another tab cancels a partially entered buffer command. In
the following list arg denotes the argument a buffer command accepts.
Buffer commands are defined as extended regular expressions. Note that
if a character is used as a shortcut it will not be interpreted as the
beginning of a buffer command. This is the case with 0.
gg go to the top of the page
gG go to the bottom of the page
[0-9]+% go to the arg percent of the page
zz go to 50% of the page
[0-9]*gu go arg levels up. If arg is missing, 1 is
assumed. Going a level up means going to a URI
obtained from the current one by removing the
last slash ('/') character and everything that
follows it
gU go to the root level, i.e. going up as many lev‐
els as possible.
gh open the home page in the current tab
m[a-zA-Z0-9] set a mark denoted by arg at the current page
position. These marks behave like those in vi or
less.
['][a-zA-Z0-9'] go to the position where mark arg was set. The
special mark "'" points to the previous page
position, after a "gg", "gG", "zz", "%" or "'"
buffer command.
M[a-zA-Z0-9] set the current uri as quickmark arg
go[a-zA-Z0-9] open the uri marked as quickmark arg in the cur‐
rent tab
gn[a-zA-Z0-9] open the uri marked as quickmark arg in a new
tab
[0-9]+t activate tab number
g0 go to first tab
g$ go to last tab
[0-9]*gt go to the arg next tab
[0-9]*gT go to the arg previous tab arg
ZZ quit xombrero
ZR restart xombrero
zi zoom in by 4%
zo zoom out by 4%
z0 set zoom level to 100%
[0-9]+Z set zoom level to arg %
QUICKMARKS
Quickmarks are like bookmarks, except they are referred to by a single
character (a letter or a digit), instead of a longer name. See the
M[a-zA-Z0-9], go[a-zA-Z0-9] and gn[a-zA-Z0-9] buffer commands for usage.
Quickmarks are stored in ~/.xombrero/quickmarks and are saved automati‐
cally after each M[a-zA-Z0-9] buffer command.
ABOUT SCREENS
The about screens are internally generated web pages by xombrero for user
interaction. These are entered in the address bar and the format is
about:screen where screen is the desired screen to display. For example
about:favorites. Any about screen can be used as the home page as speci‐
fied by home in the configuration file.
about show the about screen
blank show a blank screen
cookiewl show the cookie whitelist screen
cookiejar show the cookiejar screen
downloads show the downloads screen
favorites show the favorites screen
help show the help web page
history show the history screen
jswl show the JavaScript whitelist screen
plwl show the plugin whitelist screen
set show the settings screen
stats show the statistics screen
WHITELISTS
This section describes advanced usage settings. Most users should use
browser_mode instead to setup xombrero and skip over this section.
xombrero has a number of whitelists to control blocking cookies and
JavaScript execution for FQDNs or domains. When properly enabled these
whitelists require either the FQDN or top level domain to exist in the
whitelists in order to allow cookies to be stored or JavaScript to exe‐
cute. Both JavaScript and cookies have two whitelists associated with
them. The whitelists are called session and persistent. Items in the
session whitelists are only allowed for the lifetime of the xombrero
instance. Items in the persistent whitelists are stored on disk and are
restored upon restarting.
Setting up the whitelists is a little tricky due to intricacies of
WebKit. In fact the semantics are different for cookies and JavaScript.
Cookie whitelist requires the following configuration to be set:
cookies_enabled This is a WebKit setting and must be
set to 1 (ENABLED) in order to be able
to use a cookie whitelist.
enable_cookie_whitelist This needs to be set to 1 to enable the
cookie whitelist functionality.
cookie_wl These entries in the configuration file
are the actual domains names in the
cookie whitelist.
JavaScript whitelist requires the following configuration to be set:
enable_scripts This is a WebKit setting and must be set to
0 (DISABLED) in order to be able to use a
JavaScript whitelist.
enable_js_whitelist This needs to be set to 1 to enable the
JavaScript whitelist functionality.
js_wl These entries in the configuration file are
the actual domains names in the JavaScript
whitelist.
Plugin whitelist requires the following configuration to be set:
enable_plugins This is a WebKit setting and must be
set to 1 (ENABLED) in order to be able
to use a plugin whitelist.
enable_plugin_whitelist This needs to be set to 1 to enable the
plugin whitelist functionality.
pl_wl These entries in the configuration file
are the actual domains names in the
plugin whitelist.
See the FILES section for additional configuration file entries and
details that alter runtime behavior.
FILES
~/.xombrero.conf xombrero user specific settings.
~/.xombrero xombrero scratch directory.
xombrero tries to open the user specific file, ~/.xombrero.conf. If that
file is unavailable, it then uses built-in defaults. Any settings saved
at runtime will be saved to the file ~/.xombrero/runtime and will be
loaded as well.
The format of the file is <keyword> = <setting>. For example:
http_proxy = http://127.0.0.1:8080
Enabling or disabling an option is done by using 1 or 0 respectively.
The file supports the following keywords:
alias Defines an alias for a given URL, so
that the URL is loaded when the alias
is entered in the address bar. If the
aliased URL includes a %s format speci‐
fier, then any argument given after the
alias on the address bar is substi‐
tuted. For example, if
g,http://www.google.com/search?q=%s is
defined as an alias, then the URL
http://www.google.com/search?q=foo is
loaded when navigating to "g foo".
allow_insecure_content If set, all content referenced by a
page will be loaded. If unset,
encrypted pages will refuse to load
content that is linked from an insecure
location.
allow_insecure_scripts If set, all scripts referenced by a
page will be loaded and run using the
current javascript policy. If unset,
encrypted pages will refuse to run
scripts that are linked from an inse‐
cure location.
allow_volatile_cookies If set cookies are stored in the ses‐
sion cache but will be discarded once
xombrero exits. Unfortunately enabling
this does allow for some limited track‐
ing on the web.
anonymize_headers If set, HTTP headers taken from the
Bitrig website: https://www.bitrig.org/
will be used to feed additional values
to the xombrero HTTP header settings.
Currently only the User-Agent and Http-
Accept headers are modified, corre‐
sponding to the user_agent and
http_accept settings, respectively.
These headers are set after any header
settings are read in from your
~/.xombrero.conf. Default is 0.
append_next When set a new tab is appended after
the current tab instead of being
appended as the last tab.
auto_load_images If disabled, images will not be loaded
automatically.
autofocus_onload When set a tab that is loaded will
attempt to autofocus the default input
entry. This is only done for tabs that
are currently visible.
browser_mode The xombrero browser has 3 default
operating modes: normal (the default),
whitelist and kiosk. In the normal
mode the browser allows all cookies,
plugins and JavaScript as any other
browser would. This means that all
cookies are saved to persistent storage
and that all JavaScript and plugins
run.
On the other hand, using the whitelist
mode enables whitelists. This requires
the user to add all the required
cookie_wl, js_wl and pl_wl items. If a
domain does not appear in the
whitelists xombrero disallows cookies,
JavaScript and plugin execution. If
insecure web content or scripts are
referenced by a secure website, they
will be blocked from loading or run‐
ning.
In kiosk mode the browse works just
like normal mode however the toolbar
only has the backward, forward and home
button.
This setting must be the first entry in
~/.xombrero.conf because it sets
advanced settings that can be overrid‐
den later in the file. See the default
config file for more details.
cmd_alias This setting is used to define an alias
for a command. The syntax of this set‐
ting is cmd_alias = alias,cmd. For
example, if you wanted to set an alias
for the tabnew command to tn, add the
line cmd_alias = tn,tabnew to your
~/.xombrero.conf. This setting may not
begin with a number.
cmd_font Set the command prompt font. E.g.
cmd_font = monospace normal 9.
color_visited_uris When enabled (the default) xombrero
will color visited links. This is done
while the web page loads using
JavaScript, rather than WebKit's (bro‐
ken, see bug #51747) built-in facility
for coloring visited links. The
JavaScript approach is (probably)
slower and is not consistent across
tabs (unless the tabs are reloaded),
but has the advantage of not leaking
history data to web pages (see
http://wtikay.com/docs/details.html).
cookie_policy This field delineates the cookie pol‐
icy. Possible values are: no3rdparty,
reject 3rd party cookies. accept,
accept all cookies. reject, reject all
cookies.
cookie_wl This is a cookie whitelist item. Use
multiple times to add multiple entries.
Valid entries are for example *.moo.com
and the equivalent .moo.com. This
matches both moo.com, as well as all
subdomains. A fully qualified host is
also valid and is for example
www.moo.com or moo.com. Fully quali‐
fied hosts do not modify whitelist set‐
tings for any subdomains.
Unix extended regular expressions may
also be used to match any set of FQDNs.
Regular expressions must begin with the
prefix "re:". As an example, the regu‐
lar expression equivalent to moo.com
would be ^moo.com$, and the equivalent
to .moo.com would be ^(.*.)*moo.com$.
If using regular expressions for
whitelist items, be careful to not
accidentally match other domains; you
will almost always want to add the ^
and $ characters to the beginning and
end of the regex so that, for example,
moo.com would not match not-moo.com.
cookies_enabled Enable cookies.
ctrl_click_focus Give focus in newly created tab instead
of opening it in the background.
custom_uri This setting provides the ability to
run custom executables for special
URIs. The syntax for this setting is
custom_uri = protocol,command. The URI
is passed as a single argument to
command to be parsed and executed.
For example, to add the ability to use
custom mailto URIs, add the setting
custom_uri = mailto,command where
command is a program that will parse
the mailto URI and open your mail
client.
default_script Path to the script used as the default
value for the run_script command.
default_zoom_level Set the default browsing zoom level.
do_not_track Sets the HTTP Do Not Track header to
tell sites that you wish to be opted-
out of 3rd-party tracking for the use
of behavioral advertising. Not all
sites currently support this header,
and this is only a suggestion of a user
preference. Sites may still perform
3rd-party tracking even when this fea‐
ture is enabled.
download_dir Locations where files are downloaded
to. This directory must exist and
xombrero validates that during startup.
download_mode Controls how downloads are handled.
Possible values are:
start - automatically start download.
ask - ask user for confirmation.
add - add to downloadmanager, but
do not start.
The default is "start".
download_notifications When enabled a message is shown when
downloads are finished. Default is 0.
enable_autoscroll When enabled clicking MB3 will spawn
the autoscroll ball, scrolling can then
proceed by dragging the mouse away from
the ball.
enable_cookie_whitelist When enabled all cookies must be in the
whitelist or they are rejected. Addi‐
tionally whitelisted cookies also
enable HTML5 local storage for the
domain.
enable_cache When enabled (disabled by default), web
content will be cached into memory.
enable_favicon_entry When enabled (the default) xombrero
displays the favicon of the web page at
the URI entry. This setting affects
both normal and compact tabs.
enable_favicon_tabs When enabled (disabled by default)
xombrero displays favicons at each tab.
This setting only affects compact tabs.
enable_js_autorun Enables support for autorunning
JavaScript after page loads. When
enabled, ~/.xombrero/js/ will be
searched for default.js and
host.domain.js. If host.domain.js does
not exist, domain.js will be tried
instead. The content of the both
default and host/domain files are read
and executed on each page load.
Default is 1.
As an example, if you add the line
alert("Hello, world"); to your
default.js, a pop-up displaying "Hello,
world" will be shown on every page
reload. While not useful, any
javascript can be run through this
mechanism, making it useful for global
or site-specific modifications.
enable_js_whitelist When enabled all domains must be in the
js whitelist in order to run Java
Script. NOTE: Make sure enable_scripts
is set to 0.
enable_plugin_whitelist When enabled all domains must be in the
plugin whitelist in order to run plug‐
ins. NOTE: Make sure enable_plugins is
set to 0.
enable_plugins Enable external plugins such as Flash
and Java.
enable_strict_transport Enable support for the Strict-Trans‐
port-Security HTTP-header. When
enabled, sites that set this flag will
only be visited via HTTPS. Default
value is 1
enable_scripts Enable Java Script.
enable_socket When enabled the first instance of
xombrero will create a socket in the
~/.xombrero directory. Using the -n
url option on subsequent xombrero invo‐
cations will cause the specified URL to
be loaded in a new tab. Only a user
with identical UID and GID can use this
option.
enable_localstorage Enable html5 Local Storage.
enable_spell_checking Enables spell checking. Preferred lan‐
guages can be set using
spell_check_languages option.
encoding Set the default encoding. E.g.
encoding = ISO-8859-1.
external_editor Set which editor to use for external
editing. the string <file> will be
replaced by the current filename. E.g.
external_editor = gvim -f <file> Note!
xombrero relies on the editor not
forking into the background.
fancy_bar Enables a backward, forward, and stop
button to the toolbar. Additionally if
search_string is set it'll enable an
entry box for searches.
force_https This setting is used to define the
domains of sites that should be only
accessed over the HTTPS scheme. Any
requests to these domains over HTTP
will be rewritten to use HTTPS instead.
See cookie_wl for semantics.
gnutls_priority_string If set, this string sets the
G_TLS_GNUTLS_PRIORITY environmental
variable to define the GnuTLS priority
string that is used when initializing
the GnuTLS session. This may be used
to change the supported TLS/SSL ver‐
sions and the ciphers that are used
when making HTTPS connections.
Full details on how to modify this set‐
ting may be found in the GnuTLS docu‐
mentation, Section 8.9: Priority
Strings. For example, to disable the
128-bit RC4 cipher, change this setting
to NORMAL:!ARCFOUR-128.
If your glib-networking package is
older than version 2.33.10, or if the
G_TLS_GNUTLS_PRIORITY environmental
variable is already set, this setting
has no effect.
guess_search When enabled xombrero will try to guess
if the string you entered, in the URI
entry widget or the command widget, is
term you want to search for using
search_string (see above). If the
string does not contain a dot nor a
slash, is not a path to a local file
and does not resolves to an IP then it
is assumed to be a search term.
gui_mode To simplify configuring xombrero allows
you pick between two GUI modes: classic
(the default) and minimal. In the
classic mode the GUI looks similar to
that of most mainstream browsers. While
in minimal mode the GUI looks more vi-
like. One can get a GUI between the two
by tweaking the low-level GUI settings
found under the advanced GUI setting
section in the configuration file.
history_autosave When enabled xombrero will save all
command and search history. Upon
restarting xombrero the saved command
and search history will be restored.
home Homepage in URL format.
http_proxy Proxy server in URL format. xombrero
overrides http_proxy if it is specified
as an environment variable. It must be
noted that on older Webkit versions one
MUST use an IP address and not a FQDN.
This works as expected with Webkit
1.4.2.
If using libsoup 2.42.2 or newer, one
may use a socks proxy directly. For
example:
http_proxy = socks5://127.0.0.1:9050
Otherwise, an intermediary tool, such
as polipo or tsocks, must be used.
http_accept If set, the HTTP Accept header will be
modified for each text/html request.
If this setting is set multiple times,
the Accept header will be changed in a
round-robin order for every text/html
request on a tab. Because this setting
rotates through Accept headers on each
text/html request, a single page may
rotate through more than one Accept
header if multiple text/html requests
are made.
Please be aware that not all websites
report browser headers correctly. Most
notably, EFF's panopticlick service
also reports the HTTP Accept-Encoding
headers on the same line as the Accept
headers. If you are trying to find the
headers of another browser to model
that browser's fingerprint, it is rec‐
ommended to not use panopticlick for
this reason.
Note that this setting only rewrites
the Accept header for text/html
requests. Other requests will use
WebKit's default Accept header.
http_proxy_starts_enabled If set to 0, the http_proxy will be
disabled at startup. The user can later
enable the proxy with the proxy toggle
command or keybinding.
icon_size Permits icon sizes to be changed if
fancy_bar is enabled. Size 1 is small;
2 is normal; 3 through 6 are progres‐
sively larger.
include_config This must be a path to another configu‐
ration file. Configuration files are
usually read from top to bottom, how‐
ever, if this option is set, xombrero
will begin reading the included file at
this location and continue reading the
rest of the configuration after the
included file has finished being read.
Any simple settings set before the
include may be overridden by settings
in the included file, and any simple
settings set in the included file may
be overridden later by settings after
the include or at runtime using the
:set command. However, database set‐
tings (for example, cookie_wl, js_wl,
pl_wl, and keybinding) are only ever
added to the database, and so the order
of an included configuration file is
not pertinent to these database set‐
tings.
This feature is likely best used as the
last item in ~/.xombrero.conf.
js_auto_open_windows If enabled, javascripts will be allowed
to automatically open windows based on
the current browser_mode. If disabled,
it will never be allowed. The default
setting is 1 (enabled).
js_wl This is a JavaScript whitelist item.
See cookie_wl for semantics and more
details.
max_connections The maximum number of connections that
xombrero can open at once.
max_host_connections The maximum number of connections that
xombrero can open at once to a given
host.
mime_type Sets an action for a specific or
default MIME type. For example, to
download and view a pdf using kpdf set
mime_type = application/pdf,kpdf. To
set a default value use *, for example,
mime_type = video/*,mplayer. Note that
the action is only passed the URL and
not all applications are capable of
dealing with a URL and therefore one
might have to create a wrapper script
to download the content first. Alter‐
natively one can add the @ in front of
the MIME type to indicate "download
first". For example, mime_type =
@application/pdf,xpdf. When @ is use
the file will be downloaded to the
download_dir before the MIME handler is
called.
The special binary name "donothing" may
be used to ignore a MIME type without
displaying any warnings from being
unable to execute the binary.
oops_font Set the font used to display error mes‐
sages. E.g. oops_font = monospace
normal 9.
pl_wl This is a plugin whitelist item. See
cookie_wl for semantics and more
details.
preload_strict_transport If enabled, a preloaded list of sites
which set the HTTP Strict Transport
Security header will be used to auto‐
matically set the force_https setting
for these sites. This is used to pre‐
vent SSL stripping attacks when first
visiting these sites, before they have
been added to the strict-transport
file. This list is comprised of
domains chosen by the xombrero authors,
as well as domains included in
Chromium's preloaded HSTS list.
Default is 1.
read_only_cookies Mark cookies file read-only and discard
all cookies once the session is termi‐
nated.
refresh_interval Refresh interval while in the download
manager. The default is 10.
referer Control how “referer” is handled in
http-requests.
always - always send referer
never - never send referer
same-domain - only send referer if it's
for the same public suffix - this means that
it's OK for subdomains to refer to each other
same-fqdn - only send referer if it's FQDN match
Any other value that is also a valid
URL will use this custom value as ref‐
erer. (E.g. you could set it to
http://no-referer.com) The default
value is “always”.
resource_dir Directory that contains various
xombrero resources such as icons. This
is OS-specific and should be handled by
the porter.
save_global_history If set the global history will be saved
to ~/.xombrero/history when quitting
and restored at startup. See the KEY
BINDINGS section above for how the
global history is accessed. Global
history is not saved to disk by
default.
save_rejected_cookies Saves rejected cookies in cookie format
in {work_dir}/rejected.txt. All cook‐
ies are saved and unlike a cookie jar
they are never replaced. Make sure
there is enough disk space to enable
this feature.
search_string Default search engine string. See the
xombrero.conf file for details.
session_autosave Enable session auto-saving when chang‐
ing state (e.g. adding or removing a
tab). The session name is what is cur‐
rently in use and is described in the
session save and session open commands.
session_timeout This value is the time that is added in
seconds to a session cookie.
show_tabs Enable or disable showing tabs.
show_url Enable or disable showing the url and
toolbar.
show_scrollbars Enable or disable the showing of the
horizontal and vertical scrollbars.
Disabling this setting requires GTK3.
show_statusbar Enable or disable showing the status
bar.
single_instance If set and enable_socket is enabled
only one xombrero will be permitted to
run. If there is a URL specified it
will be opened in a new tab in the
already running xombrero session.
spell_check_languages The languages to be used for spell
checking, separated by commas. For
example, en_US.
ssl_ca_file If set to a valid PEM file all server
certificates will be validated against
it. The URL bar will be colored green
(or blue when saved) when the certifi‐
cate is trusted and yellow when
untrusted.
If ssl_ca_file is not set, the URL bar
will be colored red if the certificate
has not been saved, or blue if it has
been saved.
WebKit only supports a single PEM file.
Many OS' or distributions have many PEM
files. One can simply concatenate all
separate files into one large one.
E.g. for i in `ls`; do cat $i >>
cert.pem; done and use the resulting
cert.pem file as the input to
ssl_ca_file. It is advisable to peri‐
odically recreate the cert.pem file.
ssl_strict_certs If this value is set connections to
untrusted sites will be aborted. This
value is only used if ssl_ca_file is
set.
statusbar_elems Define the components of the status
bar. The possible components are:
| - separator
P - page progress percent
p - proxy enabled/disabled
B - buffer command
Z - page zoom level
T - current tab number
The default is "BP". These components
show nothing if there is nothing worth
showing, like zoom amount 100%.
statusbar_font Set the status bar font. E.g.
statusbar_font = monospace normal 9.
statusbar_style Set the status bar style to either url
- display the current url, or title -
display the page title. The default is
url.
tab_style Set the tab style to either normal -
the default gtk notebook tabs, or
compact for an alternative. You can
switch the tab style with the
tabnextstyle command.
tabbar_font Set the compact tab bar font. E.g.
tabbar_font = monospace normal 9.
tabless Disable tabs, and open new windows
instead. Note that this feature does
not disable the display of tabs.
Change your show_tabs setting also if
you wish to disable the display of
tabs. Default is 0.
url_regex This is the regular expression that is
used to match what constitutes a valid
URL when using guess_search.
user_agent Set to override the default xombrero
user-agent string. May be specified
several times for switching between
user-agents.
userstyle Set the stylesheet to be used as a
default for the userstyle and
userstyle_global commands when no extra
parameters are given. The default is a
low-contrast stylesheet.
userstyle_global When enabled new tabs will automati‐
cally be displayed using the custom
stylesheet specified by the userstyle
setting.
warn_cert_changes When enabled all SSL certificates from
HTTPS websites will be cached in the
~/.xombrero/certs_cache/ directory. On
each page load, if the remote certifi‐
cate differs from the cached local ver‐
sion, a warning page with options of
what to do next will be displayed
instead of the requested page. This
feature may be used in addition to the
coloring of the URL bar and can be used
to help prevent against man-in-the-mid‐
dle attacks, even if the new remote
certificate is signed by a trusted cer‐
tificate authority in ssl_ca_file.
Default is 0.
window_height Set the default height of the browser
window.
window_width Set the default width of the browser
window.
window_maximize Maximize the browser window at startup.
work_dir Set the work directory where all
xombrero scratch files are stored.
Default is ~/.xombrero.
HISTORYxombrero was inspired by vimprobable2 and the bloat in other UNIX web
browsers.
AUTHORSxombrero was written by Marco Peereboom ⟨marco@peereboom.us⟩, Stevan
Andjelkovic ⟨stevan@student.chalmers.se⟩, Edd Barrett ⟨vext01@gmail.com⟩,
Todd T. Fries ⟨todd@fries.net⟩, Raphael Graf ⟨r@undefined.ch⟩, Michal
Mazurek ⟨akfaew@jasminek.net⟩, and Josh Rickmar ⟨jrick@devio.us⟩.
BSD April 29, 2024 BSD
