IpFilter¶ ↑

IpFilter is IP filtering solution for Ruby. Common use case for this is DRM. Uses a GeoIP (or Geo::IP) database to determine the request ip’s location.

Compatibility¶ ↑

• Supports Ruby version: 1.9.2

• Supports cache store: Memcache.

• Supports Rails 3.

Install¶ ↑

As a Gem¶ ↑

Add to your Gemfile:

gem "ip_filter"

and run at the command prompt:

bundle install

Or As a Plugin¶ ↑

At the command prompt:

rails plugin install git://github.com/chtrinh/ip_filter.git

Typical Rails Configuration¶ ↑

# config/initializers/ip_filter.rb

# Location of GeoIP database file.
IpFilter::Configuration.geo_ip_dat = "lib/assets/GeoIP.dat"

# Type of ip country code to compare by.
IpFilter::Configuration.ip_code_type = "country_code2"

# Accepts a proc that must return an array with corresponding format as :ip_code_type
IpFilter::Configuration.ip_codes = Proc.new { ["FI", "US", "GB"] }

# Accepts a proc that must return an array of IPs or IP range to
IpFilter::Configuration.ip_whitelist = Proc.new { ["22.33.11.0/24", "2.3.1.4"] }

# Exception to throw when IP is NOT allowed.
# Accepts a Proc for fine-grain control of the appropriate response.
IpFilter::Configuration.ip_exception = Proc.new { raise Api::Exception::AuthorizationError.new("You region is blocked!") }

# Cache object (Memcache only).
IpFilter::Configuration.cache = Rails.cache

Whitelist Ip¶ ↑

See above configuration.

Validate IP¶ ↑

Add the following method to any controller to validate the Request#ip. IpFilter::Configuration.ip_exception is a Proc which is called when ip is NOT within the specified region/country code and NOT in IP whitelist. You can pass in filter options similar to those in before_filter.

validate_ip

You can also pass a block (with filter options) to be executed when validation of ip fails like so (defaults to IpFilter::Configuration.ip_exception proc if no block present):

validate_ip do 
  raise Exception.new "Sorry access not granted!"
end

By default, loopback/private network addresses are allowed. You can disable this in like so:

#config/initializers/ip_filter.rb

IpFilter::Configuration.allow_loopback = false

Skip validation of IP¶ ↑

Add the following method to any controller that contains validate_ip to skip over the validation.

skip_validate_ip

Internally it is just skip_before_filter so filter options can be pass to it as well.

skip_validate_ip :only => [:index, :show], :if => lambda { account.roles == "admin" }

Request Geocoding by IP Address¶ ↑

IpFilter adds a location method to the standard Rack::Request object so you can easily look up the location of any HTTP request by IP address. For example, in a Rails controller:

# returns IpFilter::Result object
result = request.location

See “Advanced Geocoding” below for more information about IpFilter::Result objects.

Advanced Geocoding¶ ↑

So far we have looked at shortcuts for assigning geocoding results to object attributes.

Every IpFilter::Result object, result, provides the following data:

• result.ip - string

• result.country_code - string

• result.country_code2 - string

• result.country_code3 - string

• result.country_name - string

• result.continent_code - string

Caching¶ ↑

It’s easy to cache ip results with IpFilter, just configure a cache store:

IpFilter::Configuration.cache = Rails.cache

Currently only Memcache is supported.

You can also set a custom prefix to be used for cache keys:

IpFilter::Configuration.cache_prefix = "..."

By default the prefix is ip_filter:

Before you implement caching in your app please be sure that doing so does not violate the Terms of Service for your geocoding service.

Use Outside of Rails¶ ↑

You can use IpFilter outside of Rails by calling the IpFilter.search method:

results = IpFilter.search("147.243.3.83")

This returns an array of IpFilter::Result objects. Please see above and in the code for details.

Contributors¶ ↑

Ihor Ratsyborynskyy

Acknowledgements¶ ↑

The architecture/design of this gem is heavily based off of Geocoder (by Alex Reisner github.com/alexreisner/geocoder). Whereas Geocoder was built with 3rd party API resources in mind, IpFilter uses a local database file (.dat) similar to Geoip (by Clifford Heath github.com/cjheath/geoip).