Migrate to Proxy by Hostname

Proxy by hostname in config.txt

The config.txt file generated and stored in your EZproxy directory when you first download and install the software contains the following, commented out configuration.

##  EZproxy must be set to Proxy-by-port or to Proxy-by-hostname:
##  see http://www.oclc.org/support/documentation/ezproxy/portvshostname.htm
##                             AND
##  http://www.oclc.org/support/documentation/ezproxy/cfg/proxybyhostname.htm

# Option ProxyByHostname

##  By default, EZproxy listens on port 2048. You can specify a different port here

# LoginPort 80

If you are configuring Proxy by Hostname in a newly installed config.txt, un-comment directive lines as necessary when stepping through the configuration instructions below. Additional directives can be included.

Proxy by hostname configuration

1. First, your DNS administrator must create two entries for your server. If your EZproxy server will run on 68.15.177.100, and if it will operate under the name ezproxy.yourlib.org, then the entries would be:

   ezproxy.yourlib.org.   IN A 68.15.177.100
   

   *.ezproxy.yourlib.org. IN A 68.15.177.100
   

   Both of these entries should be made as A records, not CNAME records.

   If you manage DNS on Windows servers, see Proxy By Hostname Windows DNS Configuration for the steps required to create these entries.

2. Verify your wildcard DNS entry by browsing to Check DNS and entering the name of your EZproxy server and selecting the wildcard check.

    Caution: Do not proceed until your wildcard entry passes this test.

3. Make a backup copy of your config.txt file.
4. Proxy by hostname is activated by editing config.txt and adding this line anywhere in the file:

   Option ProxyByHostname
   

   If you are configuring EZproxy with a new config.txt file, un-comment this line. It is located towards the top of the file in the block noted above.

5. If you are not running another web server on the EZproxy server and would like to have EZproxy operate on the standard web server port of 80, edit config.txt and add this line:

   LoginPort 80
   

   If you are configuring EZproxy with a new config.txt file, un-comment this line. It is located towards the top of the file in the block noted above.

   Running EZproxy as Root on Linux

   If you use "LoginPort 80" on a Linux system, EZproxy must be started as root. If you do this, OCLC strongly recommends that you add the RunAs directive statement to your config.txt so that EZproxy does not run as root after startup.

   Using Multiple LoginPorts

   LoginPort can appear in config.txt more than once. The first appearance defines the "primary location" for logins. Other lines can indicate alternate ports. where EZproxy should listen.

   For example, if your old URLs reference port 2048 as the main login port, you may have many old URLs that refer to this port. In your server, you could use the following to allow the old URLs to continue to function:

   LoginPort 80
   LoginPort 2048
   

6. Restart EZproxy for your changes to take effect.

Optional: Running two web servers on port 80

If you already run a web server on the same server that hosts EZproxy, but you want to use port 80 to alleviate firewall issues, this is possible, although it requires that you assign an additional TCP/IP address to the EZproxy server. For more information on how to add a second IP address see Linux or Windows.

Note: EZproxy is no longer supported on a server also running IIS. See: Add a second IP address to an existing network adapter on Windows.

If you configure EZproxy with a new IP address, you will need to complete the first two steps of this document for the new IP address before you can reconfigure EZproxy to use its new name.

If you want to keep old URLs that point to the old name:2048 working, you can use entries in config.txt similar to this:

Name ezproxy.yourlib.org
Interface 68.15.177.100
LoginPort 80
Interface ANY
LoginPort 2048

This sample configuration tells EZproxy that it should identify itself as http://ezproxy.yourlib.org:80, but it should also listen for requests on port 2048 for any other name that points to this server.

After making these changes, restart EZproxy to begin testing. EZproxy will use only a single port, but you will see the host names change as you access different sites.

If you are able to login, but then start seeing "Page not found" errors, your wildcard DNS entry may not be correct. In this instance, you should rename config.txt to another name, restore config.txt from the backup you made in step 3, restart EZproxy, and contact OCLC Support  for additional assistance.

Using CGI authentication?

If you are using CGI authentication and you change the port on which EZproxy listens (e.g. 2048 to 80), you must adjust your CGI script to reference the new port as well (e.g. $ezpport=2048; to $ezpport=80;). Failing to adjust your script will lead to a strange, confusing error message and a total disabling of login processing.