CGIProxy Installation

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

Apache has a page with all the details.

As a mod_perl script

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 nph-proxy.pl .

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

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

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 jmarshall.com.

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:

• If you're using a database other than SQLite, the "cgiproxy" database will still be there, along with any special user created for CGIProxy.
• The installation wizard may have installed various Perl modules, either in the system location (if run as root), or under the "perl5/" directory under your home directory (if not run as root).
• You may have configured your web server in order to run CGIProxy.
• If you're using a Windows server, you will need to remove any related tasks from the Task Scheduler.

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.