Beyond 'Set it and Forget it': Proactively managing your EZproxy server
Beyond ‘Set it and Forget it’: Proactively
managing your EZproxy server
Sr. Implementation Program Manager, OCLC
Sr. Implementation Program Manager
What to expect this afternoon…
1:00-1:20 Introductions, Polls
1:20-1:30 Staff Tools for EZproxy – getting access
1:30-2:15 EZproxy management – stanzas and config
2:15-2:20 Community Center
2:20-2:40 The EZproxy Admin interface
2:40-3:00 Troubleshooting and improving user access
3:20-3:40 Hosted EZproxy user survey and a case study
3:40-4:10 Dealing with security issues
4:10-4:30 Your Monthly EZproxy routine
4:30-5:00 An update from Don Hamparian; Q&A
• Tasks in this presentation assume you are running at least
• Security – current version of OpenSSL
• Increased Authentication Compatibility – Okta, Shib 3.x
• Community Center Access
• OCLC no longer supports 5.7.44 or below
The EZproxy Admin interface….Designed to be
simple to use
Access to information about:
in one place and
without needing to access
raw server logs
Admin access to your EZproxy server
• Where is it?
– Just add /admin to the end of your EZproxy base URL:
• Your normal account probably does not provide access
• Setting up access varies based on authentication method
• Help to troubleshoot usage, security, and access issues
– Are your users having trouble logging in?
– Do you need to investigate security breaches?
– How are people using your EZproxy server?
Audit Logs – do you have them?
• Not configured by default on EZproxy
• How to tell quickly?
• Admin page: View audit events
Setting up Audit Logs….
• … is easy!
• Start by adding: Audit Most to your config.txt file
• You can also decide how long to retain them with the
directive: Audit Purge (followed by the number in days
to retain them)
• How often will you check these/need to check?
• Do you have a lot of usage and/or are you concerned about disk
• Admin page:
• Audit Logs:
Example Very Basic Stanza - Correct
Title A very important science journal
Starting point URL for this resource:
Example Very Basic Stanza - Incorrect
Title A very important science journal
What’s wrong here?
Adding a new stanza
But, look around
the website to
Title Journal of Interdisciplinary Music Studies
All other relevant links only had path ending changes
EZproxy only cares about the origin URL (and not anything
after the .com/.org, etc. – OTHER than a port number)
Breaking it down – Title (T)
Title Journal of Interdisciplinary Music Studies
• Can be whatever you want, but needs to be on one line (no carriage
• If you need to add additional info about a former title, add another line
with a pound sign: # This denotes a comment
• Title information appears on internal EZproxy menu page
Target URL (U)
• You only need to configure to the top-level URL of the resource
• Include either the http:// or https:// (and pick whichever is accurate)
• EZproxy does not care what comes after the .org here, unless it’s a
• If there are additional URLs a patron might use to initially access a
resource, use an H or HJ
– Example: American Marketing Association
• main site: https://ama.org
• archive: https://archive.ama.org
• If a database platform has different products using different hosts
– Example: ABC-CLIO databases all use the abc-clio.com domain but have
• Does not use http:// or https://
• No need for both D and DJ for same domain
• EZproxy reads the config.txt from top to bottom
• Host and Domain (or HJ and DJ) statements are not position-dependent (within a
• Most OCLC-provided stanzas have Hosts before Domains
• Title needs to come first
• Best practice to have URL second, so that you predictably know that is the URL that will
appear on the EZproxy menu page
• Only URLs or H/HJ lines are used to determine if a starting point URL can be proxied
• Before adding an additional stanza for a new resource, test first by creating an SPU.
• Example – Your library currently subscribes to Ebsco’s Academic Search Premier
Target URL: (http://search.ebscohost.com/login.aspx?authtype=ip,uid&profile=ehost&defaultdb=aph)
Your Existing Stanza:
Title Ebscohost – Academic Search Complete
• Your library adds a subscription to Business Source Complete
Target URL: (http://search.ebscohost.com/login.aspx?authtype=ip,uid&profile=ehost&defaultdb=bth)
Question: Do you need to add a new stanza?
Repetitive Stanzas, Part 2
Answer: No, you do not need to add an additional stanza.
• User clicks on one of the starting point URLs
• EZproxy reads config.txt and finds the origin in the URL directive of the Ebscohost Stanza matches
the origin of your Target URL for Business Source Premier (http://search.ebscohost.com). EZproxy
ignores the path of the URL (the part after the origin of http://search.ebscohost.com)
Title Ebscohost (Academic Search Premier)
Repetitive Stanzas, Part 3
• If you need to add a new stanza or a new host to an existing stanza, you will see the
needhost.htm page from EZproxy when testing your SPU
“Floating” Host Statements
• Adding a new HJ or Host statement at the bottom or top of config.txt every time you
receive a needhost error is unwise.
• Why is it bad when it so easily fixes your problem?
– Hosts outside of a stanza will not receive any special processing that is normally part of that resource’s stanza
– Hosts not connected to another stanza implicitly become part of the last stanza before them. All special
processing in that stanza will apply.
– EZproxy reads config.txt from top to bottom. Floating hosts can interfere with the correct processing for a
resource that might be configured further down in config.txt
– Troubleshooting database proxying problems becomes nightmarish with lots of floating hosts.
– You will need to use the EZproxy server status page from the admin login to see which stanza is controlling the
behavior of a given host/resource.
• The preferred alternative:
– If this is a new host which is part of an existing resource, add the HJ or H statement to that resource’s stanza
– If this is a new resource, create a basic stanza: Title, URL, DJ
What to do about Open-Access Titles?
• To Proxy or Not To Proxy?
• Some considerations:
– Proxying an open-access title is effectively making it NON-open access. You are creating artificial barriers to
– Creating stanzas for all open-access resources is very time-consuming and creates a bloated config.txt file.
– Many OpenURL/KB/A-Z list/Discovery Layer products will allow you to set the proxy settings at a collection
level, so you do not necessarily need to do this globally. Consider omitting the proxy prefix for these titles
• Why might you proxy these titles anyway?
– You may wish to keep usage statistics for ALL e-resources, even open-access titles
• Alternative: Use RedirectSafes instead. These accesses will show up in your SPU logs.
– You want to provide uniformity of access experience for your patrons to all library-provided content
• Alternative: Use RedirectSafes instead. Patrons will still log in via EZproxy as normal, but the proxy will
be dropped and they will continue on to the resource.
ExcludeIP, AutoLoginIP, IncludeIP
• All of these IP-related directives CAN be abbreviated as:
– E (ExcludeIP) – users from these IP addresses will not be asked to login via EZproxy and will not be logged
; vendors will see traffic as coming from the actual IP of the user (so they need to be on file)
– A (AutoLoginIP) – users from these IP addresses will not be asked to login via EZproxy but will be logged
vendors will see traffic as coming from the EZproxy server’s IP address
– I (IncludeIP) – reverses a previous Exclude or AutoLoginIP statement and forces users to login for any stanzas
following this directive
• However, best practice would be NOT to abbreviate, but to type out the full name of the
– (ExcludeIP, AutoLoginIP, or IncludeIP)
– Easier debugging/troubleshooting if issues arise
Community Center Access
• http://oc.lc/community if you have a WorldShare login
• http://oc.lc/ezpcommunity to request access
• Requires a paid annual subscription (self-hosted or hosted)
• Discussions, product release information, news, presentations,
First time accessing –
Search for your
institution by symbol,
name, or zip code.
After selecting your
Library, you will be
directed to your
WorldShare sign on
Or, request access
Requires a current subscription
(to either self-hosted or OCLC-
Questions you can answer
• What version of EZproxy am I using?
• Do I have a cert for EZproxy?
• How many people are logged in right now? And who?
• Where are my users logging in from geographically?
• How much data are my users transferring?
• Did EZproxy start up OK?
• Does my config.txt file have any bad errors or conflicts?
What version of EZproxy am I using?
This displays at the top of the EZproxy administration page
You can also see if you have a Windows, Linux, or Solaris installation
Where are my users logging in from?
• If you have Location configured, Server Status will also
show location based on IP from MaxMind
• Will show in audit logs as well
• Helpful to spot atypical usage patterns
How much data are my users transferring?
You can also sort by number of transfers or by
amount of data transferred to look for users
with anomalously high usage
(Requires UsageLimit Global)
Did EZproxy start up ok?
• You can access the messages.txt from the admin page
• Includes information about any errors on start up or
• Indicates other issues:
– any syntax errors in config
– Hosts to which EZproxy cannot connect
– Intrusion attempts
Does my config file have any bad errors or conflicts?
• Messages.txt will show major problems
• You can also check database conflicts
– Proxying of a particular resource is not working as expected when
you are relatively sure it is configured correctly
– Shows overlapping definitions that might lead to bad behavior
– Good tool for cleaning up your config.txt file – consolidate stanzas
Major Issues and how can you help
• Needhost errors
• Login failures
• Keeping stanzas up to date
• User is trying to access a URL not configured for access
Customize your needhost.htm page
• Brand the page to match your library website or at least to match other
• Make the wording on the page meaningful to your users
• Customize the html to include a link to allow the patrons to click and
send you an email
Duggan, L., Lamb, C., & Light, R. (2018). Being earnest with collections - improving access
to electronic collections through enhanced staffing. Against the Grain, 30(2), 56-57.
Still….. Patrons may not tell you
• Search your ezplogs (also from admin page) for 599 error
codes (599 = need host error)
• Look at URLs attempting to be accessed
– Do you need a new stanza or additional host in a stanza?
– Are users using a poorly formed URL?
– Is there an out of date link to a resource on your website?
• Cannot see from EZproxy if you have an auth method that
redirects (SAML, CAS, CGI)
• In Audit Logs – recorded as Login.Failure
• Search them on a regular basis to identify patterns:
– Is the same user attempting and failing to log in repeatedly?
– Is the same user trying to log in from many different IP addresses?
– Are all of the login failures entering usernames in the wrong format?
Keep your stanzas up to date
• Look for a format change to this page coming soon!
• Check the above page first for new resources you add
• If a resource moves to https from http, add an HJ statement to cover
the new https host (or vice versa), e.g.,
Title Newly Secure Database
Hosted EZproxy Survey
Why do some Hosted EZproxy libraries have EZproxy servers with
very low use (even when controlling for user population, type of
What did we learn?
• We decided to look at login failures
• How would we troubleshoot based on these?
– Audit Logs
• look at sites with high failure rates
• What are the users doing wrong?
• What kind of information is the library providing users to help?
Access Issues for Remote Users
We found that students were:
1) entering their entire email address in the username field, not just their UIW
username, which is the first part of their email address.
2) assuming they were logged in for access to library resources because they
had signed into UIW’s Blackboard, MyWord student portal, or Cardinal Mail.
3) following standalone links to databases or individual e-resources provided by
faculty that did not include UIW’s unique EZProxy prefix.
Here’s what we did……
We added a clarification to our EZProxy login screen noting that they should
enter only their username, not their whole email address:
We created an informational page, “Accessing Library E-Resources Using
EZProxy”, that includes the following:
Links Lacking EZproxy Prefixes
We created an informational page just for faculty, “Using Proxy Links for Library
E-Resources”, that includes the following:
• Loginbu.htm had never been updated
• OCLC noticed it had not been given the same instructions
• UIW edited the loginbu page to provide login instructions
• What happened then????
University of the Incarnate Word
Users entered their
institution email 353
times and failed to
UIW updates their
login page to include
a NOTE about the
Users entered their
institution email 208
times and failed to
log in, a
loginbu page to
include the same
note as the login
Users entered their
institution email 83
times and failed to
log in, a 76%
Proactive and Reactive approaches
– add UsageLimit Global to monitor usage patterns
– Consider turning on enforce
– Monitor your login failures and locations of those failures
– A vendor contacts you and shuts off your access because of
• They may have already shut off your library’s access to
• You may be given very little time to identify the user
• Vendor-supplied log snippets
• Date and time stamps are very important
A vendor contacts you…..
• Will look very different from EZproxy logs
• Date/time stamp
• Identify a searchable characteristic
What to look for in vendor log
• Use the ezplog file from the date you identified in the
• Grep or search that log for your identifying text
• Make sure the time stamp is an approximate match
• Make note of the session ID
126.96.36.199 - f31cUjTZNKauIQu [02/Nov/2015:21:23:18 -0500] "GET
HTTP/1.1" 404 13113
• Must be using Option LogSession (or Option LogUser)
along with %u as part of your LogFormat
Search the EZplogs
• Log in to your EZproxy admin page at:
https://EZproxy.yourlib.edu:2048/admin (substituting your
server URL and port number as needed).
• Click on the hyperlink View Audit Events under the
Current Activity heading.
Identify the user(s) in question
• Set the number of previous days to search back far
enough to cover the date in question.
• Place the Session ID into the search box.
• Select “Session” from the drop down list and search
Identify the users in question (cont.)
• Find the session in question. It should match up to the
date from the vendor’s logs.
• Identify the user associated with the session.
Identify the user(s) in question (cont.)
• Repeat this process as necessary to identify all users
associated with the flagged usage.
• It is most likely NOT necessary to search all flagged items.
Search a sampling of sessions over different time periods
• Record all usernames you find.
Identifying more users
• Go back to your main admin page and select “View
• Search all text on this page for each username to see if
there are any active sessions.
• If you find active sessions, click the sessionID of any
session associated with that user and then click
“Terminate the session.”
What to do next
• If appropriate, contact your IT department to let them know
you have a potentially compromised user account.
• Give them the username and ask that the password be
reset and that the user be blocked from accessing other
• If your IT department cannot act fast enough, you can
block usernames in user.txt.
• Authentication method-specific instructions
What to do next – follow up
• Account may belong to a faculty member or researcher
who may legitimately need high volume access to the
• Refer to license agreements for access terms
• If a vendor has flagged this usage, it most likely violates
• You may still need to temporarily block user to satisfy
• Reach out to user to determine methods of access
What if the account is not compromised?
• You can place UsageLimit Global before any database
stanzas in config.txt
• This simply allows monitoring of usage by user over the
last 24 hours.
• From the “View Usage Limits and Clear Suspensions”
link on the admin page, you can sort by MB transferred to
identify high use users
For troubleshooting access issues, security issues,
• Search audit logs for Login.Failure
• Monitor usage patterns with UsageLimit (add enforce as
• Review needhost errors (ezplogs on admin page)
• Monitor the database stanza page for updates – sort by
date added/changed and incorporate necessary changes
• Use best practices when maintaining your config.txt file
• Community Center
• Roundtable presentations
• Doc on Admin page
• Open Access doaj script
VIRTUAL Q&A CHAT WITH DON HAMPARIAN
AND THE OCLC EZPROXY TEAM
Back in Dublin, Ohio……