XXXTERM(1)

NAME
xxxterm - lightweight web browser

SYNOPSIS
xxxterm [-nSTtV] [-f file] [-s session_name] [url ...]

DESCRIPTION
xxxterm 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.

xxxterm 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 possible customizations.

The options are as follows:

-f file
    Specify an alternative configuration file.

-n  Open a new tab in a running xxxterm 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 xxxterm instance. This option requires enable_socket to be enabled. Example run: xxxterm -e "tabnew openbsd.org"; xxxterm -e tabclose; xxxterm -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.

-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 xxxterm assign numbers to each link on the page; entering that number on the keyboard will prompt xxxterm to follow the link.

KEY BINDINGS
xxxterm 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. 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 configuration file.

Shift should be used sparingly since it gets in the way of non-USA keyboards. See the accompanying configuration file for examples.

The various bindings are documented below. The relevant keybinding action is given afterwards, in parentheses.

  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 xxxterm 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. It can be useful when the -S option is used.

F1  Alias for ":help"
F4  Alias for ":toplevel toggle"
F9  Alias for ":open" (promptopen)
F10 Alias for ":open current-uri" (promptopencurrent)
F11 Alias for ":tabnew" (prompttabnew)
F12 Alias for ":tabnew current-uri" (prompttabnewcurrent)

  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)
C-R Reload page without using any cached data (reloadforce)
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 Java Script enabled for FQDN (js)
C-s Toggle source view (togglesrc)
M-c Toggle cookie enabled for FQDN (cookie)

  Tab Manipulation
xxxterm 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-w Destroy current tab (tabclose)
U   Undo close tab (tabundoclose)
C-Left
    Go to the previous tab (tabprevious)
C-Right
    Go to the next tab (tabnext)
C-[1..0]
    Jump to page N (tabnext [1..0])
C-minus
    Shrink font size by one point (focusout)
C-plus, C-equal
    Grow font size by one point (focusin)

  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 xxxterm will follow the link.

f   Highlight all links and prefix them with a number. (hinting)

  Exiting
Commands to exit the browser.

C-q Quit (quitall)

  Low-Contrast Color Scheme
This command toggles the page's style between the default CSS and a low-contrast color scheme with light grey text on a dark grey background.

i   Toggle the current tab's style. (userstyle)

COMMAND MODE
Command mode works in a similar fashion to the vi(1) editor; it is entered by typing a colon and exited by typing Esc. The commands and their descriptions are listed below.

about, version
    Show the "About" page.

buffers, ls, tabs
    Displays the currently open tabs and lets the user switch tab by typing the tab number or using the mouse.

ca  Display CA certificates.

cert, cert show
    Download and display certificates of domain on 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 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.

fav Show favorites.

favadd
    Add the current page to favorites.

fullscreen, f
    Toggle hiding tabs and url entry toolbar.

h, hist, history
    Show global history.

help
    Show help page.

home
    Go to home URL.

js  The js command is used to manipulate the Java Script whitelist. Used by itself it expands to js show all.

js save, save fqdn
    Saves the FQDN to the persistent whitelist. For example, the www.peereboom.us domain would result in saving .www.peereboom.us.

js save domain
    Saves 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 Java Script if it is currently disabled for this entry.

js show all
    Shows all persistent and session entries in the JS whitelist.

js show persistent
    Shows all persistent entries in the JS whitelist.

js show session
    Shows all session entries in the JS whitelist.

js toggle, js toggle fqdn
    Toggle Java Script execution for the current FQDN.

js toggle domain
    Toggle Java Script execution for the current top level domain.

open, op, o URL
    Open URL.

print
    Print page.

qa, qall, quitall
    Quit xxxterm.

quit, q
    Close current tab and quit xxxterm if it is the last tab.

restart
    Restart xxxterm and reload all current tabs.

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>
    Open session_name and close all currently open tabs. Going forward this session is named session_name.

session save <session_name>
    Save current tabs to session_name session. This will close the current session and going forward this session is named session_name.

stats
    Show blocked cookie statistics. These statistics vary based on settings and are not persistent.

statushide, statush
    Hide status bar.

statusshow, statuss
    Show status bar.

tabclose, tabc
    Close current tab.

tabhide
    Hide tabs.

tabnew, tabedit, tabe URL
    Create new tab and optionally open provided URL.

tabnext, tabn
    Go to the next tab.

tabprevious, tabp
    Go to the previous tab.

tabshow
    Show tabs.

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 tool bar.

urlshow, urls
    Show url entry and tool bar.

w   Save open tabs to current session. The tabs will be restored next time xxxterm the session is opened. See the session command for additional details.

wq  Save open tabs and quit. The tabs will be restored next time xxxterm the session is opened. See the session command for additional details.

ABOUT SCREENS
The about screens are internally generated web pages by xxxterm 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 specified 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 Java Script whitelist screen
set show the settings screen
stats
    show the statistics screen

WHITELISTS
This section descibes advanced usage settings. Most users should use browser_mode instead to setup xxxterm and skip over this section.

xxxterm has a number of whitelists to control blocking cookies and Java Script 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 Java Script to execute. Both Java Script 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 xxxterm 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 Java Script.

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.

Java Script 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 Java Script whitelist.
enable_js_whitelist
    This needs to be set to 1 to enable the Java Script whitelist functionality.
js_wl
    These entries in the configuration file are the actual domains names in the Java Script whitelist.

See the FILES section for additional configuration file entries and details that alter runtime behavior.

FILES
~/.xxxterm.conf
    xxxterm user specific settings.
~/.xxxterm
    xxxterm scratch directory.

xxxterm tries to open the user specific file, ~/.xxxterm.conf. If that file is unavailable, it then uses built-in defaults.

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 specifier, then any argument given after the alias on the address bar is substituted. 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_volatile_cookies
    If set cookies are stored in the session cache but will be discarded once xxxterm exits. Unfortunately enabling this does allow for some limited tracking on the web.
append_next
    When set a new tab is appended after the current tab instead of being appended as the last tab.
browser_mode
    The xxxterm browser has 3 default operating modes: normal (the default), whitelist and kiosk. In the normal mode the browser allows all cookies and Java Script as any other browser would. This means that all cookies are saved to persistent storage and that all Java Script runs.

    On the other hand, using the whitelist mode enables whitelists. This requires the user to add all the required cookie_wl and js_wl items. If a domain does not appear in the whitelists xxxterm disallows cookies and Java Script execution.

    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 ~/.xxxterm.conf because it sets advanced settings that can be overridden later in the file. See the default config file for more details.
cmd_font
    Set the command prompt font. E.g. cmd_font = monospace normal 9.
cookie_policy
    This field delineates the cookie policy. 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. A fully qualified host is also valid and is for example www.moo.com.
cookies_enabled
    Enable cookies.
ctrl_click_focus
    Give focus in newly created tab instead of opening it in the background.
default_font_size
    Set the default browsing font size.
default_zoom_level
    Set the default browsing zoom level.
download_dir
    Locations where files are downloaded to. This directory must exist and xxxterm validates that during startup.
enable_cookie_whitelist
    When enabled all cookies must be in the whitelist or they are rejected.
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_plugins
    Enable plugins.
enable_scripts
    Enable scripts.
enable_socket
    When enabled the first instance of xxxterm will create a socket in the ~/.xxxterm directory. Using the -n url option on subsequent xxxterm invocations 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 languages can be set using spell_check_languages option.
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.
guess_search
    When enabled xxxterm 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.
home
    Homepage in URL format.
http_proxy
    Proxy server in URL format. xxxterm overrides http_proxy if it is specified as an environment variable. It must be noted that one MUST use an IP address and not a FQDN.

    If one desires to use a socks proxy then an intermediary tool must be used. It has been reported that tsocks works with xxxterm.
icon_size
    Permits icon sizes to be changed if fancy_bar is enabled. Size 1 is small; 2 is normal; 3 through 6 are progressively larger.
js_wl
    This is a Java Script whitelist item. See cookie_wl for semantics and more details.
max_connections
    The maximum number of connections that xxxterm can open at once.
max_host_connections
    The maximum number of connections that xxxterm 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. Alternatively 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.
read_only_cookies
    Mark cookies file read-only and discard all cookies once the session is terminated.
refresh_interval
    Refresh interval while in the download manager. The default is 10.
resource_dir
    Directory that contains various xxxterm 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 ~/.xxxterm/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 cookies 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 xxxterm.conf file for details.
session_autosave
    Enable session auto-saving when changing state (e.g. adding or removing a tab). The session name is what is currently 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_statusbar
    Enable or disable showing the status bar.
single_instance
    If set only one xxxterm will be permitted to run. If there is a URL specified it will be opened in a new tab in the already running xxxterm 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 when the certificate is trusted and yellow when untrusted.

    If ssl_ca_file is not set then the URL bar will color all HTTPS connections red.
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_font
    Set the status bar font. E.g. statusbar_font = monospace normal 9.
user_agent
    Set to override the default xxxterm user-agent string.
window_height
    Set the default height of the browser window.
window_width
    Set the default width of the browser window.
work_dir
    Set the work directory where all xxxterm scratch files are stored. Default is ~/.xxxterm.

HISTORY
xxxterm was inspired by vimprobable2 and the bloat in other UNIX web browsers.

AUTHORS
-nosplit xxxterm was written by Marco Peereboom <marco@peereboom.us>, Stevan Andjelkovic <stevan@student.chalmers.se>, Edd Barrett <vext01@gmail.com>, and Todd T. Fries <todd@fries.net>.

BUGS
When save_global_history is enabled xxxterm is supposed to, in addition to restoring the global history, color the visited links accordingly; however due to bug #51747 in WebKit this does not happen.