Introduction to database stanza directives
Overview
Every resource that your users access remotely using EZproxy must be configured in the config.txt file. This file contains a listing of the databases that you subscribe to with instructions for EZproxy about what resources within those databases users are allowed to access. The instructions are the directives, and when combined, these directives form database stanzas. When your users attempt to access a database, after they have been authenticated, EZproxy reads your institution’s list of resources and directives in the config.txt file and determines whether or not the resource the user is trying to access is available to your users, and either grants access (by rewriting the URL into a proxied URL) or denies access.
The following document will provide an overview of basic EZproxy database stanza construction and how EZproxy reads those database stanzas. This will help you to better understand how to create your own basic stanzas and when an existing stanza in your config.txt will provide access to a newly licensed resource.
Basic stanza construction
Basic EZproxy database stanzas consist of up to six directive statements. While many additional directives and configurations can be used, and are necessary in some cases, the basic database stanza is often all that is needed to provide access to resources. It also serves as a starting point to examine how EZproxy reads and processes information when a user clicks on the resource URLs you have listed on your website.
The basic directives used in stanza construction are as follows:
Title
URL
Host
HostJavascript
Domain
DomainJavascript
Not all basic database stanzas will contain all of these directives, but they will contain at minimum the first two, title and URL, and most will be followed by at least one Host/HostJavascript and one Domain/DomainJavascript.
Directive definitions
Database stanzas can be made up of multiple directives, but most database stanzas are constructed using some combination of six basic directives: Title, URL, Host, HostJavascript, Domain, and/or DomainJavascript. The following table provides definitions for these directives, examples of their use, and the result of entering that example as part of a config.txt file.
| Directive | What it does | Example |
|---|---|---|
Title |
Any entry following the title directive will appear in the alphabetical list of resources on your default test page. The title has no bearing on how EZproxy handles a given database. It is there just for your reference to help identify the given database. |
If your config.txt file has the following line
Science Database would appear on your admin /menu (LINK) page, with a hyperlink to the proxied webpage specified in the URL line following the title. |
URL |
The first directive EZproxy reads to determine whether the URL a user is trying to access matches any of the databases in the config.txt file. If the URL a user is trying to access matches a URL in the config.txt file, proxied access is granted. |
If your config.txt file has the following line URL http://www.sciencedb.com A user who clicks on a link with the starting point URL http://ezproxy.abclib.org:2048/login?url=http://www.sciencedb.com would be allowed to access the Science Database because the URLs match. |
|
&
|
The next directives EZproxy reads to determine whether the URL a user is trying to access matches any of the databases in the config.txt file. If the URL a user is trying to access matches a Host or a HostJavascript in the config.txt file, proxied access is granted. |
If your config.txt file has either of the following lines OR A user who clicks on a link with the starting point URL http://ezproxy.abclib.org:2048/login?url=http://www.physics.sciencedb.com would be allowed to access the Physics resource at the Science Database because the URL matches the Host directive. |
|
&
|
After a user has accessed a proxied database, additional links within that site may be encountered. When a user clicks on a link within a proxied site, EZproxy reads config.txt for the first Domain or DomainJavascript statement that matches that URL. If the URL matches a domain statement in the config.txt file, proxied access is granted. If the DJ directive is used, any javascript in that URL will be rewritten as well. The Domain directive will not rewrite javascript encountered in the URL. |
If your config.txt file has either of the following lines OR A user within a proxied site who clicked on a link with the URL http://www.physics.sciencedb.com would be allowed to access the Physics resource at the Science Database because the URL matches the domain directive. This domain statement would also allow the user to access the Astronomy resource with the following URL http://www.astronomy.sciencedb.com. Even though the URLs for the Physics and Astronomy resources are different, because they end with the domain sciencedb.com, the domain statement above will ensure that the user is granted access to both these, and any other resource with a URL ending in sciencedb.com. |
URL, Host & HostJavascript
Standard port URLs
Every EZproxy transaction begins with a Starting Point URL. In one of the two following forms, depending on whether your instance of EZproxy is standalone or hosted.
Standalone: http://ezproxy.abclib.org:2048/login?url=http://www.sciencedb.com/index.html
Hosted: http://abclib.idm.oclc.org/login?url=http://www.sciencedb.com/index.html
In both of these examples, the user is trying to use EZproxy to reach the content provider Science Database located at
http://www.sciencedb.com/index.html
When processing this starting point URL, EZproxy will take the origin of the request http://www.sciencedb.com:80 (which consists of the origin URL, http://www.sciencedb.com and the standard port, :80) and try to find a URL, Host, or HostJavascript (HJ) directive in the config.txt file with an identical origin. For a more detailed discussion of the origin and other components of URLs, please see Understanding URLs. Neither Domain nor DomainJavascript directives will be read in the config.txt file when EZproxy begins processing this starting point URL. EZproxy only reads the URL, Host, and HostJavascript directives when searching for a match to the starting point URL.
Any of the following directives in config.txt would be considered a match to the starting point URL above since they have the same origin (http://www.sciencedb.com:80) as the database URL above.
URL http://www.sciencedb.com
URL http://www.sciencedb.com/index.html
URL http://www.sciencedb.com/biology
Host www.sciencedb.com
Host http://www.sciencedb.com
HJ www.sciencedb.com
HJ http://www.sciencedb.com
Non-default and secure port URLs
Non-default URLs
The previous examples all assume that the destination URLs in the Starting Point URL use the default scheme http and the default port 80. If a destination URL uses the secure https scheme with its 443 port or a non-default port, then it will only match a URL, Host, or HostJavascript (HJ) line that includes port information.
For example, the following Starting Point URL,
http://ezproxy.abclib.org:2048/login?url=http://www.sciencedb.com:8080/index.html
would not match any of the previous examples because it contains the port number 8080, not the default port 80. This Starting Point URL, however, would match any of the following directive lines, which all have the origin http://www.sciencedb.com:8080, which matches the origin of the destination URL in the Starting Point URL..
URL http://www.sciencedb.com:8080/
URL http://www.sciencedb.com:8080/index.html
URL http://www.sciencedb.com:8080/history
Host www.sciencedb.com:8080
Host http://www.sciencedb.com:8080
HJ www.sciencedb.com:8080
HJ http://www.sciencedb.com:8080
Secure port URLs
Likewise, the starting point URL that follows would not be a match with any of the previous URL, Host, or HJ statements because it contains the scheme https, which points the URL to a different default port, 443. So, the following starting point URL,
http://abclib.idm.oclc.org/login?url=https://www.sciencedb.com/index.html
would require a separate URL, Host, or HJ statement for EZproxy to read this starting point URL as a match and allow proxied access. Any of the following directive lines, which all have the origin of the destination URL, https://www.sciencedb.com:443 would be matches for this secure port URL:
URL https://www.sciencedb.com
URL https://www.sciencedb.com/index.html
URL https://www.sciencedb.com/history/
Host https://www.sciencedb.com
HJ https://www.sciencedb.com
Domain & DomainJavascript
Once a user begins using a site through EZproxy, additional links may be encountered, and EZproxy must read the config.txt file to determine whether or not to proxy these links and allow the user to continue on to these resources while still proxied. EZproxy will attempt to match the newly encountered URL against URL, Host, and HJ statements, but it will also consider the Domain and DomainJavascript (DJ) directives at this time.
When attempting to match the Domain or DJ lines, EZproxy ignores the scheme (http:// and https://) and port. Instead, EZproxy considers a URL to match a Domain or DJ directive if the URL matches the domain name or ends in the domain name. For instance, a user might click on the following URL while using the proxied site http://www.sciencedb.com.
http://www.physics.sciencedb.com
The origin of this URL (http://www.physics.sciencedb.com:80) would not match any of the previous URL, Host, or HostJavascript directives given in the previous tab. However it would match the following Domain or DJ directives:
Domain sciencedb.com
DJ sciencedb.com
Domain physics.sciencedb.com
DJ physics.sciencedb.com
Domain www.physics.sciencedb.com
DJ www.physics.sciencedb.com
In each of these examples, the destination URL either matches the specified domain exactly, or ends with a period followed by the given domain.
While any of these Domain or DJ directive lines would provide your users with access to the given destination URL, the first Domain and first DJ lines are the recommended construction for these directives because they would match multiple destination URLs encountered on a proxied site. Any URL encountered on the proxied site that ended with sciencedb.com would be rewritten if a user clicked on it. For example, the statements
Domain sciencedb.com
and
DJ sciencedb.com
would be domain matches for any of the following URLs
http://www.physics.sciencedb.com
http://www.astronomy.sciencedb.com
http://www.biology.sciencedb.com
because all of these URLs end with sciencedb.com, but all the other Domain and DJ lines would only match
http://www.physics.sciencedb.com
Examples
| Stanza | Result |
|---|---|
Title Science Databases |
The Title Science Databases will appear on your default test page Users will be able to access the URL http://www.sciencedb.com from a starting point URL through the proxy server; it will be rewritten with your proxy prefix in front of it as http://ezproxy.abclib.org:2048/login?url=http://www.physics.sciencedb.com Once on the site Science Databases, this Domain directive will allow users to access the resources located at http://www.chemistry.sciencedb.com as well as http://www.astronomy.sciencedb.com, and both will be rewritten with the proxy prefix http://ezproxy.abclib.org:2048/login?url=http://www.chemistry.sciencedb.com or http://ezproxy.abclib.org:2048/login?url=http://www.astronomy.sciencedb.com |
Title Social Science Database |
The Title Social Science Database will appear on your default test page Users will be able to access the URL http://www.socialscidb.com from a starting point URL http://ezproxy.abclib.org:2048/login...ocialscidb.com through the proxy server. Users will also be able to access the URLs: http://www.economics.socialscidb.com, because they have been included as Host or HostJavascript statements. When rewritten with proxy access, only the URL will be rewritten for the two following the Host statement. When rewritten with proxy access, the JavaScript for the URL following the HostJavascript statement will also be rewritten. Once at the proxied site Social Science Database, the Domain and DomainJavascript statements allow users to access any URL link that ends with socialscidb.com. The DomainJavascript statement will cause the JavaScript at that link will also be rewritten. This means users can access additional resources located at links like http://www.freud.psychology.socialscidb.com and http://www.micro.economics.socialscidb.com. However, because psychology.socialscidb.com follows a Domain statement, and this statement is listed first, the first URL will be rewritten, but JavaScript at the URL will not be rewritten. Because socialscidb.com follows a DJ statement, the second URL will be rewritten, and so will the JavaScript at the URL. |