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, 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.
CGIProxy requires the following on the machine where it is installed:
These are recommended, but not required:
To see if you already have OpenSSL, run "openssl version"
from the command line to see either the installed version or an error message.
Please note that all of these packages are completely unaffiliated with CGIProxy, and may have their own terms of use.
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.
Configure CGIProxy by editing nph-proxy.cgi in a text editor.
The configuration section starts after some initial comments and code, near
line 291. 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.
If you want to hide nph-proxy.cgi from other people on
the same server, you can rename it. 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 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. To use a database, set $DB_DRIVER to either "MySQL" or "Oracle"-- those are the two database engines that CGIProxy supports.
You need a username and password for the database-- ask your database administrator for those if you can't create them yourself. Set $DB_USER and $DB_PASS to the username and password that you're using.
If you don't have the permissions to create databases, ask the database administrator to also create a database called "cgiproxy" for you. You can name the database something else by setting the $DB_NAME variable-- do this if you don't want other people on the same server to know you're running CGIProxy.
All database configuration in CGIProxy is described in the section DATABASE CONFIGURATION OPTIONS.
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".
In Unix or Mac, 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 -c purge-db
To purge the database every night at 2:00 am, add the line:
0 2 * * * /path/to/script/nph-proxy.cgi -c purge-db
(Replace "/path/to/script/" with the full path to nph-proxy.cgi .)
There are four ways to run CGIProxy:
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:
nph-proxy.cgi onto your Web server somewhere,
but not at the top Web directory, or else it will be easily discovered.
chmod +x nph-proxy.cgi"; there are
other ways.
nph-proxy.cgi, run the
command "./nph-proxy.cgi install-modules" (or in Windows,
"perl nph-proxy.cgi install-modules"). This installs the optional
Perl modules to e.g. let you visit secure sites. 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>.
.htaccess
file.
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.
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.
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:
nph-proxy.cgi to your server machine. Do not
put it under your Web directory.
chmod +x nph-proxy.cgi"; there are
other ways.
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. It may take a while
the first time you run it, as it will install some required Perl modules
if you don't already have them; you can ignore the scrolling text. If
it asks you any questions, you can just hit <return>.
To stop the FastCGI process, run the command "killall nph-proxy.cgi".
Include a section like this in your nginx.conf, within
the secure server section:
location /secret/ {
include fastcgi.conf;
fastcgi_pass unix:/tmp/cgiproxy.fcgi.socket;
}
Replace "/secret/" with your setting of $SECRET_PATH, and
replace "/tmp/cgiproxy.fcgi.socket" with your setting of $FCGI_SOCKET .
Include a line like this in your httpd.conf:
FastCgiExternalServer /var/www/html/secret -socket /tmp/cgiproxy.fcgi.socket
Replace "/var/www/html/secret" with your setting of $SECRET_PATH
appended to your DocumentRoot, and
replace "/tmp/cgiproxy.fcgi.socket" with your setting of $FCGI_SOCKET .
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. This is true of any secure server.
To install CGIProxy using its own embedded server:
.cgiproxy" directory under your home directory
(or whatever you may have set $PROXY_DIR to).
nph-proxy.cgi to your server machine. Do not
put it under your Web directory.
chmod +x nph-proxy.cgi"; there are
other ways.
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.
It may take a while the first time you run it, as it will install some required Perl modules if you don't already have them; you can ignore the scrolling text. If it asks you any questions, you can just hit <return>.
To stop the embedded server, run the command "killall nph-proxy.cgi".
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.
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.
| Last Modified: February 4, 2013 | http://www.jmarshall.com/tools/cgiproxy/install.html |