lua-location(3)

Name

lua-location - Lua module to query the IPFire Location Database

Synopsis

location = require("location")

db = location.Database.open(location.DATABASE_PATH)

network = db:lookup("81.3.27.38")

Description

The location module makes libloc available in Lua 5.1 to 5.4. It can look up addresses, fetch Autonomous Systems and countries, list all networks, and verify databases. Unlike the Python module (see python-location(3)), it cannot write databases.

Functions that look something up return nil if there is nothing. Anything that goes wrong raises an error with a message, which can be caught with pcall().

AS numbers, address families, flags and times are returned as integers in Lua 5.3 and later. Older versions of Lua only have one type for numbers.

Functions and Constants

location.version(): Returns the version of libloc.
location.set_log_level(priority): Sets the priority of the messages that the library logs, as a syslog(3) priority, for example 7 for LOG_DEBUG.
location.set_log_callback(function): Calls function(priority, message) for every message that the library logs, instead of writing it to the console.
location.DATABASE_PATH: The path of the database of the system, usually /var/lib/location/database.db.
location.NETWORK_FLAG_ANONYMOUS_PROXY, location.NETWORK_FLAG_SATELLITE_PROVIDER, location.NETWORK_FLAG_ANYCAST, location.NETWORK_FLAG_DROP: The flags that a network can have.

Database

location.Database.open(path): Opens the database at path. The database is mapped into memory, and is read again automatically when its file has been replaced, so that it only needs to be opened once.
db:lookup(address): Returns the Network that address is in, or nil if the database knows nothing about it. address is a string, for example "81.3.27.38" or "2001:db8::1". Invalid addresses raise an error.
db:get_as(number): Returns the AS with that number, or nil.
db:get_country(code): Returns the Country with that code, or nil.
db:list_networks(): Returns an iterator over all networks, for use with for … in.
db:verify(path): Returns whether the database has been signed with the public key in the file path.
db:created_at(): Returns when the database was created, as seconds since the epoch.
db:get_vendor(), db:get_description(), db:get_license(): Return who has created the database, what it is, and under which license it has been published.

Network

location.Network.new(network): Creates a network from a string, for example "10.0.0.0/8".
network:get_country_code(), network:get_asn(): Return the country code and the AS number of the network, or nil.
network:get_family(): Returns the address family of the network, which is 2 for IPv4 (AF_INET), and 10 for IPv6 (AF_INET6) on Linux.
network:has_flag(flag): Returns whether the network has flag.
network:subnets(): Returns a table with the two halves of the network.
network:reverse_pointer(suffix): Returns the name of the network in the DNS, which ends in suffix, or in in-addr.arpa. or ip6.arpa. if suffix is omitted, for example "*.10.in-addr.arpa.", or nil if the prefix of the network is not a multiple of 8 for IPv4, or of 4 for IPv6.

tostring() returns the network as a string.

AS

location.AS.new(number): Creates an Autonomous System.
as:get_number(), as:get_name(): Return the AS number, and the name of the Autonomous System, or nil.

tostring() returns for example "AS204867 - Lightning Wire Labs GmbH".

Country

location.Country.new(code): Creates a country.
country:get_code(), country:get_name(), country:get_continent_code(): Return the country code, the name of the country, and the code of its continent, or nil.

Countries can be compared with ==. tostring() returns the code.

Examples

Look up an address:

location = require("location")

db = location.Database.open(location.DATABASE_PATH)

network = db:lookup("81.3.27.38")
if network then
        print(tostring(network), network:get_country_code(), network:get_asn())
end

Find out whether an address belongs to an anycast network:

network = db:lookup("8.8.8.8")
if network and network:has_flag(location.NETWORK_FLAG_ANYCAST) then
        print("anycast")
end

Print the name of a country:

country = db:get_country("DE")
print(country:get_name())

Count all networks:

n = 0
for network in db:list_networks() do
        n = n + 1
end

Authors

Michael Tremer