feat: add various example usage demos

examples/Commands.txt

@@ -0,0 +1,63 @@
+# check configuration validity:
+dnscontrol check
+
+# apply formatting to configuration
+dnscontrol fmt dnsconfig.js
+
+# preview what changes would be made
+dnscontrol preview
+
+# full preview
+dnscontrol preview --full
+
+# preview with a notification hook (slack)
+dnscontrol preview --notify
+
+# check credentials against Porkbun API:
+dnscontrol check-creds porkbun
+
+# push DNS record changes
+dnscontrol push
+
+# push and notify (slack)
+dnscontrol push --notify
+
+# push and output a text report
+mkdir reports
+dnscontrol push --report "./reports/$(date '+%Y-%m-%d')-Report.txt"
+
+# import / retrieve current records via a 'zone' file
+dnscontrol get-zones --format=zone porkbun - noclocks.dev
+
+# import / retrieve current records via a 'zone' file with output
+mkdir zones
+dnscontrol get-zones --format=zone porkbun - noclocks.dev > zones/noclocks.dev.zone
+
+# get zones (names only)
+dnscontrol get-zones --format=nameonly porkbun - noclocks.dev
+
+# get zones (zone file format using the BIND provider)
+dnscontrol get-zones --format=zone bind - noclocks.dev
+
+# get zones (table format)
+dnscontrol get-zones --format=tsv porkbun - noclocks.dev
+
+# get zones (table format and output to CSV/TSV data file)
+dnscontrol get-zones --format=tsv porkbun - noclocks.dev > reports/noclocks.dev.csv
+
+# get zones formatted with `djs` (JavaScript with leading commas)
+dnscontrol get-zones --format=djs porkbun - noclocks.dev
+
+# get zones formatted with `djs` (JavaScript with leading commas) & output to file
+dnscontrol get-zones --format=djs porkbun - noclocks.dev > noclocks.dev.js
+
+# get zones formatted as JavaScript
+dnscontrol get-zones --format=js porkbun - noclocks.dev
+
+# get zones formatted as JavaScript and output to file
+dnscontrol get-zones --format=js porkbun - noclocks.dev > noclocks.dev.js
+
+# utilize dnsutils 'dig' to check DNS record propogation, etc.
+sudo apt install dnsutils
+dig noclocks.dev
+dig +short noclocks.dev

examples/NameServers_and_DNSRecords.txt

@@ -0,0 +1,20 @@
+
+NAMESERVER("curitiba.ns.porkbun.com."),
+NAMESERVER("fortaleza.ns.porkbun.com."),
+NAMESERVER("maceio.ns.porkbun.com."),
+NAMESERVER("salvador.ns.porkbun.com."),
+
+CNAME("www", "noclocks.dev."),
+CNAME("blog", "39843493.group43.sites.hubspot.net."),
+CNAME("*", "lixie.porkbun.com."),
+CNAME("docs", "noclocks.github.io."),
+
+MX("@", 1, "fwd1.porkbun.com."),
+MX("@", 1, "fwd2.porkbun.com."),
+
+TXT("@", "v=spf1 include:_spf.porkbun.com ~all"),
+TXT("default._domainkey", "v=DKIM1; k=rsa; p=MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQC5wVNukpz+fpCVe3pTPph5GNNgljwTdL43ykZ2P4Vm/HiwFqsGGpuZaMhbVJtmmnItAAjdQfCqITYvMbQFU0DYAZpJencyelIU4bznlZM8NvwPlFo9so2C1zDfUs2Y9rgF71+4V/fyu3tXa0r8l8r6STpYGB0GsmL6idTZy3PJKQIDAQAB"),
+TXT("_dmarc", "v=DMARC1; p=quarantine; rua=mailto:25f8c5e6@mxtoolbox.dmarc-report.com; ruf=mailto:25f8c5e6@forensics.dmarc-report.com; fo=1"),
+TXT("_acme-challenge", "YfcZoPb1JoXtiwUP0k4aimMlw712-NxzrrIsxMAJJtY"),
+TXT("_acme-challenge", "duFW0ARxb60Rd6snfskR9b4db08jaoGVrM_dGY-PUcA"),
+TXT("_github-pages-challenge-noclocks", "8c88c3f5791a75585aedc0a0e821fb"),

examples/README.md

@@ -0,0 +1,4 @@
+# Examples
+
+> [!NOTE]
+> Examples of how to use `dnscontrol`

examples/noclocks.dev.djs

@@ -0,0 +1,19 @@
+var DSP_PORKBUN = NewDnsProvider("porkbun");
+var REG_NONE = NewRegistrar("none");
+
+D("noclocks.dev", REG_NONE
+	, DnsProvider(DSP_PORKBUN)
+	, DefaultTTL(600)
+	, ALIAS("@", "lixie.porkbun.com.")
+	, CNAME("*", "lixie.porkbun.com.")
+	, CNAME("blog", "39843493.group43.sites.hubspot.net.")
+	, CNAME("docs", "noclocks.github.io.")
+	, MX("@", 1, "fwd1.porkbun.com.")
+	, MX("@", 1, "fwd2.porkbun.com.")
+	, TXT("@", "v=spf1 include:_spf.porkbun.com ~all", TTL(300))
+	, TXT("default._domainkey", "v=DKIM1; k=rsa; p=MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQD23fAyoPbewQ6QAdP6FN30wbbEtWfpSvee3SR1CGqZc3YREGfXwPVi6R5cyR+qwx0DdJUuo5yOlFJ6rXyJUI6PSJ63sq5eNqKU+n6cqLlDaN4VxjS/NmLw+6szGeH52PhfrwRSyI2yMAnSszqvIO8YvN/bieqhIzcQjt8lQtWkJQIDAQAB", TTL(300))
+	, TXT("_dmarc", "v=DMARC1; p=quarantine; rua=mailto:25f8c5e6@mxtoolbox.dmarc-report.com; ruf=mailto:25f8c5e6@forensics.dmarc-report.com; fo=1", TTL(300))
+	, TXT("_acme-challenge", "YfcZoPb1JoXtiwUP0k4aimMlw712-NxzrrIsxMAJJtY")
+	, TXT("_acme-challenge", "duFW0ARxb60Rd6snfskR9b4db08jaoGVrM_dGY-PUcA")
+	, TXT("_github-pages-challenge-noclocks", "8c88c3f5791a75585aedc0a0e821fb")
+)

examples/noclocks.dev.js

@@ -0,0 +1,19 @@
+var DSP_PORKBUN = NewDnsProvider("porkbun");
+var REG_NONE = NewRegistrar("none");
+
+D("noclocks.dev", REG_NONE,
+	DnsProvider(DSP_PORKBUN),
+	DefaultTTL(600),
+	ALIAS("@", "lixie.porkbun.com."),
+	CNAME("*", "lixie.porkbun.com."),
+	CNAME("blog", "39843493.group43.sites.hubspot.net."),
+	CNAME("docs", "noclocks.github.io."),
+	MX("@", 1, "fwd1.porkbun.com."),
+	MX("@", 1, "fwd2.porkbun.com."),
+	TXT("@", "v=spf1 include:_spf.porkbun.com ~all", TTL(300)),
+	TXT("default._domainkey", "v=DKIM1; k=rsa; p=MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQD23fAyoPbewQ6QAdP6FN30wbbEtWfpSvee3SR1CGqZc3YREGfXwPVi6R5cyR+qwx0DdJUuo5yOlFJ6rXyJUI6PSJ63sq5eNqKU+n6cqLlDaN4VxjS/NmLw+6szGeH52PhfrwRSyI2yMAnSszqvIO8YvN/bieqhIzcQjt8lQtWkJQIDAQAB", TTL(300)),
+	TXT("_dmarc", "v=DMARC1; p=quarantine; rua=mailto:25f8c5e6@mxtoolbox.dmarc-report.com; ruf=mailto:25f8c5e6@forensics.dmarc-report.com; fo=1", TTL(300)),
+	TXT("_acme-challenge", "YfcZoPb1JoXtiwUP0k4aimMlw712-NxzrrIsxMAJJtY"),
+	TXT("_acme-challenge", "duFW0ARxb60Rd6snfskR9b4db08jaoGVrM_dGY-PUcA"),
+	TXT("_github-pages-challenge-noclocks", "8c88c3f5791a75585aedc0a0e821fb")
+)

examples/noclocks.dev.tsv

@@ -0,0 +1,12 @@
+noclocks.dev	@	600	IN	ALIAS	lixie.porkbun.com.
+*.noclocks.dev	*	600	IN	CNAME	lixie.porkbun.com.
+blog.noclocks.dev	blog	600	IN	CNAME	39843493.group43.sites.hubspot.net.
+docs.noclocks.dev	docs	600	IN	CNAME	noclocks.github.io.
+noclocks.dev	@	600	IN	MX	1 fwd1.porkbun.com.
+noclocks.dev	@	600	IN	MX	1 fwd2.porkbun.com.
+noclocks.dev	@	300	IN	TXT	v=spf1 include:_spf.porkbun.com ~all
+default._domainkey.noclocks.dev	default._domainkey	300	IN	TXT	v=DKIM1; k=rsa; p=MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQD23fAyoPbewQ6QAdP6FN30wbbEtWfpSvee3SR1CGqZc3YREGfXwPVi6R5cyR+qwx0DdJUuo5yOlFJ6rXyJUI6PSJ63sq5eNqKU+n6cqLlDaN4VxjS/NmLw+6szGeH52PhfrwRSyI2yMAnSszqvIO8YvN/bieqhIzcQjt8lQtWkJQIDAQAB
+_dmarc.noclocks.dev	_dmarc	300	IN	TXT	v=DMARC1; p=quarantine; rua=mailto:25f8c5e6@mxtoolbox.dmarc-report.com; ruf=mailto:25f8c5e6@forensics.dmarc-report.com; fo=1
+_acme-challenge.noclocks.dev	_acme-challenge	600	IN	TXT	YfcZoPb1JoXtiwUP0k4aimMlw712-NxzrrIsxMAJJtY
+_acme-challenge.noclocks.dev	_acme-challenge	600	IN	TXT	duFW0ARxb60Rd6snfskR9b4db08jaoGVrM_dGY-PUcA
+_github-pages-challenge-noclocks.noclocks.dev	_github-pages-challenge-noclocks	600	IN	TXT	8c88c3f5791a75585aedc0a0e821fb

examples/noclocks.dev.zone

@@ -0,0 +1,15 @@
+$ORIGIN noclocks.dev.
+$TTL 600
+@                IN MX    1 fwd1.porkbun.com.
+                 IN MX    1 fwd2.porkbun.com.
+           300   IN TXT   "v=spf1 include:_spf.porkbun.com ~all"
+;@                IN ALIAS lixie.porkbun.com.
+*                IN CNAME lixie.porkbun.com.
+_acme-challenge  IN TXT   "YfcZoPb1JoXtiwUP0k4aimMlw712-NxzrrIsxMAJJtY"
+                 IN TXT   "duFW0ARxb60Rd6snfskR9b4db08jaoGVrM_dGY-PUcA"
+_dmarc     300   IN TXT   "v=DMARC1; p=quarantine; rua=mailto:25f8c5e6@mxtoolbox.dmarc-report.com; ruf=mailto:25f8c5e6@forensics.dmarc-report.com; fo=1"
+default._domainkey 300 IN TXT "v=DKIM1; k=rsa; p=MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQD23fAyoPbewQ6QAdP6FN30wbbEtWfpSvee3SR1CGqZc3YREGfXwPVi6R5cyR+qwx0DdJUuo5yOlFJ6rXyJUI6PSJ63sq5eNqKU+n6cqLlDaN4VxjS/NmLw+6szGeH52PhfrwRSyI2yMAnSszqvIO8YvN/bieqhIzcQjt8lQtWkJQIDAQAB"
+_github-pages-challenge-noclocks IN TXT "8c88c3f5791a75585aedc0a0e821fb"
+blog             IN CNAME 39843493.group43.sites.hubspot.net.
+docs             IN CNAME noclocks.github.io.
+