Forge Home

Modules

Puppet

Resources

PuppetEcosystemPuppet CommunityUpdates

geoip

Install tools and update process for GeoIP database.
Project URLRSS FeedReport issues

27,038 downloads

668 latest version

5.0 quality score

We run a couple of automated
scans to help you access a
module's quality. Each module is
given a score based on how well
the author has formatted their
code and documentation and
modules are also checked for
malware using VirusTotal.

Please note, the information below
is for guidance only and neither of
these methods should be considered
an endorsement by Puppet.

Version information

  • 6.0.1 (latest)
  • 6.0.0
  • 5.0.1
  • 5.0.0
  • 4.1.0
  • 4.0.1
  • 4.0.0
  • 3.2.1
  • 3.2.0
  • 3.1.0
  • 3.0.1
  • 3.0.0
  • 2.2.0
  • 2.1.1
  • 2.1.0
  • 2.0.0
  • 1.0.1
  • 1.0.0
  • 0.2.0
  • 0.1.1
released Jul 18th 2023
This version is compatible with:
  • Puppet Enterprise 2023.2.x, 2023.1.x, 2023.0.x, 2021.7.x, 2021.6.x, 2021.5.x, 2021.4.x, 2021.3.x, 2021.2.x, 2021.1.x, 2021.0.x, 2019.8.x
  • Puppet >=6.21.0 < 8.0.0
  • , ,

Start using this module

  • r10k or Code Manager
  • Bolt
  • Manual installation
  • Direct download

Add this module to your Puppetfile:

mod 'trepasi-geoip', '6.0.1'
Learn more about managing modules with a Puppetfile

Add this module to your Bolt project:

bolt module add trepasi-geoip
Learn more about using this module with an existing project

Manually install this module globally with Puppet module tool:

puppet module install trepasi-geoip --version 6.0.1

Direct download is not typically how you would use a Puppet module to manage your infrastructure, but you may want to download the module in order to inspect the code.

Download
Tags: maxmind, geoip

Documentation

trepasi/geoip — version 6.0.1 Jul 18th 2023

GeoIP

Project status

GitHub: GitHub issues GitHub tag GitHub

Nightly CI Workflow: CI

Puppet Forge: PDK Version Puppet Forge

Table of Contents

Description

This Puppet module installs and maintains tools and processes to use GeoIP databases from MaxMind. These include the lookup tools for lookup and update the databases. It will manage the configuration for the update tool which enables to set up your subscription settings, product IDs and other settings, e.g. proxy settings. If systemd is available, a service is defined in order to enable a seamless update process.

Setup

What geoip affects

The module will install some packages, create a configuration file and a systemd service unit.

Setup Requirements

Neccesary packages must be available for installation by the package management tools used on the target system. As this is not the case on many systems, you have to take care about the availability of the packages. The list of the packages to be installed is a configuration option.

Beginning with geoip

The only thing to start with geoip is to include the class in the manifest of your nodes.

contain geoip

All configuration parameter can be assigned hiera. The default values are also lookuped up by hiera using the database shipped with the module.

Usage

Note, that MaxMind does not allow to download databases without subscription, but there is a free tier which can be used to download three GeoLite2 databases.

The configuration depends on the version of the geoipupdate tool to use, as there is a difference between versions starting at 3.1.1 and the older ones. The module referns to these settings via parameter geoip::config_version using the value lt311 for versions less than 3.1.1 and value ge311 for version greater or equal to 3.1.1.

Configuring versions less than 3.1.1

geoip::config:
  userid: '<yourAccountID>'
  licensekey: '<yourLicenseKey>'

Replace the values for userid and licensekey with actual data from your subscription.

Optional configuration settings are available, enable to set:

  • productids: array of productids of the databases you want to download; it defaults to the freely available databases ['GeoLite2-ASN', 'GeoLite2-City', 'GeoLite2-Country']
  • database_directory: where to store the database files
  • protocol: HTTP or HTTPS
  • proxy: URL to the Proxy service allowing access to the Internet
  • proxy_user_password: Username and password to the Proxy, if needed.
  • skip_hostname_verification: Disable hostname verification.
  • skip_peer_verification: Disable certificate validation.

Refer to your subscription to get the list of productids you are allowed to use.

Configuring versions 3.1.1 and later

geoip::config:
  accountid: '<yourAccountID>'
  licensekey: '<yourLicenseKey>'

Replace the values for accountid and licensekey with actual data from your subscription.

Optional configuration settings are available, enable to set:

  • editionids: array of IDs of the databases you want to download; it defaults to the freely available databases ['GeoLite2-ASN', 'GeoLite2-City', 'GeoLite2-Country']
  • database_directory: where to store the database files
  • host: the update server to use
  • proxy: URL to the Proxy service allowing access to the Internet
  • proxy_user_password: Username and password to the Proxy, if needed.
  • lock_file: location of the lock file to use to prevent running multiple updates at the same time

Refer to your subscription to get the list of editionids you are allowed to use.

Upgrading to 3.1.1 or later

Versions of geoipupdate 3.1.1 or later will accept the configuration file format of former versions. Making use of that, the module provides the geoip::config_version parameter to chose the configuration format, which defaults to lt311, but is overwritten with ge311 for operating system versions known to provide geoipupdate version 3.1.1 or later (e.g. Debian Buster). While it should not needed to set this parameter in normal operation, during upgrade of multiple nodes, the parameter allows to pin the configuration version to the needed format.

Note, that a license keys issued for versions less than 3.1.1 of later will not work in both configurations, geoipupdate versions less than 3.1.1 will fail accessing the update server when a key issed for 3.1.1 or later is provided in the lt311 configuration.

Updating databases

In order to update your databases you may use the geoipupdate tool with the configuration file created by this puppet module.

If you haven't disabled geoip::manage_service, you may start the update service named geoip::service_name (defaults to geoip_update), which will do the update.

By default, the update service will retry after 5 minutes if the update was failed by any reason. This behaviour can be changed via geoip::systemd::service::restart and geoip::systemd::service::restart_sec defining SystemD restart behaviour.

Update scheduling

Updates, if handled by SystemD, can be scheduled by setting geoip::update_timers an array of timer descriptions. These timer descriptions apply on systemd timer unit OnCalendar options. For correct syntax of these timestamps see systemd.time(7)#Parsing Timestamps.

The parameter geoip::update_scatter defines the seconds for systemd timer AccuracySec option (see systemd.timer(5)#AccuracySec) to prevent multiple nodes to update at the same time.

Reference

Automatically generated reference documentation is available in the REFERENCE.md file or at https://rtib.github.io/puppet-geoip/.

Limitations

For supported operating systems and dependencies, see metadata.json.

Extensive itegration tests are run nightly to assure quality and compatibility with next releases.

Debian 11 - Bullseye

The geoipupdate package available in Debian Bullseye release is shipping SystemD units for service and timer to conduct weekly updates of the database. Default behaviour of the module will shift to use systemd_config: dropin on Debian-11 by default to rebuild the functionality on the changed environment.

Development

The module is developed using recent Puppet Development Kit, validated and extensively tested using Puppet Litmus. Automated workflows, implemented with GitHub Actions are run on demand and nightly, doing validation, spec tests and continuous integration tests.

Note, that CI-Acceptance workflow is not applied to pull requests automatically, as it needs credentials setup as secrets to work. A pull request, however, will only be merged if these tests also succeed.

As an open project, you are welcome to contribute to this module. Currently, there is no contribution guide specific to this module, general information about the workflow may apply. In case of questions feel free to open a issue or join community Slack channels #forge-modules, #puppet, #puppet-dev, #testing on slack.puppet.com.

Issues and pull requests will be addressed in a timely manner, according to community best practice. Releases are going to be published on demand, after having merged an set of sufficiently important changes and all tests succeeded. There may be automated rule enforcement in place to provide a healthy issue lifecycle.

Copyright

This product is tested using GeoLite2 data created by MaxMind, available from https://www.maxmind.com.