To configure CGIProxy after installing it, run "./nph-proxy.cgi config".
Here's a list of all the configuration options in CGIProxy, sorted into rough categories. The default settings are in square [] brackets, and should work fine for almost all situations, though see the section OPTIONS RELATED TO YOUR SERVER/NETWORK ENVIRONMENT to be sure. Also, see the other possibly needed sections as appropriate. For more information on any option, see the comments in the source code where it is set, in the user configuration section.
| OPTIONS RELATED TO YOUR SERVER/NETWORK ENVIRONMENT: | |
|---|---|
| $PROXY_DIR ["cgiproxy"] | The directory on the server where the program can place files. A relative path will be resolved relative to the home directory of the script owner. |
| $RUN_AS_USER, $RUN_AS_GROUP [none] | User ID and group to run as, in case you need to start the embedded server as root. Also used to indicate Web server's user ID and group when running as a CGI or mod_perl script. |
| $SECRET_PATH [randomly-generated] | If using FastCGI or the embedded server, set this to an alphanumeric sequence of characters that is hard to guess. It will be part of the URL of your proxy. |
| $LOCAL_LIB_DIR ['perl5'] | The directory used by the local::lib module to install Perl (CPAN) modules. Only needed if local::lib is used, i.e. if installing Perl modules not as root. |
| To enable access to secure servers: | Install the separate packages OpenSSL and Net::SSLeay. Net::SSLeay is automatically installed by running "./nph-proxy.cgi install-modules". |
| To enable compressed (gzip'd) content: | If you're not using Perl 5.9.4 or later, then install the IO::Compress::Gzip Perl module. It is automatically installed by running "./nph-proxy.cgi install-modules". |
| $RUNNING_ON_SSL_SERVER [''] | Set this if the script is running on an SSL server (i.e. accessed with an "https://" URL). Or, the default value of '' means to guess based on the server port: the script assumes SSL unless the server port is 80. |
| $NOT_RUNNING_AS_NPH [0] | Set this if the script is not running as an NPH script (not recommended; see comments for possible dangers). |
| $HTTP_PROXY, $SSL_PROXY, $NO_PROXY [none] |
If this script has to use an HTTP proxy (like a firewall), then set $HTTP_PROXY to that proxy's host (and port if needed). Set $SSL_PROXY similarly when using an SSL proxy. $NO_PROXY is a comma-separated list of servers or domains that should be accessed directly, i.e. NOT through the proxies in $HTTP_PROXY and $SSL_PROXY. Also see $USE_PASSIVE_FTP_MODE below when using a firewall. |
| $PROXY_AUTH, $SSL_PROXY_AUTH [none] |
If either or both of the proxies in $HTTP_PROXY and $SSL_PROXY require authentication, then set these two variables respectively to the required credentials. |
| $SOCKS_PROXY [none] | To use a SOCKS 5 proxy (like Tor), set this to the SOCKS 5 proxy's host and port, or just port number to default to localhost. It's strongly recommended to only use a SOCKS 5 proxy on the same server as CGIProxy, as all data is passed in the clear between them. As of version 2.2.2, you no longer need to change @BANNED_NETWORKS to use a SOCKS proxy on localhost. |
| $SOCKS_USERNAME, $SOCKS_PASSWORD [none] |
If your SOCKS 5 proxy uses username/password authentication, set these. |
| $USER_FACING_PORT [none] | If the users see a different port externally than CGIProxy sees internally, set this to the port the users see. |
| $REPORT_USAGE [no default] | If set to 1 (true), allow us to collect simple usage metrics: hit count,
total traffic in bytes, and unique users per month. All are sorted by
language used. We do NOT collect any URLs, IP addresses, or any other
private information. This helps us to develop CGIProxy, in multiple ways.
Note that if this is set, it needs two automatic jobs to be set (cron jobs
on Unix): 1) "nph-proxy.cgi report-usage" every week or month, and
2) "nph-proxy.cgi count-unique-users" run at midnight on the first of
every month. (The full path to nph-proxy.cgi has to be included in the
commands.) On Unix and Mac, the installation wizard automatically adds
these cron jobs as needed. |
| FASTCGI CONFIGURATION OPTIONS: | |
| $FCGI_SOCKET [8002] |
The local port to listen on for FastCGI communication. |
| $FCGI_NUM_PROCESSES [100] | Number of FastCGI processes to maintain (same as "-n" command-line parameter). |
| $FCGI_MAX_REQUESTS_PER_PROCESS [1000] | How many HTTP requests each FastCGI process should handle before being restarted (same as "-m" command-line parameter). |
| EMBEDDED SERVER CONFIGURATION OPTIONS: | |
| $CERTIFICATE_FILE ['plain-cert.pem'], $PRIVATE_KEY_FILE ['plain-key.pem'] |
Filenames of your certificate (public key) and private key, in PEM format and in $PROXY_DIR. |
| $EMB_USERNAME, $EMB_PASSWORD [none] |
Optional username and password to protect your proxy with. |
| DATABASE CONFIGURATION OPTIONS: | |
| $DB_DRIVER ['SQLite'] | If using a database, set this to "SQLite", "MySQL", or "Oracle". Leave it commented out if not using a database. |
| $DB_SERVER [none] | If your database isn't running on the same server as CGIProxy, or isn't on the default port, then set this to the database server and port in the form "db_host:db_port". |
| $DB_NAME ['cgiproxy'] |
Name of the database the program can use. |
| $DB_USER, $DB_PASS [none] |
CGIProxy accesses the database with this username and password. |
| $USE_DB_FOR_COOKIES [1] | Set this to true to use the server-side database to store cookies. If false, will use the old method of storing cookies in the browser and sending all cookies with each request, which may result in "Bad Request" errors. |
| COMMON CONFIGURATION OPTIONS: | |
| $TEXT_ONLY [0] | Allow only text resources through the proxy, to save bandwidth. |
| $REMOVE_COOKIES [0] | Ban all cookies to or from all servers. To allow and ban cookies by specific servers, see @ALLOWED_COOKIE_SERVERS and @BANNED_COOKIE_SERVERS. |
| $REMOVE_SCRIPTS [0] | Prevent any script content from any server from reaching the browser. This includes script statements within HTML pages, external script files, etc. To allow and ban script content by specific servers, see @ALLOWED_SCRIPT_SERVERS and @BANNED_SCRIPT_SERVERS. Anonymity is unreliable if you don't either remove scripts, or browse with scripts turned off in your browser. |
| $FILTER_ADS [0] | Remove ads from pages, based on the patterns in @BANNED_IMAGE_URL_PATTERNS. Also ban ad-related cookies by setting $NO_COOKIE_WITH_IMAGE. |
| $HIDE_REFERER [0] | Don't tell servers which link you followed to get to their page. (Yes, it's misspelled on purpose.) |
| $INSERT_ENTRY_FORM [1] | At the top of every page, include a small form that lets you enter a new URL, change your options, or manage your cookies. |
| $ALLOW_USER_CONFIG [1] | Let users set their own $REMOVE_COOKIES, $REMOVE_SCRIPTS, $FILTER_ADS, $HIDE_REFERER, and $INSERT_ENTRY_FORM, via checkboxes on the entry form. |
| sub proxy_encode {}, proxy_decode {} | (Requires minor programming.) You can customize the encoding of destination URLs by modifying these routines. The default is a simple unobscured URL, but sample obscuring code is included in the comments. Note: If you're not removing scripts, then you also need to change _proxy_jslib_proxy_encode() and _proxy_jslib_proxy_decode()-- see the comments. |
| sub cookie_encode {}, cookie_decode {} | (Requires minor programming.) You can customize the encoding of cookies sent to the user's machine by modifying these routines. The default is a simple unobscured cookie, but sample obscuring code is included in the comments. Note: If you're not removing scripts, then you also need to change _proxy_jslib_cookie_encode() and _proxy_jslib_cookie_decode()-- see the comments. |
| @ALLOWED_SERVERS, @BANNED_SERVERS [empty] |
Allow or ban specific servers from being accessed through the proxy, based on their hostname. Each array is a list of patterns (regular expressions) to match, not just single servers. |
| @BANNED_NETWORKS [('127', '192.168', '172.16-31', '10', '169.254', '244.0.0')] |
Ban specific IP addresses or networks from being accessed through the proxy. Recommended for security when this script is run on a firewall. As of version 2.2.2, a SOCKS proxy is allowed on localhost regardless of this setting. |
| @ALLOWED_COOKIE_SERVERS, @BANNED_COOKIE_SERVERS [empty] |
Allow or ban cookies from specific servers. Each array is a list of patterns (regular expressions) to match, not just single servers. |
| @ALLOWED_SCRIPT_SERVERS, @BANNED_SCRIPT_SERVERS [empty] |
Allow or ban script content from specific servers. Each array is a list of patterns (regular expressions) to match, not just single servers. |
| @BANNED_IMAGE_URL_PATTERNS [sample list in source code] |
If $FILTER_ADS is set, then ban images that match any pattern in this list. |
| $RETURN_EMPTY_GIF [0] | If an image is banned, then replace it with a 1x1 transparent GIF to show blank space instead of a broken image icon. |
| $NO_COOKIE_WITH_IMAGE [0] | Ban all cookies that come with images or other non-text resources. Those are usually just Web bugs, to track you for marketing purposes. |
| $QUIETLY_EXIT_PROXY_SESSION [0] | (NOT for use with anonymous browsing!!!) For VPN-like installations, let the user browse directly from proxied pages to unproxied pages, with no intermediate warning screens. See the comments for more info. |
| $PROXIFY_SCRIPTS [1] | Proxify all supported script content. Currently, only JavaScript is supported. |
| $PROXIFY_SWF [1] | Support Flash apps, i.e. reroute all network accesses in them back through this program. |
| $ENCODE_URL_INPUT [1] | When submitting a URL through either the start form or the top form, encode it first by using proxy_encode(). |
| $USER_IP_ADDRESS_TEST [''] | This lets you call an external test to authorize the user. See comments for more details. |
| $DESTINATION_SERVER_TEST [''] | This lets you call an external test to determine if the destination server is allowed (as opposed to using @ALLOWED_SERVERS and @BANNED_SERVERS). See comments for more details. |
| %REDIRECTS [none] | This lets you automatically redirect a URL to another URL, perhaps to one that works better through CGIProxy, such as a mobile site. |
| INSERTING A STANDARD HEADER INTO EACH PAGE: | |
| $INSERT_HTML [none] | Insert your own block of HTML into the top of every page. |
| $INSERT_FILE [none] | Insert the contents of the named file into the top of every page. Can't be used with $INSERT_HTML. |
| $ANONYMIZE_INSERTION [1] | If $INSERT_HTML or $INSERT_FILE is used, then anonymize that HTML along with the rest of the page. |
| $FORM_AFTER_INSERTION [0] | If $INSERT_HTML or $INSERT_FILE is used, and $INSERT_ENTRY_FORM is set, then put the URL entry form after the inserted HTML instead of before it. |
| MINOR OR SELDOM-USED OPTIONS: | |
| @PROXY_GROUP [empty] | This is an experimental feature which may help with load balancing, or may have other creative uses. Cookies won't work if you use this. See the comments for further info. |
| $SESSION_COOKIES_ONLY [0] | Force all cookies to expire when the current browser closes. |
| $MINIMIZE_CACHING [0] | Try to prevent the user's browser from caching, i.e. from storing anything locally. Better privacy, but consumes more bandwidth and seems slower. |
| $USER_AGENT [none] | Tell servers you're using this browser instead of what you're really using. |
| @TRANSMIT_HTML_IN_PARTS_URLS [empty] | Transmit each part of certain HTML pages back to the user as they are received, rather than wait for the whole page. This is set to a list of patterns that match URLs for which you want this treatment. |
| $USE_PASSIVE_FTP_MODE [1] | When doing FTP transfers, use "passive mode" instead of "non-passive mode". Passive mode tends to work better when this script runs behind a firewall, but that varies by network. |
| $SHOW_FTP_WELCOME [1] | When showing FTP directories, always display the FTP welcome message, instead of never displaying it. |
| $PROXIFY_COMMENTS [0] | Proxify the inside of HTML comments as if it's not inside comments. |
| $USE_POST_ON_START [1] | Use POST instead of GET when submitting the URL entry form. |
| $REMOVE_TITLES [0] | Remove titles from HTML pages. |
| $NO_BROWSE_THROUGH_SELF [0] | Prevent the script from calling itself. |
| $NO_LINK_TO_START [0] | Don't link to the start page from error pages. |
| $MAX_REQUEST_SIZE [16777216 = 16 Meg] |
(Obscure.) The largest request that can be handled in certain rare situations involving password-protected sites. |
| $ALLOW_UNPROXIFIED_SCRIPTS [0] | Allow scripts of unsupported type to pass through the proxy. |
| $COOKIE_PATH_FOLLOWS_SPEC [0] | When handling cookies with no path, treat it according to the cookie spec. If not set, behave as browsers (erroneously) do, i.e. set the path to "/". |
| $RESPECT_THREE_DOT_RULE [0] | Restrict cookie domains as they should be, based on how many dots they have. If not set, behave as browsers (erroneously) do, i.e. loosen restrictions on cookie domains with two dots. |
| $ALERT_ON_CSP_VIOLATION [0] | When there is a Content Security Policy (CSP) violation, show a message to the user. When not set, just show such error messages in the JavaScript console. This is usually just used for testing. |
| %TIMEOUT_MULTIPLIER_BY_HOST [ "www.facebook.com" => 10 ] | Multiply timeouts in JavaScript by this much, for the listed servers. This can be used to reduce crashes and improve performance on certain JavaScript-heavy sites. |
| $ALLOW_RTMP_PROXY [0] | (Currently unused.) Allow the creation of an RTMP proxy process. |
| © 2013-2018 James Marshall | https://jmarshall.com/tools/cgiproxy/options.html |
| Last Modified: November 18, 2018 |