mirror of
https://github.com/StackExchange/dnscontrol.git
synced 2024-05-11 05:55:12 +00:00
Fix the return types of *_BUILDER functions (#2583)
Co-authored-by: Tom Limoncelli <tlimoncelli@stackoverflow.com>
This commit is contained in:
Purrrpley
GitHub
@ -1,59 +0,0 @@
|
||||
---
|
||||
name: CAA_BUILDER
|
||||
parameters:
|
||||
- label
|
||||
- iodef
|
||||
- iodef_critical
|
||||
- issue
|
||||
- issuewild
|
||||
parameters_object: true
|
||||
parameter_types:
|
||||
label: string?
|
||||
iodef: string
|
||||
iodef_critical: boolean?
|
||||
issue: string[]
|
||||
issuewild: string
|
||||
---
|
||||
|
||||
DNSControl contains a `CAA_BUILDER` which can be used to simply create
|
||||
[`CAA()`](../domain/CAA.md) records for your domains. Instead of creating each [`CAA()`](../domain/CAA.md) record
|
||||
individually, you can simply configure your report mail address, the
|
||||
authorized certificate authorities and the builder cares about the rest.
|
||||
|
||||
## Example
|
||||
|
||||
For example you can use:
|
||||
|
||||
{% code title="dnsconfig.js" %}
|
||||
```javascript
|
||||
CAA_BUILDER({
|
||||
label: "@",
|
||||
iodef: "mailto:test@example.com",
|
||||
iodef_critical: true,
|
||||
issue: [
|
||||
"letsencrypt.org",
|
||||
"comodoca.com",
|
||||
],
|
||||
issuewild: "none",
|
||||
})
|
||||
```
|
||||
{% endcode %}
|
||||
|
||||
The parameters are:
|
||||
|
||||
* `label:` The label of the CAA record. (Optional. Default: `"@"`)
|
||||
* `iodef:` Report all violation to configured mail address.
|
||||
* `iodef_critical:` This can be `true` or `false`. If enabled and CA does not support this record, then certificate issue will be refused. (Optional. Default: `false`)
|
||||
* `issue:` An array of CAs which are allowed to issue certificates. (Use `"none"` to refuse all CAs)
|
||||
* `issuewild:` An array of CAs which are allowed to issue wildcard certificates. (Can be simply `"none"` to refuse issuing wildcard certificates for all CAs)
|
||||
|
||||
`CAA_BUILDER()` returns multiple records (when configured as example above):
|
||||
|
||||
{% code title="dnsconfig.js" %}
|
||||
```javascript
|
||||
CAA("@", "iodef", "mailto:test@example.com", CAA_CRITICAL)
|
||||
CAA("@", "issue", "letsencrypt.org")
|
||||
CAA("@", "issue", "comodoca.com")
|
||||
CAA("@", "issuewild", ";")
|
||||
```
|
||||
{% endcode %}
|
||||
@ -1,125 +0,0 @@
|
||||
---
|
||||
name: DMARC_BUILDER
|
||||
parameters:
|
||||
- label
|
||||
- version
|
||||
- policy
|
||||
- subdomainPolicy
|
||||
- alignmentSPF
|
||||
- alignmentDKIM
|
||||
- percent
|
||||
- rua
|
||||
- ruf
|
||||
- failureOptions
|
||||
- failureFormat
|
||||
- reportInterval
|
||||
- ttl
|
||||
parameters_object: true
|
||||
parameter_types:
|
||||
label: string?
|
||||
version: string?
|
||||
policy: "'none' | 'quarantine' | 'reject'"
|
||||
subdomainPolicy: "'none' | 'quarantine' | 'reject'?"
|
||||
alignmentSPF: "'strict' | 's' | 'relaxed' | 'r'?"
|
||||
alignmentDKIM: "'strict' | 's' | 'relaxed' | 'r'?"
|
||||
percent: number?
|
||||
rua: string[]?
|
||||
ruf: string[]?
|
||||
failureOptions: "{ SPF: boolean, DKIM: boolean } | string?"
|
||||
failureFormat: string?
|
||||
reportInterval: Duration?
|
||||
ttl: Duration?
|
||||
---
|
||||
|
||||
DNSControl contains a `DMARC_BUILDER` which can be used to simply create
|
||||
DMARC policies for your domains.
|
||||
|
||||
|
||||
## Example
|
||||
|
||||
### Simple example
|
||||
|
||||
{% code title="dnsconfig.js" %}
|
||||
```javascript
|
||||
DMARC_BUILDER({
|
||||
policy: "reject",
|
||||
ruf: [
|
||||
"mailto:mailauth-reports@example.com",
|
||||
],
|
||||
})
|
||||
```
|
||||
{% endcode %}
|
||||
|
||||
This yield the following record:
|
||||
|
||||
```text
|
||||
@ IN TXT "v=DMARC1; p=reject; ruf=mailto:mailauth-reports@example.com"
|
||||
```
|
||||
|
||||
### Advanced example
|
||||
|
||||
{% code title="dnsconfig.js" %}
|
||||
```javascript
|
||||
DMARC_BUILDER({
|
||||
policy: "reject",
|
||||
subdomainPolicy: "quarantine",
|
||||
percent: 50,
|
||||
alignmentSPF: "r",
|
||||
alignmentDKIM: "strict",
|
||||
rua: [
|
||||
"mailto:mailauth-reports@example.com",
|
||||
"https://dmarc.example.com/submit",
|
||||
],
|
||||
ruf: [
|
||||
"mailto:mailauth-reports@example.com",
|
||||
],
|
||||
failureOptions: "1",
|
||||
reportInterval: "1h",
|
||||
});
|
||||
```
|
||||
{% endcode %}
|
||||
|
||||
{% code title="dnsconfig.js" %}
|
||||
```javascript
|
||||
DMARC_BUILDER({
|
||||
label: "insecure",
|
||||
policy: "none",
|
||||
ruf: [
|
||||
"mailto:mailauth-reports@example.com",
|
||||
],
|
||||
failureOptions: {
|
||||
SPF: false,
|
||||
DKIM: true,
|
||||
},
|
||||
});
|
||||
```
|
||||
{% endcode %}
|
||||
|
||||
This yields the following records:
|
||||
|
||||
```text
|
||||
@ IN TXT "v=DMARC1; p=reject; sp=quarantine; adkim=s; aspf=r; pct=50; rua=mailto:mailauth-reports@example.com,https://dmarc.example.com/submit; ruf=mailto:mailauth-reports@example.com; fo=1; ri=3600"
|
||||
insecure IN TXT "v=DMARC1; p=none; ruf=mailto:mailauth-reports@example.com; fo=d"
|
||||
```
|
||||
|
||||
|
||||
### Parameters
|
||||
|
||||
* `label:` The DNS label for the DMARC record (`_dmarc` prefix is added, default: `"@"`)
|
||||
* `version:` The DMARC version to be used (default: `DMARC1`)
|
||||
* `policy:` The DMARC policy (`p=`), must be one of `"none"`, `"quarantine"`, `"reject"`
|
||||
* `subdomainPolicy:` The DMARC policy for subdomains (`sp=`), must be one of `"none"`, `"quarantine"`, `"reject"` (optional)
|
||||
* `alignmentSPF:` `"strict"`/`"s"` or `"relaxed"`/`"r"` alignment for SPF (`aspf=`, default: `"r"`)
|
||||
* `alignmentDKIM:` `"strict"`/`"s"` or `"relaxed"`/`"r"` alignment for DKIM (`adkim=`, default: `"r"`)
|
||||
* `percent:` Number between `0` and `100`, percentage for which policies are applied (`pct=`, default: `100`)
|
||||
* `rua:` Array of aggregate report targets (optional)
|
||||
* `ruf:` Array of failure report targets (optional)
|
||||
* `failureOptions:` Object or string; Object containing booleans `SPF` and `DKIM`, string is passed raw (`fo=`, default: `"0"`)
|
||||
* `failureFormat:` Format in which failure reports are requested (`rf=`, default: `"afrf"`)
|
||||
* `reportInterval:` Interval in which reports are requested (`ri=`)
|
||||
* `ttl:` Input for `TTL` method (optional)
|
||||
|
||||
### Caveats
|
||||
|
||||
* TXT records are automatically split using `AUTOSPLIT`.
|
||||
* URIs in the `rua` and `ruf` arrays are passed raw. You must percent-encode all commas and exclamation points in the URI itself.
|
||||
@ -1,75 +0,0 @@
|
||||
---
|
||||
name: LOC_BUILDER_DD
|
||||
parameters:
|
||||
- label
|
||||
- x
|
||||
- y
|
||||
- alt
|
||||
- ttl
|
||||
parameters_object: true
|
||||
parameter_types:
|
||||
label: string?
|
||||
x: number
|
||||
y: number
|
||||
alt: number?
|
||||
ttl: Duration?
|
||||
---
|
||||
|
||||
`LOC_BUILDER_DD({})` actually takes an object with the following properties:
|
||||
|
||||
- label (optional, defaults to `@`)
|
||||
- x (float32)
|
||||
- y (float32)
|
||||
- alt (float32, optional)
|
||||
- ttl (optional)
|
||||
|
||||
A helper to build [`LOC`](../domain/LOC.md) records. Supply four parameters instead of 12.
|
||||
|
||||
Internally assumes some defaults for [`LOC`](../domain/LOC.md) records.
|
||||
|
||||
|
||||
The cartesian coordinates are decimal degrees, like you typically find in e.g. Google Maps.
|
||||
|
||||
Examples.
|
||||
|
||||
Big Ben:
|
||||
`51.50084265331501, -0.12462541415599787`
|
||||
|
||||
The White House:
|
||||
`38.89775977858357, -77.03655125982903`
|
||||
|
||||
|
||||
{% code title="dnsconfig.js" %}
|
||||
```javascript
|
||||
D("example.com", REG_MY_PROVIDER, DnsProvider(DSP_MY_PROVIDER),
|
||||
LOC_BUILDER_DD({
|
||||
label: "big-ben",
|
||||
x: 51.50084265331501,
|
||||
y: -0.12462541415599787,
|
||||
alt: 6,
|
||||
})
|
||||
, LOC_BUILDER_DD({
|
||||
label: "white-house",
|
||||
x: 38.89775977858357,
|
||||
y: -77.03655125982903,
|
||||
alt: 19,
|
||||
})
|
||||
, LOC_BUILDER_DD({
|
||||
label: "white-house-ttl",
|
||||
x: 38.89775977858357,
|
||||
y: -77.03655125982903,
|
||||
alt: 19,
|
||||
ttl: "5m",
|
||||
})
|
||||
);
|
||||
|
||||
```
|
||||
{% endcode %}
|
||||
|
||||
|
||||
Part of the series:
|
||||
* [`LOC()`](../domain/LOC.md) - build a `LOC` by supplying all 12 parameters
|
||||
* [`LOC_BUILDER_DD({})`](../record/LOC_BUILDER_DD.md) - accepts cartesian x, y
|
||||
* [`LOC_BUILDER_DMS_STR({})`](../record/LOC_BUILDER_DMS_STR.md) - accepts DMS 33°51′31″S 151°12′51″E
|
||||
* [`LOC_BUILDER_DMM_STR({})`](../record/LOC_BUILDER_DMM_STR.md) - accepts DMM 25.24°S 153.15°E
|
||||
* [`LOC_BUILDER_STR({})`](../record/LOC_BUILDER_STR.md) - tries the cooordinate string in all `LOC_BUILDER_DM*_STR()` functions until one works
|
||||
@ -1,55 +0,0 @@
|
||||
---
|
||||
name: LOC_BUILDER_DMM_STR
|
||||
parameters:
|
||||
- label
|
||||
- str
|
||||
- alt
|
||||
- ttl
|
||||
parameters_object: true
|
||||
parameter_types:
|
||||
label: string?
|
||||
str: string
|
||||
alt: number?
|
||||
ttl: Duration?
|
||||
---
|
||||
|
||||
`LOC_BUILDER_DMM({})` actually takes an object with the following properties:
|
||||
|
||||
- label (string, optional, defaults to `@`)
|
||||
- str (string)
|
||||
- alt (float32, optional)
|
||||
- ttl (optional)
|
||||
|
||||
A helper to build [`LOC`](../domain/LOC.md) records. Supply three parameters instead of 12.
|
||||
|
||||
Internally assumes some defaults for [`LOC`](../domain/LOC.md) records.
|
||||
|
||||
|
||||
Accepts a string with decimal minutes (DMM) coordinates in the form: 25.24°S 153.15°E
|
||||
|
||||
Note that the following are acceptable forms (symbols differ):
|
||||
* `25.24°S 153.15°E`
|
||||
* `25.24 S 153.15 E`
|
||||
* `25.24° S 153.15° E`
|
||||
* `25.24S 153.15E`
|
||||
|
||||
{% code title="dnsconfig.js" %}
|
||||
```javascript
|
||||
D("example.com", REG_MY_PROVIDER, DnsProvider(DSP_MY_PROVIDER),
|
||||
LOC_BUILDER_STR({
|
||||
label: "tasmania",
|
||||
str: "42°S 147°E",
|
||||
alt: 3,
|
||||
})
|
||||
);
|
||||
|
||||
```
|
||||
{% endcode %}
|
||||
|
||||
|
||||
Part of the series:
|
||||
* [`LOC()`](../domain/LOC.md) - build a `LOC` by supplying all 12 parameters
|
||||
* [`LOC_BUILDER_DD({})`](../record/LOC_BUILDER_DD.md) - accepts cartesian x, y
|
||||
* [`LOC_BUILDER_DMS_STR({})`](../record/LOC_BUILDER_DMS_STR.md) - accepts DMS 33°51′31″S 151°12′51″E
|
||||
* [`LOC_BUILDER_DMM_STR({})`](../record/LOC_BUILDER_DMM_STR.md) - accepts DMM 25.24°S 153.15°E
|
||||
* [`LOC_BUILDER_STR({})`](../record/LOC_BUILDER_STR.md) - tries the cooordinate string in all `LOC_BUILDER_DM*_STR()` functions until one works
|
||||
@ -1,56 +0,0 @@
|
||||
---
|
||||
name: LOC_BUILDER_DMS_STR
|
||||
parameters:
|
||||
- label
|
||||
- str
|
||||
- alt
|
||||
- ttl
|
||||
parameters_object: true
|
||||
parameter_types:
|
||||
label: string?
|
||||
str: string
|
||||
alt: number?
|
||||
ttl: Duration?
|
||||
---
|
||||
|
||||
`LOC_BUILDER_DMS_STR({})` actually takes an object with the following properties:
|
||||
|
||||
- label (string, optional, defaults to `@`)
|
||||
- str (string)
|
||||
- alt (float32, optional)
|
||||
- ttl (optional)
|
||||
|
||||
A helper to build [`LOC`](../domain/LOC.md) records. Supply three parameters instead of 12.
|
||||
|
||||
Internally assumes some defaults for [`LOC`](../domain/LOC.md) records.
|
||||
|
||||
|
||||
Accepts a string with degrees, minutes, and seconds (DMS) coordinates in the form: 41°24'12.2"N 2°10'26.5"E
|
||||
|
||||
Note that the following are acceptable forms (symbols differ):
|
||||
* `33°51′31″S 151°12′51″E`
|
||||
* `33°51'31"S 151°12'51"E`
|
||||
* `33d51m31sS 151d12m51sE`
|
||||
* `33d51m31s S 151d12m51s E`
|
||||
|
||||
{% code title="dnsconfig.js" %}
|
||||
```javascript
|
||||
D("example.com", REG_MY_PROVIDER, DnsProvider(DSP_MY_PROVIDER),
|
||||
LOC_BUILDER_DMS_STR({
|
||||
label: "sydney-opera-house",
|
||||
str: "33°51′31″S 151°12′51″E",
|
||||
alt: 4,
|
||||
ttl: "5m",
|
||||
})
|
||||
);
|
||||
|
||||
```
|
||||
{% endcode %}
|
||||
|
||||
|
||||
Part of the series:
|
||||
* [`LOC()`](../domain/LOC.md) - build a `LOC` by supplying all 12 parameters
|
||||
* [`LOC_BUILDER_DD({})`](../record/LOC_BUILDER_DD.md) - accepts cartesian x, y
|
||||
* [`LOC_BUILDER_DMS_STR({})`](../record/LOC_BUILDER_DMS_STR.md) - accepts DMS 33°51′31″S 151°12′51″E
|
||||
* [`LOC_BUILDER_DMM_STR({})`](../record/LOC_BUILDER_DMM_STR.md) - accepts DMM 25.24°S 153.15°E
|
||||
* [`LOC_BUILDER_STR({})`](../record/LOC_BUILDER_STR.md) - tries the cooordinate string in all `LOC_BUILDER_DM*_STR()` functions until one works
|
||||
@ -1,62 +0,0 @@
|
||||
---
|
||||
name: LOC_BUILDER_STR
|
||||
parameters:
|
||||
- label
|
||||
- str
|
||||
- alt
|
||||
- ttl
|
||||
parameters_object: true
|
||||
parameter_types:
|
||||
label: string?
|
||||
str: string
|
||||
alt: number?
|
||||
ttl: Duration?
|
||||
---
|
||||
|
||||
`LOC_BUILDER_STR({})` actually takes an object with the following: properties.
|
||||
|
||||
- label (optional, defaults to `@`)
|
||||
- str (string)
|
||||
- alt (float32, optional)
|
||||
- ttl (optional)
|
||||
|
||||
A helper to build [`LOC`](../domain/LOC.md) records. Supply three parameters instead of 12.
|
||||
|
||||
Internally assumes some defaults for [`LOC`](../domain/LOC.md) records.
|
||||
|
||||
|
||||
Accepts a string and tries all `LOC_BUILDER_DM*_STR({})` methods:
|
||||
* [`LOC_BUILDER_DMS_STR({})`](../record/LOC_BUILDER_DMS_STR.md) - accepts DMS 33°51′31″S 151°12′51″E
|
||||
* [`LOC_BUILDER_DMM_STR({})`](../record/LOC_BUILDER_DMM_STR.md) - accepts DMM 25.24°S 153.15°E
|
||||
|
||||
|
||||
{% code title="dnsconfig.js" %}
|
||||
```javascript
|
||||
D("example.com", REG_MY_PROVIDER, DnsProvider(DSP_MY_PROVIDER),
|
||||
, LOC_BUILDER_STR({
|
||||
label: "old-faithful",
|
||||
str: "44.46046°N 110.82815°W",
|
||||
alt: 2240,
|
||||
})
|
||||
, LOC_BUILDER_STR({
|
||||
label: "ribblehead-viaduct",
|
||||
str: "54.210436°N 2.370231°W",
|
||||
alt: 300,
|
||||
})
|
||||
, LOC_BUILDER_STR({
|
||||
label: "guinness-brewery",
|
||||
str: "53°20′40″N 6°17′20″W",
|
||||
alt: 300,
|
||||
})
|
||||
);
|
||||
|
||||
```
|
||||
{% endcode %}
|
||||
|
||||
|
||||
Part of the series:
|
||||
* [`LOC()`](../domain/LOC.md) - build a `LOC` by supplying all 12 parameters
|
||||
* [`LOC_BUILDER_DD({})`](../record/LOC_BUILDER_DD.md) - accepts cartesian x, y
|
||||
* [`LOC_BUILDER_DMS_STR({})`](../record/LOC_BUILDER_DMS_STR.md) - accepts DMS 33°51′31″S 151°12′51″E
|
||||
* [`LOC_BUILDER_DMM_STR({})`](../record/LOC_BUILDER_DMM_STR.md) - accepts DMM 25.24°S 153.15°E
|
||||
* [`LOC_BUILDER_STR({})`](../record/LOC_BUILDER_STR.md) - tries the cooordinate string in all `LOC_BUILDER_DM*_STR()` functions until one works
|
||||
@ -1,70 +0,0 @@
|
||||
---
|
||||
name: M365_BUILDER
|
||||
parameters:
|
||||
- label
|
||||
- mx
|
||||
- autodiscover
|
||||
- dkim
|
||||
- skypeForBusiness
|
||||
- mdm
|
||||
- domainGUID
|
||||
- initialDomain
|
||||
parameters_object: true
|
||||
parameter_types:
|
||||
label: string?
|
||||
mx: boolean?
|
||||
autodiscover: boolean?
|
||||
dkim: boolean?
|
||||
skypeForBusiness: boolean?
|
||||
mdm: boolean?
|
||||
domainGUID: string?
|
||||
initialDomain: string?
|
||||
---
|
||||
|
||||
DNSControl offers a `M365_BUILDER` which can be used to simply set up Microsoft 365 for a domain in an opinionated way.
|
||||
|
||||
It defaults to a setup without support for legacy Skype for Business applications.
|
||||
It doesn't set up SPF or DMARC. See [`SPF_BUILDER`](/language-reference/record-modifiers/dmarc_builder) and [`DMARC_BUILDER`](/language-reference/record-modifiers/spf_builder).
|
||||
|
||||
## Example
|
||||
|
||||
### Simple example
|
||||
|
||||
{% code title="dnsconfig.js" %}
|
||||
```javascript
|
||||
M365_BUILDER({
|
||||
initialDomain: "example.onmicrosoft.com",
|
||||
});
|
||||
```
|
||||
{% endcode %}
|
||||
|
||||
This sets up `MX` records, Autodiscover, and DKIM.
|
||||
|
||||
### Advanced example
|
||||
|
||||
{% code title="dnsconfig.js" %}
|
||||
```javascript
|
||||
M365_BUILDER({
|
||||
label: "test",
|
||||
mx: false,
|
||||
autodiscover: false,
|
||||
dkim: false,
|
||||
mdm: true,
|
||||
domainGUID: "test-example-com", // Can be automatically derived in this case, if example.com is the context.
|
||||
initialDomain: "example.onmicrosoft.com",
|
||||
});
|
||||
```
|
||||
{% endcode %}
|
||||
|
||||
This sets up Mobile Device Management only.
|
||||
|
||||
### Parameters
|
||||
|
||||
* `label` The label of the Microsoft 365 domain, useful if it is a subdomain (default: `"@"`)
|
||||
* `mx` Set an `MX` record? (default: `true`)
|
||||
* `autodiscover` Set Autodiscover `CNAME` record? (default: `true`)
|
||||
* `dkim` Set DKIM `CNAME` records? (default: `true`)
|
||||
* `skypeForBusiness` Set Skype for Business/Microsoft Teams records? (default: `false`)
|
||||
* `mdm` Set Mobile Device Management records? (default: `false`)
|
||||
* `domainGUID` The GUID of _this_ Microsoft 365 domain (default: `<label>.<context>` with `.` replaced by `-`, no default if domain contains dashes)
|
||||
* `initialDomain` The initial domain of your Microsoft 365 tenant/account, ends in `onmicrosoft.com`
|
||||
Reference in New Issue
Block a user