============ ADMBrowser

Author: Alan D Moore (http://www.alandmoore.com, e-mail me_AT_alandmoore_DOT_com)

Contributors:

Isaac "hunternet93" Smith (isaac@isrv.pw)

Description

ADMBrowser is a browser specifically for use on web kiosks. It's based on PyQt6 and QtWebEngine (Chromium/Blink), and is designed to make lock-down very simple and painless.

It was originally conceived for use in library catalog terminals, when it became clear that browsers with ever-growing feature lists like Firefox and Chrome were too much work to lock down correctly and completely. It was also designed to be easily configurable using a simple text file that can be hand-edited in a terminal over SSH across a slow WAN, so no databases, XML, or crazy binaries here.

ADMBrowser is a fork of WCGBrowser, with these key differences:

WCGBrowser was based on QtWebKit, ADMBrowser is based on QtWebEngine
WCGBrowser supports Python 2 and Python 3. ADMBrowser requires Python 3.
WCGBrowser runs with Qt4 or Qt5. ADMBrowser requires Qt6.
The command line and configuration syntax may differ slightly.

ADMBROWSER IS CURRENTLY BETA QUALITY

Many features that were in WCGBrowser are broken or unavailable simply because QtWebEngine does things differently than QtWebKit.

Features

Blink (Chrome/Chromium) rendering
Text-based, YAML configuration
(Optional) Inactivity timeout
Popups/open-in-new-window can be disabled
Minimal, no-clutter interface simple for the general public.
Configurable navigation bar with bookmarks
Configurable handling of external MIME-types (PDF, etc)
(Optional) Whitelisting of hosts & domains
'Screensaver' mode to display a specified URL when idle
Printing support
Custom error screens
Much, much more...

Requirements

Python 3.6 or later
- You need the dataclasses library if you're using < 3.7
PyQt6
Python YAML library (http://pyyaml.org)

It should work on any platform, but it's only been tested on Arch Linux, Debian, and Ubuntu.

Usage

The included admbrowser.yaml file shows a documented example configuration. To use it, copy it to /etc/admbrowser.yaml, ~/.admbrowser.yaml, or specify it with the -c (--config-file) switch. You can make the admbrowser.py executable, or launch it using python, like so::

python admbrowser.py

At a minimum, you need to specify a start_url using either the config file or the -l switch, or else the browser isn't much use. Advanced configuration is probably best done in the configuration file, but many basic features can be enabled or disabled at the command line using these switches:

======================== ============================================================================================================================= Switch Description ======================== ============================================================================================================================= --debug_log Send debugging output to specified file --size Set the initial window size as "<width>x<height>" (e.g. "800x600"), "max" for maximized, or "full" for full-screen. --proxy_server Set the proxy server host and port, in the form <host>:<port> -c, --config-file Specify a configuration file to use -d, --debug Provide debugging output to stdout -e, --allow_external Allow the browser to open content in external programs via MIME type -g, --allow_plugins Allow the use of plugins like Flash, Java, etc. -h, --help Show quick help on command line syntax -i, --icon-theme The icon theme to use. You'll need to install these themes yourself -l, --url The "start location" for the browser. This is the initial URL it will load, and where it will return when reset. -n, --no-navigation Turn off the navigation panel (back, forward, home, shortcuts, etc). -p, --popups Enable the creation of new windows when a link is clicked that opens in a new window, or javascript tries to open a window -t, --timeout The timeout for the inactivity monitor. After this many seconds of inactivity, reset the browser -u, --user Set the default username to be sent when a site requests authentication -w, --password Set the default password to be sent when a site requests authentication -z, --zoom The default zoom factor for content. 0 ignores this. 1 is default, 2 would be double size, 0.5 would be half-size, etc. ======================== =============================================================================================================================

ADMBrowser also accepts the built-in Qt command-line arguments, which provide some low-level overrides. Documentation of these switches can be found at https://doc.qt.io/qt-5/qapplication.html#QApplication.

Configuration File

The sample configuration file is fully commented, and should be pretty easy to configure if you just read through it. In case you just want to start from scratch, here are the current configuration options available for the application.

====================== =============== Option Name Default Value ====================== =============== allow_external_content False allow_plugins False allow_popups False force_js_confirm "ask" suppress_alerts False allow_printing False print_settings (empty) default_password (empty) default_user (empty) icon_theme (qt5 default) navigation True navigation_layout (see below) network_down_html (empty) page_unavailable_html (empty) privacy_mode True user_agent (qt5 default) proxy_server (empty) quit_button_mode reset quit_button_text screensaver_url about:blank ssl_mode strict start_url about:blank stylesheet (empty) timeout 0 timeout_mode reset whitelist (empty) window_icon (empty) window_size "max =============================================================================================================================================================================================================================================================== Explanation =============================================================================================================================================================================================================================================================== Whether or not to allow non-html content, e.g. PDF files. If this is true, you need to specify a content handler for the MIME type or a 404 error, "Network Error", or blank page will likely be displayed to the user. If true, enables the use of plugins like flash, java, etc. Whether or not to allow navigation that requires opening a new browser window, such as JavaScript window.open() calls or links with a target of "_blank". If False, the navigation will be ignored. If True, a new window will be created as expected. If set to "accept" or "deny", will override any JavaScript are-you-sure-you-want-to-exit dialog boxes with the specified answer, if set to "ask" (the default) will ask the user each time. If True, blocks JavaScript popup alerts from appearing, or shows them when False. Enable printing of web pages from the context menu or toolbar. Specify default printer settings, see below. default password to send when pages request authentication default username to send when pages request authentication Icon theme to use for navigation icons Display the navigation bar at the top (back/forward/reload/bookmarks/quit) Sets the layout of the navigation bar. See the detailed explanation below. CURRENTLY_BROKEN The full path to a file containing HTML which will be displayed when the start_url page cannot be loaded, which probably indicates some kind of network error. CURRENTLY_BROKEN The full path to a file containing HTML which will be displayed when a page cannot be loaded, either because it's not accessible or blocked by security restrictions. Enable or disable private browsing mode Overrides the default user agent string. Sets the proxy server string for HTTP proxy. Takes the form host:port, or just host if you want to use the default port of 8080. Just like timeout_mode, only this is the action taken when the quit button is pressed (same options) "I'm &Finished" Text to display on the quit/reset button. Can include an accelerator indicator (&). The URL to visit when idle. Only matters when timeout_mode is "screensaver" and "timeout" is nonzero. Defines how the browser handles SSL certificate errors. "strict" will just give an error and prevent access to the problematic URL. "ignore" will silently ignore the errors and allow access. The starting URL Filename of a QSS-format stylesheet to use for styling the application window. See example file. Number of seconds of inactivity before the browser closes or resets itself. A value of 0 disables the feature. The action performed on inactivity timeout. Values can be "reset" (to return to the start URL and clear history), "close" (to close the program), or "screensaver" (to display the screensaver_url while idle) A list of web domains or hosts to allow access to (see below). The full path of the icon file to be shown by the window manager.

Admbrowser

Install / Use

README