Proxy By Hostname Configuration

First, an important comment on starting point URLs

The following document describes proxy by hostname. In standard proxy by port, starting point URLs typically took this form:

http://ezproxy.yourlib.org:2048/login?url=http://www.somedb.com/

In proxy by hostname, starting point URLs remain in this basic form. The only change that may occur in a switch to proxy by hostname occurs if you choose to move from port 2048 to port 80, in which case you can drop the port number, which in that instances would change the general form to:

http://ezproxy.yourlib.org/login?url=http://www.somedb.com/

In all instances, you will still have a URL composed of your EZproxy hostname, perhaps a port, then /login?url= followed by the real URL for your database.

All references below to hostnames like www.somedb.com.ezproxy.yourlib.org are used solely by EZproxy as it proxies users, just as EZproxy internally uses forms like ezproxy.yourlib.org:2050 to present remote hosts in proxy by port. These are not things that you will use in URLs that you setup for EZproxy.

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.

Proxy by hostname configuration

Traditionally, EZproxy has operated by mapping the host name/port number combinations used by web servers into a port number on your EZproxy server. With this update, EZproxy can now map host name/port number configurations into unique host names that refer back to the EZproxy server. For example, traditionally, www.somedb.com might have been mapped to ezproxy.yourlib.org:2050. Now, www.somedb.com would map to www.somedb.com.ezproxy.yourlib.org.

The key advantage to this change is that it allows EZproxy to operate on a single port. This both eases resource requirements on your server, and simplifies both local and remote firewall configuration issues.

To set up proxy by hostname, follow these directions.

  1. First, your DNS administrator must make two entries for your test 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
    If you manage DNS on Windows servers, see Proxy By Hostname Windows DNS Configuration for the steps required to create these entries.

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

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

    Do not proceed until your wildcard entry passes this test.

  3. Make a backup copy of your config.txt/ezproxy.cfg file.
  4. Proxy by hostname is activated by editing config.txt/ezproxy.cfg and adding this line anywhere in the file:
    Option ProxyByHostname
  5. If you are not running another web server on the test system and would like to have EZproxy operate on the standard web server port of 80, edit config.txt/ezproxy.cfg and add this line:
    LoginPort 80
    If you use "LoginPort 80" on a Linux or Solaris system, EZproxy must be started as root.

    LoginPort can appear in config.txt/ezproxy.cfg 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:

    LoginPort 80
    LoginPort 2048
    to allow the old URLs to continue to continue to function
  6. OPTIONAL: This step is optional and provided to answer the questions that some may have about the use of port 80 on a server already running a web server.

    If you already run a web server on the same machine 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. Information on how to add a second IP address for Linux, Solaris, and Windows.

    If EZproxy is running on a machine that also runs Microsoft's IIS web server, be sure to see EZproxy/IIS Co-Existence on Port 80 for additional requirements.

    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/ezproxy.cfg 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 of any other name that points to this server.
  7. With these changes in place, you can restart EZproxy to begin testing.

With these steps complete, you should be ready to test. 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 restore rename config.txt/ezproxy.cfg to another name, restore config.txt/ezproxy.cfg from the backup you made in step 3, restart EZproxy, and contact support@oclc.org for additional assistance.

Releasing old ports

When you convert to proxy by hostname, EZproxy will continue to listen on the old ports to allow old bookmarks to the old ports to work and as a safety precaution in case you move back to proxy by port.

Once everything is working correctly, you can direct EZproxy to release the old ports. To do this, access your server administration page and from there go to your server status page. If you are running a recent version of EZproxy, you will find a host maintenance option, and if you click on that, you will find an option to direct EZproxy to release the old ports. If you do not find the host maintenance option, you will need to update to a newer release of EZproxy to release these ports.