DEBOPS.NETBASE(5)

NAME
debops.netbase - Manage local host and network database using Ansible

SYNOPSIS

debops service/netbase [--limit group,host,...] [--diff] [--check] [--tags tag1,tag2,...] [--skip-tags tag1,tag2,...] [<ansible-playbook options>] ...

DESCRIPTION

The debops.netbase Ansible role manages the hostname stored in /etc/hostname, as well as the local host and network database located in /etc/hosts and /etc/networks files, respectively. It can be used as a substitute for a DNS service for small number of hosts; with bigger network or larger clusters usage of a real DNS server is preferred.

GETTING STARTED

  Example inventory

The role is included by default in the bootstrap.yml and common.yml playbook, therefore you don't need to do anything to enable it.

  Example playbook

If you are using this role without DebOps, here's an example Ansible playbook that uses the debops.netbase role:

---
- name: Manage local host and network database
  collections: [ 'debops.debops', 'debops.roles01',
                 'debops.roles02', 'debops.roles03' ]
  hosts: [ 'debops_all_hosts', 'debops_service_netbase' ]
  become: True
  environment: '{{ inventory__environment | d({})
                   | combine(inventory__group_environment | d({}))
                   | combine(inventory__host_environment  | d({})) }}'
  roles:
    - role: python
      tags: [ 'role::python', 'skip::python', 'role::netbase' ]
      python__dependent_packages3:
        - '{{ netbase__python__dependent_packages3 }}'
      python__dependent_packages2:
        - '{{ netbase__python__dependent_packages2 }}'
    - role: netbase
      tags: [ 'role::netbase', 'skip::netbase' ]

  Ansible tags

You can use Ansible --tags or --skip-tags parameters to limit what tasks are performed during Ansible run. This can be used after a host was first configured to speed up playbook execution, when you are sure that most of the configuration is already in the desired state.

Available role tags:

role::netbase
    Main role tag, should be used in the playbook to execute all of the role tasks as well as role dependencies.

  Other resources

List of other useful resources related to the debops.netbase Ansible role:

•   Manual pages: hostname(5) <https://manpages.debian.org/hostname(5)>, hosts(5) <https://manpages.debian.org/hosts(5)>, networks(5) <https://manpages.debian.org/networks(5)>

DEFAULT VARIABLE DETAILS

Some of debops.netbase default variables have more extensive configuration than simple strings or lists, here you can find documentation and examples for them.

  netbase__hosts

The netbase__*_hosts variables are used to define the host records in the /etc/hosts database. Each variable is a list of YAML dictionaries, the entries with the same name parameter or the dictionary key are combined together; this allows modification of the earlier entries by the later ones. See hosts(5) <https://manpages.debian.org/hosts(5)> for more details.

  Examples

Add a Fully Qualified Domain Name host entry with IPv4 and IPv6 addresses:

netbase__hosts:
  - '192.0.2.1':   [ 'host.example.org', 'host' ]
  - '2001:db8::1': [ 'host.example.org', 'host' ]
  - '192.0.2.2':   'other.example.org'

Add a host entry with IP address specified by a variable:

host_address: '192.0.2.1'
host_fqdn_hostname: [ 'host.example.org', 'host' ]
netbase__hosts:
  - name: '{{ host_address }}'
    value: '{{ host_fqdn_hostname }}'

Remove a host record from the /etc/hosts database:

netbase__hosts:
  - '127.0.1.1': ''
  # Alternative syntax
  - '127.0.1.1': []

  Syntax

Each element in the list variables is a YAML dictionary. If the dictionary contains the name parameter, it will be evaluated as the "expanded" form with specific parameters:

name
    Required. The IP address of a given host entry. In this form it can be a variable. The entries with the same name parameter (or the dictionary key in the simple form) are merged together, this allows to change the specific entries in the inventory without the need to copy the entire list.

    If the name is empty, the host record will not be added to the database.

value
    Required. A string or a YAML list with host addresses to define for a given host record. If the list is used, lists from multiple entries are combined together. To reset a list, specify an entry with an empty string as the value.

    When the template mode is used (more than 15 entries by default), the value is interpreted a bit differently: if it's a string, the first part of the address until a dot will be extracted and automatically used as a "hostname" alias. To avoid this behavior, use a YAML list to define the value.

    If the value is empty, the host record will be removed from the database.

separator
    Optional, boolean. If set and True, the generated template will contain an empty line before a given entry, to allow for better readability. This parameter is ignored when the lineinfile mode is used to manage the database.

    If the YAML dictionary does not contain a name entry, the entire dictionary is interpreted using the following simplified format: keys are the IP addresses of the host records, and values are strings or YAML lists with the hostnames or FQDN domains. It's best to use only 1 dictionary key for each host record, and not combine multiple entries together in one list element.

AUTHOR
Maciej Delmanowski

COPYRIGHT
2014-2022, Maciej Delmanowski, Nick Janetakis, Robin Schneider and others