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:

As of version 2.2.1, CGIProxy now uses an installation wizard, so this page has been completely rewritten. Please tell me about any installation problems you have on any platform, so I can fix them!

Starting in version 2.2.3, there is a simple way to upgrade CGIProxy in place, with the "upgrade" command.

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
    1. As a CGI script
    2. As a mod_perl script
    3. As a FastCGI script
    4. Using CGIProxy's embedded server
  2. Installing the CGIProxy script
  3. Upgrading CGIProxy from a previous version
  4. Uninstalling CGIProxy
  5. After you install
  6. Troubleshooting
    1. "Bad Request" errors


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

CGIProxy requires Perl and OpenSSL, but those are already installed on almost all Unix servers. If you're using a Windows server, install both of these.

There are four ways CGIProxy can run: as a CGI script, as a mod_perl script, as a FastCGI script, or with its own embedded server. As a CGI script is the slowest to run, and as a mod_perl or FastCGI script are the fastest to run. Depending on which of these ways you choose, your Web server needs to be configured to support it, as detailed in the following sections.

If you're installing on a CentOS server: CentOS doesn't include all standard Perl modules by default, so install those first by running "yum install epel-release" as root. You can't even run the installation wizard without first doing this.

If you're installing on a Windows server: The commands below that run nph-proxy.cgi are for Unix, but are almost the same for the Windows command line. In Windows, make two changes: start a command with "perl", and replace "/" with "\". You can also remove an initial "./". For example, instead of running "./nph-proxy.cgi command", run "perl nph-proxy.cgi command".

As a CGI script

Your Web server has to be configured to support CGI scripts such that any executable file ending in ".cgi" is treated as a CGI script. Your webmaster normally does this. For Apache, you need something like this in the section of httpd.conf that controls the directory where nph-proxy.cgi will be (normally a <Directory> or <Files> block):

    AddHandler cgi-script .cgi
    Options +ExecCGI

Apache has a page with all the details.

As a mod_perl script

mod_perl is an optional feature of Apache servers. With mod_perl, CGIProxy can run much faster than as a CGI script. Your webmaster normally configures 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

If you know how to configure Apache, you can tweak this as desired. If you use the block above, then rename nph-proxy.cgi to .

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.

After installing CGIProxy, configure your Web server to use CGIProxy as a FastCGI script, using your settings of $SECRET_PATH and $FCGI_SOCKET; you can view these settings in either the configuration menu or the file cgiproxy.conf . Examples of how to configure the nginx and Apache servers are just below.

To start the FastCGI process, run the command "cgiproxy/bin/nph-proxy.cgi start-fcgi" from your home directory. This runs the process in the foreground. To run it in the background, add "-q &" to the end of the command (the "-q" tells CGIProxy to be quiet, i.e. to not print messages to the console).

To stop the background FastCGI process in Unix, 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 if you changed it from the default.

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 if you changed it from the default.

Using CGIProxy's embedded server

CGIProxy includes an embedded Web server, so you don't need an external Web server to run it. However, you will need a key pair. (All secure servers need this, but external servers usually have a key pair already installed by your hosting provider.) A key pair consists of a certificate (visible to the public) and a private key (which you must keep secret). You can get a key pair for your server from a certificate authority (CA). Most certificate authorities charge an annual fee for a key pair, but Let's Encrypt provides them for free. They also provide the Certbot tool to automate the process of managing your certificate. After you install CGIProxy, you'll need to copy the certificate and private key files into the "cgiproxy" directory under your home directory.

After installing CGIProxy, start the embedded server by running the command "cgiproxy/bin/nph-proxy.cgi start-server" from your home directory. After it starts, it will tell you the URL to access the proxy with (including the actual port number), and the process ID of the running server.

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

Installing CGIProxy

As of version 2.2.3, the .tar.gz distribution file has a different structure than before, so there is one more step (described in step 3 below) to extract the nph-proxy.cgi file. Alternately, you can directly download the new script file as nph-proxy.txt, rename it to "nph-proxy.cgi", and skip step 3 below.

Once the prerequisites are in place, then to install CGIProxy:

  1. Upload the distribution file (the file ending in ".tar.gz") to your Web server.
  2. Log in to a shell account on the server.
  3. Unpack the distribution: On Unix, run the commands:
    1. tar xzvf cgiproxy.*.tar.gz
    2. tar xzvf cgiproxy-inner.*.tar.gz
    From that you have two files, nph-proxy.cgi and README . nph-proxy.cgi is the program you'll be installing and running. That's it-- just one file.
  4. If you want to rename nph-proxy.cgi (see below), do it now.
  5. Run the command "./nph-proxy.cgi install". This does almost everything required to install CGIProxy. It runs a simple installation wizard that asks you a few questions. Ideally you can run this as root, but it should work even if you don't have root access.
  6. If using the embedded server: Copy both files of your key pair (described in "Prerequisites" above) into the "cgiproxy" directory under your home directory. The filenames should match the configuration variables $CERTIFICATE_FILE and $PRIVATE_KEY_FILE, which are "plain-cert.pem" and "plain-key.pem" unless you changed them.
  7. If installing on a Windows server: Add a daily or hourly task to purge the database in the Task Scheduler, using the command "perl \path\to\script\nph-proxy.cgi" (replace with the correct path) and the parameter "purge-db". If you're allowing us to collect simple usage statistics (i.e. if $REPORT_USAGE is true), add two more tasks to the Task Scheduler:
    1. Every week or month, run "perl \path\to\script\nph-proxy.cgi" with the parameter "report-usage";
    2. At midnight at the beginning of every month, run the same command with the parameter "count-unique-users".

As part of the wizard, you will see a simple menu that lets you modify any configuration variables in CGIProxy. (You probably don't need to change anything.) When you're finished, enter "0" to save your settings and exit the configuration menu. After installing CGIProxy, you can always run the configuration menu again by running "./nph-proxy.cgi config".

After the configuration, the wizard will install all the Perl CPAN modules needed by CGIProxy. To only install these modules, and not do any other installation tasks, run "./nph-proxy.cgi install-modules". If running as root, and if the server uses any of the dnf, yum, or apt-get package managers, CGIProxy tries to use the system's package manager to install CPAN modules; otherwise, it uses the standard cpan utility to install them.

You can rename nph-proxy.cgi if you want. 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.)

Upgrading CGIProxy from a previous version

To upgrade CGIProxy from version 2.2.3 or later, simply run "./nph-proxy.cgi upgrade". If you want to run this automatically, put it in a cron job that runs weekly or monthly. This command only upgrades if there is a newer version of CGIProxy than what you are currently running.

To upgrade CGIProxy from version 2.2.2 or earlier, the easiest way is to uninstall CGIProxy and then install the new version, with these steps:

  1. First, get the new version of the script from nph-proxy.txt and rename it to "nph-proxy.cgi".
  2. If you want to save your previous configuration settings, copy the file cgiproxy/cgiproxy.conf to somewhere outside of your $PROXY_DIR (which is usually "cgiproxy/" under your home directory).
  3. Run "./nph-proxy.cgi uninstall".
  4. Run "./nph-proxy.cgi install". If you saved your old cgiproxy.conf in step 2, then run "./nph-proxy.cgi install --old-config cgiproxy.conf" instead.

When running the "upgrade" command, CGIProxy verifies the code signature of the inner .tar.gz file to ensure it's the same as the original .tar.gz file from

Uninstalling CGIProxy

*** NOTE: If you're using version 2.2.3 and your $SECRET_PATH is empty, do NOT run the "uninstall" command, as it will delete the whole directory where nph-proxy.cgi is installed. This is fixed in version 2.2.4 and later. (Using an empty $SECRET_PATH is not recommended anyway.)

To uninstall CGIProxy 2.2.3 or later, run "./nph-proxy.cgi uninstall".

To uninstall CGIProxy 2.2.2 or earlier, first get the new version of the script from nph-proxy.txt and rename it to "nph-proxy.cgi". Then, run this command with the new copy you just downloaded: "./nph-proxy.cgi uninstall". If it can't figure out exactly where the earlier version is installed, it will ask you for the complete path to the old nph-proxy.cgi.

Note that this does not remove all traces of CGIProxy-- here are traces that remain that you may want to delete:

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.


"Bad Request" errors

These happen when you accumulate too many cookies for the Web server to handle. To fix it, use a database with CGIProxy. The easiest database to use is SQLite-- to use it, just set $DB_DRIVER to "SQLite". To use a running database engine like MariaDB/MySQL or Oracle, you must also create a database account for CGIProxy to use, and set $DB_USER and $DB_PASS.

IMPORTANT: Whenever you use a database, it will accumulate old data that you need to purge periodically for both performance and security reasons. To purge the database, run "./nph-proxy.cgi purge-db" regularly. On a Unix server, do this automatically with a cron job . The CGIProxy installation wizard normally adds this cron job for you, but if it doesn't, then you can do it yourself: run "crontab -e" to edit your list of cron jobs, and add a line like this to purge the database every morning at e.g. 2:13am:

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

Replace "/path/to/script/" with the full path to nph-proxy.cgi . If you'd rather purge the database every hour, change the "2" above to "*".

If you ran "./nph-proxy.cgi install" as root, then do this as root too, but instead of running "crontab -e", run "crontab -e -u $RUN_AS_USER", where $RUN_AS_USER is that username from the CGIProxy configuration. This modifies the list of cron jobs belonging to $RUN_AS_USER .

On a Windows server, use the Task Scheduler to do this instead of a cron job.

© 2013-2019 James Marshall
Last Modified: January 26, 2019