Operational Modes

Each provider instance can operate in one of three modes, controlling how aggressively dnsweaver manages DNS records. Set via DNSWEAVER_{NAME}_MODE or the mode field in YAML configuration.

Mode Comparison

Mode	Creates Records	Deletes Own Records	Deletes Unknown Records
managed (default)	✅	✅	❌
authoritative	✅	✅	✅
additive	✅	❌	❌

Managed Mode (Default)

Behavior: dnsweaver creates and manages records it owns, leaving all other records untouched.

- name: internal
  type: technitium
  mode: managed  # default, can be omitted

When to use:

• Most deployments — safe default
• Shared zones with manually-created records
• Testing and development environments

How ownership works:

When ownership_tracking: true (default), dnsweaver creates a TXT record alongside each DNS record to track ownership:

app.home.example.com       A      192.0.2.100
_dnsweaver.app.home.example.com  TXT    "dnsweaver-id=abc123"

Only records with matching TXT ownership records are deleted when containers stop.

Providers Without TXT Support

Some providers (AdGuard Home, Pi-hole file mode, dnsmasq) cannot store TXT records. For these providers, managed mode uses target-based ownership inference: if a record's type and target match the provider instance's configured values, dnsweaver infers it created the record and will clean it up. Records with different targets are preserved. See each provider's documentation for details.

Authoritative Mode

Use with Caution

Authoritative mode deletes any record it doesn't recognize. Only use this for zones exclusively managed by dnsweaver.

Behavior: dnsweaver takes full ownership of the zone. Records not managed by dnsweaver are deleted.

- name: internal
  type: technitium
  mode: authoritative
  domains:
    - "*.apps.internal.example.com"  # Only use on dedicated subdomains

Conflicting record types: a pre-existing record whose type cannot coexist with the configured one (for example a CNAME where an A record is configured, or the reverse) is deleted and replaced by the configured record. In managed mode the same record is replaced only when DNSWEAVER_ADOPT_EXISTING=true or when dnsweaver already owns the hostname; otherwise it is skipped and a warning is logged once. Additive mode never replaces it.

When to use:

• Dedicated zones exclusively for container DNS
• Automated environments where manual records shouldn't exist
• GitOps workflows where DNS should match container state exactly

Safeguards:

• Only affects records matching the provider's domain patterns
• TXT ownership records are still created for audit trail
• Dry-run mode (DNSWEAVER_DRY_RUN=true) logs what would be deleted

Additive Mode

Behavior: dnsweaver only creates records, never deletes them — even for stopped containers.

- name: public-dns
  type: cloudflare
  mode: additive

When to use:

• Migration scenarios — gradually adding records
• Read-mostly providers where deletion is handled separately
• Hybrid setups where another system manages cleanup

Important: In additive mode:

• Stopped containers keep their DNS records
• Manual cleanup is required
• DNSWEAVER_CLEANUP_ORPHANS setting is ignored for this provider

Per-Provider Configuration

Each provider instance has its own mode setting. You can mix modes across providers:

providers:
  # Internal DNS: fully managed
  - name: internal
    type: technitium
    mode: managed
    domains: ["*.home.example.com"]

  # Public DNS: additive only (manual cleanup)
  - name: public
    type: cloudflare
    mode: additive
    domains: ["*.example.com"]

  # Dedicated container zone: authoritative
  - name: containers
    type: technitium
    mode: authoritative
    domains: ["*.containers.internal.example.com"]

Or via environment variables:

DNSWEAVER_INSTANCES=internal,public,containers
DNSWEAVER_INTERNAL_MODE=managed
DNSWEAVER_PUBLIC_MODE=additive
DNSWEAVER_CONTAINERS_MODE=authoritative

Related Settings

These global settings interact with operational modes:

Setting	Effect
DNSWEAVER_CLEANUP_ORPHANS	If false, disables deletion globally (overrides managed/authoritative)
DNSWEAVER_CLEANUP_ON_STOP	If false, only delete records when containers are removed, not stopped
DNSWEAVER_OWNERSHIP_TRACKING	If false, dnsweaver can't distinguish its own records from others
DNSWEAVER_ADOPT_EXISTING	Global default for claiming pre-existing records. Managed mode without adoption leaves unowned records untouched, including records with the wrong target or a conflicting type.
DNSWEAVER_{NAME}_ADOPT_EXISTING	Overrides the global adoption policy for one provider instance.
DNSWEAVER_{NAME}_ADOPT_EXISTING_ALLOW_OVERRIDES	Lets workload labels enable adoption for one provider instance. Defaults to false. Workload labels may always disable adoption.

Adoption precedence and workload trust

The effective adoption policy is global, then provider instance, then workload, then named record. dnsweaver.adopt applies to hostnames found by any source on the workload. dnsweaver.records.<name>.adopt is more specific and wins for that named record.

Workload configuration is not trusted to claim existing DNS records by default. An adopt=true label or annotation is ignored unless the matching provider sets ADOPT_EXISTING_ALLOW_OVERRIDES=true. An adopt=false value is always honored because it only narrows dnsweaver's authority.

Choosing the Right Mode

graph TD
    A[Do other systems create records in this zone?] -->|Yes| B[Do you need automatic cleanup?]
    A -->|No| C[authoritative]
    B -->|Yes| D[managed]
    B -->|No| E[additive]

Default recommendation: Start with managed mode. Only use authoritative for zones you completely control, and additive for special integration scenarios.