geoip

.. _section-role-geoip:

Role geoip

  • Ansible Galaxy page <https://galaxy.ansible.com/honzamach/geoip>__
  • GitHub repository <https://github.com/honzamach/ansible-role-geoip>__
  • Travis CI page <https://travis-ci.org/honzamach/ansible-role-geoip>__

Ansible role for convenient installation of the free IP geolocation databases GeoLite2 <https://dev.maxmind.com/geoip/geoip2/geolite2/#Download_Access>__ provided by MaxMind <https://www.maxmind.com/en/home>__.

Table of Contents:

  • :ref:section-role-geoip-installation
  • :ref:section-role-geoip-dependencies
  • :ref:section-role-geoip-usage
  • :ref:section-role-geoip-variables
  • :ref:section-role-geoip-files
  • :ref:section-role-geoip-author

This role is part of the MSMS <https://github.com/honzamach/msms>__ package. Some common features are documented in its :ref:manual <section-manual>.

.. _section-role-geoip-installation:

Installation

To install the role honzamach.geoip <https://galaxy.ansible.com/honzamach/geoip>__ from Ansible Galaxy <https://galaxy.ansible.com/>__ please use variation of following command::

ansible-galaxy install honzamach.geoip

To install the role directly from GitHub <https://github.com>__ by cloning the ansible-role-geoip <https://github.com/honzamach/ansible-role-geoip>__ repository please use variation of following command::

git clone https://github.com/honzamach/ansible-role-geoip.git honzamach.geoip

Currently the advantage of using direct Git cloning is the ability to easily update the role when new version comes out.

.. _section-role-geoip-dependencies:

Dependencies

This role is not dependent on any other roles.

Following roles have dependency on this role:

  • :ref:mentat <section-role-mentat>
  • :ref:mentat_dev <section-role-mentat-dev>

.. _section-role-geoip-usage:

Usage

Example content of inventory file inventory::

[servers_geoip]
your-server

Example content of role playbook file role_playbook.yml::

- hosts: servers_geoip
  remote_user: root
  roles:
    - role: honzamach.geoip
  tags:
    - role-geoip

Example usage::

# Run everything:
ansible-playbook --ask-vault-pass --inventory inventory role_playbook.yml

It is recommended to follow these configuration principles:

  • Create/edit file inventory/group_vars/all/vars.yml and within define some sensible defaults for all your managed servers. Example::

      hm_geoip__account_id: "{{ vault_hm_geoip__account_id }}"
      hm_geoip__license_key: "{{ vault_hm_geoip__license_key }}"
    
  • Create/edit :ref:vault <section-overview-vault> encrypted file inventory/group_vars/all/vault.yml and within store your backup encryption password::

      vault_hm_geoip__account_id: 123456
      vault_hm_geoip__license_key: something-so-secret-no1-is-gonna-guess
    
  • Use files inventory/host_vars/[your-server]/vars.yml to customize settings for particular servers. Please see section :ref:section-role-geoip-variables for all available options.

.. _section-role-geoip-variables:

Configuration variables

Internal role variables


.. envvar:: hm_geoip__package_url

    Default URL of the package from which to install the geoipupdate utility.

    * *Datatype:* ``string``
    * *Default:* ``https://github.com/maxmind/geoipupdate/releases/download/v4.1.5/geoipupdate_4.1.5_linux_amd64.deb``

.. envvar:: hm_geoip__account_id

    Your MaxMind account unique identifier (numeric).

    * *Datatype:* ``integer``
    * *Default:* ``null``

.. envvar:: hm_geoip__license_key

    Your MaxMind account license key. Make sure you have enabled the *Update* option during key creation.

    * *Datatype:* ``string``
    * *Default:* ``null``

.. envvar:: hm_geoip__edition_ids

    List of requested IP geolocation database to be installed on target host.

    * *Datatype:* ``list of strings``
    * *Default:* ``["GeoLite2-ASN", "GeoLite2-City", "GeoLite2-Country"]``

.. envvar:: hm_geoip__database_directory

    The directory to store the database files.

    * *Datatype:* ``string``
    * *Default:* ``/usr/share/GeoIP``


Built-in Ansible variables

.. envvar:: ansible_lsb['codename']

Debian distribution codename is used for :ref:`template customization <section-overview-role-customize-templates>`
feature.

.. _section-role-geoip-files:

Managed files

.. note::

This role supports the :ref:`template customization <section-overview-role-customize-templates>` feature.

This role manages content of following files on target system:

  • /etc/cron.d/geoipupdate [TEMPLATE]
  • /etc/GeoIP.conf [TEMPLATE]

.. _section-role-geoip-author:

Author and license

| Copyright: (C) since 2019 Honza Mach honza.mach.ml@gmail.com | Author: Honza Mach honza.mach.ml@gmail.com | Use of this role is governed by the MIT license, see LICENSE file. |

About

Ansible role for convenient installation of the free IP geolocation databases GeoLite2 provided by MaxMind.

Install
ansible-galaxy install honzamach/ansible-role-geoip
GitHub repository
License
mit
Downloads
120
Owner