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."),
];
D("primarydomain.tld", DnsProvider(...),
D("primarydomain.tld", REG_NAMECOM, DnsProvider(...),
GOOGLE_APPS_DOMAIN_MX,
GOOGLE_APPS_DOMAIN_SITES,
A(...),
CNAME(...)
}
D("aliasdomain.tld", DnsProvider(...),
D("aliasdomain.tld", REG_NAMECOM, DnsProvider(...),
GOOGLE_APPS_DOMAIN_MX,
// FYI: GOOGLE_APPS_DOMAIN_SITES is not used here.
A(...),
@ -60,7 +60,23 @@ D("aliasdomain.tld", DnsProvider(...),
Problem: We have many domains, each should have the exact same
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" %}
```javascript
@ -72,7 +88,7 @@ _.each(
"example3.tld",
],
function (d) {
D(d, REG_NAMECOM, DnsProvider(NAMECOM),
D(d, REG_NAMECOM, DnsProvider(...),
A("@", "10.2.3.4"),
CNAME("www", "@"),
END);
@ -81,7 +97,6 @@ _.each(
```
{% endcode %}
# Caveats about getting too fancy
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" %}
```javascript
D('example.com', REG, DnsProvider('GCLOUD'),
A('@', '1.2.3.4'), // The naked or 'apex' domain.
A('server1', '2.3.4.5'),
AAAA('wide', '2001:0db8:85a3:0000:0000:8a2e:0370:7334'),
CNAME('www', 'server1'),
CNAME('another', 'service.mycloud.com.'),
MX('mail', 10, 'mailserver'),
MX('mail', 20, 'mailqueue'),
TXT('the', 'message'),
NS('department2', 'ns1.dnsexample.com.'), // use different nameservers
NS('department2', 'ns2.dnsexample.com.') // for department2.example.com
D("example.com", REG, DnsProvider(...),
A("@", "1.2.3.4"), // The naked or "apex" domain.
A("server1", "2.3.4.5"),
AAAA("wide", "2001:0db8:85a3:0000:0000:8a2e:0370:7334"),
CNAME("www", "server1"),
CNAME("another", "service.mycloud.com."),
MX("mail", 10, "mailserver"),
MX("mail", 20, "mailqueue"),
TXT("the", "message"),
NS("department2", "ns1.dnsexample.com."), // use different nameservers
NS("department2", "ns2.dnsexample.com.") // for department2.example.com
)
```
{% endcode %}
@ -21,17 +21,17 @@ D('example.com', REG, DnsProvider('GCLOUD'),
## Set TTLs ##
{% code title="dnsconfig.js" %}
```javascript
var mailTTL = TTL('1h');
var mailTTL = TTL("1h");
D('example.com', registrar,
NAMESERVER_TTL('10m'), // On domain apex NS RRs
DefaultTTL('5m'), // Default for a domain
D("example.com", registrar,
NAMESERVER_TTL("10m"), // On domain apex NS RRs
DefaultTTL("5m"), // Default for a domain
MX('@', 5, '1.2.3.4', mailTTL), // use variable to
MX('@', 10, '4.3.2.1', mailTTL), // set TTL
MX("@", 5, "1.2.3.4", mailTTL), // use variable to
MX("@", 10, "4.3.2.1", mailTTL), // set TTL
A('@', '1.2.3.4', TTL('10m')), // individual record
CNAME('mail', 'mx01') // TTL of 5m, as defined per DefaultTTL()
A("@", "1.2.3.4", TTL("10m")), // individual record
CNAME("mail", "mx01") // TTL of 5m, as defined per DefaultTTL()
);
```
{% endcode %}
@ -39,17 +39,19 @@ D('example.com', registrar,
## Variables for common IP Addresses ##
{% code title="dnsconfig.js" %}
```javascript
var addrA = IP('1.2.3.4')
var addrA = IP("1.2.3.4")
D('example.com', REG, DnsProvider('R53'),
A('@', addrA), // 1.2.3.4
A('www', addrA + 1), // 1.2.3.5
var DSP_R53 = NewDnsProvider("route53_user1");
D("example.com", REG, DnsProvider(DSP_R53),
A("@", addrA), // 1.2.3.4
A("www", addrA + 1), // 1.2.3.5
)
```
{% endcode %}
{% 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 %}
{% code title="dnsconfig.js" %}
```javascript
@ -60,14 +62,16 @@ var addrAAAA = "0:0:0:0:0:0:0:0";
## Variables to swap active Data Center ##
{% code title="dnsconfig.js" %}
```javascript
var dcA = IP('5.5.5.5');
var dcB = IP('6.6.6.6');
var DSP_R53 = NewDnsProvider("route53_user1");
var dcA = IP("5.5.5.5");
var dcB = IP("6.6.6.6");
// switch to dcB to failover
var activeDC = dcA;
D('example.com', REG, DnsProvider('R53'),
A('@', activeDC + 5), // fixed address based on activeDC
D("example.com", REG, DnsProvider(DSP_R53),
A("@", activeDC + 5), // fixed address based on activeDC
)
```
{% endcode %}
@ -76,26 +80,26 @@ D('example.com', REG, DnsProvider('R53'),
{% code title="dnsconfig.js" %}
```javascript
var GOOGLE_APPS_MX_RECORDS = [
MX('@', 1, 'aspmx.l.google.com.'),
MX('@', 5, 'alt1.aspmx.l.google.com.'),
MX('@', 5, 'alt2.aspmx.l.google.com.'),
MX('@', 10, 'alt3.aspmx.l.google.com.'),
MX('@', 10, 'alt4.aspmx.l.google.com.'),
MX("@", 1, "aspmx.l.google.com."),
MX("@", 5, "alt1.aspmx.l.google.com."),
MX("@", 5, "alt2.aspmx.l.google.com."),
MX("@", 10, "alt3.aspmx.l.google.com."),
MX("@", 10, "alt4.aspmx.l.google.com."),
]
var GOOGLE_APPS_CNAME_RECORDS = [
CNAME('calendar', 'ghs.googlehosted.com.'),
CNAME('drive', 'ghs.googlehosted.com.'),
CNAME('mail', 'ghs.googlehosted.com.'),
CNAME('groups', 'ghs.googlehosted.com.'),
CNAME('sites', 'ghs.googlehosted.com.'),
CNAME('start', 'ghs.googlehosted.com.'),
CNAME("calendar", "ghs.googlehosted.com."),
CNAME("drive", "ghs.googlehosted.com."),
CNAME("mail", "ghs.googlehosted.com."),
CNAME("groups", "ghs.googlehosted.com."),
CNAME("sites", "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_CNAME_RECORDS,
A('@', '1.2.3.4')
A("@", "1.2.3.4")
)
```
{% endcode %}
@ -123,38 +127,43 @@ D("example.tld", REG, DSP, ...
```
{% 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 ##
{% code title="dnsconfig.js" %}
```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)
// 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),
A('@', '1.2.3.4')
D("example2.com", REG, DnsProvider(DSP_R53, 2), DnsProvider(DSP_GCLOUD ,2),
A("@", "1.2.3.4")
)
// or set a Provider as a non-authoritative backup (don't register its nameservers)
D('example3.com', REG, DnsProvider('R53'), DnsProvider('GCLOUD',0),
A('@', '1.2.3.4')
// or set a Provider as a non-authoritative backup (don"t register its nameservers)
D("example3.com", REG, DnsProvider(DSP_R53), DnsProvider(DSP_GCLOUD, 0),
A("@", "1.2.3.4")
)
```
{% 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 ##
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" %}
```javascript
var FASTMAIL_MX = [
MX('@', 10, 'in1-smtp.messagingengine.com.'),
MX('@', 20, 'in2-smtp.messagingengine.com.'),
MX("@", 10, "in1-smtp.messagingengine.com."),
MX("@", 20, "in2-smtp.messagingengine.com."),
]
```
{% endcode %}
@ -177,9 +186,9 @@ records dynamically.
```javascript
var FASTMAIL_DKIM = function(the_domain){
return [
CNAME('fm1._domainkey', 'fm1.' + the_domain + '.dkim.fmhosted.com.'),
CNAME('fm2._domainkey', 'fm2.' + the_domain + '.dkim.fmhosted.com.'),
CNAME('fm3._domainkey', 'fm3.' + the_domain + '.dkim.fmhosted.com.')
CNAME("fm1._domainkey", "fm1." + the_domain + ".dkim.fmhosted.com."),
CNAME("fm2._domainkey", "fm2." + 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
D("example.com", REG_NONE, DnsProvider(DSP_R53_MAIN),
FASTMAIL_MX,
FASTMAIL_DKIM('example.com')
FASTMAIL_DKIM("example.com")
)
```
{% endcode %}
### More advanced examples
See the [Code Tricks](advanced-features/code-tricks) page.