# airdress.dns.*

{/* Generated by scripts/generate-event-reference.mjs from https://schemas.airdress.co/operator/events/v1.json (operator v0.1.138).
    Do not edit by hand: run `pnpm generate:event-reference` and commit the result. */}

The events in the `airdress.dns` family. How to read a section, and what
each audience means, is on the [event reference](/events/) page.

## `airdress.dns.delegation_report.refused`

Owner warn Functions

The hub did not take this operator's DNS report (an HTTP status, or unreachable); the report is retried on the interval. Said when the outcome changes.

**Audience: owner.** About the airdress as a whole. Only the owner receives it: the owner's devices and the owner's subscriptions.

**Where it goes**

- **The operator's journal**, as one log line at this level, and **the event log**, where `airdress events tail` reads it.
- **Subscriptions** that name it, within its audience.
- **Functions bound to this operator's events** (`source: operator`).

**Versions**

- Version 1: first carried by operator v0.1.138.

**Data**

| Field | Type | Required | Description |
| ----- | ---- | -------- | ----------- |
| `outcome` | string | yes |  |

<details>
<summary>JSON Schema</summary>

```json
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "description": "The hub did not take this operator's DNS report (an HTTP status, or unreachable); the report is retried on the interval. Said when the outcome changes.",
  "properties": {
    "outcome": {
      "type": "string"
    }
  },
  "required": [
    "outcome"
  ],
  "title": "DelegationReportRefused",
  "type": "object"
}
```

</details>

## `airdress.dns.delegation_report.sent`

Owner info Functions

The hub accepted this operator's DNS report. Said when the outcome changes, not on every interval.

**Audience: owner.** About the airdress as a whole. Only the owner receives it: the owner's devices and the owner's subscriptions.

**Where it goes**

- **The operator's journal**, as one log line at this level, and **the event log**, where `airdress events tail` reads it.
- **Subscriptions** that name it, within its audience.
- **Functions bound to this operator's events** (`source: operator`).

**Versions**

- Version 1: first carried by operator v0.1.138.

**Data**

| Field | Type | Required | Description |
| ----- | ---- | -------- | ----------- |
| `serves_own_zone` | boolean | yes |  |
| `transfer` | boolean | yes | Whether the report offered zone transfer to the secondaries. |
| `zone` | string | yes |  |

<details>
<summary>JSON Schema</summary>

```json
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "description": "The hub accepted this operator's DNS report. Said when the outcome changes, not on every interval.",
  "properties": {
    "serves_own_zone": {
      "type": "boolean"
    },
    "transfer": {
      "description": "Whether the report offered zone transfer to the secondaries.",
      "type": "boolean"
    },
    "zone": {
      "type": "string"
    }
  },
  "required": [
    "serves_own_zone",
    "transfer",
    "zone"
  ],
  "title": "DelegationReportSent",
  "type": "object"
}
```

</details>

## `airdress.dns.transfer.enabled`

Owner info Functions

Zone transfers to the dns fleet's secondaries are on: AXFR/IXFR over TCP, signed with the TSIG key `key`, from the `allow` networks, with NOTIFY to `notify`.

**Audience: owner.** About the airdress as a whole. Only the owner receives it: the owner's devices and the owner's subscriptions.

**Where it goes**

- **The operator's journal**, as one log line at this level, and **the event log**, where `airdress events tail` reads it.
- **Subscriptions** that name it, within its audience.
- **Functions bound to this operator's events** (`source: operator`).

**Versions**

- Version 1: first carried by operator v0.1.138.

**Data**

| Field | Type | Required | Description |
| ----- | ---- | -------- | ----------- |
| `allow` | array of string | yes |  |
| `key` | string | yes | The TSIG key's name (never its secret). |
| `notify` | array of string | yes |  |
| `port` | integer (uint16) | yes |  |
| `refresh` | integer (uint32) | yes |  |

<details>
<summary>JSON Schema</summary>

```json
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "description": "Zone transfers to the dns fleet's secondaries are on: AXFR/IXFR over TCP, signed with the TSIG key `key`, from the `allow` networks, with NOTIFY to `notify`.",
  "properties": {
    "allow": {
      "items": {
        "type": "string"
      },
      "type": "array"
    },
    "key": {
      "description": "The TSIG key's name (never its secret).",
      "type": "string"
    },
    "notify": {
      "items": {
        "type": "string"
      },
      "type": "array"
    },
    "port": {
      "format": "uint16",
      "minimum": 0,
      "type": "integer"
    },
    "refresh": {
      "format": "uint32",
      "minimum": 0,
      "type": "integer"
    }
  },
  "required": [
    "allow",
    "key",
    "notify",
    "port",
    "refresh"
  ],
  "title": "DnsTransferEnabled",
  "type": "object"
}
```

</details>

## `airdress.dns.transfer.key_created`

Owner info Functions

This operator made its zone-transfer (TSIG) key, at this path. The key itself is never in the event.

**Audience: owner.** About the airdress as a whole. Only the owner receives it: the owner's devices and the owner's subscriptions.

**Where it goes**

- **The operator's journal**, as one log line at this level, and **the event log**, where `airdress events tail` reads it.
- **Subscriptions** that name it, within its audience.
- **Functions bound to this operator's events** (`source: operator`).

**Versions**

- Version 1: first carried by operator v0.1.138.

**Data**

| Field | Type | Required | Description |
| ----- | ---- | -------- | ----------- |
| `path` | string | yes |  |

<details>
<summary>JSON Schema</summary>

```json
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "description": "This operator made its zone-transfer (TSIG) key, at this path. The key itself is never in the event.",
  "properties": {
    "path": {
      "type": "string"
    }
  },
  "required": [
    "path"
  ],
  "title": "TransferKeyCreated",
  "type": "object"
}
```

</details>

## `airdress.dns.transfer.notify_failed`

Owner warn Functions

A NOTIFY could not be sent to a secondary; it refreshes on the SOA timer instead. Said once per target until it reaches it again.

**Audience: owner.** About the airdress as a whole. Only the owner receives it: the owner's devices and the owner's subscriptions.

**Where it goes**

- **The operator's journal**, as one log line at this level, and **the event log**, where `airdress events tail` reads it.
- **Subscriptions** that name it, within its audience.
- **Functions bound to this operator's events** (`source: operator`).

**Versions**

- Version 1: first carried by operator v0.1.138.

**Data**

| Field | Type | Required | Description |
| ----- | ---- | -------- | ----------- |
| `error` | string | yes |  |
| `target` | string | yes | The secondary's address and port. |

<details>
<summary>JSON Schema</summary>

```json
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "description": "A NOTIFY could not be sent to a secondary; it refreshes on the SOA timer instead. Said once per target until it reaches it again.",
  "properties": {
    "error": {
      "type": "string"
    },
    "target": {
      "description": "The secondary's address and port.",
      "type": "string"
    }
  },
  "required": [
    "error",
    "target"
  ],
  "title": "NotifyFailed",
  "type": "object"
}
```

</details>

## `airdress.dns.transfer.refused`

Owner warn

A zone-transfer question was refused: not on the allow list, unsigned, the wrong key, a bad signature or a stale time. Anybody can ask, so it stays off the bus.

**Audience: owner.** About the airdress as a whole. Only the owner receives it: the owner's devices and the owner's subscriptions.

**Where it goes**

- **The operator's journal**, as one log line at this level, and **the event log**, where `airdress events tail` reads it.
- **Subscriptions** that name it, within its audience.
- Not functions bound to this operator's events: it is kept off that path as too frequent or too internal. A subscription with a function target still receives it.

**Versions**

- Version 1: first carried by operator v0.1.138.

**Data**

| Field | Type | Required | Description |
| ----- | ---- | -------- | ----------- |
| `qtype` | string or null | no | The question's type (AXFR, IXFR, SOA), when it had one. |
| `reason` | string | yes |  |
| `src` | string (ip) | yes | Who asked. |
| `zone` | string | yes |  |

<details>
<summary>JSON Schema</summary>

```json
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "description": "A zone-transfer question was refused: not on the allow list, unsigned, the wrong key, a bad signature or a stale time. Anybody can ask, so it stays off the bus.",
  "properties": {
    "qtype": {
      "description": "The question's type (AXFR, IXFR, SOA), when it had one.",
      "type": [
        "string",
        "null"
      ]
    },
    "reason": {
      "type": "string"
    },
    "src": {
      "description": "Who asked.",
      "format": "ip",
      "type": "string"
    },
    "zone": {
      "type": "string"
    }
  },
  "required": [
    "reason",
    "src",
    "zone"
  ],
  "title": "TransferRefused",
  "type": "object"
}
```

</details>

## `airdress.dns.transfer.served`

Owner info

A signed zone-transfer question was answered, in this many messages. Said for every transfer a secondary pulls.

**Audience: owner.** About the airdress as a whole. Only the owner receives it: the owner's devices and the owner's subscriptions.

**Where it goes**

- **The operator's journal**, as one log line at this level, and **the event log**, where `airdress events tail` reads it.
- **Subscriptions** that name it, within its audience.
- Not functions bound to this operator's events: it is kept off that path as too frequent or too internal. A subscription with a function target still receives it.

**Versions**

- Version 1: first carried by operator v0.1.138.

**Data**

| Field | Type | Required | Description |
| ----- | ---- | -------- | ----------- |
| `messages` | integer (uint) | yes |  |
| `qtype` | string or null | no |  |
| `serial` | integer (uint64) | yes |  |
| `src` | string (ip) | yes | Who asked. |
| `zone` | string | yes |  |

<details>
<summary>JSON Schema</summary>

```json
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "description": "A signed zone-transfer question was answered, in this many messages. Said for every transfer a secondary pulls.",
  "properties": {
    "messages": {
      "format": "uint",
      "minimum": 0,
      "type": "integer"
    },
    "qtype": {
      "type": [
        "string",
        "null"
      ]
    },
    "serial": {
      "format": "uint64",
      "minimum": 0,
      "type": "integer"
    },
    "src": {
      "description": "Who asked.",
      "format": "ip",
      "type": "string"
    },
    "zone": {
      "type": "string"
    }
  },
  "required": [
    "messages",
    "serial",
    "src",
    "zone"
  ],
  "title": "TransferServed",
  "type": "object"
}
```

</details>