IP geolocation database#

SFTPPlus uses a bundled database to identify the estimated country and autonomous system (AS) associated with public IPv4 and IPv6 addresses. The Web Manager activity log displays this information for newly recorded events. Event handlers can access it through account.peer.country_code, account.peer.asn_number, and account.peer.asn_name. Private addresses and addresses without matching information have empty values. IP geolocation is an estimate and does not identify a person's location.

Lookups run locally and do not send IP addresses to an external service. The database uses the user-country and origin-asn datasets from ip-location-db, published under the PDDL v1.0 licence. The bundled database is updated with each new SFTPPlus release.

Country names are reviewed whenever the bundled database is updated for a release. If an upstream update introduces a country code without a name, release preparation fails until that name is added. Release preparation also fails if the name list includes a code absent from the refreshed bundled database.

Existing activity log entries retain their recorded information.

Country and ASN access rules#

The source_ip_filter option also accepts two-letter country codes and autonomous system numbers (ASNs). Use the ASN prefix for an autonomous system number. Country codes and ASN rules are case insensitive. The values must be present in the GeoIP database loaded by SFTPPlus. An unknown country code or ASN is rejected as invalid configuration. See the bundled country code and name guide for the codes in this release. An updated custom database can have a different set of codes and ASNs. For example:

source_ip_filter =
  allow DE
  allow es
  allow ASN1234
  deny RO
  deny ASN8324

Rules are evaluated from top to bottom, and the first match determines the action. Country and ASN rules can be mixed with IP addresses and CIDR ranges. An address without a country or ASN in the database does not match a country or ASN rule. See authentication rules for account and group behavior, and security policies for service-level behavior.

Updating and inspecting the database#

To download and validate the latest database, run the command for your platform:

bin/admin-commands.sh geoip-update

admin-commands.bat geoip-update

The command reports when the update starts and shows download, validation, and publication progress. The command saves the database as run/geoip_lite.db in the SFTPPlus installation directory. If that path already contains a file, the command backs it up as run/geoip_lite.db.bak before downloading and reports the backup path. This overwrites any earlier backup at that path, and the temporary backup is removed after a successful update.

Download or validation failures leave the existing database and backup in place. If publication fails, the command restores the existing database from the backup. If run/geoip_lite.db is a directory, the command fails before downloading any data.

The bundled database is unchanged. The update is published only after all downloaded files and the resulting database have been validated.

Restart SFTPPlus to use the updated database.

Note

At startup, SFTPPlus uses run/geoip_lite.db when that file exists. If this custom file cannot be loaded, startup fails rather than falling back to the bundled database. Remove or replace the invalid file before starting SFTPPlus again. Without a custom file, SFTPPlus uses the bundled database; startup also fails if the bundled database cannot be loaded.

To inspect the database selected by the same rule, run:

bin/admin-commands.sh geoip-search 8.8.8.8

admin-commands.bat geoip-search 8.8.8.8

The result shows the country and ASN, their names where available, and each matching IP range. For example, the output can look like this:

IP: 8.8.8.8
Country: US
Country name: United States
Country range: 8.3.128.0 - 8.10.5.255
ASN: ASN15169
ASN name: Google LLC
ASN range: 8.8.8.0 - 8.8.8.255

The country and ASN ranges can differ. An address without a matching entry is reported as Unknown.

If a custom database contains a code without a bundled country name, the country name is reported as Unknown. The custom database update still succeeds, and the code can be used in a source_ip_filter rule when it is present in that database.