Website Accelerator and FastProxy Instruction Guide

Thank You very much that you decided for VIGOS Website Accelerator / FastProxy to save bandwidth and optimize your Internet performance!

The technology behind VIGOS Website Accelerator / FastProxy evolved during more than four years of research and development in accordance with three underlying engineering principles: Stability, compatibility and customer-individual parametrization.

The strong demand confirms our opinion to offer industry's leading compressing proxy solution. Several thousand webpages throughout the world are using our Web acceleration software which has proved to handle hundreds of millions of page impressions per month.

As we permanently strive to improve in quality and service, we very much appreciate Your comments and suggestions on the VIGOS Website Accelerator / FastProxy.

Website Accelerator and FastProxy

VIGOS offers two compressing proxy types: a reverse proxy called Website Accelerator and a forward proxy called FastProxy.

While a reverse proxy acts like a webserver, forwarding the incoming requests to the original webserver and sending the webserver's response compressed to the client, a forward proxy is configured in your browser configuration. Once configured, all requests from that browser go to the forward proxy, which forwards them to the specific website and sends the compressed response to the client. This second variant is typically deployed by Internet Service Providers (ISP), who want to accelerate their dial-up customers' page load-times. Decompression (decoding) of the Web site content is achieved in both variants by the built-in browser intelligence.

This manual is valid for both types of proxies: some differences in the use of specific options are mentioned when they occur.

System Requirements

To ensure a smooth installation and a fault-free operation of VIGOS Website Accelerator / FastProxy, your IT-system environment should fulfill some general resource requirements. Below you will find some basic assumptions.

Windows Operating Systems

Linux, FreeBSD und Solaris Operating Systems

Installation

Windows NT, Windows 2000, Windows XP, Windows 2003

The installation program should start automatically. Otherwise, please execute the program "setup.exe" in the main menu on the CD-ROM.

If the Website Accelerator / FastProxy is supplied by e-mail, please start by executing the program "setup.exe".

Continue then to start the configuration program. The various parameter options will be described in chapter Configuration below.

Linux, FreeBSD, Solaris, AIX and HP-UX

Copy the directory "vigos" to your computer harddisk; we advise to install it into the directory "/opt/vigos".

If the Website Accelerator / FastProxy is supplied by e-mail, please unpack the attached file.

Adjust the configuration file "vigos.conf". A detailed description of the parameter options will be given below in chapter Configuration.

> /opt/vigos/vigos /opt/vigos/vigos.conf
> # or
> /opt/fastproxy/fastproxy /opt/fastproxy/fastproxy.conf

The process will automatically be put in the background; unless, in the configuration file the parameter "Daemon" is assigned to the value "off". In this case, however, your terminal station will be blocked up until you press the keys "CTRL-C" and thereby terminate the proxy.

Configuration

The VIGOS Website Accelerator / FastProxy will be configured by means of a text file. Each line of this file contains a parameter which has to be assigned to a numeric, boolean or language value. There are default values pre-assigned. Note that blank lines and comment lines which begin with the # sign, will be ignored.

If the software decides that the configuration file is incorrect, e.g. a parameter is missing or assigned to an invalid value, an entry will be recorded into the error logging file ErrorLog. The software automatically tries to correct the configuration error by assigning the default value. If this does not succeed, the program will terminate right after start with an error code.

Hint: When using a Windows operating system, a configuration manager with a setup screen will assist you to type in the options quite comfortably.

UserID

On UNIX-based operating systems, after binding to an IP-address, the Accelerator / FastProxy automatically drops its privileges in order to avoid security holes. The proxy changes its user id to the default user id "nobody". If you want the proxy to switch to another user id, you can configure this by setting the "UserID" option.

PIDFile

On UNIX-based operating systems, the Accelerator / FastProxy writes a small file with its process number in the start phase. This enables scripts to stop or restart the proxy with scripting, for example. This so called "PID file" is deleted if the proxy is shut down normally.

ListenIP

This parameter specifies on which IP-address the proxy should listen to browser requests. Either an IP-address or a host name may be assigned. The default value is "localhost".

ListenPort

This parameter specifies on which port the proxy should listen to browser requests. All integer numbers in the range from 1 to 10,000 are valid values. The default value is port 80.

RemoteIP

This parameter specifies the IP-address of the webserver to which the proxy should forward the incoming browser requests. Either an IP-address or a host name may be assigned. The default value is again "localhost".

This option is not available in the FastProxy version, because a forward proxy always uses the remote IP address and the remote port that is included in the HTTP-request.

RemotePort

This parameter specifies to which port of the remote webserver the proxy should forward the incoming browser requests. All integer numbers in the range from 1 to 10,000 are valid values. The default value is again port 80.

This option is not available in the FastProxy version, because a forward proxy always uses the remote IP and the remote port that is included in the HTTP-request.

Note: ListenIP and RemoteIP may be assigned to the same value (default or not). The same is true for ListenPort and RemotePort. But the combination of such two special assignments would cause an error-loop. We therefore advise to set ListenPort=80 and RemotePort=8080, for example.

HTTPProxy

This parameter specifies the IP-address and IP-Port of an HTTP proxy that shall be used. Either an IP-address or a host name can be assigned and an optional port number can be added, separated by a colon.

AccessLogFile

This parameter specifies the name of the access logging file where the user accesses will be recorded.

If this parameter is empty or not assigned, the access logging will be turned off. However, an entry will be created in the error logging file for documentation. If a file name is assigned which cannot be accessed the program will terminate with an error code.

AccessLogFormat

The parameter splits into several variables which will be assigned proper values at run time.

Indicates the HTTP-Request-Method. The values can take on "HEAD", "GET", "POST" or "UNKNOWN". Other HTTP-Request-Methods are currently not implemented.

Name of the host which was addressed by the browser. The value corresponds to the content of "Host" as delivered in the browser's request-header.

One character showing the reason why VIGOS has compressed or not. The possible values are:

-	The combination of MIME-type and browser type is not contained in the SmartShrink-file. Therefore, the response has not been compressed.
A	The response was compressed since it was compliant with the SmartShrink database.
B	No compression, because the requests has not a "User-Agent" header.
C	No compression, because the requests has not an "Accept-Encoding" header.
D	No compression, because the requests has not a "Host" header.
E	No compression, because the response has not a "Content-Type" header.
F	No compression, because the MIME-type of the response is not supported.
G	No compression, because the response status code is not 200 (OK).
H	No compression, because the hostname does not match the configured virtual hosts This effects only the Light versions.
I	The response was compressed, because it is HTML and was checked separately.
J	The response was compressed because the SmartShrink check was disabled.
K	No compression, because the request headers are missing.
L	No compression, because the response headers are missing.
?	No compression. This indicates that there was no SmartShrink check while processing this request (e.g. if the file size is too small).

NoAccessLog

ErrorLogFile

This parameter specifies the name of the file into which error messages, warnings, notices and debug information will be written.

If this parameter is empty or not assigned the messages will be redirected to the standard file "stderr".

ErrorLogLevel

This parameter specifies which error logging level will be set. Possible values are (ascending):

Example: If the error logging level is set to "warning", then only messages of the type "error" and "warning" will be recorded. All other message level types will be ignored.

Hosts

When running a full version, i.e. not a trial version, of the Website Accelerator / FastProxy, you have to define the hosts that shall be accelerated. Unless you have bought an unlimited hosts license, please configure your domains with this option. This is not necessary in the trial version of the Website Accelerator / FastProxy! If a domain name is not configured, VIGOS will not compress the responses from that domain. If you have more than one domain name, please list them, separated by a colon (":").

You have to list only the domain plus TLD (top level domain), not any sub-domains. In example below, both "www.vigos.com" and "www2.vigos.com" as well as "www.vigos.net" would be accelerated, but "www.vigos.org" not:

SmartshrinkFile

This parameter specifies where the Website Accelerator / FastProxy will find the VIGOS-proprietary knowledge data base which is essential to our unique 'SmartShrink'-technology.

IgnoreSmartshrink

If you do not wish to use the SmartShrink feature, you can disable this validation by switching the "IgnoreSmartshrink" option on. It is disabled by default. If enabled ("on"), the Website Accelerator / FastProxy will do compression only if the browser has sent an "Accept-Encoding: gzip" request header.

IgnoreAcceptEncoding

If you enable this option, the Website Accelerator / FastProxy ignores any "Accept-Encoding" header as provided from the requesting browser and assumes every request to have an "Accept-Encoding: gzip" header.

IgnoreUserAgent

If you enable this option, the original "User-Agent" header as provided by the requesting Web browser is replaced by a default value.

ExcludeMimetype

If enabled, this option excludes all responses with the given MIME-type from compression. This is most useful if you have switched on the "IgnoreSmartShrink" option. By default, this option is empty.

IPForwardHeader

This parameter specifies the name of the request-header, which will be inserted in order to pass on the client's remote IP-address to the proper webserver.

Threads / Children

This parameter specifies the number of threads resp. children which the Website Accelerator / FastProxy will create. The higher the number of threads resp. children will be chosen, the more concurrent requests can be handled. As each additional concurrent request consumes CPU-time, this parameter should be adjusted according to your individual situation. During internal benchmark tests 3-digit numbers were processed smoothly. The default value is assigned to 1 (minimum).

Note: Please note that the option "Children" is effective only if the operating system Solaris is used, while all other operating systems use "Threads".

MaxRequestsPerChild

When running the multi-process version of the Website Accelerator / FastProxy, you can configure the maximum life-time of one process. After a number of requests has been handled, the child process will shut down and re-start itself. This is important on some operating systems to free memory resources. The default value is 1,000 requests.

MaxKeepaliveConnections

This numeric value indicates how many concurrent connections may use the HTTP keep-alive feature for faster access. When a connection uses keep-alive, this connection is kept open for one particular client and thus this connection (handled by one thread or process) cannot be used by another client until the connection time-out. We recommend to set this value to the half of your "Thread" / "Children" value. The default value is zero, which means that no keep-alive is used.

MaxKeepaliveTransactions

This value tells the Website Accelerator / FastProxy how many transactions (i.e. requests) may be handled by one keep-alive connection before it is closed. The default value is 100 transactions.

SSL

Assign to the parameter SSL the boolean value "on" if you want the proxy to be operating in the SSL-mode (Secure Socket Layer). This means that all incoming client requests will be interpreted as SSL-requests which need to be decrypted.

The standard port for SSL-connections is 443. Therefore we advise to adjust the parameter "ListenPort" (see above) when utilizing the parameter "SSL".

SSLCipherlist

If the option "SSL" is enabled, you can set this option to configure the list of ciphers that are available for the communication between VIGOS and the client. Please see http://www.openssl.org/docs/apps/ciphers.html for a list of all possible cipher strings. The default value is "ALL".

KeyFile

This parameter specifies where the accelerator will find the key file necessary for SSL secured sessions. Please provide always the full path to the file.

CertFile

This parameter specifies where the accelerator will find the certificate file necessary for SSL secured sessions. Please provide always the full path.

SSLForceNocache

If enabled, this boolean option tells the Accelerator to insert 3 headers in the response to the client ("Pragma: no-cache", "Expires: -1", "Cache-Control: no-cache"). It is disabled by default.

SSLServer

If enabled, this boolean option tells the Accelerator to communicate with the Web server over HTTPS.

SSLServerCipherlist

If the option "SSLServer" is enabled, you can set this option to configure the list of ciphers that are available for the communication between the Web server and VIGOS. Please see http://www.openssl.org/docs/apps/ciphers.html for a list of all possible cipher strings.

CompressionLevel

This parameter specifies the compression level in a range from 1 (low) to 9 (high) for the outbound data traffic. But even level 0 (no encoding at all) may be chosen.

Note: Increasing compression levels mean an increasing number of CPU-cycles. A reasonable value has proved to be 6 which therefore has been set as default.

GfxOptimization

This boolean parameter switches the internal graphics optimization engine on or off. Per default, this feature is disabled. If enabled, this engine strips unnecessary bytes from JPEG files, i.e. comments, copyright notices or color tables that are not used for viewing but for editing.

RemoveWhitespaces

Most HTML-pages can achieve from a significantly higher compression ratio if dispensable white spaces such as blanks and word wraps are removed in advance.

Note: The removal of white spaces may lead into lossy compression results. Therefore check your website carefully whether this parameter causes side effects, for example, affects (outdated) "<PRE>"-commands or JavaScripts.

Add2048Bytes

When you activate this option, VIGOS will add 2048 bytes of white space at the begin of each compressed HTML file to avoid a known bug of the Microsoft Internet Explorer (MSIE), which is described in Q313712. This option is disabled by default and available in version 2.4.7 or higher.

MinFileSize

This parameter allows to exclude small files (as part of the website) from being encoded to avoid unnecessary overhead. A reasonable size from which up compression makes sense has proved to be 300 bytes, which therefore is default. Different integer values may be assigned.

MaxFileSize

If the response body from the Web server is bigger than "MaxFileSize" bytes, the response is forwarded to the client without compression. The default value is 1 MB (1,048,576 bytes).

MaxRequestSize

If the HTTP request is greater than this value, an error "413 Request Entity Too Large" will be send to the client. Default: 5 MB (5,242,880 bytes).

Daemon

This boolean parameter controls the behavior of the accelerator after getting started. The default value "on" forces the accelerator to stay in the background, see chapter Installation.

Note: This parameter is not valid for the operating systems Microsoft WindowsNT / Windows2000 / Windows XP / Windows 2003.

SetHostname

Sometimes, you want to run the Accelerator on a different machine than the original Webserver. Then , you access the proxy via its IP-address and the request is forwarded to the Web server. If the Web server is configured to switch between several Websites according to the "Host" request header, the request may fail, because the browser will send the IP-address of the proxy in its "Host" request header. To avoid this trouble, you can set a hostname and in every request, the original "Host" header will be replaced by this one.

Timeout

The Timeout option defines after how many seconds the server will abort a client connection if the connection is not used or if the client is too slow to send its data. This timeout value is used for both reading standard client requests and waiting for new requests on a keep-alive connection. See ServerTimeout for timeouts of server connections.

ServerTimeout

The Timeout option defines after how many seconds the proxy will abort a connection to the Web server if the connection is not used or if the Web server is too slow to send its data.

When you are using the VIGOS FastProxy, it is recommended to set this value either to zero or to a very high value, because the ServerTimeout covers the complete download time of a file. So if you are downloading a 100 MB file through FastProxy, 120 seconds might be to short and the download is interrupted.

RewriteRedirects
RewriteRedirectsSearchterm
RewriteRedirectsReplacement

If the boolean parameter RewriteRedirects is switched on, the "Location" header coming from the Web server is modified by replacing the searchterm with the replacement string. This is useful if your application sends redirects based on it. Default is off.

RewriteRedirects=On
RewriteRedirectsSearchterm=http://
RewriteRedirectsReplacement=https://

RewriteRedirects=On
RewriteRedirectsSearchterm=:8080/
RewriteRedirectsReplacement=/

FailoverCommand

In the rare event that the Website Accelerator / FastProxy will fail, the last action of the proxy is to call a system command if configured with the option "FailoverCommand". This can be for example a shell script that notifies the administrator and schedules the restart automatically. By default, this options is disabled.

Backlog

The VIGOS proxies can handle as many concurrent connections as there are threads or child processes. In the case that all threads or child processes are busy, the operating system can accept incoming requests and put them on a waiting queue called "backlog". Then, if a thread becomes idle, it gets a connection from this waiting queue. If the waiting queue is full, the client gets a "connection refused" error.

With this option, you can configure the size of the backlog queue. The default value is 16, but you can increases it e.g. to several thousands. The maximum value may differ from one operating system to another.

Operation

Once running (see chapter Installation for starting instructions), the VIGOS Website Accelerator need to maintainance with two exceptions:
first, the log files become too large and/or you want to rotate the log files. Second, you want to change the configuration and/or set up an update. Further maintenance is not required.

Log files

Each instance of the VIGOS Website Accelerator has two log files: an access log file and an error log file. If you want to rotate the log files, you can move them (using the 'mv' command) on UNIX operating systems and then sending the main process a USR1 signal:

# Get the main process id
less /tmp/vigos.pid
# Assuming it's 1234, we send a USR1 signal
# Please type 'man kill' for the
# correct 'kill'-syntax on your system
kill -s SIGUSR1 1234

After receiving the USR1 signal, the Accelerator will close its log files and open new ones with the same file name as defined in the configuration file.

On Windows, you have to stop the service, move or delete the log files and then start the Accelerator again. See the restarting instructions below.

Disabling compression temporarily

If you want to disable compression for maintenance reasons or due to high load on the server, you may send the USR2 signal to the parent process of VIGOS (on UNIX operating systems only) in order to switch compression off. In order to enable compression, you just have to send the USR2 signal again to the parent process.

Stopping and Restarting

On UNIX operating systems, there are two ways how to stop and restart the Accelerator: if you have started the Accelerator in front-end mode, simply press CTRL-C to cancel the execution of the program. If the Accelerator has been started as a daemon process, get the main process id (see above) and send a TERM signal to the main process:

In order to start the Accelerator again, please refer to the installation section. On Windows operating systems, either use the VIGOS configuration tool to stop and start the Accelerator or use the service manager included in the Windows system settings.

Installation and Configuration Instruction Guide

VIGOS Website Accelerator andVIGOS FastProxy

Table of Contents