Config.txt
From EZProxyWiki
Config.txt is the EZproxy configuration file. It contains general settings plus database definitions for the web resources to be proxied.
The file has been named config.txt since EZproxy 5.1a (2008-08-25). Prior to that it was named ezproxy.cfg.
The following directives are used in the config.txt file. Either the entire directive or the abbreviated form may be used; abbreviated forms are in parenthesis.
Within the config file you may preface a line with "#" to insert comments that will be ignored by EZproxy.
EZproxy must be restarted for changes to config.txt to take effect.
Official OCLC documentation is at Configuration File config.txt/ezproxy.cfg. Many directives (but not all, as at June 2010) are documented in the draft Reference Manual.
General Settings
By convention general settings are placed at the top of the file before the first Title line. Most settings don't have to be at the top, but it is more convenient if they are.
(N) Name of Server
Name of the server where EZproxy resides
e.g. "N lib5.lib.ou.edu" or "N libraries.ou.edu"
(E) ExcludeIP
Exclude computers or IP address ranges from having to use EZproxy.
e.g. "E 129.15.1.0 - 129.15.255.255" excludes anyone on OU's campus from having to use EZproxy
Can appear multiple times within ezproxy.cfg - with the settings taking effect on the next 'T' line.
(I) IncludeIP
Include computer or IP address previously excluded to force that computer to use proxy.
e.g. "I 129.15.70.30" forces that computer (currently proxy server) to use EZproxy. This allows us to use a proxy to test off campus access.
Can appear multiple times within ezproxy.cfg - with the settings taking effect on the next 'T' line.
(A) Automatically Authenticate
Allow access to this resource without the user having to be authenticated. This allows us to have databases to which we want to provide access through EZproxy but do not want to make the user authenticate from certain IP addresses.
e.g. "A 129.15.70.30" Allows access to the resource through EZproxy from this IP without any user authentication.
Can appear multiple times within ezproxy.cfg - with the settings taking effect on the next 'T' line.
(F) FIRSTPORT, default 2048
Sets the first port used by EZproxy. The ports used will be from X to Y, where X is FIRSTPORT and Y = X + MAXVIRTUALHOSTS
(MC) MaxConcurrentTransfers, default 200
MAXCONCURRENTTRANSFERS determines how many HTTP transfers can be in progress concurrently. Most web browsers are configured to attempt four simultaneous HTTP transfers so that they can load web pages and graphics at the same time. The default value of 200 allows for 50 people to concurrently downloading 4 files each without reaching this limit.
(ML) MaxLifetime, default 120
MAXLIFETIME determines how long in minutes an EZproxy session should remain valid after the last time it is accessed. The default of 120 determines that a session remains valid until 2 hours after the last time the user accesses a database through EZproxy. MAXLIFETIME is the only setting that is position dependent in ezproxy.cfg. In normal use, it should appear before the first TITLE line.
(MS) MaxSessions, default 500
MAXSESSIONS determines the maximum number of EZproxy sessions that can exists concurrently. A user's session is created during login and ends after MAXLIFETIME minutes of inactivity (default 2 hours) have occurred or when the user accesses a URL like "http://ezproxy.yourlib.org:2048/logout" to explicitly logout.
(MV) MaxVirtualHosts, default 200
MAXVIRTUALHOSTS determines the maximum number of virtual web servers that EZproxy can create. A virtual web server represents a single host name/port combination. For example, if EZproxy assigns port 2050 to www.somedb.com, 2051 to www.somedb.com:180, and 2052 to www.otherdb.com, these three ports represent three virtual hosts. In normal use, increase this parameter by no more than 50 - 100 each time, as it provides a safe guard against configuration errors in ezproxy.cfg that might lead to the creation of excessive, unneeded virtual hosts. 2048-2248 is the default port range used by EZproxy with the default MV value of 200; if ezproxy.cfg is edited to say: MV 300 (which would allow 300 ports instead of 200, the new port ranges would be 2048 - 2348.
(P) Proxy Server
Specifies the proxy server and port number (proxy:port) that EZproxy must run through to gain access to external resources.
e.g. "P proxy.yourlib.org:8000" - Specifies to use the proxy server 'proxy.yourlib.org' on port 8000
UsageLimit
See UsageLimit.
Database definitions
(T) Title
The TITLE line usually must appear first. An exception is where it is preceded by the line:
Option DomainCookieOnly
TITLE must be followed by a textual description of the database. The description entered here appears in the default menu page.
(U) URL
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.
(D) Domain
DOMAIN lines appear after the URL line. 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.
Simple example
A simple entry for a new website to proxy would be:
T My Database Name U http://www.somedb.com/db1 D somedb.com
(H) HOST
HOST lines appear after the URL line. A HOST line indicates that any URL containing the specified host name should be proxied by EZproxy. There are only certain times when a HOST line needs to be specified. Here is one example:
A problem arises with the typical example above if "somedb.com" introduces another new URL such as http://find.somedb.com/. 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/
EZproxy will generate an error indicating that you must add this line to ezproxy.cfg:
HOST find.somedb.com
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 your 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.
(HJ) HostJavaScript and (DJ) DomainJavaScript
The "J" variants of HOST and DOMAIN act the same as the "non-J" variants, except that EZproxy looks for URLs within JavaScript and rewrites them. With the "non-J" directives, EZproxy only rewrites URLs found in tags like <A HREF=...>.
Note: When EZproxy matches a host name up against ezproxy.cfg, the first database definition that matches defines the behavior for hosts. So if there was a simple "D somedb.com" earlier in the file than "DJ somedb.com", this would result in EZproxy not performing JavaScript processing on host names ending in somedb.com.
Username/password authentication
(V) Validate (HTTP Basic authentication)
The Validate line contains the username & password required by a remote web site which uses HTTP Basic browser authentication. In HTTP Basic authentication, the remote web server sends an HTTP status code of 401 causing the browser to present a small login window. The Validate line should be between the Title and URL lines, e.g.
T Chronicle of Higher Education V me:secret U http://chronicle.com/daily
This sends the user name 'me' and the password 'secret' (examples only) in the initial request to the remote server, avoiding the appearance of the login window and avoiding the need for users to be aware of the password.
FormVariable and URL -Form (HTML forms for login)
This approach submits a username and password to sites that require password authentication via an HTML form in a web page (unlike the HTTP Basic authentication approach). Employing this type of database definition requires a bit of HTML knowledge.
The username and password are not secure, although they are not usually obvious to the user. This is a method for automating login, not a security feature.
You'll need to view the login page source of the site you are configuring to get the following bits of information:
(1) the URL of the page that the form is actually processed by and the method it uses (get or post) <form action="theForUrl/here.htm" method="get|post">
(2) determine the necessary form variable keys you must pass to that form - this can be a bit of trial and error. You can just pass every single input, hidden or otherwise, but it's generally easier to start with what seems like the minimum and then add other variables as needed. Minimally, this would be a set like: <input name="somethinglikelogin"> <input name="somethinglikepassword">
Finally, you'll write up your database definition using this information, that will (minimally) be something like:
Title Old School Database
URL -Form=post osdb http://www.someDB.com/theForUrl/here.htm
FormVariable somethinglikelogin=yoursecretlogin
FormVariable somethinglikepassword=yoursecretpassword
And you'll link to the database using the format:
http://ezproxy.yourlib.edu/login/osdb
For an example, see the JAMA configuration.
