EZproxyv6.2.2ReleaseNotes
ReleaseDate:November2016
Lastupdated:December15,2016
TableofContents
OperatingSystemRequirements.......................................................................................................2
RecommendedActions.......................................................................................................................2
ReleaseNotes.....................................................................................................................................3
AdministrativeUpdates................................................................................................................................3
MoreGranularPermissionsforEZproxyAdministration..........................................................................3
SessionandVirtualHostDetailsLoggedatStartup..................................................................................5
LibraryVersionsDisplayonAboutPage...................................................................................................5
EZproxyNowUseszlib1.2.8.....................................................................................................................5
AuthenticationUpdates...............................................................................................................................6
::ReloginSupportAddedforShibboleth...................................................................................................6
SupportAddedforAuthenticationviaShibbolethV3.x............................................................................6
SupportAddedforMultipleShibbolethCertificates.................................................................................6
IIIUsernameCharacterLimitIncreased...................................................................................................7
ConfigurationUpdates.................................................................................................................................7
AJAXHeadersProcessedbyDefault.........................................................................................................7
SecurityUpdates..........................................................................................................................................7
EZproxyNowUsesOpenSSL1.0.2j...........................................................................................................7
SupportforLoadBalancerSSLManagement...........................................................................................7
StopLogging“HTTPoverHTTPS”UnlessDebuggingEnabled.................................................................8
BugFixes.......................................................................................................................................................8
CASRequestsIncluding“renew=true”HandledProperly.........................................................................8
ImprovedPerformanceforSAMLMetadataRetrieval.............................................................................9
OptionAcceptX-Forwarded-ForHandlesIPAddresseswithTrailingSpaces............................................9
EZproxyReportsInvalidObscureLDAPPasswords..................................................................................9
ebrarySiteCorrectlySpecifiesDefaultPort..............................................................................................9
StatusPageViewofSessionVariables.....................................................................................................9
LoginUserCanNowBeSettoEmptyString............................................................................................9
ImportantLinks.................................................................................................................................10
OperatingSystemRequirements
EZproxyissupportedunderthreedifferentoperatingsystems:
• Linux
• Solaris(x86)
• Windows
Thesupportedversionsoftheseoperatingsystemsalongwiththeirminimumhardware
requirementscanbefoundatEZproxy:HardwareandOperatingSystemRequirements.
RecommendedActions
Forthisrelease,werecommendthatyoureviewthefollowingchecklistsandcompletethe
relevanttasks.Thesechecklistsidentifyupdatesthatwehavedeterminedassignificantfor
mostinstitutions.Weencourageyoutoreviewalloftheitemsinthereleasenotesto
determinewhetherthereareotheritemsthatmightrequireadditionalactionorfollowupby
yourinstitution.
Action
❏ IfyouareupgradingfromanEZproxyversionearlierthanV6.0,youwillneedtorequest
anEZproxyWebServicesKey(WSKey).TorequestaWSKey,youwillneedtohavea
current,annualsubscription.EZproxymovedtotheannualsubscriptionmodelinJuly
2013,soifyoupurchasedyourEZproxysubscriptionpriortothattime,youwillneedto
update.
Topurchaseanannualsubscription,youcanrequestaquote,andyouwillbeprovided
withaquoteandinformationabouthowtosubscribe.Ifyouareuncertainifyour
subscriptioniscurrent,[email protected].
IfyouhavealreadyupgradedtoV6.x,yourexistingWSKeywillworkwiththisupgrade.
❏ ReviewEZproxyandOpenSSL,especiallyifyouareupgradingfromaversionolderthan
V5.7.44.EZproxyV6.2.xhasmanysecurityupdatesthatmaymakeprevious
configurationsinyourconfig.txtfileunnecessary,andyoucanremovecertain
directivesafterinstallingV6.2.x.
ReleaseNotes
AdministrativeUpdates
MoreGranularPermissionsforEZproxyAdministration(JIRA1605)
Previously,theEZproxyAdministrationfeatureswerean(almost)allornothingpropositionin
whichuserseitherhadtotaladministrativeprivilegeornone.Theonlyexceptionwasthe
abilitytogiveusersaccesstotheTokencross-referencefeature.
ThemajorityofoptionsontheAdministrationpagecannowbegrantedtousersindividuallyby
assigningthemtospecialgroups.Whensettingupthistypeofaccess,thehistoricalAdmin
commandisnolongerused,butinsteadusersareplacedintospecialgroupsthatcorrespondto
theURLovertheAdminfeature.Forexample,theAuditpageisavailablefrom/audit,sothe
groupthatgrantsaccesstothisisAdmin.Audit.
Thegroupsavailableare:
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
Admin.Audit
Admin.DecryptVar
Admin.Groups
Admin.Intrusion
Admin.LDAP
Admin.Messages
Admin.Restart
Admin.Shibboleth
Admin.SSLUpdate
Admin.SSLView
Admin.StatusUpdate
Admin.StatusView
Admin.Token
Admin.Usage
Admin.UsageLimits
Admin.User
Admin.Variables
The/adminpageautomaticallyadjustsbasedongroupmembershiptodisplaytheoptionsthat
correspondtothesegroupmemberships.
TheSSLandStatuspageshavetheabilitytochangekeyaspectsofEZproxy’sbehavior,sothese
featureshavebeendividedintoUpdateandViewgroups.UsersintheUpdategrouphavethe
fullfunctionalityavailableinpreviousversions,whereasusersintheViewgroupareonlyable
toviewinformationonthesepages.
UserswhoarefulladministratorsthroughtheclassicAdmincommandorwhohavethe
Admin.Groupsprivilegecanseealistofallofthesegroupsatthe/groupsURL.
Adminusersareassignedtothesegroupsviauser.txt.Theycannotbeusedwithinconfig.txt.
Donotassignindividualstogroupsasfollows:
someuser:somepass:group=Admin.StatusView
Theaboveentryisequivalentto:
::group=Admin.StatusView
someuser:somepass
whichtellsEZproxythatallusersfromthatpointforwardshouldbeassignedintothe
Admin.StatusViewgroup.
Instead,adduserstogroupsfollowingthisexample:
::group=+Admin.StatusView
someuser:somepass
otheruser:otherpass
::group=-Admin.StatusView
ThiswouldassignbothsomeuserandotheruserintotheStatusViewgroupinaddition
toanyothergroupsalreadysetup,whileensuringthatuserswhofollowwillnotbeinthis
specialgroup.
WithinanauthenticationmethodsuchasLDAP,sampleusagewouldbe:
::LDAP
BindUser CN=ezproxy,CN=users,DC=yourlib,DC=org
BindPassword verysecret
URL ldap://ldapserv.yourlib.org/CN=users,DC=yourlib,DC=org?
sAMAccountName?sub?(objectClass=person)
IfUnauthenticated; Stop
IfUser jdoe; Group +Admin.StatusView
/LDAP
inwhichspecificusersareidentifiedandhavethespecialgroupenabled.
Wheninitiallydeployinggroups,OCLCrecommendsusing:
Audit Most Login.Success.Groups
ThistellsEZproxy’sAuditfeaturetoincludethegroupstowhichauserisassignedintheOther
column,makingiteasytodetermineifusersarebeingassignedtotheexpectedgroups.
ThisenhancementoriginatedviatheOCLCCommunityCenter.Formoreinformation,see
AdminUsers.
SessionandVirtualHostDetailsLoggedatStartup(JIRA1530)
WhenEZproxystartsup,itwilllogthevalueforMaxSessionsandMaxVirtualHoststo
messages.txt.Ifeitherorbothoftheseareattheirlimits,awarningwillbeloggedto
messages.txtaboutthisaswell.Thefollowingmessagesarelogged:
Startupwithvaluesatdefault:
2016-07-14 09:35:01 MaxVirtualHosts set to default 200
2016-07-14 09:35:01 MaxSessions set to default 500
Startupwithvaluesoverridden:
2016-07-14 09:30:18 MaxVirtualHost (MV) changed from 200 to 400
2016-07-14 09:30:18 MaxSessions (MS) changed from 500 to 1000
Startupwhenthemaximumnumberofsessionsorvirtualhostsalreadyexists:
2016-07-14 09:30:19 WARNING: All 200 virtual hosts are active;
MaxVirtualHosts may need to be increased
2016-07-14 09:30:19 WARNING: All 500 sessions are active;
MaxSessions may need to be increased
Formoreinformation,seeMaxVirtualHosts(MV).InformationaboutMaxSessionsisavailablein
theEZproxyReferenceManual.
LibraryVersionsDisplayonAboutPage(JIRA1568)
Tomakeiteasierforuserstodeterminewhatcodelibraryversionsareusedbyaspecific
versionofEZproxy,theadministrative/aboutpagewillnowshowthelibraryversionscompiled
intoEZproxy.
EZproxyNowUseszlib1.2.8(JIRA1607)
EZproxynowusesversion1.2.8ofthezliblibraryforcompressionanddecompression.This
versionmadeavailableseveralbugfixesandotherimprovements.
AuthenticationUpdates
::ReloginSupportAddedforShibboleth(JIRA905)
PreviousversionsofEZproxydidnotsupportanequivalenttotheuser.txt::Relogin
directive,whichforcesuserstore-authenticateafteracertainnumberofminutes,for
Shibbolethauthentication.Supportforthisfunctionhasbeenadded.Forexample,addingthe
followingDirectivetouser.txt:
Relogin 120
toshibuser.txtwillnowforceusersauthenticatedviaShibbolethtore-entertheircredentials
aftertwohours.
SupportAddedforAuthenticationviaShibbolethV3.x(JIRA1478)
EZproxynowsupportsauthenticationviaShibbolethV3.x.Formoreinformation,see
Shibboleth.
SupportAddedforMultipleShibbolethCertificates(JIRA836)
InaShibbolethconfiguration,EZproxyactsasaServiceProvider(SP).ItiscommonforanSPto
havemultiplesigningand/orencryptioncertificatesassociatedwithit,especiallywhen
transitioningfromanoldcertificatetoanewone.AsingleEZproxyserverwaspreviously
incapableofrecognizingandsupportingtwocertificatesatthesametime;itnowcanwiththis
update.
Intheconfig.txtShibbolethMetadatadirective,toassociatemorethanonecertificate
withtheEZproxyserver,providealistofcertificatenumbersfromthe/ssladministrativepage,
separatedbycommas,suchas:
ShibbolethMetadata \ -EntityID=https://ezproxy.yourlib.org/sp \ -File=metadata.xml \ -Cert=1,2
ThedetailsontheManageShibbolethadministrativepagehavebeenslightlyreorganizedand
includeanewoption(“EZproxyMetadata”)whichdisplaysthecompleteShibbolethmetadata
fortheEZproxyserver,includingmultiplecertificateswhentheyareinuse.
Formoreinformation,seeShibbolethAuthentication.
IIIUsernameCharacterLimitIncreased(JIRA1339)
PreviousversionsofEZproxyimposeda20characterlimitontheusernameforsitesusingIII
authentication.Thislimithasbeenincreasedto128characters,butcanbereducedifneeded.
Formoreinformation,seeIIIAuthentication.
ConfigurationUpdates
AJAXHeadersProcessedbyDefault(JIRA1445)
DuetothegrowingpopularityofAJAX,EZproxynowprocessesAJAXHTTPheadersbydefault.
Inotherwords,thefollowingHTTPHeaderDirectivenolongerneedstobedeclaredexplicitlyin
config.txt:
HTTPHeader X-JSON
AJAXheaderscanstillbeblockedforindividualresources.Formoreinformation,see
HTTPHeader.
SecurityUpdates
EZproxyNowUsesOpenSSL1.0.2j(JIRA1626)
EZproxy6.2.2wasbuiltwithOpenSSL1.0.2j,whichwasreleasedonSeptember26,2016.
OpenSSL1.0.2jaddressedvulnerabilitiesandbugfixesfrompreviousversionsofOpenSSL.
Formoreinformation,seeEZproxy&OpenSSL.
SupportforLoadBalancerSSLManagement(JIRA1599)
SomeloadbalancersdecryptSSLclientrequestsbeforeforwardingthemtoEZproxy.Previous
versionsofEZproxyrequiredtheloadbalancertore-encryptthecontentbeforeforwardingitto
EZproxy.Itisnowpossibletodeclarethataportwilllistenusinghttpeventhoughitshouldbe
consideredanSSLrequestbyaddingtheoption-httptoLoginPortSSLsuchas:
LoginPortSSL -http 443
Whenusingthissyntax,EZproxydoesnotknowwhetherornottheloadbalancerispresenting
aproperwildcardcertificate(suchas*.followedbythenameoftheEZproxyserver).Theuser
mustexplicitlyindicatethetypeofcertificateusedontheloadbalancerbyspecifyingoneof
thefollowingDirectives:
Option ForceWildcardCertificate
Option IgnoreWildcardCertificate
inconfig.txtbeforetheLoginPortSSL-httpdirective.
Inthemostadvancedscenario,aloadbalancermaybereceivinghttprequestsforEZproxyon
port80andhttpsrequestsonport443usingaproperwildcardcertificatewithproxyby
hostname,butitmayalsoremapthoserequeststoport8080forhttpand8081forhttpsusing
http.Inthisscenario,anappropriateconfigurationmaybe:
Name ezproxy.yourlib.org
Option ProxyByHostname
Option ForceWildcardCertificate
LoginPort -virtual 80
LoginPortSSL -virtual 443
LoginPort 8080
LoginPortSSL -http 8081
StopLogging“HTTPoverHTTPS”UnlessDebuggingEnabled(JIRA1122)
WhenSSLsupportwasfirstaddedtoEZproxy,thefollowingdiagnosticmessagewasloggedto
messages.txt:
HTTP over HTTPS
wheneverEZproxyreceivedarequestforhttptrafficonaportconfiguredforhttps.Thereisno
needtoconstantlylogtheseconnectionerrors,sothisfunctionalityhasbeendisabledunless
thefollowingDirectiveisaddedtoconfig.txt:
DebugLevel 1
BugFixes
CASRequestsIncluding“renew=true”HandledProperly(JIRA1622)
TheCASauthenticationprotocolsupportsa"renew"requestparameter,which,whensetto
“true”,forcestheusertore-authenticate.Whenthisoptionwasincluded,previousversionsof
EZproxyenteredanendlessloop,forcingtheusertoauthenticateoverandover.Thishasbeen
corrected.
ImprovedPerformanceforSAMLMetadataRetrieval(JIRA1620)
SomesitesreportedperformanceproblemswhenEZproxyattemptedtoretrievelargeSAML
metadatafilesfromidentityfederations.Theproblemwascausedbyinadvertentparallel
processingofmultiplerequestsforthesefiles.Thishasbeencorrected.
OptionAcceptX-Forwarded-ForHandlesIPAddresseswithTrailingSpaces(JIRA1608)
EZproxy6.0introducedabuginwhich,ifOptionAcceptX-Forwarded-Forisactive,IPaddresses
inincomingX-Forwarded-Forheaderswereignoredwhenfollowedbytrailingspaces.Thishas
beencorrected.
EZproxyReportsInvalidObscureLDAPPasswords(JIRA1582)
InLDAP,ifBindPassword-Obscureisspecifiedwithapasswordthatisnotavalid,obscure
password,previousversionsofEZproxycrashedinsteadofreportingtheissues.Thishasbeen
corrected.
ebrarySiteCorrectlySpecifiesDefaultPort(JIRA1578)
EZproxy6.0stoppedprovidingthecorrectdefaultportfortheebrarySite-URLoption,causinga
“connectionrefused”errortooccurunlesstherequiredportappearedexplicitlyintheprovided
URL.Thishasbeencorrected.Itisnolongernecessarytospecifythedefaulthttpport(80),asin
theexamplebelow:
ebrarySite -URL=http://ebookcentral.proquest.com:80 sitecode
StatusPageViewofSessionVariables(JIRA1198)
FromtheEZproxy/statuspage,thereisalinktoviewdetailsofeachsession,andfromthe
sessiondetails,thereisalinktoviewthesessionvariablesforthatsession.Whenthisoption
wasselected,previousversionsofEZproxyshowedthesessionvariablesoftheuserwhois
loggedininsteadoftheuserwhosesessionwasselected.Thishasbeencorrected.
LoginUserCanNowBeSettoEmptyString(JIRA904)
Inuser.txt,itispossibletooverridethevalueoftheuserfieldfromtheloginformusingthe
login:uservariable.Ifthisvaluewassettotheemptystring(""),previousversionsof
EZproxywouldcrash.Thishasbeencorrected.
ForsitesusingShibbolethauthentication,settinglogin:usertotheemptystringin
shibuser.txtsimilarlyledtoundesirableresults.Thisvaluenowdefaultsto“shibboleth”andcan
bechangedtoanyothervaluebesidestheemptystring.
ImportantLinks
Productwebsite
Moreproductinformationcanbefoundat:https://www.oclc.org/ezproxy.en.html
Supportwebsites
Supportinformationforthisproductandrelatedproductscanbefoundat:
• Documentation:http://www.oclc.org/support/services/ezproxy.en.html
• Releasenotes:http://www.oclc.org/support/services/ezproxy/release-notes.en.html
©2016OCLC,Inc.Allrightsreserved.ThefollowingOCLCproduct,serviceandbusinessnamesaretrademarksorservicemarks
ofOCLC,Inc.:OCLC,WorldCat,WorldShareand“Becausewhatisknownmustbeshared.”Inaddition,theWorldCatand
WorldSharesymbolsareservicemarksofOCLC.Third-partyproductservicenamesaretrademarksorservicemarksoftheir
respectiveowners.OCLCgrantspermissiontophotocopythispublicationasneeded.