Database Definitions

(NOTE: This document uses Title, URL, Domain, and Host, all of which are the new, longer version of what has previously been simply T, U, D and H within config.txt/ezproxy.cfg.)

Configuration

You configure EZproxy to proxy specific databases by editing config.txt/ezproxy.cfg and making entries based on the following rules:

• Every EZproxy database definition must contain one Title line, one URL line, typically contains one or more Domain lines, and may require one or more Host lines.
• The Title line must appear first. Title must be followed by a textual description of the database. The description entered here appears in the default menu page.
• The URL line appears after the Title line. URL must be followed by the URL that is normally used to access this database. EZproxy automatically treats the host name in this URL as though it appears on its own Host line in the current database configuration. This URL is used when generating the default menu page.
• Domain and Host lines appear after the URL line. A Host line indicates that any URL containing the specified host name should be proxied by EZproxy. A Domain line indicates that any URL containing a host name that matches the Domain line, or ends in the contents of the Domain line, should be proxied.
• A typical database definition will contain one Domain line, containing the last parts of the host name from the URL. For example, if http://www.somedb.com is the URL, then "Domain somedb.com" would be the typical Domain line.

Typical Configuration

Assume that you want to configure EZproxy for use with "Some Database" which you access at http://www.somedb.com/search/. This information should be translated into a database definition in config.txt/ezproxy.cfg that looks like:

Title Some Database
URL http://www.somedb.com/search/
Domain somedb.com


Starting Point URLs

When you first configure EZproxy, after logging in, you will see the default database menu page. One of the main purposes of this page is to introduce you to what a "starting point URL" looks like. If your EZproxy server is named ezproxy.yourlib.org, then the starting point URL that would be generated by the previous database definition is:

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

A "starting point URL" is a URL that can be placed on any web server, and can be used to access a specific database. When a user clicks on such a URL, EZproxy can detect if the user is local or remote, and if the user is remote, EZproxy can determine if the user has authenticated yet or not. If the user is local, EZproxy can redirect the user straight to the database, taking itself completely out of the loop. If the user is remote but has yet to authenticate, the user is authenticated first, then sent on to the database.

If "Some Database" introduces a new feature available directly at http://www.somedb.com/history/, you can use this information to create the new starting point URL:

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

Note that this URL does not match the URL in the database definition. This is perfectly acceptable, since the host name from this URL (www.somedb.com) exactly matches the host name from the URL in the database definition above.

A problem does arise if "Some Database" introduces another new URL such as http://find.somedb.com/everything/. Technically, the host name find.somedb.com matches against "Domain somedb.com" but if you try to use the starting point URL

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

EZproxy will generate an error indicating that you must add this line to config.txt/ezproxy.cfg :

Host find.somedb.com

As mentioned above, there can only be one URL line per database definition, and that URL line creates an implicit Host line for the host name in that URL. If you use other host names as starting points into other URLs provided by the same vendor, you must pre-authorize those other host names with a Host line. (This requirement that the host name in a starting point URL must match the host name in the URL line or a Host line is a security precaution.)

Additional JavaScript Processing

The Domain directive has a special counter-part DomainJavaScript, which appears in most examples by its abbreviation DJ, and Host directive has HostJavaScript, which appears as HJ. These directives indicates that additional JavaScript processing should be performed. As an example:

Title Some Database
URL http://www.somedb.com
DJ somedb.com


indicates that all hosts that end with or are somedb.com should have additional JavaScript processing performed. In a mixture of JavaScript and non-JavaScript directives, the JavaScript directives takes priority. For example, in:

Title Some Database
URL http://www.somedb.com
Host search.somedb.com
DJ somedb.com


when search.somedb.com is proxied, JavaScript processing will be enabled since its name matches the "DJ somedb.com" directive.

When developing database definitions, the recommendation is to start with the normal form of the directives, but if you see the user slipping away from proxying, try using the JavaScript counter-parts to see if they resolve the issue.