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 fileinventory/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. |
Ansible role for convenient installation of the free IP geolocation databases GeoLite2 provided by MaxMind.
ansible-galaxy install honzamach/ansible-role-geoip