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 10.1.0).

You might already have this collection installed if you are using the ansible package. 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.