Documentation for ansible selfhost plugin

This is the original documentation of the ansible plugin for the selfhost.de API. The plugin is hosted at ansible galaxy as lithilion.selfhost.

Content

• selfhost_dns_record_info Get information about existing DNS records
• selfhost_dns_record Create, modify, or delete DNS records

selfhost_dns_record_info

This module lists existing DNS records under a relative domain (name) or gets single records.

• Retrieve information about DNS records from the selfhosted DNS API service.
• All API calls use POST with TLS certificate validation.
• Respects rate limits (HTTP 429) and validates response integrity.

Parameters

Parameter	Choices/Defaults	Comments
api_key string		The API key for authentication in the format "numericalid.64hexchars".
api_key_auth_header string		Authentication via Authorization Bearer header.
action string (required)	list, get	The action to perform.
record_id int		The unique ID of the DNS record to retrieve. Required for action=get.
name string		Filter records by exact relative domain name.
type string	A, AAAA, CAA, CNAME, MX, NS, SPF, SRV, TXT	Filter records by DNS record type.
limit int	Default: 100	Maximum records per page (1-100)
after_id int		Pagination cursor.
api_url string	Default: https://my.selfhost.de/cgi-bin/dns-records-api.pl	Base URL of the API. Must be HTTPS.
validate_certs bool	Default: true	Whether to validate TLS certificates.
timeout int	Default: 30	HTTP request timeout in seconds.

Return Values

Key	Returned	Description
response dict	Always	The JSON response from the DNS API.

Examples

- name: get all TXT records of the root domain
  lithilion.selfhost.selfhost_dns_record_info:
    api_key: API_KEY
    action: list
    type: TXT

- name: get all CNAME records of the subdomain "files"
  lithilion.selfhost.selfhost_dns_record_info:
    api_key: API_KEY
    action: list
    type: CNAME
    name: files


- name: get record with id 12345
  lithilion.selfhost.selfhost_dns_record_info:
    api_key: API_KEY
    action: get
    record_id: 12345

selfhost_dns_record

This module creates, modifies, or deletes DNS records supporting check_mode and idempotency.

• Create, update, or delete DNS records via the selfhosted DNS API service.
• All API calls use POST with TLS certificate validation.
• Supports check_mode and idempotent operations.
• Before creating a record, checks if it already exists to ensure idempotency.
• Respects rate limits (HTTP 429) and validates response integrity.

Parameters

Parameter	Choices/Defaults	Comments
api_key string		The API key for authentication in the format "numericalid.64hexchars".
api_key_auth_header string		Authentication via Authorization Bearer header.
state string (required)	present, absent	Desired state of the DNS record.
name string (required)		Relative domain name for the DNS record.
type string (required)	A, AAA, CAA, CNAME, MX, TXT	DNS record type
content string (required)		Content/value of the DNS record.
ttl int	10	Time-to-live in seconds.
priority int		Priority for MX records only. Required for MX type.
api_url string	Default: https://my.selfhost.de/cgi-bin/dns-records-api.pl	Base URL of the API. Must be HTTPS.
validate_certs bool	Default: true	Whether to validate TLS certificates.
timeout int	Default: 30	HTTP request timeout in seconds.

Return Values

Key	Returned	Description
record_id int	when state=present	ID of the DNS record (for created or existing records).
record dict	when state=present	The DNS record object from the API response.

Notes

• Record types NS, SPF, SRV are completely untested, although they work.

Examples

- name: modify stuff via loop for the relative domain api-test.EXAMPLE.COM
  lithilion_at.selfhost.selfhost_dns_record:
    api_key: API-KEY
    name: api-test
    type: "{{ item.type }}"
    content: "{{ item.content }}"
    state: "{{ item.state }}"
    ttl: "{{ item.ttl | default(omit) }}"
    priority: "{{ item.priority | default(omit) }}"
  with_items:
    - {type: TXT, content: loop, state: present, ttl: 60}
    - {type: A, content: 1.1.1.1, state: present, ttl: 60}
    - {type: AAAA, content: "fdda:db83:178c:0:1436:bd0f:8390:1fec",  state: present, ttl: 60}
    - {type: AAAA, content: "2001:0db8:0000:0000:0000:0000:0000:0001",  state: present, ttl: 60}
    - {type: AAAA, content: "fe80::1",  state: present, ttl: 60}
    - {type: AAAA, content: "2001:db8::1",  state: present, ttl: 60}
    - {type: CAA, content: '0 iodef "admin@lithilion.at"',  state: present, ttl: 60}
    - {type: CAA, content: '1 issue "letsencrypt.org"',  state: present, ttl: 60}
    - {type: CNAME, content: lithilion.at,  state: present, ttl: 60}
    - {type: MX, content: mx43.services.blackmesa.at,  state: present, ttl: 60, priority: 30}

Further Reading

• Download at Ansible Galaxy Repository
• Source
• Selfhost.de

Previous Blog Entry

---

Last update: 2026-11-01