DEBOPS.ETC_SERVICES(5)

NAME
debops.etc_services - Manage /etc/services database using Ansible

SYNOPSIS

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

DESCRIPTION

The debops.etc_services role can be used to "reserve" or "register" a service port in the /etc/services file. Service ports configured this way can appear as named entries in many command outputs, such as iptables --list or netstat --listening --program. You can also have convenient database of reserved and free ports on a particular host, and reference ports by their names in firewall configuration files.

GETTING STARTED

  Using debops.etc_services from other roles

One common use case for debops.etc_services is to use it from other roles to configure /etc/services.

To do this, you can define the services in your defaults/main.yml file. Example:

# Configuration for ``debops.etc_services`` role which registers port numbers
# for Apt-Cacher NG.
apt_cacher_ng__etc_services__dependent_list:
  - name: 'acng'
    port: '3142'
    comment: 'Apt-Cacher NG caching proxy server'

And then in the playbook for this role, hand the apt_cacher_ng__etc_services__dependent_list variable over to the debops.etc_services role:

---
- name: Configure package proxy server apt-cacher-ng
  hosts: [ 'debops_service_apt_cacher_ng' ]
  become: True
  roles:
    - role: debops.etc_services
      tags: [ 'role::etc_services' ]
      etc_services__dependent_list:
        - '{{ apt_cacher_ng__etc_services__dependent_list }}'

  Example inventory

To configure debops.etc_services on a given remote host, it needs to be added to [debops_all_hosts] or debops_service_etc_services Ansible inventory group:

[debops_all_hosts]
hostname

  Example playbook

Here's a minimal example playbook that can be used to manage the /etc/services file:

---
- name: Manage /etc/services database
  collections: [ 'debops.debops', 'debops.roles01',
                 'debops.roles02', 'debops.roles03' ]
  hosts: [ 'debops_all_hosts', 'debops_service_etc_services' ]
  become: True
  environment: '{{ inventory__environment | d({})
                   | combine(inventory__group_environment | d({}))
                   | combine(inventory__host_environment  | d({})) }}'
  roles:
    - role: etc_services
      tags: [ 'role::etc_services', 'skip::etc_services' ]

This playbooks is shipped with this role under docs/playbooks/etc_services.yml from which you can symlink it to your playbook directory.

DEFAULT VARIABLE DETAILS

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

  etc_services__list

The etc_services__*_list list variables allow you to generate entries for local services not included in the officially distributed /etc/services file. They will generate separate files for each configured service in /etc/services.d/ which then will be assembled into the /etc/services file.

Each list entry is a YAML dictionary with specific parameters:

name
    String, required. Name of the service, should be short and unique.

port
    String, required. TCP or UDP ort used by the service.

protocols
    List of strings, optional. Transport layer protocols of the service corresponding with port. Common choices: tcp, udp.

comment
    String, optional. Comment to add to the service entry.

filename
    String, optional. Use this filename instead of a generated one.

custom
    String, optional. Specify custom file contents instead of templated one. If it is used, options like name and port are ignored.

state
    Either present or absent. If it's defined and absent, the local service configuration will be removed.

delete
    Boolean, optional, defaults to False. Delete the given local service.

  Examples

Create an entry for a custom TCP and UDP service:

etc_services__list:
  - name: 'servicename'
    port: '12345'
    protocols: [ 'tcp', 'udp' ]
    comment: 'Example service'

AUTHOR
Maciej Delmanowski, Robin Schneider

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