3 .\" Copyright (c) 2010, 2011 Marco Peereboom <marco@peereboom.us>
4 .\" Copyright (c) 2011 Jason McIntyre <jmc@openbsd.org>
6 .\" Permission to use, copy, modify, and distribute this software for any
7 .\" purpose with or without fee is hereby granted, provided that the above
8 .\" copyright notice and this permission notice appear in all copies.
10 .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
11 .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
12 .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
13 .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
14 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
15 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
16 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
23 .Nd lightweight web browser
29 .Op Fl s Ar session_name
34 is a minimalistic web browser that tries to stay out of the way so that
35 valuable screen real estate can be used for much more important stuff.
36 It has sane defaults and does not require one to learn a language to do any
38 It was written by hackers for hackers
39 and it strives to be small, compact, and fast.
42 is very simple in its use.
43 Most actions are initiated via key or mouse bindings.
44 Key bindings are based on those of the
47 giving web browsing a similar feel to navigating a text document.
50 section below documents the various defaults and possible customizations.
52 The options are as follows:
55 Specify an alternative configuration file.
57 Open a new tab in a running
59 for each specified URL.
64 Execute arbitrary command (see the
66 section below) in a running
68 instance. This option requires
70 to be enabled. Example run: xxxterm -e "tabnew openbsd.org"; xxxterm -e
71 tabclose; xxxterm -e wq.
74 .It Fl s Ar session_name
75 Open session that was saved with ":session save" command.
77 Disable visualization of tabs.
81 Display version and exit.
84 The following notation is used throughout this page:
86 .Bl -tag -width Ds -offset indent -compact
92 Meta 1 (sometimes marked Alt)
98 Meta 4 (sometimes marked Windows)
105 To browse to a specific address,
106 either use the mouse to click on the address bar
109 to shift the keyboard focus to the address bar.
110 The address is then entered manually.
112 The mouse can be used to navigate the page in the traditional manner,
113 or the keyboard can be used instead.
118 will scroll up and down the page.
121 either click on it or use the
125 assign numbers to each link on the page;
126 entering that number on the keyboard will prompt
131 provides many actions accessed via key or mouse bindings.
132 Most can be reprogrammed using a
134 entry in the configuration file.
135 Each keyboard shortcut requires exactly one entry in the configuration file.
136 A shortcut can have multiple entries in the configuration file.
137 The format of the keybinding entry is as follows:
139 .D1 keybinding = action,(!)keystroke(s)
141 For example, "keybinding = tabnew,C-t" where
147 GTK has some default keybindings for manipulating text inside input
148 fields, such as the URI or search entry widget, for example
150 deletes a word. To override these defaults prefix your key with an
151 exclamation mark, like this: "keybinding = tabclose,!C-w".
154 key word is special and is meant to reset the key binding list to the GTK+
156 This keyword should be the first
158 entry in the configuration file.
160 Shift should be used sparingly since it gets in the way of non-USA keyboards.
161 See the accompanying configuration file for examples.
163 The various bindings are documented below.
164 The relevant keybinding action is given afterwards, in parentheses.
166 These commands are used to search for text strings within a web page.
168 .Bl -tag -width Ds -offset indent -compact
173 Start a backwards search
176 Next item matching search
179 Previous item matching search
183 These commands are used to shift the focus of
185 from one area to another.
187 .Bl -tag -width Ds -offset indent -compact
192 Focus on search entry
196 These commands allow the user to map specific actions to specific keys.
197 It can be useful when the
201 .Bl -tag -width Ds -offset indent -compact
205 Alias for ":toplevel toggle"
210 Alias for ":open current-uri"
211 .Pq Cm promptopencurrent
216 Alias for ":tabnew current-uri"
217 .Pq Cm prompttabnewcurrent
219 .Ss Navigation Commands
220 These commands allow the user to navigate web pages and,
224 .Bl -tag -width "Space, C-f, PageDownXXX" -offset indent -compact
228 .It Cm Backspace, M-Left
231 .It Cm S-BackSpace, M-Right
238 Previous line on page
246 .It Cm Space, C-f, PageDown
248 .Pq Cm scrollpagedown
260 .Pq Cm scrollfarright
280 Toggle Java Script enabled for FQDN
286 Toggle cookie enabled for FQDN
291 supports tabbed browsing.
292 That is, web pages may be opened in separate tabs,
293 allowing the user to quickly move from one page to another,
295 These commands then are used to create, destroy, and move between tabs.
297 .Bl -tag -width "C-plus, C-equalXXX" -offset indent -compact
299 Open new tab with the clicked link
301 Create new tab with focus in URL entry
310 Go to the previous tab
318 .Pq Cm tabnext [1..9]
322 .It Cm C-plus, C-equal
326 Set zoom level to 100%
329 .Ss Yanking and pasting
330 These commands copy and paste text to and from the clipboard.
332 .Bl -tag -width Ds -offset indent -compact
334 Paste the contents of the clipboard into the address bar
337 Paste the contents of the clipboard into a new tab
340 Yank the current URL into the clipboard
343 .Ss Hyperlink Following
344 This allows the user to follow hyperlinks
345 without using a mouse.
346 Enter the corresponding number to follow the link.
347 Alternatively one can type the name of the link and when there are no more
350 will follow the link.
352 .Bl -tag -width Ds -offset indent -compact
354 Highlight all links and prefix them with a number.
358 Commands to exit the browser.
360 .Bl -tag -width Ds -offset indent -compact
365 .Ss Low-Contrast Color Scheme
366 This command toggles the page's style between the default CSS and a
367 low-contrast color scheme with light grey text on a dark grey background.
369 .Bl -tag -width Ds -offset indent -compact
371 Toggle the current tab's style.
375 Command mode works in a similar fashion to the
378 it is entered by typing a colon and exited by typing Esc.
379 The commands and their descriptions are listed below.
380 .Bl -tag -width Ds -offset indent
381 .It Cm about , version
382 Show the "About" page.
383 .It Cm buffers , ls , tabs
384 Displays the currently open tabs and lets the user switch tab by typing
385 the tab number or using the mouse.
387 Display CA certificates.
388 .It Cm cert , cert show
389 Download and display certificates of domain on tab.
391 Save certificate into a local store.
392 The next time the site is visited it is compared against the store.
393 If the certificate matches,
394 the address bar will be blue;
395 if it doesn't the bar will be red.
399 command is used to manipulate the cookie whitelist.
400 Used by itself it expands to
401 .Cm cookie show all .
403 Show cookie jar contents.
404 .It Cm cookie save, cookie save fqdn
405 Save the current fully qualified domain name (FQDN)
406 to the persistent whitelist.
408 the www.peereboom.us domain would result in saving .www.peereboom.us.
409 .It Cm cookie save domain
410 Save the top level domain name to the persistent whitelist.
412 the www.peereboom.us domain would result in saving .peereboom.us.
414 This action enables cookies if it is currently disabled for this entry.
415 .It Cm cookie show all
416 Show all persistent and session entries in the cookie whitelist.
417 .It Cm cookie show persistent
418 Show all persistent entries in the cookie whitelist.
419 .It Cm cookie show session
420 Show all session entries in the cookie whitelist.
421 .It Cm cookie toggle domain
422 Toggle cookie support for the current top level domain.
423 .It Cm cookie toggle, cookie toggle fqdn
424 Toggle cookie support for the current FQDN.
426 Show download manager.
430 Add the current page to favorites.
431 .It Cm fullscreen , f
432 Toggle hiding tabs and url entry toolbar.
433 .It Cm h , hist , history
442 command is used to manipulate the Java Script whitelist.
443 Used by itself it expands to
445 .It Cm js save, save fqdn
446 Saves the FQDN to the persistent whitelist.
448 the www.peereboom.us domain would result in saving .www.peereboom.us.
449 .It Cm js save domain
450 Saves the top level domain name to the persistent whitelist.
452 the www.peereboom.us domain would result in saving .peereboom.us.
454 This action enables Java Script if it is currently disabled for this entry.
456 Shows all persistent and session entries in the JS whitelist.
457 .It Cm js show persistent
458 Shows all persistent entries in the JS whitelist.
459 .It Cm js show session
460 Shows all session entries in the JS whitelist.
461 .It Cm js toggle, js toggle fqdn
462 Toggle Java Script execution for the current FQDN.
463 .It Cm js toggle domain
464 Toggle Java Script execution for the current top level domain.
465 .It Cm open , op , o URL
469 .It Cm qa , qall , quitall
473 Close current tab and quit
475 if it is the last tab.
479 and reload all current tabs.
480 .It Cm run_script [path_to_script]
481 Runs the script path_to_script with the current uri as the argument.
482 If path_to_script is not provided, the value of default_script is used
484 .It Cm session , Cm session show
485 Display the current session name.
486 By default the session name is main_session.
487 To create a new session use the
490 A session is defined as the lifetime of the browser application.
491 .It Cm session delete <session_name>
492 Delete session session_name from persistent storage.
493 If session_name is the current session then the session will revert to
495 .It Cm session open <session_name>
496 Open session_name and close all currently open tabs.
497 Going forward this session is named session_name.
498 .It Cm session save <session_name>
499 Save current tabs to session_name session.
500 This will close the current session and going forward this session is named
503 Show blocked cookie statistics.
504 These statistics vary based on settings and are not persistent.
505 .It Cm statustoggle , statust
507 .It Cm tabclose , tabc
511 .It Cm tabnew , tabedit , tabe URL
512 Create new tab and optionally open provided URL.
513 .It Cm tabnext , tabn
515 .It Cm tabprevious , tabp
516 Go to the previous tab.
519 .It Cm toplevel , toplevel toggle
520 Toggle the top level domain name cookie and JS session whitelist.
521 This is to enable/disable short lived full site functionality without
522 permanently adding the top level domain to the persistent whitelist.
523 .It Cm urlhide , urlh
524 Hide url entry and tool bar.
525 .It Cm urlshow , urls
526 Show url entry and tool bar.
528 Save open tabs to current session.
529 The tabs will be restored next time the session is opened.
530 See the session command for additional details.
532 Save open tabs and quit.
533 The tabs will be restored next time
535 the session is opened.
536 See the session command for additional details.
539 In addition to shortcuts and commands
541 provides buffer commands. Buffer commands are short, multi character
542 vi-like commands, often requiring an argument. Partial buffer commands
544 displayed in the buffer command statusbar element (see
545 .Cm statusbar_elems ) .
546 Pressing Esc or switching to another tab cancels a partially entered
547 buffer command. In the following list
549 denotes the argument a buffer command accepts. Buffer commands are
550 defined as extended regular experssions.
551 Note that if a character is used as a shortcut it will not be interpreted
552 as the beginning of a buffer command. This is the case with
555 .Bl -tag -width "[`'][a-zA-Z0-9]XXX" -offset indent -compact
557 go to the top of the page
559 go to the bottom of the page
569 is missing, 1 is assumed. Going a
570 level up means going to a uri obtained from the current one by removing
571 the last slash ('/') character and everything that follows it
573 open the home page in the current tab
575 set a mark denoted by
577 at the current page position. These marks behave like those in vi or
579 .It Cm [`'][a-zA-Z0-9]
580 go to the position where mark
584 set the current uri as quickmark
587 open the uri marked as quickmark
591 open the uri marked as quickmark
608 set zoom level to 100%
615 Quickmarks are like bookmarks, except they are refered to by a single
616 character (a letter or a digit), instead of a longer name. See the
621 buffer commands for usage. Quickmarks are stored in
622 .Pa ~/.xxxterm/quickmarks
623 and are saved automatically after each
627 The about screens are internally generated web pages by
629 for user interaction.
630 These are entered in the address bar and the format is
632 where screen is the desired screen to display.
633 For example about:favorites.
634 Any about screen can be used as the home page as specified by
636 in the configuration file.
638 .Bl -tag -width "downloadsXXX" -offset indent -compact
640 show the about screen
644 show the cookie whitelist screen
646 show the cookiejar screen
648 show the downloads screen
650 show the favorites screen
652 show the help web page
654 show the history screen
656 show the Java Script whitelist screen
658 show the settings screen
660 show the statistics screen
663 This section describes advanced usage settings.
664 Most users should use
668 and skip over this section.
671 has a number of whitelists to control blocking cookies and Java Script
672 execution for FQDNs or domains.
673 When properly enabled these whitelists require either the FQDN or top level
674 domain to exist in the whitelists in order to allow cookies to be stored or
675 Java Script to execute.
676 Both Java Script and cookies have two whitelists associated with them.
677 The whitelists are called session and persistent.
678 Items in the session whitelists are only allowed for the lifetime of the
681 Items in the persistent whitelists are stored on disk and are restored
684 Setting up the whitelists is a little tricky due to intricacies of WebKit.
685 In fact the semantics are different for cookies and Java Script.
687 Cookie whitelist requires the following configuration to be set:
689 .Bl -tag -width "enable_cookie_whitelistXXX" -offset indent -compact
690 .It Cm cookies_enabled
691 This is a WebKit setting and must be set to
694 in order to be able to use a
696 .It Cm enable_cookie_whitelist
697 This needs to be set to
699 to enable the cookie whitelist functionality.
701 These entries in the configuration file are the actual domains names in the
705 Java Script whitelist requires the following configuration to be set:
707 .Bl -tag -width "enable_js_whitelistXXX" -offset indent -compact
708 .It Cm enable_scripts
709 This is a WebKit setting and must be set to
712 in order to be able to use a
713 Java Script whitelist.
714 .It Cm enable_js_whitelist
715 This needs to be set to
717 to enable the Java Script whitelist functionality.
719 These entries in the configuration file are the actual domains names in the
720 Java Script whitelist.
725 section for additional configuration file entries and details
726 that alter runtime behavior.
728 .Bl -tag -width "/etc/xxxterm.confXXX" -compact
729 .It Pa ~/.xxxterm.conf
731 user specific settings.
738 tries to open the user specific file,
739 .Pa ~/.xxxterm.conf .
740 If that file is unavailable,
741 it then uses built-in defaults.
743 The format of the file is \*(Ltkeyword\*(Gt = \*(Ltsetting\*(Gt.
746 .Dl http_proxy = http://127.0.0.1:8080
748 Enabling or disabling an option is done by using 1 or 0 respectively.
750 The file supports the following keywords:
752 .Bl -tag -width "enable_cookie_whitelistXXX" -offset indent -compact
754 Defines an alias for a given URL, so that the URL is loaded when the alias is
755 entered in the address bar.
756 If the aliased URL includes a %s format specifier, then any argument given after
757 the alias on the address bar is substituted.
758 For example, if g,http://www.google.com/search?q=%s is defined as an alias,
759 then the URL http://www.google.com/search?q=foo is loaded when navigating to
761 .It Cm allow_volatile_cookies
762 If set cookies are stored in the session cache but will be discarded once
765 Unfortunately enabling this does allow for some limited tracking on the web.
767 When set a new tab is appended after the current tab instead of being appended
772 browser has 3 default operating modes:
780 mode the browser allows all cookies and Java Script as any other browser
782 This means that all cookies are saved to persistent storage and that all
785 On the other hand, using the
787 mode enables whitelists.
788 This requires the user to add all the required
793 If a domain does not appear in the whitelists
795 disallows cookies and Java Script execution.
799 mode the browse works just like
801 mode however the toolbar only has the backward, forward and home button.
803 This setting must be the first entry in
805 because it sets advanced settings that can be overridden later in the file.
806 See the default config file for more details.
808 Set the command prompt font.
810 .Pa cmd_font = monospace normal 9 .
812 This field delineates the cookie policy.
813 Possible values are: no3rdparty, reject 3rd party cookies.
814 accept, accept all cookies.
815 reject, reject all cookies.
817 This is a cookie whitelist item.
818 Use multiple times to add multiple entries.
819 Valid entries are for example *.moo.com and the equivalent .moo.com.
820 A fully qualified host is also valid and is for example www.moo.com.
821 .It Cm cookies_enabled
823 .It Cm ctrl_click_focus
824 Give focus in newly created tab instead of opening it in the background.
825 .It Cm default_script
826 Path to the script used as the default value for the run_script
828 .It Cm default_zoom_level
829 Set the default browsing zoom level.
831 Locations where files are downloaded to.
832 This directory must exist and
834 validates that during startup.
835 .It Cm enable_cookie_whitelist
836 When enabled all cookies must be in the whitelist or they are rejected.
837 .It Cm enable_js_whitelist
838 When enabled all domains must be in the js whitelist in order to run Java Script.
842 .It Cm enable_plugins
844 .It Cm enable_scripts
847 When enabled the first instance of
849 will create a socket in the
852 Using the -n url option on subsequent
854 invocations will cause the specified URL to be loaded in a new tab.
855 Only a user with identical UID and GID can use this option.
856 .It Cm enable_localstorage
857 Enable html5 Local Storage.
858 .It Cm enable_spell_checking
859 Enables spell checking. Preferred languages can be set using
860 .Cm spell_check_languages
863 Enables a backward, forward, and stop button to the toolbar.
866 is set it'll enable an entry box for searches.
870 will try to guess if the string you entered, in the URI entry widget or
871 the command widget, is term you want to search for using search_string
873 If the string does not contain a dot nor a slash, is not a
874 path to a local file and does not resolves to an IP then it is assumed
877 Homepage in URL format.
879 Proxy server in URL format.
883 if it is specified as an environment variable.
884 It must be noted that one MUST use an IP address and not a FQDN.
886 If one desires to use a socks proxy then an intermediary tool must be used.
887 It has been reported that tsocks works with
890 Permits icon sizes to be changed if
893 Size 1 is small; 2 is normal; 3 through 6 are progressively larger.
895 This is a Java Script whitelist item.
898 for semantics and more details.
899 .It Cm max_connections
900 The maximum number of connections that
903 .It Cm max_host_connections
904 The maximum number of connections that
906 can open at once to a given host.
908 Sets an action for a specific or default MIME type.
909 For example, to download and view a pdf using kpdf set
910 .Pa mime_type = application/pdf,kpdf .
911 To set a default value use *, for example,
912 .Pa mime_type = video/*,mplayer .
913 Note that the action is only passed the URL and not all applications are
914 capable of dealing with a URL and therefore one might have to create a wrapper
915 script to download the content first. Alternatively one can add the
917 in front of the MIME type to indicate "download first".
919 .Pa mime_type = @application/pdf,xpdf .
922 is use the file will be downloaded to the
924 before the MIME handler is called.
926 Set the font used to display error messages.
928 .Pa oops_font = monospace normal 9 .
929 .It Cm read_only_cookies
930 Mark cookies file read-only and discard all cookies once the session is
932 .It Cm refresh_interval
933 Refresh interval while in the download manager.
936 Directory that contains various
938 resources such as icons.
939 This is OS-specific and should be handled by the porter.
940 .It Cm save_global_history
941 If set the global history will be saved to
942 .Pa ~/.xxxterm/history
944 and restored at startup.
947 section above for how the global history is accessed.
948 Global history is not saved to disk by default.
949 .It Cm save_rejected_cookies
950 Saves rejected cookies in cookie format in {work_dir}/rejected.txt.
951 All cookies are saved and unlike a cookie jar they are never replaced.
952 Make sure there is enough disk space to enable this feature.
954 Default search engine string.
958 .It Cm session_autosave
959 Enable session auto-saving when changing state (e.g. adding or removing a tab).
960 The session name is what is currently in use and is described in the
965 .It Cm session_timeout
966 This value is the time that is added in seconds to a session cookie.
968 Enable or disable showing tabs.
970 Enable or disable showing the url and toolbar.
971 .It Cm show_statusbar
972 Enable or disable showing the status bar.
973 .It Cm single_instance
976 will be permitted to run.
977 If there is a URL specified it will be opened in a new tab in the already
981 .It Cm spell_check_languages
982 The languages to be used for spell checking, separated by commas. For example,
985 If set to a valid PEM file
986 all server certificates will be validated against it.
987 The URL bar will be colored green (or blue when saved ) when the certificate is
988 trusted and yellow when untrusted.
992 is not set then the URL bar will color all HTTPS connections red.
994 WebKit only supports a single PEM file.
995 Many OS' or distributions have many PEM files.
996 One can simply concatenate all separate files into one large one.
998 .Cm for i in `ls`; do cat $i >> cert.pem; done
999 and use the resulting cert.pem file as the input to
1001 It is advisable to periodically recreate the cert.pem file.
1002 .It Cm ssl_strict_certs
1003 If this value is set connections to untrusted sites will be aborted.
1004 This value is only used if
1007 .It Cm statusbar_elems
1008 Define the components of the status bar. The possible components are:
1009 .Bd -literal -offset indent
1011 P - page progress percent
1015 The default is "BP".
1016 These components show nothing if there is nothing worth showing, like
1018 .It Cm statusbar_font
1019 Set the status bar font.
1021 .Pa statusbar_font = monospace normal 9 .
1023 Set the tab style to either
1025 - the default gtk notebook tabs, or
1028 You can switch the tab style with the
1032 Set the compact tab bar font.
1034 .Pa tabbar_font = monospace normal 9 .
1036 Set to override the default
1039 .It Cm window_height
1040 Set the default height of the browser window.
1042 Set the default width of the browser window.
1044 Set the work directory where all
1046 scratch files are stored.
1052 was inspired by vimprobable2 and the bloat in other
1059 .An Marco Peereboom Aq marco@peereboom.us ,
1060 .An Stevan Andjelkovic Aq stevan@student.chalmers.se ,
1061 .An Edd Barrett Aq vext01@gmail.com ,
1062 .An Todd T. Fries Aq todd@fries.net ,
1063 .An Raphael Graf Aq r@undefined.ch ,
1065 .An Michal Mazurek Aq akfaew@jasminek.net .
1068 .Cm save_global_history
1071 is supposed to, in addition to restoring the global history, color the
1072 visited links accordingly; however due to bug #51747 in WebKit this does