Location
Knowing your users' locations can be valuable when you are examining the security of your EZproxy, and the location directive allows you to both audit and then enforce security settings based on your user location.
From an auditing standpoint, including the location directive and recording that information in the audit logs allows you to easily identify where your patrons are located when they access EZproxy. If a content provider contacts you asking about problem accounts, having this additional information in the audit logs can be one piece of data to help you determine if a particular user's use of EZproxy is legitimate or if that person's account credentials have been compromised. If you know a particular user would not be in a particular location, but their credentials are being used to log in to EZproxy from an unlikely location, you can identify that account as a potential security threat and look into its use in more detail. While location alone might not provide you with enough information to determine whether a particular user account has been compromised, it can be a starting point for further investigation.
In addition to serving as a tool to evaluate security, the location directive is also an important tool in enforcing security. Many security directives such as Option BlockCountryChange and conditions such as IfRegion, IfCountry, and IfCity rely on the data accompanying Location to block users based on location. This directive also allows you to create exceptions to these rules when you have users who fall outside of these broad security settings.
Location is a position-dependent config.txt directive that must appear after any directives, such as Audit and audit-related directives, that must reference the information from this directive. Location associates IP addresses with geographic locations and records that information in your audit log. EZproxy can read IP address/geographic information when it is saved in the form of a zipped GeoLite file containing a list of IP addresses/geographies, or it can read individual Location directive statements with IP addresses or ranges that you have manually associated with a specific location. Manually specified IP address location information always overrides the data found in the GeoLite city data.
In addition to recording your users’ IP addresses and locations in the audit log, Location is also used as a resource EZproxy checks when carrying out other location-specific, security-related actions as specified by additional directives in your config.txt or user.txt file. The following directives or conditions require the Location directive to be included in config.txt because they reference the IP addresses/geographic locations specified in the directive when commanding EZproxy to perform certain actions:
Option BlockCountryChange IfCity IfCountry IfRegion
These directives require the typical Location configuration required to record data to the Audit logs. For more details about how these directives interact with Location, click on the directive or condition you are interested in learning about.
Defining Location
IP address and geographic location can be collected from the Location directive in several different ways, outlined below.
GeoLite Data
EZproxy is licensed to include support for GeoLite City data created by MaxMind, available from www.maxmind.com. This data provides country of origin information for IP addresses worldwide. When this file has been downloaded and added to your config.txt file, your audit logs will record IP address and country of origin information for all users who access resources through EZproxy. This data can also be used to enforce security settings using the directives and conditions listed above.
V6.4.4 and later
In April 2018, MaxMind discontinued support for their version 1 library and database format often referred to as GeoIP. EZproxy 6.4.4 and later added support for GeoIP2 and no longer support the legacy GeoIP files. The Location directive is still used to activate geolocation support. Typical usage now is:
Location -file=GeoLite2-City.mmdb
If an existing site updates from an earlier version that points to a version 1 file, EZproxy will report:
Location file is not a GeoIP2 mmdb file
to messages.txt, but will still startup. EZproxy does not store location information, but rather looks it up as needed, so no data will be lost in this instance. Once config.txt has been updated to point to a GeoIP2 file and restarted, everything will return to normal.
MaxMind provides access to the free version of their database file at https://dev.maxmind.com/geoip/geoip2/geolite2/ . The correct file to download is the “GeoLite2-City / GeoIP2 Binary (.mmdb)” version.
This file must be downloaded to the directory where EZproxy is installed. The file is distributed as a tar.gz file which must be expanded to access the mmdb file that EZproxy requires. For Linux, the tar command can be used to expand the file. For Windows, a utility such as 7z will be required.
When downloading updated versions of GeoLiteCity.dat.gz, it is necessary to restart EZproxy to make EZproxy load the updated file, but it is not necessary to delete GeoLiteCity.dat unless you suspect it has become corrupt.
V6.3.5 and earlier
EZproxy V6.3.5 and earlier used MaxMind's legacy data format, known as GeoIP. The GeoLite City data was updated every month and available for download from https://dev.maxmind.com/geoip/geoip2/geolite2/. This file should FIRST be downloaded to the directory where EZproxy is installed. AFTER you have saved this file in the EZproxy installation directory, add the following directive to config.txt :
Location -File=GeoLiteCity.dat.gz
EZproxy will automatically decompress this file to GeoLiteCity.dat.
When downloading updated versions of GeoLite2-City.tar.gz, it is necessary to restart EZproxy to make EZproxy load the updated file, but it is not necessary to delete GeoLite2-City.mmdb unless you suspect it has become corrupt.
Manually specifying IP information
In addition to supporting GeoLite City data, EZproxy also allows you to specify location information manually by IP address. Any IP address that matches a manual rule overrides the data found in the GeoLite City data.
This option can be helpful when you are refining the security settings listed above because even though GeoLite provides an extensive listing of IP addresses and their corresponding locations, not all IP addresses and locations are always listed. Further, if you have remote users in other countries, it may be necessary to provide specific IP address/location combinations for those users to ensure their access is not interrupted by your EZproxy security settings. For more details about when manual IP specification is necessary, see the example tab on this page or the individual pages of the directives above.
The basic format for manually specifying IP information is as follows:
Location IPStart-IPEnd Country/Region/City
where you will specify all of the information following the directive using the following formats:
| Field | Optional? | Description |
|---|---|---|
| IPStart-IPEnd | No | The individual IP address or IP range for which you would like to specify a geographic location. |
| Country | No | The country to be associated with the given IP address/range entered using two-character extended ISO 3166 cores. |
| Region | Yes | The region to be associated with the given IP address/range entered using the two-character ISO 3166-2 subcountry code for the US and Canada or the FIPS 10-4 subcountry code for other regions of the world. |
| City | Yes | The city to be associated with the given IP address/range entered using the textual name of the city. |
Private IP addresses
The most typical use of manually specifying location information is to assign geographic information for private IP addresses, such as those that start with 10, 172.16-172.31, or 192.168. This can also be helpful when refining the security settings listed above. For additional information about how and when to use this setting, see the examples tab on this page, or the individual directive listed above that you would like to include in your config.txt.
For example:
Location 192.168.0.0-192.168.255.255 US/OH/Dublin
If no manual rules are specified for private IP addresses, these addresses appear as country 98, no region, no city.
Example
The following table provides scenarios that could require you to utilize the Location directive along with others in the config.txt or user.txt. The config.txt column provides you with the directive statement to include in your config.txt or user.txt, and the Why This Works column provides details about how this configuration will help you achieve "What you want to do."
| What you want to do | config.txt directive | Why this works |
|---|---|---|
|
User Location Data You want to begin to monitor your users' remote locations when they log in to EZproxy to determine the appropriate security settings you should implement. You do not want to block legitimate users, but you would like to get a better idea of whether you can block certain geographic locations where you have no users to minimize potential security threats. |
(Include this directive in your config.txt after you have downloaded the GeoLite City data from MxMind and saved it to the directory where EZproxy is installed.) |
Including the Audit and Location directives in your config.txt will cause EZproxy to record your users' locations (IP address and the corresponding geographic location) in two columns on the audit table alongside any audit events that occur, as configured by default with the Most field. This will allow you to assess the locations of your users and determine if you can block IP addresses from certain locations that should not be accessing resources through your EZproxy. If users are accessing your resources using a private IP address, no location will be recorded for these users, only the code 98. |
|
Define a location for an IP address to allow access that would otherwise be blocked You have set conditions in your user.txt to block EZproxy access from all countries outside of the United States; however, a professor who works for your institution lives outside of the United States part time, but still needs access to your institution's resources during that time. You can find out what IP address that will be used when signing into EZproxy. |
(Where you substitute the IP address or range of IP addresses that will be used by your institution's professor when signing in out of the country, and your location information for US/OH/Dublin.) |
By assigning your professor's IP address a US location, it will appear that the user is signing in from the United States when accessing EZproxy, and will thus, not be blocked. This will allow anyone with an internet connection on this same range of IP addresses to sign in to your EZproxy if they have valid credentials, so the smaller your range, the more secure your EZproxy will be. |
|
Define locations for private IP addresses to refine Option BlockCountryChange You added the Option BlockCountryChange to your config.txt as a security measure to prevent unregistered users from gaining access to your resources using compromised credentials. However, some of your legitimate users are now having problems accessing EZproxy. You want to retain the BlockCountryChange option for security, but you want to allow these users to gain access. |
(Where you substitute a more limited range of IP addresses that your users regularly utilize and enter your location instead of US/OH/Dublin, using a country code at minimum, but adding more specific location information as you see fit.) |
If your users sign in to EZproxy with a public address in the United States and then move to an IP address with no associated country, they will be blocked from EZproxy if you do not assign United States as a location to the IP addresses being used by your users. This will happen as a result of the Option BlockCountryChange directive because there is a change in the users' location from the United States to undefined. If you add a location directive with the IP ranges over which information is transferred and assign those IPs a US location, then they will no longer be blocked when signing in from a US IP address and receiving information over a location-undefined IP address. |