Configuration file

Settings of the program are stored in configuration file(s). This article explains how to configure WebOne.

The article contains information related to WebOne version 0.12.2.

Common

Location

• Windows and macOS: by default it is webone.conf in program installation directory, and all *.conf files in it.
• Linux: by default it is /etc/webone.conf and all *.conf files in /etc/webone.conf.d directory.

⭐ It is better to store your configuration in /etc/webone.conf.d directory on Linux or program installation directory on Windows & macOS. Your custom configuration files will override everything from webone.conf, while have small size and are easier to maintain. Also these files will not be overwritten by software updates.

To load an other configuration file(s) instead of default, launch the proxy server as webone path\filename.ext.

Syntax

The configuration file format is similar to well-known INI format, but also can contain raw lists of strings.

Section names may contain masks. Such sections are used to apply some rules to some URLs or to some content and their section headers are looking like this: [SectionType:Section mask] (e.g. [Edit:jquery.min.js]). Regular section names are looking simpler: [Server].

Parameters are looking as parameter=value. The values of parameters (or options) can be a text, numbers or Boolean values. Boolean (binary) parameters can be set to 1/0, y/n, yes/no, on/off, enable/disable or true/false.

Comments must begin with ";".

The file is case sensitive, so be aware on all parameter names and values.

If any parameter is not written in real configuration file or if the file cannot be loaded, default values are used. All lists are empty by default.

Default pre-installed configuration file is containing optimal settings for most of users. Note that some options in it is not strictly default (that's if they would't typed in configuration file at all).

Proxy server configuration

[Server] options

The section configures common proxy server settings.

• Port - TCP port where the server should be run. Default: 80. Port can be overriden by starting server as webone PORT or webone PORT CONFIGFILE.
• OutputEncoding - encoding (code page) of output content. WebOne can convert text-based content from source encoding to any set in this parameter. This may allow browsing non-English sites on MS-DOS/Unix machines or via non-Unicode-aware browser. Here you may set any code page number, Windows (to auto-detect ANSI code page for server's locale), DOS (to auto-detect OEM code page), EBCDIC (to auto-detect IBM code page) or Mac (to auto-detect Apple code page for server's locale). Or to do not touch the code page set it to AsIs. Default: AsIs.
• Authenticate - HTTP Proxy authentication credentials. See below for details. Default: empty (no authentication).
• HideClientErrors - hide any client's errors in WebOne log. If browser rejects packages from proxy (if user has clicked "Stop" button, closed the tab, the browser doesn't like format of the file, etc) WebOne begins to be sad. Because empty tears are not need to be logged, they may be ignored by this parameter. Default: no (errors will be shown).
• SearchInArchive - allow searching of archived copies of unavailable content via Internet Archive Wayback Machine. Default: no.
• HideArchiveRedirect - return archived pages just as they are still live. Default: no.
• ArchiveUrlSuffix - may be fw_ to hide archive.org toolbar, id_ to keep original links or empty to return default archive.org pages. Default: empty (no suffix).
• ShortenArchiveErrors - because very old browser can't correctly display Archive.org error pages, WebOne can show internal error pages that are friendly to retro browsers. They can be enabled by this parameter. Default: no.
• ArchiveDateLimit - upper date limit for Archive.org page snapshots (YYYYMMDD). Default: 0 (no limit/current date).
• SecurityProtocols - possible workaround for SSL/TLS errors. It enables or disables particular security protocols. This setting is based on SecurityProtocolType Enum and can be either a single type or an OR-ed combination of them. Default: unset or 4032 (4032 = 192 | 768 | 3072) depending on OS version and MS IE settings.
• ValidateCertificates - enable or disable TLS certificate validation. May be useful if the server have incorrect date and time or if you need to browse websites with incorrect certificates. Default: enable.
• DefaultHostName - proxy host's name. It may be either %HostName% placeholder (default server PC name), a MS LAN Manager computer name, a IP address or a DNS name. By default WebOne is using local computer/host name for calling itself in network things, but UNIX/Linux/BSD clients don't understand Microsoft LAN Manager (Windows 7) computer names. Also if the server is working on Linux, any Windows PCs will not resolve it by its UNIX hostname. To solve such problems, enter here a IP/DNS address that can be used by clients to connect to the proxy server. Default: %HostName%.
• UserAgent - user-agent string which servers will see on attempts to get something via this proxy. Default: %Original% WebOne/%WOVer%.
• TemporaryDirectory - folder where WebOne should store temporary files (e.g. used by format converters, etc). It may be set to default system temporary directory by using %TEMP% or $TEMP mask. Default: current directory.
• LogFile - path to file which should contain log of operations through the proxy. Default: no log file. LogFile can be overriden by starting server as webone --log LOGFILENAME or webone --log no.
• AppendLogFile - similar to LogFile, but the log file will be appended rather than erased on start time. Default: no log file.
• DisplayStatusPage - configures content of proxy server status page (http://localhost:port/). It can be a short status page, full (with some debug information), or the page should no have content (to disable the status page). Default: full.

[HostNames] section

List of alternate server host names. If WebOne is running on a VPS, enter here all its public names, like mydomain.com, 140.82.121.4, vps-140821214.panel.hosting.net.za.

⭐ If you're running WebOne on non-public server or have no compatibility/performance issues, you don't need to use this section.

HTTP traffic processing configuration

[ForceHttps] list

WebOne can automatically convert HTTP traffic to HTTPS. But some sites have incorrect redirection from old HTTP to new and secure HTTPS. The example is phantom.sannata.org where (on January, 2021) still used a Meta-Refresh tag to redirect clients which is not a good practice. Those sites (domain names) should be added to the ForceHttps list. It's some looking like HSTS list in modern browsers so it also can be used for security purposes.

Note that all sites with automatic HTTP->HTTPS security upgrades are adding to memory-stored version of this list until close of WebOne. So you don't need to add here all sites that are want to browse, except for security paranoia purposes.

[ForceUtf8] list

If you're using code page conversion you might encounter lost of non-English characters on some sites or pages. This is caused by incorrect detection of source encoding, WebOne thinks that the page in encoded in Windows CP however it's really a UTF-8 page. Regular expression masks of URLs of such content can be added to this list to force downloading content as UTF-8 and solve conversion problems.

[TextTypes] list

WebOne applies edits only to text-based content, binary files are transferring as is. This section contains list of MIME types (or parts of types) that are corresponding to content which should be edited. By default it's "text/", "javascript" (means text/* and *javascript).

[Edit:] sections

All changes to WWW traffic, doing by the proxy, are stored in Sets of edits. They describe edits applied to HTTP headers, requests, responses, page bodies and file contents. Edit Sets replaced old FixableURL, FixableType and ContentPatch sections known from WebOne 0.3.x-0.9.x.

The Set can contain detection rules (determining when the Set should be used) and edition rules (what should be edited to make the web site usable in particular browser).

ℹ️ See full article about the Sets of edits.

[Edit] sections

See above.

[Converters] list

White list of file format converters that can be used inside WebOne as a equivalent to online converter(s). The converters are local executable files (on Windows - EXE, COM, BAT, CMD and such) that can get 2-4 arguments. Converter entry should contain converter executable file name and masks for all arguments (see below). The default converter is ImageMagick's convert, running as convert %SRC% %ARG1% %DEST% %ARG2% (convert.exe SOURCE.EXT -ARGUMENT1 VALUE1 DESTINATION.EXT -ARGUMENT2 VALUE2).

The converter entry can contain following masks:

• %SRC% - source file name
• %ARG1% - first argument(s)
• %DEST% - destination file name
• or %DESTEXT% - destination file extension
• %ARG2% - second argument(s)
• %SRCURL% - source file's URL

If the converter does not know argument by %DEST% mask, WebOne thinks that it gives result to STDOUT. E.g. ImageMagick can return source.ext picture converted to GIF format through STDOUT when called as magick source.ext gif:-. This is faster that traditional temporary file for conversion result, especially on large files and for video streams. Similar is for %SRC% mask, skipping of it meaning that the converter want to get input data via STDIN stream.

If the converter have %SRCURL% mask instead of %SRC% WebOne will not download the source file, thinking that the converter will download itself. It is useful in some cases like using of Youtube-dl.

All in-proxy converters can be accessed via special Edit rules (AddConvert+AddConvertDest+AddConvertArg1+etc) or through URLs (they was used in [FixableType] sections before introduction of Sets of edits):

• http://proxyhost/!convert/?url=source url&dest=destination extension&type=destination mime type&util=converter.exe
• or http://proxyhost/!convert/?url=source url&dest=destination extension&type=destination mime type
• or http://proxyhost/!convert/?src=source local file&dest=...
• or ...&arg=-ARGUMENT1%20VALUE1&arg2=-ARGUMENT2%20VALUE2

By default the dest="xbm", type="image/xbitmap" and util="convert". This meaning that a short call like http://proxyhost/!convert/?url=source url will produce a X Bitmap file by ImageMagick.

Because any converter is an application, to be used in WebOne it must be listed in the [Converters] list for security purposes. Unlisted (disallowed) applications will not run at all.

[Translit] section

Some browsers cannot display anything other than English letters (Code Page 437 or something). To add ability to display non-English content in such browsers, WebOne can change (transliterate) non-English letters to their equivalents from Latin alphabet. E.g. Cyrillic "Д" to Latin "D" or Greek "Σ" to Latin "S".

Transliteration rule should contain original letter on left, then a "=" character, and then the latin letter (or letters) on the right. E.g. "Д=D". Note that the section is case sensitive, so д/Д and d/D are different letters.

To solve problems with encodings, the configuration file should be saved in UTF-8 encoding and have OutputEncoding option set to anything other than AsIs.

To enable transliteration, add an Edit set with AddTranslit=yes editing rule.

User access management

[Authenticate] options

To make the proxy be protected from unwanted users, you may use HTTP Proxy Authentication. It is a good thing if the Proxy Server is accessible from Internet (have a "white" IP or similar reason). Every unprotected proxy can be used by bad guys to do something bad.

In simple case, write HTTP Proxy authentication credentials in the [Authenticate] section. WebOne is using basic authentication with login:password pair. Multiple user accounts are supported. For shortness, you may use Authenticate=login:password setting in [Server] section too. It will be equivalent.

To configure username request window (shown by browser), the section also may contain options:

• AuthenticateMessage - message, shown in error page if user don't want to enter credentials (e.g. clicked "Cancel" button). Default: Hello! This Web 2.0-to-1.0 proxy server is private. Please reload this page and enter your credentials in browser's pop-up window..
• AuthenticateRealm - authentication realm, which is used by Web browser to save credentials in password manager. Default: WebOne.

Example:

[Authenticate]
AuthenticateMessage=To get user name, ask administrator by sanya@example.com or call +7-977-123-45-67.
AuthenticateRealm=PC Museum
sanya:qwerty
elonmusk:lada2101
billgates:12345
stevejobs:54321
adabyron:mysuperstrongpassword

Note: some browsers don't well support password-protected proxies.

⭐ If your log file contains a large amount of unknown user connections, adding password protection will prevent banning of your IP on popular sites and unwanted talks with Internet Service Provider support.

[IpBanList] section

To deny some clients access to the proxy server, enter their IPs in [IpBanList] section. This might be useful against hacker attacks to your proxy.

[UrlBlackList] section

If you don't want to allow access to some web sites via proxy, enter parts of their URLs in this section.

[UrlWhiteList] section

If you want to limit access through proxy only to particular web sites, enter parts of allowed URLs in this section. Note that all other addresses will be not available to clients through the proxy.

[IpWhiteList] section

To limit access to the proxy only for clients with particular IP addresses, enter them here. All other clients will no able to use proxy. This feature is intended for private proxies running on public servers (with "white" IP).

Removed sections

All of them were used in early versions of WebOne. Since v0.10.0 they became obsolete (but support was kept for compatibility purposes), and in v0.11+ their support was removed. All of these sections can be rewritten to new-style Sets of edits and they will work exactly as intended.

[FixableURL:] sections

❌ Support removed. To replace some resources that are not need to be delivered to the "elderly" browser WebOne can make HTTP-302 redirections to other resources that are better in this case. Examples of such redirections are was included in default webone.conf file.

The section header should contain regular expression mask for detection of "unwanted" URL. Be careful here and don't forget to add string begin and string end anchors.

• ValidMask - to simplify RegExp masks after entering the section the URL checks again to contain second RegExp from this parameter. If the URL containing something from it, any processing stops and no redirections occur.
• Redirect - the redirection destination address. May contain masks.
• Internal - the redirection can be hidden from browser. Enable internal redirectons to solve problems if any.

Upgrade to:

[Edit:ex title]
IgnoreUrl=ex ValidMask
AddRedirect=ex Redirect (only when no ex Internal)
AddInternalRedirect=ex Redirect (only when ex Internal=yes)

[ContentPatch:] lists

❌ Support removed. Some text-based stuff in traffic can be edited like "Find and replace" feature of most popular text editors. This section is analog of that feature. It can edit (or "apply patches") anything in files of types listed in TextTypes list. This may be useful for patching modern JavaScript code for running in Netscape 3 or to fix Microsoft CDF files.

The section name containing Regular Expression mask and capture groups used to find blocks that should be edited.

• Replace - replacement mask. Use multiple RegExp capture groups to make complex content patches.
• IfURL - apply the patch only to content with specified URL (RegExp mask). Default: .* (all pages)
• IfType - apply the patch only to content with specified MIME content type (RegExp mask). Default: .* (all text types)

Tip: Use RegExp debuggers to create excellent masks and shorten time of Content Patch developing. I'm recommending RegExr (Flash) and Regular Expressions 101.

Upgrade to:

[Edit]
OnUrl=ex IfURL
OnContentType=ex IfType
AddFind=ex section title
AddReplace=ex Replace

[FixableType:] lists

❌ Support removed. List of online file format converters that can be used with WebOne. They may be used, for example, to convert WebP graphics to GIF. The proxy server will redirect client on any attempt to download a file with MIME type from name of the section.

• IfUrl - RegExp mask of URLs where the rule should be used.
• NotUrl - RegExp mask of URLs wherу the rule should not be used.
• Redirect - URL of a online converter which should make the conversion. May contain masks.

Upgrade to:

; identical to [FixableType:] feel, but can break CAPTCHAs:
[Edit]
OnContentType=ex section title
IgnoreUrl=ex NotUrl
AddRedirect=ex Redirect

; better way:
[Edit]
OnContentType=ex section title
IgnoreUrl=ex NotUrl
AddConvert=convert
AddConvertDest=gif
AddResponseHeader=Content-Type: image/gif
;conversion options may differ depending on task

[InternalRedirectOn] list

❌ Support removed. WebOne before version 0.7.0 has differently processed HTTP 302 redirections. Instead of returning the code to client, v0.6.x and earlier versions of proxy interprets it inside and returns target page. In v0.7.0 this behavior was changed to correct, standard-compliant. But some sites worked better if the 302 redirection is interpreted inside proxy, not by client. This was caused by some bugs in v0.7.0, fixed few versions later. But for first time there was a feature to bring back old behavior for particular sites. Now this is not actual. Support for this lists was removed in WebOne v0.12.2.

Cascaded file loading

[Include:] pseudo-section

To include contents from another configuration file or a directory, add [Include:somepath/*.conf] or [Include:mysuperconfig.txt] directive to the configuration file. By default this is used by WebOne to load all *.conf files from special directories (listed above).

---

See comments in default configuration file for notes about bugs in the current version and recent changes.

Change log: 0.12.1 0.12.1 0.12.0 0.11.3 0.11.2 0.11.1 0.11.0 0.10.7 0.10.6 0.10.5 0.10.4 0.10.3 0.10.2 0.10.1 0.10.0 .