community.general.fqdn_valid test – Validates fully-qualified domain names against RFC 1123

Note

This test plugin is part of the community.general collection (version 6.6.9).

It is not included in ansible-core. To check whether it is installed, run ansible-galaxy collection list.

To install it, use: ansible-galaxy collection install community.general. You need further requirements to be able to use this test plugin, see Requirements for details.

To use it in a playbook, specify: community.general.fqdn_valid.

New in community.general 8.1.0

Synopsis

  • This test validates Fully Qualified Domain Names (FQDNs) conforming to the Internet Engineering Task Force specification RFC 1123 and RFC 952.

  • The design intent is to validate that a string would be traditionally acceptable as a public Internet hostname to RFC-conforming software, which is a strict subset of the logic in modern web browsers like Mozilla Firefox and Chromium that determines whether make a DNS lookup.

  • Certificate Authorities like Let’s Encrypt run a narrower set of string validation logic to determine validity for issuance. This test is not intended to achieve functional parity with CA issuance.

  • Single label names are allowed by default (min_labels=1).

Requirements

The below requirements are needed on the local controller node that executes this test.

  • fqdn>=1.5.1 (PyPI)

Input

This describes the input of the test, the value before is community.general.fqdn_valid or is not community.general.fqdn_valid.

Parameter

Comments

Input

string / required

Name of the host.

Keyword parameters

This describes keyword parameters of the test. These are the values key1=value1, key2=value2 and so on in the following examples: input is community.general.fqdn_valid(key1=value1, key2=value2, ...) and input is not community.general.fqdn_valid(key1=value1, key2=value2, ...)

Parameter

Comments

allow_underscores

boolean

Allow underscore characters.

Choices:

  • false ← (default)

  • true

min_labels

integer

Required minimum of labels, separated by period.

Default: 1

Examples

- name: Make sure that hostname is valid
  ansible.builtin.assert:
    that: hostname is community.general.fqdn_valid

- name: Make sure that hostname is at least 3 labels long (a.b.c)
  ansible.builtin.assert:
    that: hostname is community.general.fqdn_valid(min_labels=3)

- name: Make sure that hostname is at least 2 labels long (a.b). Allow '_'
  ansible.builtin.assert:
    that: hostname is community.general.fqdn_valid(min_labels=2, allow_underscores=True)

Return Value

Key

Description

Return value

boolean

Whether the name is valid.

Returned: success

Authors

  • Vladimir Botka (@vbotka)

Hint

Configuration entries for each entry type have a low to high priority order. For example, a variable that is lower in the list will override a variable that is higher up.