1
0
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
2023-10-09 02:39:18 +11:00
committed by GitHub
parent f661cd4777
commit 7e79713603
8 changed files with 14 additions and 14 deletions

View File

@ -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 %}

View File

@ -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.

View File

@ -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°5131″S 151°1251″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

View File

@ -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°5131″S 151°1251″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

View File

@ -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°5131″S 151°1251″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°5131″S 151°1251″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°5131″S 151°1251″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

View File

@ -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°5131″S 151°1251″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°2040″N 6°1720″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°5131″S 151°1251″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

View File

@ -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`