{"id":18000091,"url":"https://github.com/rtib/puppet-geoip","last_synced_at":"2025-07-31T00:40:42.524Z","repository":{"id":16330484,"uuid":"79724631","full_name":"rtib/puppet-geoip","owner":"rtib","description":"Puppet module to install tools and update process for GeoIP database.","archived":false,"fork":false,"pushed_at":"2025-05-26T18:24:13.000Z","size":290,"stargazers_count":0,"open_issues_count":2,"forks_count":6,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-06-18T00:45:22.652Z","etag":null,"topics":["geoip-database","puppet"],"latest_commit_sha":null,"homepage":null,"language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rtib.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-01-22T15:06:19.000Z","updated_at":"2025-05-26T18:24:16.000Z","dependencies_parsed_at":"2024-06-21T04:18:25.408Z","dependency_job_id":"d2f0c54f-619b-4aab-b365-7041338d75fa","html_url":"https://github.com/rtib/puppet-geoip","commit_stats":null,"previous_names":[],"tags_count":20,"template":false,"template_full_name":null,"purl":"pkg:github/rtib/puppet-geoip","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rtib%2Fpuppet-geoip","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rtib%2Fpuppet-geoip/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rtib%2Fpuppet-geoip/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rtib%2Fpuppet-geoip/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rtib","download_url":"https://codeload.github.com/rtib/puppet-geoip/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rtib%2Fpuppet-geoip/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":260857429,"owners_count":23073439,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["geoip-database","puppet"],"created_at":"2024-10-29T22:16:21.178Z","updated_at":"2025-07-31T00:40:42.477Z","avatar_url":"https://github.com/rtib.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"# GeoIP\n\n## Project status\n\nGitHub: [![GitHub issues](https://img.shields.io/github/issues/rtib/puppet-geoip.svg)](https://github.com/rtib/puppet-geoip/issues) ![GitHub tag](https://img.shields.io/github/commit-activity/y/rtib/puppet-geoip) ![GitHub](https://img.shields.io/github/last-commit/rtib/puppet-geoip)\n\nNightly CI Workflow: [![CI](https://github.com/rtib/puppet-geoip/actions/workflows/ci.yaml/badge.svg)](https://github.com/rtib/puppet-geoip/actions/workflows/ci.yaml)\n\nPuppet Forge: ![PDK Version](https://img.shields.io/puppetforge/pdk-version/trepasi/geoip.svg) [![Puppet Forge](https://img.shields.io/puppetforge/v/trepasi/geoip.svg)](https://forge.puppet.com/trepasi/geoip)\n\n## Table of Contents\n\n\u003c!-- @import \"[TOC]\" {cmd=\"toc\" depthFrom=2 depthTo=3 orderedList=false} --\u003e\n\n\u003c!-- code_chunk_output --\u003e\n\n- [GeoIP](#geoip)\n  - [Project status](#project-status)\n  - [Table of Contents](#table-of-contents)\n  - [Description](#description)\n  - [Setup](#setup)\n    - [What geoip affects](#what-geoip-affects)\n    - [Setup Requirements](#setup-requirements)\n    - [Beginning with geoip](#beginning-with-geoip)\n  - [Usage](#usage)\n    - [Configuring versions less than 3.1.1](#configuring-versions-less-than-311)\n    - [Configuring versions 3.1.1 and later](#configuring-versions-311-and-later)\n    - [Upgrading to 3.1.1 or later](#upgrading-to-311-or-later)\n    - [Updating databases](#updating-databases)\n    - [Update scheduling](#update-scheduling)\n  - [Reference](#reference)\n  - [Limitations](#limitations)\n    - [Debian 11 - Bullseye](#debian-11---bullseye)\n  - [Development](#development)\n  - [Copyright](#copyright)\n\n\u003c!-- /code_chunk_output --\u003e\n\n## Description\n\nThis Puppet module installs and maintains tools and processes to use GeoIP databases\nfrom [MaxMind][1]. These include the lookup tools for lookup and update the databases. It will manage the configuration for the\nupdate tool which enables to set up your subscription settings, product IDs and other\nsettings, e.g. proxy settings. If systemd is available, a service is defined in order\nto enable a seamless update process.\n\n## Setup\n\n### What geoip affects\n\nThe module will install some packages, create a configuration file and a systemd\nservice unit.\n\n### Setup Requirements\n\nNeccesary packages must be available for installation by the package management tools\nused on the target system. As this is not the case on many systems, you have to take care\nabout the availability of the packages. The list of the packages to be installed is a configuration option.\n\n### Beginning with geoip\n\nThe only thing to start with geoip is to include the class in the manifest of your nodes.\n\n```puppet\ncontain geoip\n```\n\nAll configuration parameter can be assigned hiera. The default values are also lookuped up by hiera using the database shipped with the module.\n\n## Usage\n\nNote, 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.\n\nThe 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.\n\n### Configuring versions less than 3.1.1\n\n```yaml\ngeoip::config:\n  userid: '\u003cyourAccountID\u003e'\n  licensekey: '\u003cyourLicenseKey\u003e'\n```\n\nReplace the values for `userid` and `licensekey` with actual data from your subscription.\n\nOptional configuration settings are available, enable to set:\n\n- `productids`: array of productids of the databases you want to download; it defaults to the freely available databases `['GeoLite2-ASN', 'GeoLite2-City', 'GeoLite2-Country']`\n- `database_directory`: where to store the database files\n- `protocol`: HTTP or HTTPS\n- `proxy`: URL to the Proxy service allowing access to the Internet\n- `proxy_user_password`: Username and password to the Proxy, if needed.\n- `skip_hostname_verification`: Disable hostname verification.\n- `skip_peer_verification`: Disable certificate validation.\n\nRefer to your subscription to get the list of `productids` you are allowed to use.\n\n### Configuring versions 3.1.1 and later\n\n```yaml\ngeoip::config:\n  accountid: '\u003cyourAccountID\u003e'\n  licensekey: '\u003cyourLicenseKey\u003e'\n```\n\nReplace the values for `accountid` and `licensekey` with actual data from your subscription.\n\nOptional configuration settings are available, enable to set:\n\n- `editionids`: array of IDs of the databases you want to download; it defaults to the freely available databases `['GeoLite2-ASN', 'GeoLite2-City', 'GeoLite2-Country']`\n- `database_directory`: where to store the database files\n- `host`: the update server to use\n- `proxy`: URL to the Proxy service allowing access to the Internet\n- `proxy_user_password`: Username and password to the Proxy, if needed.\n- `lock_file`: location of the lock file to use to prevent running multiple updates at the same time\n\nRefer to your subscription to get the list of `editionids` you are allowed to use.\n\n### Upgrading to 3.1.1 or later\n\nVersions 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.\n\nNote, 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.\n\n### Updating databases\n\nIn order to update your databases you may use the `geoipupdate` tool with the configuration file created by this puppet module.\n\nIf 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.\n\nBy 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.\n\n### Update scheduling\n\nUpdates, 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](https://www.freedesktop.org/software/systemd/man/systemd.time.html#Parsing%20Timestamps).\n\nThe parameter `geoip::update_scatter` defines the seconds for systemd timer AccuracySec option (see [systemd.timer(5)#AccuracySec](https://www.freedesktop.org/software/systemd/man/systemd.timer.html#AccuracySec=)) to prevent multiple nodes to update at the same time.\n\n## Reference\n\nAutomatically generated reference documentation is available in the [REFERENCE.md][2] file or at [https://rtib.github.io/puppet-geoip/][3].\n\n## Limitations\n\nFor supported operating systems and dependencies, see [metadata.json](https://github.com/rtib/puppet-cassandra/blob/main/metadata.json).\n\nExtensive itegration tests are run nightly to assure quality  and compatibility with next releases.\n\n### Debian 11 - Bullseye\n\nThe `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.\n\n## Development\n\nThe module is developed using recent [Puppet Development Kit][4], [validated][5] and extensively tested using [Puppet Litmus][6]. Automated workflows, implemented with [GitHub Actions][7] are run on demand and nightly, doing validation, spec tests and continuous integration tests.\n\nNote, that [CI-Acceptance](https://github.com/rtib/puppet-geoip/actions/workflows/ci-acceptance.yaml) 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.\n\nAs 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.\n\nIssues 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.\n\n## Copyright\n\nThis product is tested using GeoLite2 data created by MaxMind, available from [https://www.maxmind.com][1].\n\n[1]: https://www.maxmind.com\n[2]: https://github.com/rtib/puppet-geoip/blob/main/REFERENCE.md\n[3]: https://rtib.github.io/puppet-geoip/\n[4]: https://puppet.com/docs/pdk/2.x/pdk.html\n[5]: https://puppet.com/docs/pdk/1.x/pdk_testing.html\n[6]: https://github.com/puppetlabs/puppet_litmus\n[7]: https://docs.github.com/en/actions\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frtib%2Fpuppet-geoip","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frtib%2Fpuppet-geoip","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frtib%2Fpuppet-geoip/lists"}