CGIProxy Installation


CGIProxy Home | News | Installation | Usage | Options | Limits | Disclaimer |
Latest Download | Security | FAQ | Changes | Translating | Online Demo (login "free/speech")

Subscribe to announcement list:

This page may look long, but you won't need most of it. Installing CGIProxy is often trivial. Parts of it require running commands from the command line (the "shell"), but we'll tell you exactly which commands you need to run.

You need to install CGIProxy on a machine that's outside of any censoring firewall, but that is still accessible to people behind the firewall. You do NOT need to install anything on the browsing machine(s). Once CGIProxy is installed on a machine, any number of people can use it, if they know its URL.

Table of Contents

  1. Prerequisites
  2. Configuring CGIProxy
    1. Using a database
  3. Installing the CGIProxy script
    1. as a CGI script
    2. under mod_perl
    3. as a FastCGI script
    4. using CGIProxy's own embedded server
  4. After you install
  5. Troubleshooting
    1. If you don't know Perl, but need to configure CGIProxy

Prerequisites

Now's a great time to review security when using CGIProxy.

CGIProxy requires the following on the machine where it is installed:

Please note that all of these packages are completely unaffiliated with CGIProxy, and may have their own terms of use.

Configuring CGIProxy

First, unpack the distribution (the file ending in ".tar.gz"). On Unix and Mac, you can do this with the command "tar xzvf cgiproxy.*.tar.gz". In it are two files, nph-proxy.cgi and README . nph-proxy.cgi is the program you'll be configuring and installing. That's it-- just one file.

Almost all configuration is optional, and the defaults should be fine for most situations. However, if you need to set an HTTP proxy, or there is anything else unusual about your network or server, then see the section OPTIONS RELATED TO YOUR SERVER/NETWORK ENVIRONMENT. In particular, set $PROXY_DIR and $RUN_AS_USER . If you don't have root access on your server, then set $LOCAL_LIB_DIR .

Configure CGIProxy by editing nph-proxy.cgi in a text editor. The configuration section starts after some initial comments and code, near line 338. Each configuration variable has a block of text above it fully describing how to use it; here's a summary table of all options. If you don't know Perl, here's some help.

Depending on how you install CGIProxy, there may be other configuration needed. This will be detailed for each of the installation methods below.

You can rename nph-proxy.cgi if you like. However, if you're installing it as a CGI script or under mod_perl, be sure the name still starts with "nph-". (You can change that requirement for mod_perl, by reconfiguring mod_perl.) These instructions will still refer to "nph-proxy.cgi", but you should substitute the actual name of your file.

Using a database

As of CGIProxy 2.1.15, the default database driver is SQLite, which means you don't need to run a database engine (like MariaDB/MySQL or Oracle) to use a database-- SQLite simply uses a file for its database, which for CGIProxy is in the directory "cgiproxy/sqlite/" under your home directory, with the filename "cgiproxy". (This location and filename can be configured if needed.) Using a database is optional, but it will get rid of any "Bad Request" errors you see when you have too many cookies for your Web server to handle.

You'll need to purge old data from your database periodically. In Unix or Mac, do this with a "cron job". In Windows, use the Task Scheduler. The command to purge the database is "nph-proxy.cgi purge-db".

On most Unix or Mac machines, you can edit your list of cron jobs (one per line) with the command "crontab -e". To purge the database at the top of every hour, add the line:

0 * * * * /path/to/script/nph-proxy.cgi purge-db

To purge the database every night at 2:00 am, add the line:

0 2 * * * /path/to/script/nph-proxy.cgi purge-db

(Replace "/path/to/script/" with the full path to nph-proxy.cgi .)

Installing the CGIProxy script

There are four ways to run CGIProxy:

As a CGI script

This is the easiest way to install CGIProxy, but it will run the slowest of all four installation methods. However, if not too many people are using it, the speed may be OK. To install CGIProxy:

  1. Copy the file nph-proxy.cgi onto your Web server somewhere, but not at the top Web directory, or else it will be easily discovered.
  2. Change the file's permissions to be executable. On Unix and Mac, you can do this with the command "chmod +x nph-proxy.cgi"; there are other ways.
  3. In the directory where you copied nph-proxy.cgi, run the command "./nph-proxy.cgi init" (or in Windows, "perl nph-proxy.cgi init"). This sets up required directories, installs the Perl modules used by CGIProxy, and creates the database. If you can't run this as root/administrator, it will still work, but see the instructions displayed at the end after all the scrolling text (which you can ignore). If it asks you any questions, you can just hit <return>.
  4. If you're using a database, add the cron job to purge old data-- see Using a database above.
  5. Optionally, protect the proxy with a password; see your Web server documentation for how to do this. With Apache, you can use the .htaccess file.

Under mod_perl

If you have mod_perl available on your Apache server (ask your webmaster), then with it CGIProxy can run many times faster than as a CGI script. The installation is similar to that of a CGI script, but requires some extra Apache configuration if mod_perl hasn't already been set up. To install CGIProxy under mod_perl, do the same thing as installing it as a CGI script, above. Depending on how mod_perl is configured, you may need to rename the script file to nph-proxy.pl or something else.

Configuring mod_perl

If you're configuring your own mod_perl, you can use this block in your httpd.conf to make all scripts ending in ".pl" use mod_perl:

<Files *.pl>
    Options +ExecCGI
    SetHandler perl-script
    PerlResponseHandler ModPerl::Registry
    PerlOptions +ParseHeaders
    PerlSendHeader Off
    <Files nph-*>
        PerlOptions -ParseHeaders
    </Files>
</Files>

If you know how to configure Apache, you can tweak this as desired.

As a FastCGI script

FastCGI scripts are similar to CGI scripts in some ways, but run faster than CGI scripts. FastCGI can be used with most Web servers, including those that don't support CGI scripts, such as nginx. A FastCGI script runs as multiple managed processes on a server, and is called by the Web server process.

To install CGIProxy as a FastCGI script:

  1. Set $SECRET_PATH, and possibly $FCGI_SOCKET . Other configurable parameters are listed in FASTCGI CONFIGURATION OPTIONS.
  2. Configure your Web server to use the same two values you set in the previous step (see the next sections for examples).
  3. Copy nph-proxy.cgi to your server machine. Do not put it under your Web directory.
  4. Change the file's permissions to be executable. On Unix and Mac, you can do this with the command "chmod +x nph-proxy.cgi"; there are other ways.
  5. In the directory where you copied nph-proxy.cgi, run the command "./nph-proxy.cgi init" (or in Windows, "perl nph-proxy.cgi init"). This sets up required directories, installs the Perl modules used by CGIProxy, and creates the database. If you can't run this as root/administrator, it will still work, but see the instructions displayed at the end after all the scrolling text (which you can ignore). If it asks you any questions, you can just hit <return>.
  6. If you're using a database, add the cron job to purge old data-- see Using a database above.

To start the FastCGI process, run the command "./nph-proxy.cgi start-fcgi" (or in Windows, "perl nph-proxy.cgi start-fcgi") from the directory where you uploaded the script.

To stop the FastCGI process, run the command "killall nph-proxy.cgi".

Configuring nginx with FastCGI

Include a section like this in your nginx.conf, within the secure server section:

location /secret/ {
    fastcgi_pass             localhost:8002;
    fastcgi_split_path_info  ^(/secret)(/?.*)$;
    fastcgi_param            SCRIPT_NAME $fastcgi_script_name;
    fastcgi_param            PATH_INFO $fastcgi_path_info;
    include                  fastcgi.conf;      # if not included elsewhere
}

The first three lines need to match your configuration in nph-proxy.cgi : replace "secret" (in two places!) with your setting of $SECRET_PATH, and replace "8002" with your setting of $FCGI_SOCKET .

Configuring Apache with FastCGI

Include a line like this in your httpd.conf:

FastCgiExternalServer /var/www/html/secret -host localhost:8002

Replace "/var/www/html/secret" with your setting of $SECRET_PATH appended to your DocumentRoot, and replace "8002" with your setting of $FCGI_SOCKET .

Using CGIProxy's own embedded server

You can run CGIProxy without a Web server, using its embedded server. This method will run faster than as a CGI script, but probably slower than under mod_perl or as a FastCGI script.

To run any secure server, including CGIProxy's embedded server, you need a "certificate" and a "private key", also known as a "key pair". (A certificate contains a "public key".) To get a key pair, you can either buy one from a certificate authority, or you can generate your own "self-signed" key pair. The disadvantage of using a self-signed key pair is that your users will see a browser warning about an untrusted certificate, and won't be able to trust the connection. This is true of any secure server.

To install CGIProxy using its own embedded server:

  1. Set $SECRET_PATH.
  2. Copy your certificate and private key, both in PEM format, into the "cgiproxy" directory under your home directory (or whatever you may have set $PROXY_DIR to).
  3. Set $CERTIFICATE_FILE and $PRIVATE_KEY_FILE to the file names from the previous step.
  4. Optionally, you can password-protect your proxy by setting $EMB_USERNAME and $EMB_PASSWORD.
  5. If you intend to run CGIProxy as root (superuser), then it's highly recommended that you set $RUN_AS_USER to the user that CGIProxy should have the permissions of (i.e. NOT root).
  6. Copy nph-proxy.cgi to your server machine. Do not put it under your Web directory.
  7. Change the file's permissions to be executable. On Unix and Mac, you can do this with the command "chmod +x nph-proxy.cgi"; there are other ways.
  8. In the directory where you copied nph-proxy.cgi, run the command "./nph-proxy.cgi init" (or in Windows, "perl nph-proxy.cgi init"). This sets up required directories, installs the Perl modules used by CGIProxy, and creates the database. If you can't run this as root/administrator, it will still work, but see the instructions displayed at the end after all the scrolling text (which you can ignore). If it asks you any questions, you can just hit <return>.
  9. If you're using a database, add the cron job to purge old data-- see Using a database above.

To start the embedded server, run the command "./nph-proxy.cgi start-server" (or in Windows, "perl nph-proxy.cgi start-server") from the directory where you uploaded the script. It will try to use the port you tell it with the "-p" option (default=443); if that fails, it will use another random port. After you run the command, it will tell you the URL to access the proxy with (including the actual port number), and the process ID of the server.

To stop the embedded server, run the command "killall nph-proxy.cgi".

After you install

Please review the security guidelines before doing anything further.

If you want your proxy to be usable by other people, you need to communicate the proxy URL to them. Try to use a secure method to do so, or else the proxy could easily be discovered by censors and blocked, or worse.

In particular, don't be tempted to post your proxy URL to any public sites that list available proxies. If you do, the censors will quickly see your proxy and block it, or there may be even worse consequences. These proxy-listing sites may be useful for anonymity, but for getting around censorship they are dangerous! They make the censors' job easier.

In addition, people should only be using proxies installed by people or organizations that they trust.

If heavy use of this proxy puts too much load on your server, see "NOTES ON PERFORMANCE" near the top of the source code. The biggest improvement comes from running this under mod_perl or FastCGI.


Troubleshooting

If you don't know Perl, but need to configure CGIProxy

Here's an entry from the FAQ:
If you don't know Perl, you can guess how to set an option's value by emulating the examples already in there. Variables starting with "$" hold single values, and variables starting with "@" hold lists of values. Lines beginning with "#" are comments and are ignored when the program runs. As in most programming languages, 1 means true and 0 means false. Also as in most programming languages, values that are text-like and not numbers (like server names or IP addresses) are called "strings" and should be enclosed in single or double quotes.

© 2013-2017 James Marshall http://www.jmarshall.com/tools/cgiproxy/install.html
Last Modified: January 29, 2017