mesh-catalog/modules/dnsmasq/module.json

{
  "module": "dnsmasq",
  "version": "1",
  "provides": [
    {
      "name": "wildcard-resolution",
      "scope": "mesh"
    }
  ],
  "requires": [
    "mesh-addressing"
  ],
  "emits": [
    "name.added",
    "name.removed"
  ],
  "own-secrets": {
    "broker": "${dir:mesh-state}/broker"
  },
  "claims": [
    {
      "name": "mesh-dns-resolver",
      "scope": "mesh"
    }
  ],
  "listens": [
    {
      "name": "dns-udp",
      "port": 53,
      "protocol": "udp",
      "from": "mesh",
      "why": "the mesh's one resolver (ADR 0194, 0196): every node's and every container's first resolver — the mesh's own names answered here, a module's zone forwarded to it, the rest forwarded upstream",
      "fixed": true
    },
    {
      "name": "dns-tcp",
      "port": 53,
      "protocol": "tcp",
      "from": "mesh",
      "why": "the same names over tcp, which a resolver answers on as well and is asked for whenever an answer will not fit in a datagram. Declared because the daemon serves it: a declaration that covers one of the two protocols its own service listens on leaves the other closed while everything reports success",
      "fixed": true
    }
  ],
  "resources": [
    {
      "id": "mesh-state",
      "type": "directory",
      "mode": "0700",
      "place": "mesh"
    },
    {
      "id": "package",
      "type": "package",
      "package": "dnsmasq"
    },
    {
      "id": "config",
      "type": "file",
      "path": "/etc/dnsmasq.conf",
      "mode": "0644",
      "content": "# Managed by the mesh. dnsmasq's own defaults are replaced whole rather than\n# patched, because this module owns the file and a patch would leave whatever\n# was there before to be discovered later.\n#\n# This is the mesh's one resolver (novox/hq ADR 0194, 0196): it holds the\n# `mesh-dns-resolver` seat, every node and every container asks it first, and a\n# public resolver is asked only when it is silent. It holds the mesh's own names\n# and nothing else (ADR 0191) — no copy of them lives on any other machine.\n\n# What the mesh computed: one wildcard per machine — its name and everything\n# under it — and the mesh's own suffix as a local domain, so a name under it is\n# answered here or not at all and is never asked upstream. Rewritten whenever a\n# machine joins or leaves, which is why the service below restarts on it: a\n# reload makes dnsmasq re-read hosts files, not its configuration, and a\n# wildcard is configuration.\nconf-file=/etc/mesh-resolver/nodes.conf\n\n# Every zone a module answers itself (ADR 0199): one forwarding line per zone, to\n# the private address of the machine its module runs on and the port its\n# answerer is published on. Nothing in a zone is answered here; what names a zone\n# holds is the module's. Rewritten whenever a zone is declared or moves, and the\n# service restarts on it for the same reason as above.\nconf-file=/etc/mesh-resolver/zones.conf\n\n# Where it answers: this machine's private address, so every node — and every\n# container on every node, which copies its machine's resolvers — can ask; and\n# loopback, for this machine's own use. Never a LAN address: a device that is\n# not a member cannot reach what the mesh's names point at, and a LAN's resolver\n# is its router's (ADR 0194).\n#\n# Named as an ADDRESS and not as the interface that carries it, on purpose. A\n# container's query is addressed to this address but arrives on the runtime's\n# bridge, and dnsmasq checks every query against what it was told to answer on:\n# an `interface=` line admits queries by the interface they arrive on, a\n# `listen-address=` line by the address they are sent to. With `interface=mesh0`\n# alone, a query from a container was received and dropped without a word\n# (novox/hq 04-ISSUES/110). The address admits it whatever bridge it comes in on.\n#\n# bind-dynamic rather than bind-interfaces: the private address does not exist\n# until the machine is on the private network, and binding an address that is\n# not there yet fails to start rather than waiting for it.\nbind-dynamic\nlisten-address=${machine:address}\nlisten-address=127.0.0.1\n\n# **It must never read resolv.conf to find out where to forward.** This\n# machine's resolv.conf names this resolver — so a resolver that read it for\n# upstreams would find itself, and every query it could not answer locally would\n# loop until its receive queue filled. That is not theoretical: it filled with\n# 15KB of queries and every lookup on the machine hung. no-resolv makes that loop\n# impossible: the upstreams are the two lines below, and nothing on the machine\n# can redirect them. The mesh's own names never reach them: the local= line in\n# the file above stops them here, answered or refused.\nno-resolv\nserver=1.1.1.1\nserver=8.8.8.8\n\n# Both upstreams validate DNSSEC and say so with the Authenticated Data bit,\n# and this passes that bit down rather than dropping it, which dnsmasq does\n# unless told. It does not validate itself: an answer's trust is the upstream's\n# and the path to it, which is what a forwarding resolver's trust always was.\n# Without it a program that refuses to run behind a resolver that does not\n# validate — a mail system's admin does exactly that check at start — cannot\n# use this resolver (novox/hq 04-ISSUES/171).\nproxy-dnssec\n\n# A name without a dot is never forwarded, and reverse lookups of private ranges\n# are answered here rather than asking the world who 10.x is.\ndomain-needed\nbogus-priv\n\n# **No hosts file, and no operator's files.** This machine's /etc/hosts is its\n# own — the hosts module's block and the operator's lines (ADR 0199) — and the\n# mesh's resolver answers every node, so a line written for one machine's own\n# programs must not become an answer for all of them. Every per-node resolver\n# went wrong exactly here: a hosts file read once at start, an operator's old\n# line beside the mesh's, a drop-in read from a directory nobody owned.\nno-hosts\n"
    },
    {
      "id": "service",
      "type": "service",
      "unit": "dnsmasq.service",
      "state": "running",
      "boot": "enabled",
      "restart-on": [
        "config",
        "dnsmasq.fact-node-zones",
        "dnsmasq.fact-zones"
      ]
    }
  ],
  "facts": {
    "node-zones": {
      "path": "/etc/mesh-resolver/nodes.conf",
      "template": "# Generated by the mesh. Do not edit — this file is replaced whenever a machine\n# joins or leaves, and an edit would survive until then and vanish.\n\nlocal=/{{.Suffix}}/\n{{range .Machines}}address=/{{.FQDN}}/{{.Address}}\n{{end}}"
    },
    "zones": {
      "path": "/etc/mesh-resolver/zones.conf",
      "template": "# Generated by the mesh. Do not edit — this file is replaced whenever a module declares a zone or\n# its machine moves (novox/hq ADR 0199). One forwarding line per zone, to the module answering it.\n\n{{range .Zones}}server=/{{.Zone}}/{{.Address}}#{{.Port}}\n{{end}}"
    }
  }
}