.. _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. |