7.4. Geolocation

Home Prev	cOS Stream 4.00.03 Administration Guide	Next

An additional traffic filtering option that is available in IPRule objects is Geolocation. This feature allows filtering of IPv4 and IPv6 addresses for the traffic source and/or destination according to its geographic association. Some IP addresses may not have a known geographic association but these can also be targeted by this feature.

The geolocation feature can be used in two ways:

An IPRule object can allow traffic from and/or to specific geographical areas.
An IPRule object can deny traffic from and/or to specific geographical areas.

The following IPRule properties determine geographic filtering:

SourceGeolocation - The geographic filter for the traffic source.
DestinationGeolocation - The geographic filter for the traffic destination.

Geolocation Setup Steps

The steps required for setting up the geolocation feature are as follows:

If the predefined GeolocationFilter objects are not suitable targeted geographic area, define a custom GeolocationFilter area that includes the desired regions.
Use either predefined or custom GeolocationFilter objects as the value for the SourceGeolocation property and/or the DestinationGeolocation property in an IPRule object. The IPRule determines how triggering traffic will be handled.

These configuration components will now be described in more detail.

Selecting a Geographic Area

The value assigned to the SourceGeolocation and/or DestinationGeolocation properties can be one of the following two types:

A predefined GeolocationFilter object.

cOS Stream provides a predefined list of GeolocationFilter objects which correspond to regions. The names of the predefined GeolocationFilter objects are the following:
- any-region (all locations)
- Africa
- Antarctica
- Asia
- Europe
- North America
- Oceana
- South America
The any-region value is the default setting for geolocation if no region is specified for an IP rule and this will include all regions. All the predefined filters have their MatchPrivate and MatchUnknown properties disabled with the exception of any-region which has both properties enabled. In other words, any-region will match on both unknown and private IP addresses but the other predefined filters will not.

To list the regions included in a predefined filter use a CLI command like the following:
```
System:/> show GeolocationFilter Europe

This object is read-only.

     Property  Value                                     Remarks
-------------  ----------------------------------------  ---------
        Name:  Europe                                    Read-only
     Regions:  AD, AL, AT, AX, BA, BE, BG, BY, CH, CY,   Read-only
               CZ, DE, DK, EE, ES, FI, FO, FR, GB, GG,
               GI, GR, HR, HU, IE, IM, IS, IT, JE, LI,
               LT, LU, LV, MC, MD, ME, MK, MT, NL, NO,
               PL, PT, RO, RS, RU, SE, SI, SJ, SK, SM,
               UA, VA, XK
MatchPrivate:  No                                        Read-only
MatchUnknown:  No                                        Read-only
    Comments:  Europe                                    Read-only
```
The region list is given as a set of 2 character codes which follow the ISO-3166-1 Alpha-2 convention. Note that the predefined filters are read-only and cannot be edited by the administrator.
A Custom GeolocationFilter object.

For finer control of the targeted geographic area, the administrator can create a custom GeolocationFilter object which consists of one or more targeted regions. This object can then be used as the value for the SourceGeolocation and/or DestinationGeolocation properties of an IPRule object.

The principal property in the Geolocation filter is Regions. This property should be assigned a comma separated list of 2 character ISO-3166-1 Alpha-2 codes representing regions. Tab completion in the CLI will provide a list of all available codes.

In addition to specifying regions for a GeolocationFilter object, or instead of regions, the following two additional options can be enabled in the filter:
1. Match Private Networks - This includes the IP addresses used for private networks. This includes the IPv4 networks 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16 and the IPv6 network fd00::/8. Although this option is not directly related to geolocation and could be implemented through the address book, it is provided as a convenience.
2. Match Unclassified Networks - This will match any IP address that is public but does not have a known region association.

Tip: Using tab completion to list codes

	Tip: Using tab completion to list codes
When, for example, creating a new Geolocation object, tab completion can be used to list all available country codes. However, it can be useful to also see the country names associated with codes and this is done by entered a question mark '?' before pressing the TAB key: `System:/>` add Geolocation Filter my-gf Regions=?<TAB> Name Description ------- -------------------------------------------- AD Andorra AE United Arab Emirates AF Afghanistan AG Antigua and Barbuda AI Anguilla AL Albania AM Armenia AO Angola AQ Antarctica

When, for example, creating a new Geolocation object, tab completion can be used to list all available country codes. However, it can be useful to also see the country names associated with codes and this is done by entered a question mark '?' before pressing the TAB key:

System:/> add Geolocation Filter my-gf Regions=?<TAB>
Name     Description
-------  --------------------------------------------
AD       Andorra
AE       United Arab Emirates
AF       Afghanistan
AG       Antigua and Barbuda
AI       Anguilla
AL       Albania
AM       Armenia
AO       Angola
AQ       Antarctica

Updating the Geolocation Database Files

The predefined geolocation regions and their associated IP addresses are defined by two files found on the firewall. One file is for IPv4 addresses and the other is for IPv6 addresses. All cOS Stream software versions come with two default files already installed and activated:

geoip4.bin - Geolocation data for IPv4 addresses.
geoip6.bin - Geolocation data for IPv6 addresses.

Note that the filetype of these two database files must always be .bin. Clavister will release new versions of these files periodically which can then be uploaded using SCP. They will automatically overwrite their older versions.

Activating Geolocation Files

Once a file is uploaded, it must be activated before it will be used by cOS Stream. This is done with the geoip -activate command but this is only available with the advanced command view :

System:/> geoip -activate=<filename>

A file can be deleted from storage with the -remove option:

System:/> geoip -remove=<filename>

However, it should be noted that -remove operation does not affect the currently activated definitions, it removes the file from which the definitions came.

The current status of all files can be displayed with the -status option:

System:/> geoip -status

The -lookup option can also be used to display the region that corresponds to a given IP address:

System:/> geoip -lookup=<ip-address>

The geoip command and its options are fully described in the separate CLI Reference Guide.

Example 7.4. IP Rule Filtering Using Geolocation

This example will set up an IPRule object that will drop all Internet traffic to a DMZ which is coming from the mythical region of Hackerland. This is done by first creating a GeolocationFilter object that includes only the fictitious regions Hackerland (fictitious ISO code: HA) and Phisherland (fictitious ISO code: PI). An IPRule object will then be defined which will drop all flows that originate from these regions.

In addition, the IPRule will also drop traffic that comes from any IP address that is not known to be associated with a region by enabling the MatchUnknown property in the GeolocationFilter object.

Command-Line Interface

First, create the GeolocationFilter object:

System:/> add GeolocationFilter my_geo_filter
			Regions=HA,PI
			MatchUnknown=Yes

Next, create the IPRule object that uses this filter:

System:/> add IPRule SourceInterface=wan
			SourceNetwork=all-nets
			DestinationInterface=dmz
			DestinationNetwork=all-nets
			Service=all_services
			Action=Deny
			SourceGeoFilter=my_geo_filter
			Name=wan_to_dmz

Note that all-nets includes both all IPv4 and all IPv6 addresses (it is a combination of all-nets-ip4 and all-nets-ip6) so the rule will be applied to both IPv4 and IPv6 source addresses.