openapi: 3.1.0
info:
title: systemd-resolved (org.freedesktop.resolve1)
version: '1.0'
summary: D-Bus API of systemd-resolved modeled as REST operations.
description: |
Documentation/contract artifact for the `org.freedesktop.resolve1` D-Bus interface set on the
system bus. systemd-resolved provides hostname/address/record/service resolution using DNS
(incl. DNS-over-TLS), Multicast DNS, and LLMNR, plus DNSSEC validation and per-link DNS
configuration.
license: { name: LGPL-2.1-or-later, url: https://github.com/systemd/systemd/blob/main/LICENSES/LGPL-2.1-or-later.txt }
servers: [{ url: 'dbus://system/org.freedesktop.resolve1' }]
tags:
- name: Resolution
- name: Configuration
- name: Cache
paths:
/resolve/hostname:
post:
tags: [Resolution]
operationId: ResolveHostname
summary: Resolve A Hostname To Addresses
description: Mirrors `ResolveHostname(ifindex, name, family, flags)`.
requestBody:
content:
application/json:
schema:
type: object
required: [name]
properties:
ifindex: { type: integer, default: 0 }
name: { type: string }
family: { type: integer, description: 'AF_UNSPEC=0, AF_INET=2, AF_INET6=10', default: 0 }
flags: { type: integer, default: 0 }
responses: { '200': { description: Resolved addresses., content: { application/json: { schema: { $ref: '#/components/schemas/AddressList' } } } } }
/resolve/address:
post:
tags: [Resolution]
operationId: ResolveAddress
summary: Resolve An Address To Hostnames
description: Mirrors `ResolveAddress(ifindex, family, address, flags)`.
requestBody:
content:
application/json:
schema:
type: object
required: [family, address]
properties:
ifindex: { type: integer, default: 0 }
family: { type: integer }
address: { type: array, items: { type: integer } }
flags: { type: integer, default: 0 }
responses: { '200': { description: Resolved names., content: { application/json: { schema: { type: array, items: { type: object, properties: { ifindex: { type: integer }, name: { type: string } } } } } } } }
/resolve/record:
post:
tags: [Resolution]
operationId: ResolveRecord
summary: Resolve A Generic DNS Resource Record
description: Mirrors `ResolveRecord(ifindex, name, class, type, flags)`.
requestBody:
content:
application/json:
schema:
type: object
required: [name, class, type]
properties:
ifindex: { type: integer, default: 0 }
name: { type: string }
class: { type: integer, description: DNS class (1=IN). }
type: { type: integer, description: DNS RR type (1=A, 28=AAAA, 5=CNAME, 16=TXT, 33=SRV, ...). }
flags: { type: integer, default: 0 }
responses: { '200': { description: Array of raw RRs., content: { application/json: { schema: { type: array, items: { type: object } } } } } }
/resolve/service:
post:
tags: [Resolution]
operationId: ResolveService
summary: Resolve A DNS-SD/SRV Service
description: Mirrors `ResolveService(ifindex, name, type, domain, family, flags)`.
requestBody:
content:
application/json:
schema:
type: object
properties:
ifindex: { type: integer, default: 0 }
name: { type: string }
type: { type: string }
domain: { type: string }
family: { type: integer, default: 0 }
flags: { type: integer, default: 0 }
responses: { '200': { description: Service records with TXT data., content: { application/json: { schema: { type: object, additionalProperties: true } } } } }
/cache/flush:
post:
tags: [Cache]
operationId: FlushCaches
summary: Flush All DNS Caches
description: Mirrors `FlushCaches()`.
responses: { '204': { description: Cache flushed. } }
/cache/reset-server-features:
post:
tags: [Cache]
operationId: ResetServerFeatures
summary: Reset Server Feature Detection
description: Mirrors `ResetServerFeatures()`.
responses: { '204': { description: Reset. } }
/links/{ifindex}/dns:
parameters: [{ name: ifindex, in: path, required: true, schema: { type: integer } }]
put:
tags: [Configuration]
operationId: SetLinkDNS
summary: Set DNS Servers On A Link
description: Mirrors `SetLinkDNS(ifindex, servers)`.
requestBody: { content: { application/json: { schema: { type: object, properties: { servers: { type: array, items: { type: object, properties: { family: { type: integer }, address: { type: array, items: { type: integer } } } } } } } } } }
responses: { '204': { description: Updated. } }
/links/{ifindex}/dnssec:
parameters: [{ name: ifindex, in: path, required: true, schema: { type: integer } }]
put:
tags: [Configuration]
operationId: SetLinkDNSSEC
summary: Set DNSSEC Mode On A Link
description: Mirrors `SetLinkDNSSEC(ifindex, mode)`. Mode is `yes`, `no`, or `allow-downgrade`.
requestBody: { content: { application/json: { schema: { type: object, properties: { mode: { type: string, enum: [yes, no, allow-downgrade] } } } } } }
responses: { '204': { description: Updated. } }
/links/{ifindex}/dns-over-tls:
parameters: [{ name: ifindex, in: path, required: true, schema: { type: integer } }]
put:
tags: [Configuration]
operationId: SetLinkDNSOverTLS
summary: Set DNS-over-TLS Mode On A Link
description: Mirrors `SetLinkDNSOverTLS(ifindex, mode)`. Mode is `yes`, `no`, or `opportunistic`.
requestBody: { content: { application/json: { schema: { type: object, properties: { mode: { type: string, enum: [yes, no, opportunistic] } } } } } }
responses: { '204': { description: Updated. } }
components:
schemas:
AddressList:
type: array
items:
type: object
properties:
ifindex: { type: integer }
family: { type: integer }
address: { type: array, items: { type: integer } }