Skip to content

Configuration file

Jump to bottom Edit New page
Alexander Tauenis edited this page Oct 26, 2023 · 35 revisions

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.16.1.

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. It is splitted to many sections, which can contain options or lists of values.

Sections are starting with their names (titles), enclosed in square brackets. E.g. [Server] or [Edit:jquery.min.js]. The configuration may have multiple sections with same name. Last written section have higher priority.

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.

Lines starting with semicolon (;) are ignored, so may be used to store comments.

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. FAQ.
  • 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.
  • RemoteHttpVersion - set version of HTTP(S) protocol, used to communicate with web servers. Format of the option is xY.Z where Y.Z is HTTP version, and x is version policy. The policy can be = (use only the specified version), < (use the version or earlier) or > (use the version or newer). Also auto value can be used, which meaning use of HTTP/1.x and prefer HTTP/2 on systems with HTTP/2 support (so no Win7/8 support here). Set to <3.0 or =3.0 to enable experimental HTTP/3 QUIC support. Default: auto.
  • MultipleHttp2Connections - make HTTP/2 communication faster by enabling multiple TCP/IP connections to HTTP servers. This violates the protocol, can overload some networks, but speeds up the communication. Default: disable.
  • AllowHttpCompression - allow or disallow compression of HTTP(S) traffic with remote servers. This is a regular part of HTTP protocol in modern days, but sometimes may cause errors. For troubleshooting, you may disallow the HTTP compression. Default: yes.
  • DefaultHostName - proxy host's name. It may be either %HostName% placeholder (will be set to system host name), a DNS name of the server, a real server IP, or a Microsoft Network computer name. This is used in client autoconfig scripts (PAC/WPAD) and for local mode. If the option is not set over default value, WebOne will use server's IP for autoconfig script and system host name for other things. 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.
  • UpperProxy - another upper proxy server (if any) or no to don't use any upper proxies. If value is not set, system-wide proxy settings will be used. Default: use system proxy settings.
  • PageStyleHtml - style of internal pages (HTML 3.2, not CSS). This allows set custom colors for internal pages (text/bgcolor/link/vlink/alink="#RRGGBB") even in browsers without CSS support. Default: empty.
  • EnableWebFtp - enable built-in FTP client. Default: enable.
  • UseMsHttpApi - enable legacy traffic processing code. Useful to solve problems with communicating with the proxy if any (but this option will also disable SSL&FTP support) Default: no.

[HostNames] list

List of alternate server host names. If WebOne is running on a public VPS, enter here all its public names, like mydomain.com, 140.82.121.4, vps-140821214.panel.hosting.net.za. By default, this list contains only DefaultHostName, all local IPs, 127.0.0.1, [::1] and localhost.

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

[PAC] section

The Proxy Automatic Configuration script, used by clients to set proxy configuration. This is the file, which can be requested by http://proxyhost:port/auto.pac URL.

ℹ️ See full article about the PAC/WPAD scripts.

[Http10Only] section

Some antique browsers does not support HTTP 1.1 replies, and thus incorrectly interpreting complex content type information (text/html; charset=windows-1252), sent by modern servers. Add parts of User Agent strings of such browsers in the list. Browsers listed in this section will receive HTTP 0.9/1.0-style content type strings (e.g. text/html). By default the list is empty, and default webone.conf contains IBM WebExplorer (part of IBM Internet Connection for OS/2 Warp) User Agent string.

[PageStyleCss] section

This section defines style sheet for all internal pages. This is similar to PageStyleHtml option, but intended for browsers with CSS support. These styles are not applied to Internet pages, and only used on WebOne internal error, status and information pages. By default it is empty (no CSS styles at all), but webone.conf contains some light style.

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).

HTTPS/SSL proxy and non-HTTP protocols support

According to RFC9110, §9.3.6, HTTPS proxies are using HTTP 1.1 protocol only for initial connection establishing (the CONNECT method). Then the proxy is working as agent which is keeping a low-level TCP tunnel between the client and the server. As result any HTTPS proxy, such as WebOne, can transfer any TCP/IP based protocol, not limiting to HTTP/HTTPS. The traffic encryption used in HTTPS and other SSL/TLS-based protocols are identical. And some other protocols, compatible with HTTPS proxies, are not using encryption at all.

ℹ️ See full article about the HTTPS and SSL.

[SecureProxy] section

This section configures work of HTTPS/SSL Proxy Server.

  • SslEnable - enable HTTPS proxy. Default: yes.
  • SslCertificate - path to CA certificate file. Default: ssl.crt.
  • SslPrivateKey - path to CA certificate private key file. Default: ssl.key.
  • SslProtocols - versions of SSL/TLS protocols used to communicate with clients (syntax). Default: 0 (let OS choice).
  • SslRootValidAfter - begin of life period of CA Certificate. Default: 1970-01-01 00:00:00+0.
  • SslRootValidBefore - end of life period of CA Certificate. Default: 2070-12-31 23:59:00+0.
  • SslHashAlgorithm - signature algorithm for CA certificate (MD5, SHA1 are ok for old browsers; SHA256, SHA384, SHA512 for modern). Default: SHA1.
  • SslRootSubject - subject string of CA certificate. Default: C=SU, O=MITM Proxy, OU=This is not really secure connection, CN=WebOne Certificate Authority.
  • SslCertVaildBeforeNow - begin of life period of sites certificates (relative to today). Default: -7 days.
  • SslCertVaildAfterNow - end of life period of sites certificates (relative to today): +7 days.
  • SslSiteCerts - path to site certificate files (if use external generator). Default: blank, unused.
  • SslSiteCertGenerator - external utility which will generate site certificates and private keys. Default: blank, unused.
  • AllowNonHttpsCONNECT - allow use HTTPS proxy tunnel (CONNECT method) with non-HTTPS protocols. Default: yes.

All CA certificate generator options are used only when .crt and .key files are not exist, and WebOne is attempting to build them from scratch. It's not possible to update existing CA certificate without its delete and then re-creation.

[NonHttpSslServers] section

By default, WebOne is working with all remote servers on Port 443 as with HTTPS servers, and with all other as insecure plain-text servers (like Telnet, IRC, etc). To enable SSL processing with servers running on other ports (like IRCS running on port 6697), add them onto the list.

This section is working only if AllowNonHttpsCONNECT SecureProxy option is set to true.

[NonHttpConnectRedirect] sections

This is a single Edit set which is working with non-HTTP protocols. WebOne can redirect connection from a one non-HTTP server to other.

This section is working only if AllowNonHttpsCONNECT SecureProxy option is set to true.

Online video converting

[WebVideoOptions] section

This section configures online video downloading feature of WebOne. Some options configures the proxy server, and some are for third-party applications used as video downloader (Youtube-DL or YT-DLP) and converter (FFmpeg).

Enable

Set Enable=yes to enable video player, downloader and converter. Or set to Enable=no to disable this. May be useful on slow systems to reduce CPU/RAM/LAN load.

YouTubeDlApp, FFmpegApp

Paths to the specified programs. You may use youtube-dl instead of yt-dlp, and avconv instead of ffmpeg.

format

YT-DLP parameter. Resolution of video, which will be obtained by the downloader program. By default it's best but can be reduced if your network is slow.

merge-output-format

YT-DLP parameter. Because YouTube uses DASH format with separate picture and sound files, it is not easy to transfer film contents to converter or client. So to solve this, the downloader program should merge picture and sound streams to a single file. This option sets the container used as input stream for FFmpeg.

f

FFmpeg parameter. Container for audio&video content, which will be used to serve the client. By default it's mpegts (MPEG Transport Stream).

vcodec, acodec

FFmpeg parameters. Codecs, used for video (vcodec) and audio (acodec) in the container file. You may choose any codecs, supported by FFmpeg, or keep default value (copy - use YouTube's default codecs).

Other YT-DLP and FFmpeg parameters

You may specify many other options for these programs, according to their documentation. Also all parameters (except Enable, YouTubeDlApp, FFmpegApp) can be overridden by client when he/she set them in Retro Online Video Player GUI.

Note that errors will be displayed only if the WebOne is started in a Terminal window, and only in it. Some YT-DLP errors are redirected to HTTP program as HTML (and gets saved to WebOne log), but not all. And any FFmpeg error will produce a 0 byte long file.

Any warnings and info messages produced by YT-DLP or FFmpeg are displaying only in Terminal window, and not saving or redirecting anywhere.

ℹ️ Short set of cheat sheets below:

Web-FTP client

Some options of built-in FTP client can be configured. How to disable or re-enable it, see above.

[MimeTypes] list

Some files from FTP servers can be previewed in browser instead of full download. To use such feature, there must be a MIME Content-Type associated with file extension. And if the browser knows the specified Content-Type, it will display the file in window. The example is TXT, HTML files, JPG/PNG graphics. And in MS Internet Explorer also MS Office documents.

The list items are stored in extension=content/type format. E.g. htm=text/html, txt=text/plain or doc=application/msword.

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:

Add a custom footer

Usage:

Web standards timeline:

Troubleshooting guides:

Developer corner:

Clone this wiki locally