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.
65 .It Fl s Ar session_name
66 Open session that was saved with ":session save" command.
68 Disable visualization of tabs.
72 Display version and exit.
75 The following notation is used throughout this page:
77 .Bl -tag -width Ds -offset indent -compact
83 Meta 1 (sometimes marked Alt)
89 Meta 4 (sometimes marked Windows)
96 To browse to a specific address,
97 either use the mouse to click on the address bar
100 to shift the keyboard focus to the address bar.
101 The address is then entered manually.
103 The mouse can be used to navigate the page in the traditional manner,
104 or the keyboard can be used instead.
109 will scroll up and down the page.
112 either click on it or use the
116 assign numbers to each link on the page;
117 entering that number on the keyboard will prompt
122 provides many actions accessed via key or mouse bindings.
123 Most can be reprogrammed using a
125 entry in the configuration file.
126 Each keyboard shortcut requires exactly one entry in the configuration file.
127 A shortcut can have multiple entries in the configuration file.
128 The format of the keybinding entry is as follows:
130 .D1 keybinding = action,keystroke(s)
132 For example, "keybinding = tabnew,C-t" where
140 key word is special and is meant to reset the key binding list to the GTK+
142 This keyword should be the first
144 entry in the configuration file.
146 Shift should be used sparingly since it gets in the way of non-USA keyboards.
147 See the accompanying configuration file for examples.
149 The various bindings are documented below.
150 The relevant keybinding action is given afterwards, in parentheses.
152 These commands are used to search for text strings within a web page.
154 .Bl -tag -width Ds -offset indent -compact
158 Start a backwards search
160 Next item matching search
163 Previous item matching search
167 These commands are used to shift the focus of
169 from one area to another.
171 .Bl -tag -width Ds -offset indent -compact
176 Focus on search entry
180 These commands allow the user to map specific actions to specific keys.
181 It can be useful when the
185 .Bl -tag -width Ds -offset indent -compact
189 Alias for ":open current-uri"
193 Alias for ":tabnew current-uri"
195 .Ss Navigation Commands
196 These commands allow the user to navigate web pages and,
200 .Bl -tag -width "Space, C-f, PageDownXXX" -offset indent -compact
205 Reload page without using any cached data
207 .It Cm Backspace, M-Left
210 .It Cm S-BackSpace, M-Right
217 Previous line on page
225 .It Cm Space, C-f, PageDown
227 .Pq Cm scrollpagedown
239 .Pq Cm scrollfarright
259 Toggle Java Script enabled for FQDN
265 Toggle cookie enabled for FQDN
270 supports tabbed browsing.
271 That is, web pages may be opened in separate tabs,
272 allowing the user to quickly move from one page to another,
274 These commands then are used to create, destroy, and move between tabs.
276 .Bl -tag -width "C-plus, C-equalXXX" -offset indent -compact
278 Open new tab with the clicked link
280 Create new tab with focus in URL entry
289 Go to the previous tab
299 Shrink font size by one point
301 .It Cm C-plus, C-equal
302 Grow font size by one point
305 .Ss Yanking and pasting
306 These commands copy and paste text to and from the clipboard.
308 .Bl -tag -width Ds -offset indent -compact
310 Paste the contents of the clipboard into the address bar
313 Paste the contents of the clipboard into a new tab
316 Yank the current URL into the clipboard
319 .Ss Hyperlink Following
320 This allows the user to follow hyperlinks
321 without using a mouse.
322 Enter the corresponding number to follow the link.
323 Alternatively one can type the name of the link and when there are no more
326 will follow the link.
328 .Bl -tag -width Ds -offset indent -compact
330 Highlight all links and prefix them with a number.
334 Commands to exit the browser.
336 .Bl -tag -width Ds -offset indent -compact
342 Command mode works in a similar fashion to the
345 it is entered by typing a colon and exited by typing Esc.
346 The commands and their descriptions are listed below.
347 .Bl -tag -width Ds -offset indent
348 .It Cm about , version
349 Show the "About" page.
351 Display CA certificates.
352 .It Cm cert , cert show
353 Download and display certificates of domain on tab.
355 Save certificate into a local store.
356 The next time the site is visited it is compared against the store.
357 If the certificate matches,
358 the address bar will be blue;
359 if it doesn't the bar will be red.
363 command is used to manipulate the cookie whitelist.
364 Used by itself it expands to
365 .Cm cookie show all .
367 Show cookie jar contents.
368 .It Cm cookie save, cookie save fqdn
369 Save the current fully qualified domain name (FQDN)
370 to the persistent whitelist.
372 the www.peereboom.us domain would result in saving .www.peereboom.us.
373 .It Cm cookie save domain
374 Save the top level domain name to the persistent whitelist.
376 the www.peereboom.us domain would result in saving .peereboom.us.
378 This action enables cookies if it is currently disabled for this entry.
379 .It Cm cookie show all
380 Show all persistent and session entries in the cookie whitelist.
381 .It Cm cookie show persistent
382 Show all persistent entries in the cookie whitelist.
383 .It Cm cookie show session
384 Show all session entries in the cookie whitelist.
385 .It Cm cookie toggle domain
386 Toggle cookie support for the current top level domain.
387 .It Cm cookie toggle, cookie toggle fqdn
388 Toggle Java Script execution for the current FQDN.
390 Show download manager.
394 Add the current page to favorites.
395 .It Cm fullscreen , f
396 Toggle hiding tabs and url entry toolbar.
397 .It Cm h , hist , history
406 command is used to manipulate the Java Script whitelist.
407 Used by itself it expands to
409 .It Cm js save, save fqdn
410 Saves the FQDN to the persistent whitelist.
412 the www.peereboom.us domain would result in saving .www.peereboom.us.
413 .It Cm js save domain
414 Saves the top level domain name to the persistent whitelist.
416 the www.peereboom.us domain would result in saving .peereboom.us.
418 This action enables Java Script if it is currently disabled for this entry.
420 Shows all persistent and session entries in the JS whitelist.
421 .It Cm js show persistent
422 Shows all persistent entries in the JS whitelist.
423 .It Cm js show session
424 Shows all session entries in the JS whitelist.
425 .It Cm js toggle, js toggle fqdn
426 Toggle Java Script execution for the current FQDN.
427 .It Cm js toggle domain
428 Toggle Java Script execution for the current top level domain.
429 .It Cm open , op , o URL
437 Close current tab and quit
439 if it is the last tab.
443 and reload all current tabs.
444 .It Cm session , Cm session show
445 Display the current session name.
446 By default the session name is main_session.
447 To create a new session use the
450 A session is defined as the lifetime of the browser application.
451 .It Cm session delete <session_name>
452 Delete session session_name from persistent storage.
453 If session_name is the current session then the session will revert to
455 .It Cm session open <session_name>
456 Open session_name and close all currently open tabs.
457 Going forward this session is named session_name.
458 .It Cm session save <session_name>
459 Save current tabs to session_name session.
460 This will close the current session and going forward this session is named
463 Show blocked cookie statistics.
464 These statistics vary based on settings and are not persistent.
465 .It Cm statushide , statush
467 .It Cm statusshow , statuss
469 .It Cm tabclose , tabc
471 .It Cm tabhide , tabh
473 .It Cm tabnew , tabedit , tabe URL
474 Create new tab and optionally open provided URL.
475 .It Cm tabnext , tabn
477 .It Cm tabprevious , tabp
478 Go to the previous tab.
479 .It Cm tabshow , tabs
481 .It Cm urlhide , urlh
482 Hide url entry and tool bar.
483 .It Cm urlshow , urls
484 Show url entry and tool bar.
486 Save open tabs to current session.
487 The tabs will be restored next time
489 the session is opened.
490 See the session command for additional details.
492 Save open tabs and quit.
493 The tabs will be restored next time
495 the session is opened.
496 See the session command for additional details.
499 The about screens are internally generated web pages by
501 for user interaction.
502 These are entered in the address bar and the format is
504 where screen is the desired screen to display.
505 For example about:favorites.
506 Any about screen can be used as the home page as specified by
508 in the configuration file.
510 .Bl -tag -width "downloadsXXX" -offset indent -compact
512 show the about screen
516 show the cookie whitelist screen
518 show the cookiejar screen
520 show the downloads screen
522 show the favorites screen
524 show the help web page
526 show the history screen
528 show the Java Script whitelist screen
530 show the settings screen
532 show the statistics screen
535 This section descibes advanced usage settings.
536 Most users should use
540 and skip over this section.
543 has a number of whitelists to control blocking cookies and Java Script
544 execution for FQDNs or domains.
545 When properly enabled these whitelists require either the FQDN or top level
546 domain to exist in the whitelists in order to allow cookies to be stored or
547 Java Script to execute.
548 Both Java Script and cookies have two whitelists associated with them.
549 The whitelists are called session and persistent.
550 Items in the session whitelists are only allowed for the lifetime of the
553 Items in the persistent whitelists are stored on disk and are restored
556 Setting up the whitelists is a little tricky due to intricacies of WebKit.
557 In fact the semantics are different for cookies and Java Script.
559 Cookie whitelist requires the following configuration to be set:
561 .Bl -tag -width "enable_cookie_whitelistXXX" -offset indent -compact
562 .It Cm cookies_enabled
563 This is a WebKit setting and must be set to
566 in order to be able to use a
568 .It Cm enable_cookie_whitelist
569 This needs to be set to
571 to enable the cookie whitelist functionality.
573 These entries in the configuration file are the actual domains names in the
577 Java Script whitelist requires the following configuration to be set:
579 .Bl -tag -width "enable_js_whitelistXXX" -offset indent -compact
580 .It Cm enable_scripts
581 This is a WebKit setting and must be set to
584 in order to be able to use a
585 Java Script whitelist.
586 .It Cm enable_js_whitelist
587 This needs to be set to
589 to enable the Java Script whitelist functionality.
591 These entries in the configuration file are the actual domains names in the
592 Java Script whitelist.
597 section for additional configuration file entries and details
598 that alter runtime behavior.
600 .Bl -tag -width "/etc/xxxterm.confXXX" -compact
601 .It Pa ~/.xxxterm.conf
603 user specific settings.
610 tries to open the user specific file,
611 .Pa ~/.xxxterm.conf .
612 If that file is unavailable,
613 it then uses built-in defaults.
615 The format of the file is \*(Ltkeyword\*(Gt = \*(Ltsetting\*(Gt.
618 .Dl http_proxy = http://127.0.0.1:8080
620 Enabling or disabling an option is done by using 1 or 0 respectively.
622 The file supports the following keywords:
624 .Bl -tag -width "enable_cookie_whitelistXXX" -offset indent -compact
626 Defines an alias for a given URL, so that the URL is loaded when the alias is
627 entered in the address bar.
628 If the aliased URL includes a %s format specifier, then any argument given after
629 the alias on the address bar is substituted.
630 For example, if g,http://www.google.com/search?q=%s is defined as an alias,
631 then the URL http://www.google.com/search?q=foo is loaded when navigating to
633 .It Cm allow_volatile_cookies
634 If set cookies are stored in the session cache but will be discarded once
637 Unfortunately enabling this does allow for some limited tracking on the web.
639 When set a new tab is appended after the current tab instead of being appended
644 browser has 2 default operating modes:
650 mode the browser allows all cookies and Java Script as any other browser
652 This means that all cookies are saved to persistent storage and that all
655 On the other hand, using the
657 mode enables whitelists.
658 This requires the user to add all the required
663 If a domain does not appear in the whitelists
665 disallows cookies and Java Script execution.
667 This setting must be the first entry in
669 because it sets advanced settings that can be overridden later in the file.
670 See the default config file for more details.
672 This field delineates the cookie policy.
673 Possible values are: no3rdparty, reject 3rd party cookies.
674 accept, accept all cookies.
675 reject, reject all cookies.
677 This is a cookie whitelist item.
678 Use multiple times to add multiple entries.
679 Valid entries are for example *.moo.com and the equivalent .moo.com.
680 A fully qualified host is also valid and is for example www.moo.com.
681 .It Cm cookies_enabled
683 .It Cm ctrl_click_focus
684 Give focus in newly created tab instead of opening it in the background.
685 .It Cm default_font_size
686 Set the default browsing font size.
687 .It Cm default_zoom_level
688 Set the default browsing zoom level.
690 Locations where files are downloaded to.
691 This directory must exist and
693 validates that during startup.
694 .It Cm enable_cookie_whitelist
695 When enabled all cookies must be in the whitelist or they are rejected.
696 .It Cm enable_js_whitelist
697 When enabled all domains must be in the js whitelist in order to run Java Script.
701 .It Cm enable_plugins
703 .It Cm enable_scripts
706 When enabled the first instance of
708 will create a socket in the
711 Using the -n url option on subsequent
713 invocations will cause the specified URL to be loaded in a new tab.
714 Only a user with identical UID and GID can use this option.
716 Enables a backward, forward, and stop button to the toolbar.
719 is set it'll enable an entry box for searches.
723 will try to guess if the string you entered, in the URI entry widget or
724 the command widget, is term you want to search for using search_string
726 If the string does not contain a dot nor a slash, is not a
727 path to a local file and does not resolves to an IP then it is assumed
730 Homepage in URL format.
732 Proxy server in URL format.
736 if it is specified as an environment variable.
737 It must be noted that one MUST use an IP address and not a FQDN.
739 If one desires to use a socks proxy then an intermediary tool must be used.
740 It has been reported that tsocks works with
743 Permits icon sizes to be changed if
746 Size 1 is small; 2 is normal; 3 through 6 are progressively larger.
748 This is a Java Script whitelist item.
751 for semantics and more details.
753 Sets an action for a specific or default MIME type.
754 For example, to download and view a pdf using kpdf set mime_type =
755 application/pdf,kpdf.
756 To set a default value use *, for example mime_type = video/*,mplayer.
757 Note that the action is only passed the URL and not all applications are
758 capable of downloading content and therefore one might have to create a wrapper
759 script to download the content first.
760 .It Cm read_only_cookies
761 Mark cookies file read-only and discard all cookies once the session is
763 .It Cm refresh_interval
764 Refresh interval while in the download manager.
767 Directory that contains various
769 resources such as icons.
770 This is OS-specific and should be handled by the porter.
771 .It Cm save_global_history
772 If set the global history will be saved to
773 .Pa ~/.xxxterm/history
775 and restored at startup.
778 section above for how the global history is accessed.
779 Global history is not saved to disk by default.
780 .It Cm save_rejected_cookies
781 Saves rejected cookies in cookie format in {work_dir}/rejected.txt.
782 All cookies are saved and unlike a cookie jar they are never replaced.
783 Make sure there is enough disk space to enable this feature.
785 Default search engine string.
789 .It Cm session_autosave
790 Enable session auto-saving when changing state (e.g. adding or removing a tab).
791 The session name is what is currently in use and is described in the
796 .It Cm session_timeout
797 This value is the time that is added in seconds to a session cookie.
799 Enable or disable showing tabs.
801 Enable or disable showing the url and toolbar.
802 .It Cm show_statusbar
803 Enable or disable showing the status bar.
804 .It Cm single_instance
807 will be permitted to run.
808 If there is a URL specified it will be opened in a new tab in the already
813 If set to a valid PEM file
814 all server certificates will be validated against it.
815 The URL bar will be colored green when the certificate is trusted
816 and yellow when untrusted.
820 is not set then the URL bar will color all HTTPS connections red.
821 .It Cm ssl_strict_certs
822 If this value is set connections to untrusted sites will be aborted.
823 This value is only used if
827 Set to override the default
831 Set the default height of the browser window.
833 Set the default width of the browser window.
835 Set the work directory where all
837 scratch files are stored.
843 was inspired by vimprobable2 and the bloat in other
850 .An Marco Peereboom Aq marco@peereboom.us ,
851 .An Stevan Andjelkovic Aq stevan@student.chalmers.se ,
852 .An Edd Barrett Aq vext01@gmail.com ,
854 .An Todd T. Fries Aq todd@fries.net .
857 .Cm save_global_history
860 is supposed to, in addition to restoring the global history, color the
861 visited links accordingly; however due to bug #51747 in WebKit this does