mirror/stackexchange-dnscontrol
1
0
Fork 0
mirror of https://github.com/StackExchange/dnscontrol.git synced 2024-05-11 05:55:12 +00:00
Code Issues Releases Activity

DOCS: Document functions that return lists (#2358)

Browse Source 
Co-authored-by: Tom Limoncelli <tal@whatexit.org>
This commit is contained in:
Tom Limoncelli
2023-05-15 20:05:05 -04:00
committed by GitHub
parent 3aac3d3b44
commit 75a0d5d8b5
2 changed files with 99 additions and 70 deletions
Download Patch File Download Diff File Expand all files Collapse all files

25
documentation/code-tricks.md
View File

@@ -38,14 +38,14 @@ var GOOGLE_APPS_DOMAIN_SITES = [
CNAME("start", "ghs.googlehosted.com."), CNAME("start", "ghs.googlehosted.com."),
]; ];
D("primarydomain.tld", DnsProvider(...), D("primarydomain.tld", REG_NAMECOM, DnsProvider(...),
GOOGLE_APPS_DOMAIN_MX, GOOGLE_APPS_DOMAIN_MX,
GOOGLE_APPS_DOMAIN_SITES, GOOGLE_APPS_DOMAIN_SITES,
A(...), A(...),
CNAME(...) CNAME(...)
} }
D("aliasdomain.tld", DnsProvider(...), D("aliasdomain.tld", REG_NAMECOM, DnsProvider(...),
GOOGLE_APPS_DOMAIN_MX, GOOGLE_APPS_DOMAIN_MX,
// FYI: GOOGLE_APPS_DOMAIN_SITES is not used here. // FYI: GOOGLE_APPS_DOMAIN_SITES is not used here.
A(...), A(...),
@@ -60,7 +60,23 @@ D("aliasdomain.tld", DnsProvider(...),
Problem: We have many domains, each should have the exact same Problem: We have many domains, each should have the exact same
records. records.
Solution: Use a loop. (Note: See caveats below.) Solution 1: Use a macro.
```
function PARKED_R53(name) {
D(name, REG_NAMECOM, DnsProvider(...),
A("@", "10.2.3.4"),
CNAME("www", "@"),
SPF_NONE, //deters spammers from using the domain in From: lines.
END);
}
PARKED_R53("example1.tld");
PARKED_R53("example2.tld");
PARKED_R53("example3.tld");
```
Solution 2: Use a loop. (Note: See caveats below.)
{% code title="dnsconfig.js" %} {% code title="dnsconfig.js" %}
```javascript ```javascript
@@ -72,7 +88,7 @@ _.each(
"example3.tld", "example3.tld",
], ],
function (d) { function (d) {
D(d, REG_NAMECOM, DnsProvider(NAMECOM), D(d, REG_NAMECOM, DnsProvider(...),
A("@", "10.2.3.4"), A("@", "10.2.3.4"),
CNAME("www", "@"), CNAME("www", "@"),
END); END);
@@ -81,7 +97,6 @@ _.each(
``` ```
{% endcode %} {% endcode %}
# Caveats about getting too fancy # Caveats about getting too fancy
The `dnsconfig.js` language is JavaScript. On the plus side, this means The `dnsconfig.js` language is JavaScript. On the plus side, this means

144
documentation/examples.md
View File

@@ -2,17 +2,17 @@
{% code title="dnsconfig.js" %} {% code title="dnsconfig.js" %}
```javascript ```javascript
D('example.com', REG, DnsProvider('GCLOUD'), D("example.com", REG, DnsProvider(...),
A('@', '1.2.3.4'), // The naked or 'apex' domain. A("@", "1.2.3.4"), // The naked or "apex" domain.
A('server1', '2.3.4.5'), A("server1", "2.3.4.5"),
AAAA('wide', '2001:0db8:85a3:0000:0000:8a2e:0370:7334'), AAAA("wide", "2001:0db8:85a3:0000:0000:8a2e:0370:7334"),
CNAME('www', 'server1'), CNAME("www", "server1"),
CNAME('another', 'service.mycloud.com.'), CNAME("another", "service.mycloud.com."),
MX('mail', 10, 'mailserver'), MX("mail", 10, "mailserver"),
MX('mail', 20, 'mailqueue'), MX("mail", 20, "mailqueue"),
TXT('the', 'message'), TXT("the", "message"),
NS('department2', 'ns1.dnsexample.com.'), // use different nameservers NS("department2", "ns1.dnsexample.com."), // use different nameservers
NS('department2', 'ns2.dnsexample.com.') // for department2.example.com NS("department2", "ns2.dnsexample.com.") // for department2.example.com
) )
``` ```
{% endcode %} {% endcode %}
@@ -21,17 +21,17 @@ D('example.com', REG, DnsProvider('GCLOUD'),
## Set TTLs ## ## Set TTLs ##
{% code title="dnsconfig.js" %} {% code title="dnsconfig.js" %}
```javascript ```javascript
var mailTTL = TTL('1h'); var mailTTL = TTL("1h");
D('example.com', registrar, D("example.com", registrar,
NAMESERVER_TTL('10m'), // On domain apex NS RRs NAMESERVER_TTL("10m"), // On domain apex NS RRs
DefaultTTL('5m'), // Default for a domain DefaultTTL("5m"), // Default for a domain
MX('@', 5, '1.2.3.4', mailTTL), // use variable to MX("@", 5, "1.2.3.4", mailTTL), // use variable to
MX('@', 10, '4.3.2.1', mailTTL), // set TTL MX("@", 10, "4.3.2.1", mailTTL), // set TTL
A('@', '1.2.3.4', TTL('10m')), // individual record A("@", "1.2.3.4", TTL("10m")), // individual record
CNAME('mail', 'mx01') // TTL of 5m, as defined per DefaultTTL() CNAME("mail", "mx01") // TTL of 5m, as defined per DefaultTTL()
); );
``` ```
{% endcode %} {% endcode %}
@@ -39,17 +39,19 @@ D('example.com', registrar,
## Variables for common IP Addresses ## ## Variables for common IP Addresses ##
{% code title="dnsconfig.js" %} {% code title="dnsconfig.js" %}
```javascript ```javascript
var addrA = IP('1.2.3.4') var addrA = IP("1.2.3.4")
D('example.com', REG, DnsProvider('R53'), var DSP_R53 = NewDnsProvider("route53_user1");
A('@', addrA), // 1.2.3.4
A('www', addrA + 1), // 1.2.3.5 D("example.com", REG, DnsProvider(DSP_R53),
A("@", addrA), // 1.2.3.4
A("www", addrA + 1), // 1.2.3.5
) )
``` ```
{% endcode %} {% endcode %}
{% hint style="info" %} {% hint style="info" %}
**NOTE**: The [`IP()`](functions/global/IP.md) function doesn't currently support IPv6 (PRs welcome!). IPv6 addresses are strings. **NOTE**: The [`IP()`](functions/global/IP.md) function doesn"t currently support IPv6 (PRs welcome!). IPv6 addresses are strings.
{% endhint %} {% endhint %}
{% code title="dnsconfig.js" %} {% code title="dnsconfig.js" %}
```javascript ```javascript
@@ -60,14 +62,16 @@ var addrAAAA = "0:0:0:0:0:0:0:0";
## Variables to swap active Data Center ## ## Variables to swap active Data Center ##
{% code title="dnsconfig.js" %} {% code title="dnsconfig.js" %}
```javascript ```javascript
var dcA = IP('5.5.5.5'); var DSP_R53 = NewDnsProvider("route53_user1");
var dcB = IP('6.6.6.6');
var dcA = IP("5.5.5.5");
var dcB = IP("6.6.6.6");
// switch to dcB to failover // switch to dcB to failover
var activeDC = dcA; var activeDC = dcA;
D('example.com', REG, DnsProvider('R53'), D("example.com", REG, DnsProvider(DSP_R53),
A('@', activeDC + 5), // fixed address based on activeDC A("@", activeDC + 5), // fixed address based on activeDC
) )
``` ```
{% endcode %} {% endcode %}
@@ -76,26 +80,26 @@ D('example.com', REG, DnsProvider('R53'),
{% code title="dnsconfig.js" %} {% code title="dnsconfig.js" %}
```javascript ```javascript
var GOOGLE_APPS_MX_RECORDS = [ var GOOGLE_APPS_MX_RECORDS = [
MX('@', 1, 'aspmx.l.google.com.'), MX("@", 1, "aspmx.l.google.com."),
MX('@', 5, 'alt1.aspmx.l.google.com.'), MX("@", 5, "alt1.aspmx.l.google.com."),
MX('@', 5, 'alt2.aspmx.l.google.com.'), MX("@", 5, "alt2.aspmx.l.google.com."),
MX('@', 10, 'alt3.aspmx.l.google.com.'), MX("@", 10, "alt3.aspmx.l.google.com."),
MX('@', 10, 'alt4.aspmx.l.google.com.'), MX("@", 10, "alt4.aspmx.l.google.com."),
] ]
var GOOGLE_APPS_CNAME_RECORDS = [ var GOOGLE_APPS_CNAME_RECORDS = [
CNAME('calendar', 'ghs.googlehosted.com.'), CNAME("calendar", "ghs.googlehosted.com."),
CNAME('drive', 'ghs.googlehosted.com.'), CNAME("drive", "ghs.googlehosted.com."),
CNAME('mail', 'ghs.googlehosted.com.'), CNAME("mail", "ghs.googlehosted.com."),
CNAME('groups', 'ghs.googlehosted.com.'), CNAME("groups", "ghs.googlehosted.com."),
CNAME('sites', 'ghs.googlehosted.com.'), CNAME("sites", "ghs.googlehosted.com."),
CNAME('start', 'ghs.googlehosted.com.'), CNAME("start", "ghs.googlehosted.com."),
] ]
D('example.com', REG, DnsProvider('R53'), D("example.com", REG, DnsProvider(DSP_R53),
GOOGLE_APPS_MX_RECORDS, GOOGLE_APPS_MX_RECORDS,
GOOGLE_APPS_CNAME_RECORDS, GOOGLE_APPS_CNAME_RECORDS,
A('@', '1.2.3.4') A("@", "1.2.3.4")
) )
``` ```
{% endcode %} {% endcode %}
@@ -123,38 +127,43 @@ D("example.tld", REG, DSP, ...
``` ```
{% endcode %} {% endcode %}
## Set default records modifiers ##
{% code title="dnsconfig.js" %}
```javascript
DEFAULTS(
NAMESERVER_TTL("24h"),
DefaultTTL("12h"),
CF_PROXY_DEFAULT_OFF
);
```
# Advanced Examples #
## Dual DNS Providers ## ## Dual DNS Providers ##
{% code title="dnsconfig.js" %} {% code title="dnsconfig.js" %}
```javascript ```javascript
D('example.com', REG, DnsProvider('R53'), DnsProvider('GCLOUD'),
A('@', '1.2.3.4') var DSP_R53 = NewDnsProvider("route53_user1");
var DSP_GCLOUD = NewDnsProvider("gcloud_admin");
D("example.com", REG, DnsProvider(DSP_R53), DnsProvider(DSP_GCLOUD),
A("@", "1.2.3.4")
) )
// above zone uses 8 NS records total (4 from each provider dynamically gathered) // above zone uses 8 NS records total (4 from each provider dynamically gathered)
// below zone will only take 2 from each for a total of 4. May be better for performance reasons. // below zone will only take 2 from each for a total of 4. May be better for performance reasons.
D('example2.com', REG, DnsProvider('R53',2), DnsProvider('GCLOUD',2), D("example2.com", REG, DnsProvider(DSP_R53, 2), DnsProvider(DSP_GCLOUD ,2),
A('@', '1.2.3.4') A("@", "1.2.3.4")
) )
// or set a Provider as a non-authoritative backup (don't register its nameservers) // or set a Provider as a non-authoritative backup (don"t register its nameservers)
D('example3.com', REG, DnsProvider('R53'), DnsProvider('GCLOUD',0), D("example3.com", REG, DnsProvider(DSP_R53), DnsProvider(DSP_GCLOUD, 0),
A('@', '1.2.3.4') A("@", "1.2.3.4")
) )
``` ```
{% endcode %} {% endcode %}
## Set default records modifiers ##
{% code title="dnsconfig.js" %}
```javascript
DEFAULTS(
NAMESERVER_TTL('24h'),
DefaultTTL('12h'),
CF_PROXY_DEFAULT_OFF
);
```
# Advanced Examples #
## Automate Fastmail DKIM records ## ## Automate Fastmail DKIM records ##
In this example we need a macro that can dynamically change for each domain. In this example we need a macro that can dynamically change for each domain.
@@ -163,8 +172,8 @@ Suppose you have many domains that use Fastmail as an MX. Here's a macro that se
{% code title="dnsconfig.js" %} {% code title="dnsconfig.js" %}
```javascript ```javascript
var FASTMAIL_MX = [ var FASTMAIL_MX = [
MX('@', 10, 'in1-smtp.messagingengine.com.'), MX("@", 10, "in1-smtp.messagingengine.com."),
MX('@', 20, 'in2-smtp.messagingengine.com.'), MX("@", 20, "in2-smtp.messagingengine.com."),
] ]
``` ```
{% endcode %} {% endcode %}
@@ -177,9 +186,9 @@ records dynamically.
```javascript ```javascript
var FASTMAIL_DKIM = function(the_domain){ var FASTMAIL_DKIM = function(the_domain){
return [ return [
CNAME('fm1._domainkey', 'fm1.' + the_domain + '.dkim.fmhosted.com.'), CNAME("fm1._domainkey", "fm1." + the_domain + ".dkim.fmhosted.com."),
CNAME('fm2._domainkey', 'fm2.' + the_domain + '.dkim.fmhosted.com.'), CNAME("fm2._domainkey", "fm2." + the_domain + ".dkim.fmhosted.com."),
CNAME('fm3._domainkey', 'fm3.' + the_domain + '.dkim.fmhosted.com.') CNAME("fm3._domainkey", "fm3." + the_domain + ".dkim.fmhosted.com.")
] ]
} }
``` ```
@@ -190,6 +199,11 @@ We can then use the macros as such:
```javascript ```javascript
D("example.com", REG_NONE, DnsProvider(DSP_R53_MAIN), D("example.com", REG_NONE, DnsProvider(DSP_R53_MAIN),
FASTMAIL_MX, FASTMAIL_MX,
FASTMAIL_DKIM('example.com') FASTMAIL_DKIM("example.com")
) )
``` ```
{% endcode %}
### More advanced examples
See the [Code Tricks](advanced-features/code-tricks) page.