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!

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. After you install
  4. 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

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 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 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 "\path\to\script\nph-proxy.cgi" (replace with the correct path) and the parameter "purge-db".

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. This may generate a lot of scrolling text, which you can ignore. If it asks you any questions, you can just hit <enter>. 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.)

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-2017 James Marshall
Last Modified: July 16, 2017