NASIG 2018 presentation by Jenny Rosenfeld

1. NASIG 2018
Beyond ‘Set it and Forget it’: Proactively
managing your EZproxy server
Jenny Rosenfeld
Sr. Implementation Program Manager, OCLC

2. Sr. Implementation Program Manager
Jenny Rosenfeld

3. What to expect this afternoon…
Time Topic
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:00-3:20 BREAK
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

4. INTRODUCTIONS

7. Why upgrade?
• Tasks in this presentation assume you are running at least
version 6.0
• Security – current version of OpenSSL
• Upgradability
• Increased Authentication Compatibility – Okta, Shib 3.x
• Community Center Access
• OCLC no longer supports 5.7.44 or below
• https://www.oclc.org/content/dam/oclc/EZproxy/ezproxy-
upgrade-flyer.pdf

11. STAFF ACCESS - TOOLS

12. The EZproxy Admin interface….Designed to be
simple to use
Access to information about:
• Security
• Usage
• Configuration
• Monitoring
• Testing
in one place and
without needing to access
raw server logs

13. Admin access to your EZproxy server
• Where is it?
– Just add /admin to the end of your EZproxy base URL:
https://EZproxy.yourlib.edu/admin
• Your normal account probably does not provide access
• Setting up access varies based on authentication method
• https://www.oclc.org/support/services/EZproxy/documenta
tion/url/admin.en.html

14. What does it look
like?

15. Audit Logs
• 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?

16. Audit Logs – do you have them?
• Not configured by default on EZproxy
• How to tell quickly?
• Admin page: View audit events

17. 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)
– Considerations:
• How often will you check these/need to check?
• Do you have a lot of usage and/or are you concerned about disk
space?

18. More information
• Admin page:
https://www.oclc.org/support/services/EZproxy/documenta
tion/url/admin.en.html
• Audit Logs:
https://www.oclc.org/support/services/EZproxy/documenta
tion/cfg/audit.en.html

19. MANAGING CONFIG.TXT -
STANZAS

20. Database Stanzas – Crash Course!
Basic Components:
Title (T)
URL (U)
Host (H)
HostJavascript (HJ)
Domain (D)
DomainJavascript (DJ)

21. Example Very Basic Stanza - Correct
Title A very important science journal
URL http://www.vipsj.com
DJ vipsj.com
Starting point URL for this resource:
http://EZproxy.yourlibrary.edu/login?url=http://www.vipsj.com

22. Example Very Basic Stanza - Incorrect
Title A very important science journal
URL http://www.vipsj.com
H www.vipsj.com
HJ www.vipsj.com
D vipsj.com
DJ vipsj.com
What’s wrong here?

23. Adding a new stanza
Start with:
Title
URL
Domain
But, look around
the website to
check URLs:
http://musicstudies.org
http://musicstudies.org/about
http://musicstudies.org/all-issues
http://musicstudies.org/interdisciplinarity

24. Resulting stanza
Title Journal of Interdisciplinary Music Studies
URL http://musicstudies.org
DJ musicstudies.org
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)

25. 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
returns)
• 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

26. Target URL (U)
URL http://musicstudies.org
• 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
port number

27. Host (H) or Host JavaScript (HJ)
• 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
different hosts:
• http://americanindian.abc-clio.com
• http://ancienthistory.abc-clio.com
• http://worldatwar.abc-clio.com

28. Domain (D) or Domain JavaScript (DJ)
DJ musicstudies.org
• Does not use http:// or https://
• If the domain uses JavaScript, use DJ
• A DJ statement allows for javascript processing for all hosts on that
domain
• No need for both D and DJ for same domain

29. CONFIG.TXT BEST PRACTICES

30. Stanza formatting
• EZproxy reads the config.txt from top to bottom
• Host and Domain (or HJ and DJ) statements are not position-dependent (within a
stanza)
• 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

31. Repetitive Stanzas
• 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
URL http://search.ebscohost.com
DJ ebscohost.com
• 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?

32. Repetitive Stanzas, Part 2
Answer: No, you do not need to add an additional stanza.
Why not?
• User clicks on one of the starting point URLs
– https://yourlib.idm.oclc.org/login?url=http://search.ebscohost.com/login.aspx?authtype=ip,uid&profile=ehost&def
aultdb=aph OR
– https://yourlib.idm.oclc.org/login?url=http://search.ebscohost.com/login.aspx?authtype=ip,uid&profile=ehost&def
aultdb=bth
• 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)
URL http://search.ebscohost.com
DJ ebscohost.com

33. 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

34. “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

35. 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
information.
– 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.

36. 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
directive:
– (ExcludeIP, AutoLoginIP, or IncludeIP)
– Easier debugging/troubleshooting if issues arise

37. EZPROXY COMMUNITY CENTER

38. 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,
tips

40. 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
screen

41. Or, request access
Requires a current subscription
(to either self-hosted or OCLC-
hosted EZproxy)

42. What’s in the Community Center?

43. USING THE ADMIN INTERFACE

44. 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?

45. 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

46. Do I have a certificate installed?

47. See the list of certs
available in EZproxy’s
ssl directory
See details of your active
certificate.

48. How many people are logged in?

49. Where are my users logging in from?
• If you have Location configured, Server Status will also
show location based on IP from MaxMind
• https://www.oclc.org/support/services/EZproxy/documenta
tion/cfg/location.en.html
• Will show in audit logs as well
• Helpful to spot atypical usage patterns

50. 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)

51. Did EZproxy start up ok?
• You can access the messages.txt from the admin page
• Includes information about any errors on start up or
shutdown
• Indicates other issues:
– any syntax errors in config
– Hosts to which EZproxy cannot connect
– Intrusion attempts

53. 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

54. IMPROVING ACCESS FOR USERS

55. Major Issues and how can you help
• Needhost errors
• Login failures
• Keeping stanzas up to date

56. Needhost errors
• User is trying to access a URL not configured for access

57. Customize your needhost.htm page
• Brand the page to match your library website or at least to match other
EZproxy pages
• 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.

58. 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?

59. Search the day’s logs from admin page

61. Login Failures
• 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?

62. View Audit Events

64. Keep your stanzas up to date
• https://www.oclc.org/support/services/EZproxy/documentation/db.en.ht
ml
• 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
URL http://www.somedatabase.com
HJ https://www.somedatabase.com
DJ somedatabase.com

65. Hosted EZproxy Survey
Why do some Hosted EZproxy libraries have EZproxy servers with
very low use (even when controlling for user population, type of
library, etc.)?

67. 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?

68. Clear login instructions

69. UIWTX: A CASE STUDY

70. Thanks to….
Michael Peters, University of the Incarnate Word

71. UIW EZproxy Login
Looks pretty easy and straightforward, doesn’t it……

72. 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……

73. Username Issues
We added a clarification to our EZProxy login screen noting that they should
enter only their username, not their whole email address:

74. Misunderstanding Authentication
We created an informational page, “Accessing Library E-Resources Using
EZProxy”, that includes the following:

75. Links Lacking EZproxy Prefixes
We created an informational page just for faculty, “Using Proxy Links for Library
E-Resources”, that includes the following:

76. Improvements, but….
• Loginbu.htm had never been updated
• OCLC noticed it had not been given the same instructions
as login.htm

78. So…..
• UIW edited the loginbu page to provide login instructions
• What happened then????

79. University of the Incarnate Word
2017
MARCH
Users entered their
institution email 353
times and failed to
log in
2017
JULY
UIW updates their
login page to include
a NOTE about the
correct username
2017
OCTOBER
Users entered their
institution email 208
times and failed to
log in, a
41% decrease
2018
FEBRUARY
UIW updates
loginbu page to
include the same
note as the login
page
2018
MARCH
Users entered their
institution email 83
times and failed to
log in, a 76%
decrease

80. SECURITY ISSUES

81. Proactive and Reactive approaches
• Proactive
– add UsageLimit Global to monitor usage patterns
– Consider turning on enforce
https://www.oclc.org/support/services/EZproxy/documentation/cfg/
usagelimit.en.html
– Monitor your login failures and locations of those failures
• Reactive
– A vendor contacts you and shuts off your access because of
excessive usage

82. VENDOR-FLAGGED USAGE

83. • They may have already shut off your library’s access to
their resource
• 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…..

84. • Will look very different from EZproxy logs
Vendor logs

85. • Date/time stamp
• Identify a searchable characteristic
What to look for in vendor log

86. • Use the ezplog file from the date you identified in the
vendor log.
• Grep or search that log for your identifying text
• Make sure the time stamp is an approximate match
• Make note of the session ID
66.162.36.106 - f31cUjTZNKauIQu [02/Nov/2015:21:23:18 -0500] "GET
http://onlinelibrary.wiley.com:80/doi/10.1002/pbfchkn.20815/pdf
HTTP/1.1" 404 13113
• Must be using Option LogSession (or Option LogUser)
along with %u as part of your LogFormat
Search the EZplogs

87. • 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

88. Admin interface

89. • 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.)

90. • 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.)

91. • 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
and dates.
• Record all usernames you find.
Identifying more users

92. • Go back to your main admin page and select “View
server status.”
• 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

93. What to do next – Terminate sessions

94. • 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
institutional resources
• 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

95. • Account may belong to a faculty member or researcher
who may legitimately need high volume access to the
resource
• Refer to license agreements for access terms
• If a vendor has flagged this usage, it most likely violates
these terms.
• You may still need to temporarily block user to satisfy
vendor
• Reach out to user to determine methods of access
What if the account is not compromised?

96. • 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
Usage Limits

97. MONTHLY ROUTINE

98. For troubleshooting access issues, security issues,
monitoring usage
• Search audit logs for Login.Failure
• Monitor usage patterns with UsageLimit (add enforce as
necessary)
• Review needhost errors (ezplogs on admin page)
• Monitor the database stanza page for updates – sort by
date added/changed and incorporate necessary changes
monthly
• Use best practices when maintaining your config.txt file

99. Resources
• Community Center
• Roundtable presentations
• Doc on Admin page
• Open Access doaj script

100. VIRTUAL Q&A CHAT WITH DON HAMPARIAN
AND THE OCLC EZPROXY TEAM

101. Back in Dublin, Ohio……
Don,
Hank,
Jimmy,
Susan

102. Thank you!
Jenny Rosenfeld
Senior Implementation Program Manager, OCLC
rosenfej@oclc.org