From 757a1fab37a1dcf84808a790d0844f7a215ae8dd Mon Sep 17 00:00:00 2001 From: Paul Date: Sun, 26 Mar 2023 01:28:02 +0100 Subject: [PATCH 1/9] Code to auto build TOC entries based on folder structure --- build/generate/docuTOC.go | 178 ++++++++++++++++++ build/generate/featureMatrix.go | 24 +-- build/generate/functionTypes.go | 37 +++- build/generate/generate.go | 13 ++ documentation/SUMMARY.md | 7 +- documentation/getting-started.md | 2 +- documentation/index.md | 2 +- .../JavaScript_DSL.md} | 0 .../domain_modifier_functions}/A.md | 2 +- .../domain_modifier_functions}/AAAA.md | 0 .../domain_modifier_functions}/ALIAS.md | 0 .../AUTODNSSEC_OFF.md | 0 .../AUTODNSSEC_ON.md | 0 .../domain_modifier_functions}/CAA.md | 2 +- .../domain_modifier_functions}/CNAME.md | 0 .../domain_modifier_functions}/DS.md | 0 .../domain_modifier_functions}/DefaultTTL.md | 0 .../domain_modifier_functions}/DnsProvider.md | 2 +- .../domain_modifier_functions}/FRAME.md | 0 .../domain_modifier_functions}/IGNORE.md | 0 .../domain_modifier_functions}/IGNORE_NAME.md | 0 .../IGNORE_TARGET.md | 0 .../IMPORT_TRANSFORM.md | 0 .../domain_modifier_functions}/INCLUDE.md | 0 .../domain_modifier_functions}/LOC.md | 8 +- .../domain_modifier_functions}/MX.md | 0 .../domain_modifier_functions}/NAMESERVER.md | 0 .../NAMESERVER_TTL.md | 4 +- .../domain_modifier_functions}/NAPTR.md | 0 .../domain_modifier_functions}/NO_PURGE.md | 0 .../domain_modifier_functions}/NS.md | 0 .../domain_modifier_functions}/PTR.md | 2 +- .../domain_modifier_functions}/PURGE.md | 0 .../domain_modifier_functions}/SOA.md | 0 .../domain_modifier_functions}/SRV.md | 0 .../domain_modifier_functions}/SSHFP.md | 0 .../domain_modifier_functions}/TLSA.md | 0 .../domain_modifier_functions}/TXT.md | 2 +- .../domain_modifier_functions}/URL.md | 0 .../domain_modifier_functions}/URL301.md | 0 .../ClouDNS}/CLOUDNS_WR.md | 0 .../NS1}/NS1_URLFWD.md | 0 .../akamai_edge_dns}/AKAMAICDN.md | 0 .../amazon_route_53}/R53_ALIAS.md | 2 +- .../azure_dns}/AZURE_ALIAS.md | 0 .../cloudflare_dns}/CF_REDIRECT.md | 0 .../cloudflare_dns}/CF_TEMP_REDIRECT.md | 0 .../cloudflare_dns}/CF_WORKER_ROUTE.md | 0 .../service_provider_specific/ignore-me.md | 0 .../record_modifier_functions}/CAA_BUILDER.md | 2 +- .../DMARC_BUILDER.md | 0 .../LOC_BUILDER_DD.md | 0 .../LOC_BUILDER_DMM_STR.md | 0 .../LOC_BUILDER_DMS_STR.md | 14 +- .../LOC_BUILDER_STR.md | 0 .../record_modifier_functions}/SPF_BUILDER.md | 0 .../record_modifier_functions}/TTL.md | 2 +- .../amazon_route_53}/R53_ZONE.md | 2 +- .../service_provider_specific/ignore-me.md | 0 .../top_level_functions}/D.md | 2 +- .../top_level_functions}/DEFAULTS.md | 2 +- .../top_level_functions}/DOMAIN_ELSEWHERE.md | 2 +- .../DOMAIN_ELSEWHERE_AUTO.md | 2 +- .../top_level_functions}/D_EXTEND.md | 2 +- .../top_level_functions}/FETCH.md | 0 .../top_level_functions}/IP.md | 0 .../top_level_functions}/NewDnsProvider.md | 0 .../top_level_functions}/NewRegistrar.md | 0 .../top_level_functions}/PANIC.md | 0 .../top_level_functions}/REV.md | 2 +- .../getConfiguredDomains.md | 0 .../top_level_functions}/require.md | 0 .../top_level_functions}/require_glob.md | 0 .../{ => service_providers}/providers.md | 0 .../providers/akamaiedgedns.md | 0 .../providers/autodns.md | 0 .../providers/axfrddns.md | 0 .../providers/azure_dns.md | 0 .../{ => service_providers}/providers/bind.md | 0 .../providers/cloudflareapi.md | 0 .../providers/cloudns.md | 0 .../providers/cscglobal.md | 0 .../providers/desec.md | 0 .../providers/digitalocean.md | 0 .../providers/dnsimple.md | 0 .../providers/dnsmadeeasy.md | 0 .../providers/dnsoverhttps.md | 0 .../providers/domainnameshop.md | 0 .../providers/easyname.md | 0 .../providers/gandi_v5.md | 0 .../providers/gcloud.md | 0 .../providers/gcore.md | 0 .../providers/hedns.md | 0 .../providers/hetzner.md | 0 .../providers/hexonet.md | 0 .../providers/hostingde.md | 0 .../providers/internetbs.md | 0 .../{ => service_providers}/providers/inwx.md | 0 .../providers/linode.md | 0 .../providers/loopia.md | 0 .../providers/luadns.md | 0 .../providers/msdns.md | 0 .../providers/namecheap.md | 0 .../providers/namedotcom.md | 0 .../providers/netcup.md | 0 .../providers/netlify.md | 0 .../{ => service_providers}/providers/ns1.md | 0 .../providers/oracle.md | 0 .../{ => service_providers}/providers/ovh.md | 0 .../providers/packetframe.md | 0 .../providers/porkbun.md | 0 .../providers/powerdns.md | 0 .../providers/route53.md | 0 .../{ => service_providers}/providers/rwth.md | 0 .../providers/softlayer.md | 0 .../providers/transip.md | 0 .../providers/vultr.md | 0 main.go | 2 +- 118 files changed, 270 insertions(+), 51 deletions(-) create mode 100644 build/generate/docuTOC.go rename documentation/{js.md => language_reference/JavaScript_DSL.md} (100%) rename documentation/{functions/domain => language_reference/domain_modifier_functions}/A.md (92%) rename documentation/{functions/domain => language_reference/domain_modifier_functions}/AAAA.md (100%) rename documentation/{functions/domain => language_reference/domain_modifier_functions}/ALIAS.md (100%) rename documentation/{functions/domain => language_reference/domain_modifier_functions}/AUTODNSSEC_OFF.md (100%) rename documentation/{functions/domain => language_reference/domain_modifier_functions}/AUTODNSSEC_ON.md (100%) rename documentation/{functions/domain => language_reference/domain_modifier_functions}/CAA.md (79%) rename documentation/{functions/domain => language_reference/domain_modifier_functions}/CNAME.md (100%) rename documentation/{functions/domain => language_reference/domain_modifier_functions}/DS.md (100%) rename documentation/{functions/domain => language_reference/domain_modifier_functions}/DefaultTTL.md (100%) rename documentation/{functions/domain => language_reference/domain_modifier_functions}/DnsProvider.md (94%) rename documentation/{functions/domain => language_reference/domain_modifier_functions}/FRAME.md (100%) rename documentation/{functions/domain => language_reference/domain_modifier_functions}/IGNORE.md (100%) rename documentation/{functions/domain => language_reference/domain_modifier_functions}/IGNORE_NAME.md (100%) rename documentation/{functions/domain => language_reference/domain_modifier_functions}/IGNORE_TARGET.md (100%) rename documentation/{functions/domain => language_reference/domain_modifier_functions}/IMPORT_TRANSFORM.md (100%) rename documentation/{functions/domain => language_reference/domain_modifier_functions}/INCLUDE.md (100%) rename documentation/{functions/domain => language_reference/domain_modifier_functions}/LOC.md (84%) rename documentation/{functions/domain => language_reference/domain_modifier_functions}/MX.md (100%) rename documentation/{functions/domain => language_reference/domain_modifier_functions}/NAMESERVER.md (100%) rename documentation/{functions/domain => language_reference/domain_modifier_functions}/NAMESERVER_TTL.md (81%) rename documentation/{functions/domain => language_reference/domain_modifier_functions}/NAPTR.md (100%) rename documentation/{functions/domain => language_reference/domain_modifier_functions}/NO_PURGE.md (100%) rename documentation/{functions/domain => language_reference/domain_modifier_functions}/NS.md (100%) rename documentation/{functions/domain => language_reference/domain_modifier_functions}/PTR.md (97%) rename documentation/{functions/domain => language_reference/domain_modifier_functions}/PURGE.md (100%) rename documentation/{functions/domain => language_reference/domain_modifier_functions}/SOA.md (100%) rename documentation/{functions/domain => language_reference/domain_modifier_functions}/SRV.md (100%) rename documentation/{functions/domain => language_reference/domain_modifier_functions}/SSHFP.md (100%) rename documentation/{functions/domain => language_reference/domain_modifier_functions}/TLSA.md (100%) rename documentation/{functions/domain => language_reference/domain_modifier_functions}/TXT.md (98%) rename documentation/{functions/domain => language_reference/domain_modifier_functions}/URL.md (100%) rename documentation/{functions/domain => language_reference/domain_modifier_functions}/URL301.md (100%) rename documentation/{functions/domain => language_reference/domain_modifier_functions/service_provider_specific/ClouDNS}/CLOUDNS_WR.md (100%) rename documentation/{functions/domain => language_reference/domain_modifier_functions/service_provider_specific/NS1}/NS1_URLFWD.md (100%) rename documentation/{functions/domain => language_reference/domain_modifier_functions/service_provider_specific/akamai_edge_dns}/AKAMAICDN.md (100%) rename documentation/{functions/domain => language_reference/domain_modifier_functions/service_provider_specific/amazon_route_53}/R53_ALIAS.md (96%) rename documentation/{functions/domain => language_reference/domain_modifier_functions/service_provider_specific/azure_dns}/AZURE_ALIAS.md (100%) rename documentation/{functions/domain => language_reference/domain_modifier_functions/service_provider_specific/cloudflare_dns}/CF_REDIRECT.md (100%) rename documentation/{functions/domain => language_reference/domain_modifier_functions/service_provider_specific/cloudflare_dns}/CF_TEMP_REDIRECT.md (100%) rename documentation/{functions/domain => language_reference/domain_modifier_functions/service_provider_specific/cloudflare_dns}/CF_WORKER_ROUTE.md (100%) create mode 100644 documentation/language_reference/domain_modifier_functions/service_provider_specific/ignore-me.md rename documentation/{functions/record => language_reference/record_modifier_functions}/CAA_BUILDER.md (93%) rename documentation/{functions/record => language_reference/record_modifier_functions}/DMARC_BUILDER.md (100%) rename documentation/{functions/record => language_reference/record_modifier_functions}/LOC_BUILDER_DD.md (100%) rename documentation/{functions/record => language_reference/record_modifier_functions}/LOC_BUILDER_DMM_STR.md (100%) rename documentation/{functions/record => language_reference/record_modifier_functions}/LOC_BUILDER_DMS_STR.md (53%) rename documentation/{functions/record => language_reference/record_modifier_functions}/LOC_BUILDER_STR.md (100%) rename documentation/{functions/record => language_reference/record_modifier_functions}/SPF_BUILDER.md (100%) rename documentation/{functions/record => language_reference/record_modifier_functions}/TTL.md (89%) rename documentation/{functions/record => language_reference/record_modifier_functions/service_provider_specific/amazon_route_53}/R53_ZONE.md (72%) create mode 100644 documentation/language_reference/record_modifier_functions/service_provider_specific/ignore-me.md rename documentation/{functions/global => language_reference/top_level_functions}/D.md (94%) rename documentation/{functions/global => language_reference/top_level_functions}/DEFAULTS.md (88%) rename documentation/{functions/global => language_reference/top_level_functions}/DOMAIN_ELSEWHERE.md (89%) rename documentation/{functions/global => language_reference/top_level_functions}/DOMAIN_ELSEWHERE_AUTO.md (89%) rename documentation/{functions/global => language_reference/top_level_functions}/D_EXTEND.md (91%) rename documentation/{functions/global => language_reference/top_level_functions}/FETCH.md (100%) rename documentation/{functions/global => language_reference/top_level_functions}/IP.md (100%) rename documentation/{functions/global => language_reference/top_level_functions}/NewDnsProvider.md (100%) rename documentation/{functions/global => language_reference/top_level_functions}/NewRegistrar.md (100%) rename documentation/{functions/global => language_reference/top_level_functions}/PANIC.md (100%) rename documentation/{functions/global => language_reference/top_level_functions}/REV.md (93%) rename documentation/{functions/global => language_reference/top_level_functions}/getConfiguredDomains.md (100%) rename documentation/{functions/global => language_reference/top_level_functions}/require.md (100%) rename documentation/{functions/global => language_reference/top_level_functions}/require_glob.md (100%) rename documentation/{ => service_providers}/providers.md (100%) rename documentation/{ => service_providers}/providers/akamaiedgedns.md (100%) rename documentation/{ => service_providers}/providers/autodns.md (100%) rename documentation/{ => service_providers}/providers/axfrddns.md (100%) rename documentation/{ => service_providers}/providers/azure_dns.md (100%) rename documentation/{ => service_providers}/providers/bind.md (100%) rename documentation/{ => service_providers}/providers/cloudflareapi.md (100%) rename documentation/{ => service_providers}/providers/cloudns.md (100%) rename documentation/{ => service_providers}/providers/cscglobal.md (100%) rename documentation/{ => service_providers}/providers/desec.md (100%) rename documentation/{ => service_providers}/providers/digitalocean.md (100%) rename documentation/{ => service_providers}/providers/dnsimple.md (100%) rename documentation/{ => service_providers}/providers/dnsmadeeasy.md (100%) rename documentation/{ => service_providers}/providers/dnsoverhttps.md (100%) rename documentation/{ => service_providers}/providers/domainnameshop.md (100%) rename documentation/{ => service_providers}/providers/easyname.md (100%) rename documentation/{ => service_providers}/providers/gandi_v5.md (100%) rename documentation/{ => service_providers}/providers/gcloud.md (100%) rename documentation/{ => service_providers}/providers/gcore.md (100%) rename documentation/{ => service_providers}/providers/hedns.md (100%) rename documentation/{ => service_providers}/providers/hetzner.md (100%) rename documentation/{ => service_providers}/providers/hexonet.md (100%) rename documentation/{ => service_providers}/providers/hostingde.md (100%) rename documentation/{ => service_providers}/providers/internetbs.md (100%) rename documentation/{ => service_providers}/providers/inwx.md (100%) rename documentation/{ => service_providers}/providers/linode.md (100%) rename documentation/{ => service_providers}/providers/loopia.md (100%) rename documentation/{ => service_providers}/providers/luadns.md (100%) rename documentation/{ => service_providers}/providers/msdns.md (100%) rename documentation/{ => service_providers}/providers/namecheap.md (100%) rename documentation/{ => service_providers}/providers/namedotcom.md (100%) rename documentation/{ => service_providers}/providers/netcup.md (100%) rename documentation/{ => service_providers}/providers/netlify.md (100%) rename documentation/{ => service_providers}/providers/ns1.md (100%) rename documentation/{ => service_providers}/providers/oracle.md (100%) rename documentation/{ => service_providers}/providers/ovh.md (100%) rename documentation/{ => service_providers}/providers/packetframe.md (100%) rename documentation/{ => service_providers}/providers/porkbun.md (100%) rename documentation/{ => service_providers}/providers/powerdns.md (100%) rename documentation/{ => service_providers}/providers/route53.md (100%) rename documentation/{ => service_providers}/providers/rwth.md (100%) rename documentation/{ => service_providers}/providers/softlayer.md (100%) rename documentation/{ => service_providers}/providers/transip.md (100%) rename documentation/{ => service_providers}/providers/vultr.md (100%) diff --git a/build/generate/docuTOC.go b/build/generate/docuTOC.go new file mode 100644 index 0000000000..6c72b3624e --- /dev/null +++ b/build/generate/docuTOC.go @@ -0,0 +1,178 @@ +package main + +import ( + "fmt" + "golang.org/x/text/cases" + "golang.org/x/text/language" + "os" + "path/filepath" + "sort" + "strings" +) + +func generateDocuTOC(folderPath string, targetFile string, onlyThisPath string, startMarker string, endMarker string) error { + if folderPath == "" { + return fmt.Errorf("empty docutoc path") + } + + var exclusivePath string + if onlyThisPath != "" { + // if onlyThisPath is provided, build a list of files exclusively in this (sub)folder + exclusivePath = string(filepath.Separator) + onlyThisPath + } + // Find all the markdown files in the specified folder and its subfolders. + markdownFiles, err := findMarkdownFiles(folderPath + exclusivePath) + if err != nil { + return err + } + + //First sort by folders, then by filename. + sort.SliceStable(markdownFiles, func(i, j int) bool { + if filepath.Dir(markdownFiles[i]) == filepath.Dir(markdownFiles[j]) { + return strings.ToLower(markdownFiles[i]) < strings.ToLower(markdownFiles[j]) + } else { + return filepath.Dir(strings.ToLower(markdownFiles[i])) < filepath.Dir(strings.ToLower(markdownFiles[j])) + } + }) + + // Create the table of contents. + toc := generateTableOfContents(folderPath, markdownFiles) + + err = replaceTextBetweenMarkers(filepath.Join(folderPath, targetFile), startMarker, endMarker, toc) + if err != nil { + return err + } + + return nil +} + +// func stringInSlice(a string, list []string) bool { +// for _, b := range list { +// if b == a { +// return true +// } +// } +// return false +// } + +func generateTableOfContents(folderPath string, markdownFiles []string) string { + var toc strings.Builder + currentFolder := "" + + // skip over these root entries (dont print these "#" headings) + rootFolderExceptions := []string{ + "documentation", + } + + // dont print these folder names as bullets (which lack a link) + folderExceptions := []string{ + "providers", + } + // dont print these file names as bullets + fileExceptions := []string{ + "index.md", + "summary.md", + "ignore-me.md", + } + + caser := cases.Title(language.Und, cases.NoLower) + + for _, file := range markdownFiles { + //depthCount is folder depth for toc indentation, minus one for docu folder + depthCount := strings.Count(file, string(filepath.Separator)) - 1 + filename := filepath.Base(file) + + fileFolder := filepath.Dir(file) + if fileFolder != currentFolder { + // we are in a new folder + + // hop over these entries altogether + if stringInSlice(strings.ToLower(fileFolder), rootFolderExceptions) { + continue + } + currentFolder = fileFolder + folderName := filepath.Base(currentFolder) + + // if we're in an "exception" folder, deeper than a heading "#", skip printing it + // this has the effect of putting subentries under an entry that is already a link, + // without printing an entry to represent the folder name that is not a link + // e.g. provider md files are all links, under the provider.md file which is a link + if stringInSlice(strings.ToLower(folderName), folderExceptions) && depthCount > 1 { + continue + } else { + if depthCount > 1 { + // if we're deeper in heirarchy, print an indented bullet "*" to add to bullet heirarchy + toc.WriteString(strings.Repeat(" ", depthCount-1) + "* ") + } else { + // If we're in folder root, just print an unindented heading "#" + toc.WriteString("\n## ") + } + // Captalize folder names, replace underscores with spaces for # headings + toc.WriteString(strings.TrimSpace(caser.String(strings.ReplaceAll(folderName, "_", " "))) + "\n") + } + } + //if the file is an exception listed above, skip it. + if stringInSlice(strings.ToLower(filename), fileExceptions) { + continue + } + + // naming exceptions - function names shall retain "_" + displayfilename := strings.TrimSuffix(filename, filepath.Ext(filename)) + if !strings.Contains(file, "functions") { + displayfilename = strings.TrimSpace(caser.String(strings.ReplaceAll(displayfilename, "_", " "))) + } + + // print the filename as a bullet, and as a [link](hyperlink) + toc.WriteString(strings.Repeat(" ", depthCount)) + toc.WriteString("* [" + displayfilename + "](" + filepath.Join(".", strings.ReplaceAll(file, folderPath, "")) + ")\n") + } + return toc.String() +} + +// replaceTextBetweenMarkers inserts the generated table of contents between the two markers in the specified markdown file. +func replaceTextBetweenMarkers(targetFile, startMarker, endMarker, newcontent string) error { + // Read the contents of the markdown file into memory. + input, err := os.ReadFile(targetFile) + if err != nil { + return err + } + + // Find the starting and ending positions of the table of contents markers. + startPos := strings.Index(string(input), startMarker) + if startPos == -1 { + return fmt.Errorf("could not find start marker %q in file %q", startMarker, targetFile) + } + endPos := strings.Index(string(input), endMarker) + if endPos == -1 { + return fmt.Errorf("could not find end marker %q in file %q", endMarker, targetFile) + } + + // Construct the new contents of the markdown file with the updated table of contents. + output := string(input[:startPos+len(startMarker)]) + newcontent + string(input[endPos:]) + + // Write the updated contents to the markdown file. + err = os.WriteFile(targetFile, []byte(output), 0644) + if err != nil { + return err + } + + return nil +} + +// findMarkdownFiles returns a list of all the markdown files in the specified folder and its subfolders. +func findMarkdownFiles(folderPath string) ([]string, error) { + markdownFiles := make([]string, 0) + err := filepath.Walk(folderPath, func(path string, info os.FileInfo, err error) error { + if err != nil { + return err + } + if !info.IsDir() && filepath.Ext(path) == ".md" { + markdownFiles = append(markdownFiles, path) + } + return nil + }) + if err != nil { + return nil, err + } + return markdownFiles, err +} diff --git a/build/generate/featureMatrix.go b/build/generate/featureMatrix.go index 35a74adaf6..af52d00124 100644 --- a/build/generate/featureMatrix.go +++ b/build/generate/featureMatrix.go @@ -76,20 +76,20 @@ func matrixData() *FeatureMatrix { OfficialSupport = "Official Support" // vs. community supported ProviderDNSProvider = "DNS Provider" ProviderRegistrar = "Registrar" - DomainModifierAlias = "[`ALIAS`](functions/domain/ALIAS.md)" - DomainModifierCaa = "[`CAA`](functions/domain/CAA.md)" - DomainModifierDnssec = "[`AUTODNSSEC`](functions/domain/AUTODNSSEC_ON.md)" - DomainModifierLoc = "[`LOC`](functions/domain/LOC.md)" - DomainModifierNaptr = "[`NAPTR`](functions/domain/NAPTR.md)" - DomainModifierPtr = "[`PTR`](functions/domain/PTR.md)" - DomainModifierSoa = "[`SOA`](functions/domain/SOA.md)" - DomainModifierSrv = "[`SRV`](functions/domain/SRV.md)" - DomainModifierSshfp = "[`SSHFP`](functions/domain/SSHFP.md)" - DomainModifierTlsa = "[`TLSA`](functions/domain/TLSA.md)" - DomainModifierDs = "[`DS`](functions/domain/DS.md)" + DomainModifierAlias = "[`ALIAS`](../language_reference/domain_modifier_functions/ALIAS.md)" + DomainModifierCaa = "[`CAA`](../language_reference/domain_modifier_functions/CAA.md)" + DomainModifierDnssec = "[`AUTODNSSEC`](../language_reference/domain_modifier_functions/AUTODNSSEC_ON.md)" + DomainModifierLoc = "[`LOC`](../language_reference/domain_modifier_functions/LOC.md)" + DomainModifierNaptr = "[`NAPTR`](../language_reference/domain_modifier_functions/NAPTR.md)" + DomainModifierPtr = "[`PTR`](../language_reference/domain_modifier_functions/PTR.md)" + DomainModifierSoa = "[`SOA`](../language_reference/domain_modifier_functions/SOA.md)" + DomainModifierSrv = "[`SRV`](../language_reference/domain_modifier_functions/SRV.md)" + DomainModifierSshfp = "[`SSHFP`](../language_reference/domain_modifier_functions/SSHFP.md)" + DomainModifierTlsa = "[`TLSA`](../language_reference/domain_modifier_functions/TLSA.md)" + DomainModifierDs = "[`DS`](../language_reference/domain_modifier_functions/DS.md)" DualHost = "dual host" CreateDomains = "create-domains" - NoPurge = "[`NO_PURGE`](functions/domain/NO_PURGE.md)" + NoPurge = "[`NO_PURGE`](../language_reference/domain_modifier_functions/NO_PURGE.md)" GetZones = "get-zones" ) diff --git a/build/generate/functionTypes.go b/build/generate/functionTypes.go index ad508acc72..6701269301 100644 --- a/build/generate/functionTypes.go +++ b/build/generate/functionTypes.go @@ -49,20 +49,43 @@ func parseFrontMatter(content string) (map[string]interface{}, string, error) { } var returnTypes = map[string]string{ - "domain": "DomainModifier", - "global": "void", - "record": "RecordModifier", + "domain_modifier_functions": "DomainModifier", + "top_level_functions": "void", + "record_modifier_functions": "RecordModifier", +} + +func stringInSlice(a string, list []string) bool { + for _, b := range list { + if b == a { + return true + } + } + return false } func generateFunctionTypes() (string, error) { funcs := []Function{} + folderExceptions := []string{ + ".DS_Store", + "js.md", + } + fileExceptions := []string{ + ".DS_Store", + "JavaScript_DSL.md", + } - srcRoot := join("documentation", "functions") + srcRoot := join("documentation", "language_reference") types, err := os.ReadDir(srcRoot) if err != nil { return "", err } for _, t := range types { + if stringInSlice(t.Name(), folderExceptions) { + continue + } + if stringInSlice(t.Name(), fileExceptions) { + continue + } if !t.IsDir() { return "", errors.New("not a directory: " + join(srcRoot, t.Name())) } @@ -73,9 +96,13 @@ func generateFunctionTypes() (string, error) { } for _, f := range funcNames { + if stringInSlice(f.Name(), fileExceptions) { + continue + } fPath := join(tPath, f.Name()) if f.IsDir() { - return "", errors.New("not a file: " + fPath) + // return "", errors.New("not a file: " + fPath) + continue } // println("Processing", fPath) content, err := os.ReadFile(fPath) diff --git a/build/generate/generate.go b/build/generate/generate.go index 4753aed486..12eed0d34a 100644 --- a/build/generate/generate.go +++ b/build/generate/generate.go @@ -2,6 +2,13 @@ package main import "log" +const ( + langRefStartMarker = "\n" + langRefEndMarker = "" + providerStartMarker = "\n" + providerEndMarker = "" +) + func main() { if err := generateFeatureMatrix(); err != nil { log.Fatal(err) @@ -13,4 +20,10 @@ func main() { if err := generateDTSFile(funcs); err != nil { log.Fatal(err) } + if err := generateDocuTOC("documentation", "SUMMARY.md", "language_reference", langRefStartMarker, langRefEndMarker); err != nil { + log.Print(err) + } + if err := generateDocuTOC("documentation", "SUMMARY.md", "service_providers", providerStartMarker, providerEndMarker); err != nil { + log.Print(err) + } } diff --git a/documentation/SUMMARY.md b/documentation/SUMMARY.md index 5a31fa3371..5f86278b0c 100644 --- a/documentation/SUMMARY.md +++ b/documentation/SUMMARY.md @@ -8,7 +8,7 @@ * [Examples](examples.md) * [Migrating zones to DNSControl](migrating.md) * [TypeScript autocomplete and type checking](typescript.md) - + ## Language Reference * [JavaScript DSL](js.md) @@ -87,8 +87,9 @@ * Service Provider specific * Amazon Route 53 * [R53_ZONE](functions/record/R53_ZONE.md) + * [Why CNAME/MX/NS targets require a "dot"](why-the-dot.md) - + ## Service Providers * [Providers](providers.md) @@ -135,7 +136,7 @@ * [SoftLayer DNS](providers/softlayer.md) * [TransIP](providers/transip.md) * [Vultr](providers/vultr.md) - + ## Commands * [creds.json](creds-json.md) diff --git a/documentation/getting-started.md b/documentation/getting-started.md index cae42c28ac..b8a783bfce 100644 --- a/documentation/getting-started.md +++ b/documentation/getting-started.md @@ -99,7 +99,7 @@ D('example.com', REG_NONE, DnsProvider(DNS_BIND), ``` {% endcode %} -Modify this file to match your particular providers and domains. See [the DNSConfig docs](js.md) and [the provider docs](providers.md) for more details. +Modify this file to match your particular providers and domains. See [the DNSConfig docs](language_reference/JavaScript_DSL.md) and [the provider docs](providers.md) for more details. Create a file called `creds.json` for storing provider configurations (API tokens and other account information). For example, to use both name.com and Cloudflare, you would have: diff --git a/documentation/index.md b/documentation/index.md index 58b4a8ad79..bd14d61707 100644 --- a/documentation/index.md +++ b/documentation/index.md @@ -4,7 +4,7 @@ # Try It -Want to jump right in? Follow our [quick start tutorial](getting-started.md) on a new domain or [migrate](migrating.md) an existing one. Read the [language spec](js.md) for more info. +Want to jump right in? Follow our [quick start tutorial](getting-started.md) on a new domain or [migrate](migrating.md) an existing one. Read the [language spec](02_language_reference/JavaScript_DSL.md) for more info. # Use It diff --git a/documentation/js.md b/documentation/language_reference/JavaScript_DSL.md similarity index 100% rename from documentation/js.md rename to documentation/language_reference/JavaScript_DSL.md diff --git a/documentation/functions/domain/A.md b/documentation/language_reference/domain_modifier_functions/A.md similarity index 92% rename from documentation/functions/domain/A.md rename to documentation/language_reference/domain_modifier_functions/A.md index 28eac09371..434dca67b4 100644 --- a/documentation/functions/domain/A.md +++ b/documentation/language_reference/domain_modifier_functions/A.md @@ -12,7 +12,7 @@ parameter_types: A adds an A record To a domain. The name should be the relative label for the record. Use `@` for the domain apex. -The address should be an ip address, either a string, or a numeric value obtained via [IP](../global/IP.md). +The address should be an ip address, either a string, or a numeric value obtained via [IP](../top_level_functions/IP.md). Modifiers can be any number of [record modifiers](https://docs.dnscontrol.org/language-reference/record-modifiers) or JSON objects, which will be merged into the record's metadata. diff --git a/documentation/functions/domain/AAAA.md b/documentation/language_reference/domain_modifier_functions/AAAA.md similarity index 100% rename from documentation/functions/domain/AAAA.md rename to documentation/language_reference/domain_modifier_functions/AAAA.md diff --git a/documentation/functions/domain/ALIAS.md b/documentation/language_reference/domain_modifier_functions/ALIAS.md similarity index 100% rename from documentation/functions/domain/ALIAS.md rename to documentation/language_reference/domain_modifier_functions/ALIAS.md diff --git a/documentation/functions/domain/AUTODNSSEC_OFF.md b/documentation/language_reference/domain_modifier_functions/AUTODNSSEC_OFF.md similarity index 100% rename from documentation/functions/domain/AUTODNSSEC_OFF.md rename to documentation/language_reference/domain_modifier_functions/AUTODNSSEC_OFF.md diff --git a/documentation/functions/domain/AUTODNSSEC_ON.md b/documentation/language_reference/domain_modifier_functions/AUTODNSSEC_ON.md similarity index 100% rename from documentation/functions/domain/AUTODNSSEC_ON.md rename to documentation/language_reference/domain_modifier_functions/AUTODNSSEC_ON.md diff --git a/documentation/functions/domain/CAA.md b/documentation/language_reference/domain_modifier_functions/CAA.md similarity index 79% rename from documentation/functions/domain/CAA.md rename to documentation/language_reference/domain_modifier_functions/CAA.md index 8509a1df44..e389608bda 100644 --- a/documentation/functions/domain/CAA.md +++ b/documentation/language_reference/domain_modifier_functions/CAA.md @@ -38,4 +38,4 @@ D("example.com", REGISTRAR, DnsProvider("GCLOUD"), ``` {% endcode %} -DNSControl contains a [`CAA_BUILDER`](../record/CAA_BUILDER.md) which can be used to simply create `CAA()` records for your domains. Instead of creating each CAA record individually, you can simply configure your report mail address, the authorized certificate authorities and the builder cares about the rest. +DNSControl contains a [`CAA_BUILDER`](../record_modifier_functions/CAA_BUILDER.md) which can be used to simply create `CAA()` records for your domains. Instead of creating each CAA record individually, you can simply configure your report mail address, the authorized certificate authorities and the builder cares about the rest. diff --git a/documentation/functions/domain/CNAME.md b/documentation/language_reference/domain_modifier_functions/CNAME.md similarity index 100% rename from documentation/functions/domain/CNAME.md rename to documentation/language_reference/domain_modifier_functions/CNAME.md diff --git a/documentation/functions/domain/DS.md b/documentation/language_reference/domain_modifier_functions/DS.md similarity index 100% rename from documentation/functions/domain/DS.md rename to documentation/language_reference/domain_modifier_functions/DS.md diff --git a/documentation/functions/domain/DefaultTTL.md b/documentation/language_reference/domain_modifier_functions/DefaultTTL.md similarity index 100% rename from documentation/functions/domain/DefaultTTL.md rename to documentation/language_reference/domain_modifier_functions/DefaultTTL.md diff --git a/documentation/functions/domain/DnsProvider.md b/documentation/language_reference/domain_modifier_functions/DnsProvider.md similarity index 94% rename from documentation/functions/domain/DnsProvider.md rename to documentation/language_reference/domain_modifier_functions/DnsProvider.md index ccefe44b88..2ad8c6553c 100644 --- a/documentation/functions/domain/DnsProvider.md +++ b/documentation/language_reference/domain_modifier_functions/DnsProvider.md @@ -9,7 +9,7 @@ parameter_types: --- DnsProvider indicates that the specified provider should be used to manage -records for this domain. The name must match the name used with [NewDnsProvider](../global/NewDnsProvider.md). +records for this domain. The name must match the name used with [NewDnsProvider](../top_level_functions/NewDnsProvider.md). The nsCount parameter determines how the nameservers will be managed from this provider. diff --git a/documentation/functions/domain/FRAME.md b/documentation/language_reference/domain_modifier_functions/FRAME.md similarity index 100% rename from documentation/functions/domain/FRAME.md rename to documentation/language_reference/domain_modifier_functions/FRAME.md diff --git a/documentation/functions/domain/IGNORE.md b/documentation/language_reference/domain_modifier_functions/IGNORE.md similarity index 100% rename from documentation/functions/domain/IGNORE.md rename to documentation/language_reference/domain_modifier_functions/IGNORE.md diff --git a/documentation/functions/domain/IGNORE_NAME.md b/documentation/language_reference/domain_modifier_functions/IGNORE_NAME.md similarity index 100% rename from documentation/functions/domain/IGNORE_NAME.md rename to documentation/language_reference/domain_modifier_functions/IGNORE_NAME.md diff --git a/documentation/functions/domain/IGNORE_TARGET.md b/documentation/language_reference/domain_modifier_functions/IGNORE_TARGET.md similarity index 100% rename from documentation/functions/domain/IGNORE_TARGET.md rename to documentation/language_reference/domain_modifier_functions/IGNORE_TARGET.md diff --git a/documentation/functions/domain/IMPORT_TRANSFORM.md b/documentation/language_reference/domain_modifier_functions/IMPORT_TRANSFORM.md similarity index 100% rename from documentation/functions/domain/IMPORT_TRANSFORM.md rename to documentation/language_reference/domain_modifier_functions/IMPORT_TRANSFORM.md diff --git a/documentation/functions/domain/INCLUDE.md b/documentation/language_reference/domain_modifier_functions/INCLUDE.md similarity index 100% rename from documentation/functions/domain/INCLUDE.md rename to documentation/language_reference/domain_modifier_functions/INCLUDE.md diff --git a/documentation/functions/domain/LOC.md b/documentation/language_reference/domain_modifier_functions/LOC.md similarity index 84% rename from documentation/functions/domain/LOC.md rename to documentation/language_reference/domain_modifier_functions/LOC.md index 4431017e2e..a0252168f9 100644 --- a/documentation/functions/domain/LOC.md +++ b/documentation/language_reference/domain_modifier_functions/LOC.md @@ -86,10 +86,10 @@ the LOC record type will supply defaults where values were absent on DNS import. One must supply the `LOC()` js helper all parameters. If that seems like too much work, see also helper functions: - * [`LOC_BUILDER_DD({})`](../record/LOC_BUILDER_DD.md) - build a `LOC` by supplying only **d**ecimal **d**egrees. - * [`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 + * [`LOC_BUILDER_DD({})`](../record_modifier_functions/LOC_BUILDER_DD.md) - build a `LOC` by supplying only **d**ecimal **d**egrees. + * [`LOC_BUILDER_DMS_STR({})`](../record_modifier_functions/LOC_BUILDER_DMS_STR.md) - accepts DMS 33°51′31″S 151°12′51″E + * [`LOC_BUILDER_DMM_STR({})`](../record_modifier_functions/LOC_BUILDER_DMM_STR.md) - accepts DMM 25.24°S 153.15°E + * [`LOC_BUILDER_STR({})`](../record_modifier_functions/LOC_BUILDER_STR.md) - tries the cooordinate string in all `LOC_BUILDER_DM*_STR()` functions until one works ## Format ## diff --git a/documentation/functions/domain/MX.md b/documentation/language_reference/domain_modifier_functions/MX.md similarity index 100% rename from documentation/functions/domain/MX.md rename to documentation/language_reference/domain_modifier_functions/MX.md diff --git a/documentation/functions/domain/NAMESERVER.md b/documentation/language_reference/domain_modifier_functions/NAMESERVER.md similarity index 100% rename from documentation/functions/domain/NAMESERVER.md rename to documentation/language_reference/domain_modifier_functions/NAMESERVER.md diff --git a/documentation/functions/domain/NAMESERVER_TTL.md b/documentation/language_reference/domain_modifier_functions/NAMESERVER_TTL.md similarity index 81% rename from documentation/functions/domain/NAMESERVER_TTL.md rename to documentation/language_reference/domain_modifier_functions/NAMESERVER_TTL.md index af336263d6..9cde93409f 100644 --- a/documentation/functions/domain/NAMESERVER_TTL.md +++ b/documentation/language_reference/domain_modifier_functions/NAMESERVER_TTL.md @@ -10,7 +10,7 @@ parameter_types: NAMESERVER_TTL sets the TTL on the domain apex NS RRs defined by [`NAMESERVER`](NAMESERVER.md). -The value can be an integer or a string. See [`TTL`](../record/TTL.md) for examples. +The value can be an integer or a string. See [`TTL`](/documentation/02_language_reference/record_modifier_functions/TTL.md) for examples. {% code title="dnsconfig.js" %} ```javascript @@ -36,4 +36,4 @@ D('example.com', REGISTRAR, DnsProvider('xyz'), ``` {% endcode %} -To apply a default TTL to all other record types, see [`DefaultTTL`](../domain/DefaultTTL.md) +To apply a default TTL to all other record types, see [`DefaultTTL`](/documentation/02_language_reference/domain_modifier_functions/DefaultTTL.md) diff --git a/documentation/functions/domain/NAPTR.md b/documentation/language_reference/domain_modifier_functions/NAPTR.md similarity index 100% rename from documentation/functions/domain/NAPTR.md rename to documentation/language_reference/domain_modifier_functions/NAPTR.md diff --git a/documentation/functions/domain/NO_PURGE.md b/documentation/language_reference/domain_modifier_functions/NO_PURGE.md similarity index 100% rename from documentation/functions/domain/NO_PURGE.md rename to documentation/language_reference/domain_modifier_functions/NO_PURGE.md diff --git a/documentation/functions/domain/NS.md b/documentation/language_reference/domain_modifier_functions/NS.md similarity index 100% rename from documentation/functions/domain/NS.md rename to documentation/language_reference/domain_modifier_functions/NS.md diff --git a/documentation/functions/domain/PTR.md b/documentation/language_reference/domain_modifier_functions/PTR.md similarity index 97% rename from documentation/functions/domain/PTR.md rename to documentation/language_reference/domain_modifier_functions/PTR.md index 2360d8ca04..117c60bc0d 100644 --- a/documentation/functions/domain/PTR.md +++ b/documentation/language_reference/domain_modifier_functions/PTR.md @@ -53,7 +53,7 @@ are all equivalent: * `PTR('4.3',` // Assuming the domain is `2.1.in-addr.arpa` All magic is RFC2317-aware. We use the first format listed in the -RFC for both [`REV()`](../global/REV.md) and `PTR()`. The format is +RFC for both [`REV()`](../top_level_functions/REV.md) and `PTR()`. The format is `FIRST/MASK.C.B.A.in-addr.arpa` where `FIRST` is the first IP address of the zone, `MASK` is the netmask of the zone (25-31 inclusive), and A, B, C are the first 3 octets of the IP address. For example diff --git a/documentation/functions/domain/PURGE.md b/documentation/language_reference/domain_modifier_functions/PURGE.md similarity index 100% rename from documentation/functions/domain/PURGE.md rename to documentation/language_reference/domain_modifier_functions/PURGE.md diff --git a/documentation/functions/domain/SOA.md b/documentation/language_reference/domain_modifier_functions/SOA.md similarity index 100% rename from documentation/functions/domain/SOA.md rename to documentation/language_reference/domain_modifier_functions/SOA.md diff --git a/documentation/functions/domain/SRV.md b/documentation/language_reference/domain_modifier_functions/SRV.md similarity index 100% rename from documentation/functions/domain/SRV.md rename to documentation/language_reference/domain_modifier_functions/SRV.md diff --git a/documentation/functions/domain/SSHFP.md b/documentation/language_reference/domain_modifier_functions/SSHFP.md similarity index 100% rename from documentation/functions/domain/SSHFP.md rename to documentation/language_reference/domain_modifier_functions/SSHFP.md diff --git a/documentation/functions/domain/TLSA.md b/documentation/language_reference/domain_modifier_functions/TLSA.md similarity index 100% rename from documentation/functions/domain/TLSA.md rename to documentation/language_reference/domain_modifier_functions/TLSA.md diff --git a/documentation/functions/domain/TXT.md b/documentation/language_reference/domain_modifier_functions/TXT.md similarity index 98% rename from documentation/functions/domain/TXT.md rename to documentation/language_reference/domain_modifier_functions/TXT.md index 183948f868..8b4c29d229 100644 --- a/documentation/functions/domain/TXT.md +++ b/documentation/language_reference/domain_modifier_functions/TXT.md @@ -87,7 +87,7 @@ double quotes, back-ticks, or other chars. #### How can you tell if a provider will support a particular `TXT()` record? -Include the `TXT()` record in a [`D()`](../global/D.md) as usual, along +Include the `TXT()` record in a [`D()`](../top_level_functions/D.md) as usual, along with the `DnsProvider()` for that provider. Run `dnscontrol check` to see if any errors are produced. The check command does not talk to the provider's API, thus permitting you to do this without having an diff --git a/documentation/functions/domain/URL.md b/documentation/language_reference/domain_modifier_functions/URL.md similarity index 100% rename from documentation/functions/domain/URL.md rename to documentation/language_reference/domain_modifier_functions/URL.md diff --git a/documentation/functions/domain/URL301.md b/documentation/language_reference/domain_modifier_functions/URL301.md similarity index 100% rename from documentation/functions/domain/URL301.md rename to documentation/language_reference/domain_modifier_functions/URL301.md diff --git a/documentation/functions/domain/CLOUDNS_WR.md b/documentation/language_reference/domain_modifier_functions/service_provider_specific/ClouDNS/CLOUDNS_WR.md similarity index 100% rename from documentation/functions/domain/CLOUDNS_WR.md rename to documentation/language_reference/domain_modifier_functions/service_provider_specific/ClouDNS/CLOUDNS_WR.md diff --git a/documentation/functions/domain/NS1_URLFWD.md b/documentation/language_reference/domain_modifier_functions/service_provider_specific/NS1/NS1_URLFWD.md similarity index 100% rename from documentation/functions/domain/NS1_URLFWD.md rename to documentation/language_reference/domain_modifier_functions/service_provider_specific/NS1/NS1_URLFWD.md diff --git a/documentation/functions/domain/AKAMAICDN.md b/documentation/language_reference/domain_modifier_functions/service_provider_specific/akamai_edge_dns/AKAMAICDN.md similarity index 100% rename from documentation/functions/domain/AKAMAICDN.md rename to documentation/language_reference/domain_modifier_functions/service_provider_specific/akamai_edge_dns/AKAMAICDN.md diff --git a/documentation/functions/domain/R53_ALIAS.md b/documentation/language_reference/domain_modifier_functions/service_provider_specific/amazon_route_53/R53_ALIAS.md similarity index 96% rename from documentation/functions/domain/R53_ALIAS.md rename to documentation/language_reference/domain_modifier_functions/service_provider_specific/amazon_route_53/R53_ALIAS.md index 28f628c582..b00606b633 100644 --- a/documentation/functions/domain/R53_ALIAS.md +++ b/documentation/language_reference/domain_modifier_functions/service_provider_specific/amazon_route_53/R53_ALIAS.md @@ -13,7 +13,7 @@ provider: ROUTE53 `R53_ALIAS` is a Route53 specific virtual record type that points a record at either another record or an AWS entity (like a Cloudfront distribution, an ELB, etc...). It is analogous to a `CNAME`, but is usually resolved at request-time and served as an `A` record. Unlike `CNAME` records, `ALIAS` records can be used at the zone apex (`@`) -Unlike the regular [`ALIAS`](ALIAS.md) directive, `R53_ALIAS` is only supported on Route53. Attempting to use `R53_ALIAS` on another provider than Route53 will result in an error. +Unlike the regular [`ALIAS`](../../ALIAS.md) directive, `R53_ALIAS` is only supported on Route53. Attempting to use `R53_ALIAS` on another provider than Route53 will result in an error. The name should be the relative label for the domain. diff --git a/documentation/functions/domain/AZURE_ALIAS.md b/documentation/language_reference/domain_modifier_functions/service_provider_specific/azure_dns/AZURE_ALIAS.md similarity index 100% rename from documentation/functions/domain/AZURE_ALIAS.md rename to documentation/language_reference/domain_modifier_functions/service_provider_specific/azure_dns/AZURE_ALIAS.md diff --git a/documentation/functions/domain/CF_REDIRECT.md b/documentation/language_reference/domain_modifier_functions/service_provider_specific/cloudflare_dns/CF_REDIRECT.md similarity index 100% rename from documentation/functions/domain/CF_REDIRECT.md rename to documentation/language_reference/domain_modifier_functions/service_provider_specific/cloudflare_dns/CF_REDIRECT.md diff --git a/documentation/functions/domain/CF_TEMP_REDIRECT.md b/documentation/language_reference/domain_modifier_functions/service_provider_specific/cloudflare_dns/CF_TEMP_REDIRECT.md similarity index 100% rename from documentation/functions/domain/CF_TEMP_REDIRECT.md rename to documentation/language_reference/domain_modifier_functions/service_provider_specific/cloudflare_dns/CF_TEMP_REDIRECT.md diff --git a/documentation/functions/domain/CF_WORKER_ROUTE.md b/documentation/language_reference/domain_modifier_functions/service_provider_specific/cloudflare_dns/CF_WORKER_ROUTE.md similarity index 100% rename from documentation/functions/domain/CF_WORKER_ROUTE.md rename to documentation/language_reference/domain_modifier_functions/service_provider_specific/cloudflare_dns/CF_WORKER_ROUTE.md diff --git a/documentation/language_reference/domain_modifier_functions/service_provider_specific/ignore-me.md b/documentation/language_reference/domain_modifier_functions/service_provider_specific/ignore-me.md new file mode 100644 index 0000000000..e69de29bb2 diff --git a/documentation/functions/record/CAA_BUILDER.md b/documentation/language_reference/record_modifier_functions/CAA_BUILDER.md similarity index 93% rename from documentation/functions/record/CAA_BUILDER.md rename to documentation/language_reference/record_modifier_functions/CAA_BUILDER.md index 04bc365c39..fe1f23c82e 100644 --- a/documentation/functions/record/CAA_BUILDER.md +++ b/documentation/language_reference/record_modifier_functions/CAA_BUILDER.md @@ -16,7 +16,7 @@ parameter_types: --- 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 +`CAA` records for your domains. Instead of creating each `CAA` record individually, you can simply configure your report mail address, the authorized certificate authorities and the builder cares about the rest. diff --git a/documentation/functions/record/DMARC_BUILDER.md b/documentation/language_reference/record_modifier_functions/DMARC_BUILDER.md similarity index 100% rename from documentation/functions/record/DMARC_BUILDER.md rename to documentation/language_reference/record_modifier_functions/DMARC_BUILDER.md diff --git a/documentation/functions/record/LOC_BUILDER_DD.md b/documentation/language_reference/record_modifier_functions/LOC_BUILDER_DD.md similarity index 100% rename from documentation/functions/record/LOC_BUILDER_DD.md rename to documentation/language_reference/record_modifier_functions/LOC_BUILDER_DD.md diff --git a/documentation/functions/record/LOC_BUILDER_DMM_STR.md b/documentation/language_reference/record_modifier_functions/LOC_BUILDER_DMM_STR.md similarity index 100% rename from documentation/functions/record/LOC_BUILDER_DMM_STR.md rename to documentation/language_reference/record_modifier_functions/LOC_BUILDER_DMM_STR.md diff --git a/documentation/functions/record/LOC_BUILDER_DMS_STR.md b/documentation/language_reference/record_modifier_functions/LOC_BUILDER_DMS_STR.md similarity index 53% rename from documentation/functions/record/LOC_BUILDER_DMS_STR.md rename to documentation/language_reference/record_modifier_functions/LOC_BUILDER_DMS_STR.md index 728999f333..53be6ff54f 100644 --- a/documentation/functions/record/LOC_BUILDER_DMS_STR.md +++ b/documentation/language_reference/record_modifier_functions/LOC_BUILDER_DMS_STR.md @@ -20,9 +20,9 @@ parameter_types: - alt (float32, optional) - ttl (optional) -A helper to build [`LOC`](../domain/LOC.md) records. Supply three parameters instead of 12. +A helper to build [`LOC`](../domain_modifier_functions/LOC.md) records. Supply three parameters instead of 12. -Internally assumes some defaults for [`LOC`](../domain/LOC.md) records. +Internally assumes some defaults for [`LOC`](../domain_modifier_functions/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 @@ -49,8 +49,8 @@ D("example.com","none" 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 + * [`LOC()`](../domain_modifier_functions/LOC.md) - build a `LOC` by supplying all 12 parameters + * [`LOC_BUILDER_DD({})`](../record_modifier_functions/LOC_BUILDER_DD.md) - accepts cartesian x, y + * [`LOC_BUILDER_DMS_STR({})`](../record_modifier_functions/LOC_BUILDER_DMS_STR.md) - accepts DMS 33°51′31″S 151°12′51″E + * [`LOC_BUILDER_DMM_STR({})`](../record_modifier_functions/LOC_BUILDER_DMM_STR.md) - accepts DMM 25.24°S 153.15°E + * [`LOC_BUILDER_STR({})`](../record_modifier_functions/LOC_BUILDER_STR.md) - tries the cooordinate string in all `LOC_BUILDER_DM*_STR()` functions until one works diff --git a/documentation/functions/record/LOC_BUILDER_STR.md b/documentation/language_reference/record_modifier_functions/LOC_BUILDER_STR.md similarity index 100% rename from documentation/functions/record/LOC_BUILDER_STR.md rename to documentation/language_reference/record_modifier_functions/LOC_BUILDER_STR.md diff --git a/documentation/functions/record/SPF_BUILDER.md b/documentation/language_reference/record_modifier_functions/SPF_BUILDER.md similarity index 100% rename from documentation/functions/record/SPF_BUILDER.md rename to documentation/language_reference/record_modifier_functions/SPF_BUILDER.md diff --git a/documentation/functions/record/TTL.md b/documentation/language_reference/record_modifier_functions/TTL.md similarity index 89% rename from documentation/functions/record/TTL.md rename to documentation/language_reference/record_modifier_functions/TTL.md index 490e9d2eb3..51e9186440 100644 --- a/documentation/functions/record/TTL.md +++ b/documentation/language_reference/record_modifier_functions/TTL.md @@ -7,7 +7,7 @@ parameter_types: --- TTL sets the TTL for a single record only. This will take precedence -over the domain's [DefaultTTL](../domain/DefaultTTL.md) if supplied. +over the domain's [DefaultTTL](/documentation/02_language_reference/domain_modifier_functions/DefaultTTL.md) if supplied. The value can be: diff --git a/documentation/functions/record/R53_ZONE.md b/documentation/language_reference/record_modifier_functions/service_provider_specific/amazon_route_53/R53_ZONE.md similarity index 72% rename from documentation/functions/record/R53_ZONE.md rename to documentation/language_reference/record_modifier_functions/service_provider_specific/amazon_route_53/R53_ZONE.md index 02fb9dd9b7..0347007591 100644 --- a/documentation/functions/record/R53_ZONE.md +++ b/documentation/language_reference/record_modifier_functions/service_provider_specific/amazon_route_53/R53_ZONE.md @@ -12,4 +12,4 @@ R53_ZONE lets you specify the AWS Zone ID for an entire domain (D()) or a specif When used with D(), it sets the zone id of the domain. This can be used to differentiate between split horizon domains in public and private zones. -When used with R53_ALIAS() it sets the required Route53 hosted zone id in a R53_ALIAS record. See [R53_ALIAS's documentation](../domain/R53_ALIAS.md) for details. +When used with R53_ALIAS() it sets the required Route53 hosted zone id in a R53_ALIAS record. See [R53_ALIAS's documentation](02_language_reference/domain_modifier_functions/service_provider_specific/amazon_route_53/R53_ALIAS.md) for details. diff --git a/documentation/language_reference/record_modifier_functions/service_provider_specific/ignore-me.md b/documentation/language_reference/record_modifier_functions/service_provider_specific/ignore-me.md new file mode 100644 index 0000000000..e69de29bb2 diff --git a/documentation/functions/global/D.md b/documentation/language_reference/top_level_functions/D.md similarity index 94% rename from documentation/functions/global/D.md rename to documentation/language_reference/top_level_functions/D.md index 181ecc46ab..913e5f5f33 100644 --- a/documentation/functions/global/D.md +++ b/documentation/language_reference/top_level_functions/D.md @@ -12,7 +12,7 @@ parameter_types: `D` adds a new Domain for DNSControl to manage. The first two arguments are required: the domain name (fully qualified `example.com` without a trailing dot), and the name of the registrar (as previously declared with [NewRegistrar](NewRegistrar.md)). Any number of additional arguments may be included to add DNS Providers with [DNSProvider](NewDnsProvider.md), -add records with [A](../domain/A.md), [CNAME](../domain/CNAME.md), and so forth, or add metadata. +add records with [A](/documentation/02_language_reference/domain_modifier_functions/A.md), [CNAME](/documentation/02_language_reference/domain_modifier_functions/CNAME.md), and so forth, or add metadata. Modifier arguments are processed according to type as follows: diff --git a/documentation/functions/global/DEFAULTS.md b/documentation/language_reference/top_level_functions/DEFAULTS.md similarity index 88% rename from documentation/functions/global/DEFAULTS.md rename to documentation/language_reference/top_level_functions/DEFAULTS.md index 7a81ba54e5..28d073167f 100644 --- a/documentation/functions/global/DEFAULTS.md +++ b/documentation/language_reference/top_level_functions/DEFAULTS.md @@ -11,7 +11,7 @@ arguments passed as if they were the first modifiers in the argument list. ## Example -We want to create backup zone files for all domains, but not actually register them. Also create a [`DefaultTTL`](../domain/DefaultTTL.md). +We want to create backup zone files for all domains, but not actually register them. Also create a [`DefaultTTL`](/documentation/02_language_reference/domain_modifier_functions/DefaultTTL.md). The domain `example.com` will have the defaults set. {% code title="dnsconfig.js" %} diff --git a/documentation/functions/global/DOMAIN_ELSEWHERE.md b/documentation/language_reference/top_level_functions/DOMAIN_ELSEWHERE.md similarity index 89% rename from documentation/functions/global/DOMAIN_ELSEWHERE.md rename to documentation/language_reference/top_level_functions/DOMAIN_ELSEWHERE.md index bfcb367f93..f3adfb1966 100644 --- a/documentation/functions/global/DOMAIN_ELSEWHERE.md +++ b/documentation/language_reference/top_level_functions/DOMAIN_ELSEWHERE.md @@ -40,6 +40,6 @@ D("example.com", REG_NAMEDOTCOM, {% endcode %} {% hint style="info" %} -**NOTE**: The [`NO_PURGE`](../domain/NO_PURGE.md) is used out of abundance of caution but since no +**NOTE**: The [`NO_PURGE`](/documentation/02_language_reference/domain_modifier_functions/NO_PURGE.md) is used out of abundance of caution but since no `DnsProvider()` statements exist, no updates would be performed. {% endhint %} diff --git a/documentation/functions/global/DOMAIN_ELSEWHERE_AUTO.md b/documentation/language_reference/top_level_functions/DOMAIN_ELSEWHERE_AUTO.md similarity index 89% rename from documentation/functions/global/DOMAIN_ELSEWHERE_AUTO.md rename to documentation/language_reference/top_level_functions/DOMAIN_ELSEWHERE_AUTO.md index 3c11a7756b..48134c922c 100644 --- a/documentation/functions/global/DOMAIN_ELSEWHERE_AUTO.md +++ b/documentation/language_reference/top_level_functions/DOMAIN_ELSEWHERE_AUTO.md @@ -44,5 +44,5 @@ D("example.com", REG_NAMEDOTCOM, {% endcode %} {% hint style="info" %} -**NOTE**: The [`NO_PURGE`](../domain/NO_PURGE.md) is used to prevent DNSControl from changing the records. +**NOTE**: The [`NO_PURGE`](/documentation/02_language_reference/domain_modifier_functions/NO_PURGE.md) is used to prevent DNSControl from changing the records. {% endhint %} diff --git a/documentation/functions/global/D_EXTEND.md b/documentation/language_reference/top_level_functions/D_EXTEND.md similarity index 91% rename from documentation/functions/global/D_EXTEND.md rename to documentation/language_reference/top_level_functions/D_EXTEND.md index 9b0d9848d6..ea67a8afdc 100644 --- a/documentation/functions/global/D_EXTEND.md +++ b/documentation/language_reference/top_level_functions/D_EXTEND.md @@ -29,7 +29,7 @@ defined as separate domains via separate [`D()`](D.md) statements, then not `domain.tld`. Some operators only act on an apex domain (e.g. -[`CF_REDIRECT`](../domain/CF_REDIRECT.md) and [`CF_TEMP_REDIRECT`](../domain/CF_TEMP_REDIRECT.md)). Using them +[`CF_REDIRECT`](/documentation/02_language_reference/domain_modifier_functions/service_provider_specific/cloudflare_dns/CF_REDIRECT.md) and [`CF_TEMP_REDIRECT`](/documentation/02_language_reference/domain_modifier_functions/service_provider_specific/cloudflare_dns/CF_TEMP_REDIRECT.md)). Using them in a `D_EXTEND` subdomain may not be what you expect. {% code title="dnsconfig.js" %} diff --git a/documentation/functions/global/FETCH.md b/documentation/language_reference/top_level_functions/FETCH.md similarity index 100% rename from documentation/functions/global/FETCH.md rename to documentation/language_reference/top_level_functions/FETCH.md diff --git a/documentation/functions/global/IP.md b/documentation/language_reference/top_level_functions/IP.md similarity index 100% rename from documentation/functions/global/IP.md rename to documentation/language_reference/top_level_functions/IP.md diff --git a/documentation/functions/global/NewDnsProvider.md b/documentation/language_reference/top_level_functions/NewDnsProvider.md similarity index 100% rename from documentation/functions/global/NewDnsProvider.md rename to documentation/language_reference/top_level_functions/NewDnsProvider.md diff --git a/documentation/functions/global/NewRegistrar.md b/documentation/language_reference/top_level_functions/NewRegistrar.md similarity index 100% rename from documentation/functions/global/NewRegistrar.md rename to documentation/language_reference/top_level_functions/NewRegistrar.md diff --git a/documentation/functions/global/PANIC.md b/documentation/language_reference/top_level_functions/PANIC.md similarity index 100% rename from documentation/functions/global/PANIC.md rename to documentation/language_reference/top_level_functions/PANIC.md diff --git a/documentation/functions/global/REV.md b/documentation/language_reference/top_level_functions/REV.md similarity index 93% rename from documentation/functions/global/REV.md rename to documentation/language_reference/top_level_functions/REV.md index 9aba56cd6b..f1ab8e2958 100644 --- a/documentation/functions/global/REV.md +++ b/documentation/language_reference/top_level_functions/REV.md @@ -51,6 +51,6 @@ D(REV('2001:db8:302::/48'), REGISTRAR, DnsProvider(BIND), ``` {% endcode %} -In the future we plan on adding a flag to [`A()`](../domain/A.md)which will insert +In the future we plan on adding a flag to [`A()`](/documentation/02_language_reference/domain_modifier_functions/A.md)which will insert the correct PTR() record in the appropriate `D(REV())` domain (i.e. `.arpa` domain) has been defined. diff --git a/documentation/functions/global/getConfiguredDomains.md b/documentation/language_reference/top_level_functions/getConfiguredDomains.md similarity index 100% rename from documentation/functions/global/getConfiguredDomains.md rename to documentation/language_reference/top_level_functions/getConfiguredDomains.md diff --git a/documentation/functions/global/require.md b/documentation/language_reference/top_level_functions/require.md similarity index 100% rename from documentation/functions/global/require.md rename to documentation/language_reference/top_level_functions/require.md diff --git a/documentation/functions/global/require_glob.md b/documentation/language_reference/top_level_functions/require_glob.md similarity index 100% rename from documentation/functions/global/require_glob.md rename to documentation/language_reference/top_level_functions/require_glob.md diff --git a/documentation/providers.md b/documentation/service_providers/providers.md similarity index 100% rename from documentation/providers.md rename to documentation/service_providers/providers.md diff --git a/documentation/providers/akamaiedgedns.md b/documentation/service_providers/providers/akamaiedgedns.md similarity index 100% rename from documentation/providers/akamaiedgedns.md rename to documentation/service_providers/providers/akamaiedgedns.md diff --git a/documentation/providers/autodns.md b/documentation/service_providers/providers/autodns.md similarity index 100% rename from documentation/providers/autodns.md rename to documentation/service_providers/providers/autodns.md diff --git a/documentation/providers/axfrddns.md b/documentation/service_providers/providers/axfrddns.md similarity index 100% rename from documentation/providers/axfrddns.md rename to documentation/service_providers/providers/axfrddns.md diff --git a/documentation/providers/azure_dns.md b/documentation/service_providers/providers/azure_dns.md similarity index 100% rename from documentation/providers/azure_dns.md rename to documentation/service_providers/providers/azure_dns.md diff --git a/documentation/providers/bind.md b/documentation/service_providers/providers/bind.md similarity index 100% rename from documentation/providers/bind.md rename to documentation/service_providers/providers/bind.md diff --git a/documentation/providers/cloudflareapi.md b/documentation/service_providers/providers/cloudflareapi.md similarity index 100% rename from documentation/providers/cloudflareapi.md rename to documentation/service_providers/providers/cloudflareapi.md diff --git a/documentation/providers/cloudns.md b/documentation/service_providers/providers/cloudns.md similarity index 100% rename from documentation/providers/cloudns.md rename to documentation/service_providers/providers/cloudns.md diff --git a/documentation/providers/cscglobal.md b/documentation/service_providers/providers/cscglobal.md similarity index 100% rename from documentation/providers/cscglobal.md rename to documentation/service_providers/providers/cscglobal.md diff --git a/documentation/providers/desec.md b/documentation/service_providers/providers/desec.md similarity index 100% rename from documentation/providers/desec.md rename to documentation/service_providers/providers/desec.md diff --git a/documentation/providers/digitalocean.md b/documentation/service_providers/providers/digitalocean.md similarity index 100% rename from documentation/providers/digitalocean.md rename to documentation/service_providers/providers/digitalocean.md diff --git a/documentation/providers/dnsimple.md b/documentation/service_providers/providers/dnsimple.md similarity index 100% rename from documentation/providers/dnsimple.md rename to documentation/service_providers/providers/dnsimple.md diff --git a/documentation/providers/dnsmadeeasy.md b/documentation/service_providers/providers/dnsmadeeasy.md similarity index 100% rename from documentation/providers/dnsmadeeasy.md rename to documentation/service_providers/providers/dnsmadeeasy.md diff --git a/documentation/providers/dnsoverhttps.md b/documentation/service_providers/providers/dnsoverhttps.md similarity index 100% rename from documentation/providers/dnsoverhttps.md rename to documentation/service_providers/providers/dnsoverhttps.md diff --git a/documentation/providers/domainnameshop.md b/documentation/service_providers/providers/domainnameshop.md similarity index 100% rename from documentation/providers/domainnameshop.md rename to documentation/service_providers/providers/domainnameshop.md diff --git a/documentation/providers/easyname.md b/documentation/service_providers/providers/easyname.md similarity index 100% rename from documentation/providers/easyname.md rename to documentation/service_providers/providers/easyname.md diff --git a/documentation/providers/gandi_v5.md b/documentation/service_providers/providers/gandi_v5.md similarity index 100% rename from documentation/providers/gandi_v5.md rename to documentation/service_providers/providers/gandi_v5.md diff --git a/documentation/providers/gcloud.md b/documentation/service_providers/providers/gcloud.md similarity index 100% rename from documentation/providers/gcloud.md rename to documentation/service_providers/providers/gcloud.md diff --git a/documentation/providers/gcore.md b/documentation/service_providers/providers/gcore.md similarity index 100% rename from documentation/providers/gcore.md rename to documentation/service_providers/providers/gcore.md diff --git a/documentation/providers/hedns.md b/documentation/service_providers/providers/hedns.md similarity index 100% rename from documentation/providers/hedns.md rename to documentation/service_providers/providers/hedns.md diff --git a/documentation/providers/hetzner.md b/documentation/service_providers/providers/hetzner.md similarity index 100% rename from documentation/providers/hetzner.md rename to documentation/service_providers/providers/hetzner.md diff --git a/documentation/providers/hexonet.md b/documentation/service_providers/providers/hexonet.md similarity index 100% rename from documentation/providers/hexonet.md rename to documentation/service_providers/providers/hexonet.md diff --git a/documentation/providers/hostingde.md b/documentation/service_providers/providers/hostingde.md similarity index 100% rename from documentation/providers/hostingde.md rename to documentation/service_providers/providers/hostingde.md diff --git a/documentation/providers/internetbs.md b/documentation/service_providers/providers/internetbs.md similarity index 100% rename from documentation/providers/internetbs.md rename to documentation/service_providers/providers/internetbs.md diff --git a/documentation/providers/inwx.md b/documentation/service_providers/providers/inwx.md similarity index 100% rename from documentation/providers/inwx.md rename to documentation/service_providers/providers/inwx.md diff --git a/documentation/providers/linode.md b/documentation/service_providers/providers/linode.md similarity index 100% rename from documentation/providers/linode.md rename to documentation/service_providers/providers/linode.md diff --git a/documentation/providers/loopia.md b/documentation/service_providers/providers/loopia.md similarity index 100% rename from documentation/providers/loopia.md rename to documentation/service_providers/providers/loopia.md diff --git a/documentation/providers/luadns.md b/documentation/service_providers/providers/luadns.md similarity index 100% rename from documentation/providers/luadns.md rename to documentation/service_providers/providers/luadns.md diff --git a/documentation/providers/msdns.md b/documentation/service_providers/providers/msdns.md similarity index 100% rename from documentation/providers/msdns.md rename to documentation/service_providers/providers/msdns.md diff --git a/documentation/providers/namecheap.md b/documentation/service_providers/providers/namecheap.md similarity index 100% rename from documentation/providers/namecheap.md rename to documentation/service_providers/providers/namecheap.md diff --git a/documentation/providers/namedotcom.md b/documentation/service_providers/providers/namedotcom.md similarity index 100% rename from documentation/providers/namedotcom.md rename to documentation/service_providers/providers/namedotcom.md diff --git a/documentation/providers/netcup.md b/documentation/service_providers/providers/netcup.md similarity index 100% rename from documentation/providers/netcup.md rename to documentation/service_providers/providers/netcup.md diff --git a/documentation/providers/netlify.md b/documentation/service_providers/providers/netlify.md similarity index 100% rename from documentation/providers/netlify.md rename to documentation/service_providers/providers/netlify.md diff --git a/documentation/providers/ns1.md b/documentation/service_providers/providers/ns1.md similarity index 100% rename from documentation/providers/ns1.md rename to documentation/service_providers/providers/ns1.md diff --git a/documentation/providers/oracle.md b/documentation/service_providers/providers/oracle.md similarity index 100% rename from documentation/providers/oracle.md rename to documentation/service_providers/providers/oracle.md diff --git a/documentation/providers/ovh.md b/documentation/service_providers/providers/ovh.md similarity index 100% rename from documentation/providers/ovh.md rename to documentation/service_providers/providers/ovh.md diff --git a/documentation/providers/packetframe.md b/documentation/service_providers/providers/packetframe.md similarity index 100% rename from documentation/providers/packetframe.md rename to documentation/service_providers/providers/packetframe.md diff --git a/documentation/providers/porkbun.md b/documentation/service_providers/providers/porkbun.md similarity index 100% rename from documentation/providers/porkbun.md rename to documentation/service_providers/providers/porkbun.md diff --git a/documentation/providers/powerdns.md b/documentation/service_providers/providers/powerdns.md similarity index 100% rename from documentation/providers/powerdns.md rename to documentation/service_providers/providers/powerdns.md diff --git a/documentation/providers/route53.md b/documentation/service_providers/providers/route53.md similarity index 100% rename from documentation/providers/route53.md rename to documentation/service_providers/providers/route53.md diff --git a/documentation/providers/rwth.md b/documentation/service_providers/providers/rwth.md similarity index 100% rename from documentation/providers/rwth.md rename to documentation/service_providers/providers/rwth.md diff --git a/documentation/providers/softlayer.md b/documentation/service_providers/providers/softlayer.md similarity index 100% rename from documentation/providers/softlayer.md rename to documentation/service_providers/providers/softlayer.md diff --git a/documentation/providers/transip.md b/documentation/service_providers/providers/transip.md similarity index 100% rename from documentation/providers/transip.md rename to documentation/service_providers/providers/transip.md diff --git a/documentation/providers/vultr.md b/documentation/service_providers/providers/vultr.md similarity index 100% rename from documentation/providers/vultr.md rename to documentation/service_providers/providers/vultr.md diff --git a/main.go b/main.go index 758f54048c..26b52d8f60 100644 --- a/main.go +++ b/main.go @@ -12,7 +12,7 @@ import ( "github.com/fatih/color" ) -//go:generate go run build/generate/generate.go build/generate/featureMatrix.go build/generate/functionTypes.go build/generate/dtsFile.go +//go:generate go run build/generate/generate.go build/generate/featureMatrix.go build/generate/functionTypes.go build/generate/dtsFile.go build/generate/docuTOC.go // Version management. Goals: // 1. Someone who just does "go get" has at least some information. From 0238b08814824769ac5457a184e3d04605d8941f Mon Sep 17 00:00:00 2001 From: Paul Date: Fri, 24 Mar 2023 03:09:04 +0100 Subject: [PATCH 2/9] Change featureMatrix to use the new replace function (it has more error checks) --- build/generate/featureMatrix.go | 31 ++----------------------------- 1 file changed, 2 insertions(+), 29 deletions(-) diff --git a/build/generate/featureMatrix.go b/build/generate/featureMatrix.go index af52d00124..56b0c45198 100644 --- a/build/generate/featureMatrix.go +++ b/build/generate/featureMatrix.go @@ -1,7 +1,6 @@ package main import ( - "os" "sort" "strings" @@ -18,9 +17,9 @@ func generateFeatureMatrix() error { return err } - replaceInlineContent( + replaceTextBetweenMarkers( "documentation/providers.md", - "", + "\n", "", markdownTable, ) @@ -290,29 +289,3 @@ type FeatureMatrix struct { Features []string Providers map[string]FeatureMap } - -func replaceInlineContent( - file string, - startMarker string, - endMarker string, - newContent string, -) { - contentBytes, err := os.ReadFile(file) - if err != nil { - panic(err) - } - content := string(contentBytes) - - start := strings.Index(content, startMarker) - end := strings.Index(content, endMarker) - - newContentString := startMarker + "\n" + newContent + endMarker - newContentBytes := []byte(newContentString) - contentBytes = []byte(content) - contentBytes = append(contentBytes[:start], append(newContentBytes, contentBytes[end+len(endMarker):]...)...) - - err = os.WriteFile(file, contentBytes, 0644) - if err != nil { - panic(err) - } -} From 2e40fc4f0d16f8880d5330ad62dd3992836a54fd Mon Sep 17 00:00:00 2001 From: Paul Date: Fri, 24 Mar 2023 20:49:52 +0100 Subject: [PATCH 3/9] featureMatrix shall use new service_providers path for links --- build/generate/featureMatrix.go | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/build/generate/featureMatrix.go b/build/generate/featureMatrix.go index 56b0c45198..60e4ef0222 100644 --- a/build/generate/featureMatrix.go +++ b/build/generate/featureMatrix.go @@ -18,7 +18,7 @@ func generateFeatureMatrix() error { } replaceTextBetweenMarkers( - "documentation/providers.md", + "documentation/service_providers/providers.md", "\n", "", markdownTable, @@ -37,7 +37,7 @@ func markdownTable(matrix *FeatureMatrix) (string, error) { featureMap := matrix.Providers[providerName] var tableDataRow []string - tableDataRow = append(tableDataRow, "[`"+providerName+"`](providers/"+strings.ToLower(providerName)+".md)") + tableDataRow = append(tableDataRow, "[`"+providerName+"`](service_providers/"+strings.ToLower(providerName)+".md)") for _, featureName := range matrix.Features { tableDataRow = append(tableDataRow, featureEmoji(featureMap, featureName)) } From 3af6441cee4ff95c036711fb66843273a7e0edde Mon Sep 17 00:00:00 2001 From: Paul Date: Fri, 24 Mar 2023 03:09:25 +0100 Subject: [PATCH 4/9] Refresh --- commands/types/dnscontrol.d.ts | 2038 ++++++++++++++------------------ documentation/SUMMARY.md | 243 ++-- 2 files changed, 1039 insertions(+), 1242 deletions(-) diff --git a/commands/types/dnscontrol.d.ts b/commands/types/dnscontrol.d.ts index 90ece50825..fcbe000bb5 100644 --- a/commands/types/dnscontrol.d.ts +++ b/commands/types/dnscontrol.d.ts @@ -182,7 +182,7 @@ declare const DISABLE_REPEATED_DOMAIN_CHECK: RecordModifier; /** * A adds an A record To a domain. The name should be the relative label for the record. Use `@` for the domain apex. * - * The address should be an ip address, either a string, or a numeric value obtained via [IP](../global/IP.md). + * The address should be an ip address, either a string, or a numeric value obtained via [IP](../top_level_functions/IP.md). * * Modifiers can be any number of [record modifiers](https://docs.dnscontrol.org/language-reference/record-modifiers) or JSON objects, which will be merged into the record's metadata. * @@ -221,14 +221,6 @@ declare function A(name: string, address: string | number, ...modifiers: RecordM */ declare function AAAA(name: string, address: string, ...modifiers: RecordModifier[]): DomainModifier; -/** - * AKAMAICDN is a proprietary record type that is used to configure [Zone Apex Mapping](https://blogs.akamai.com/2019/08/fast-dns-zone-apex-mapping-dnssec.html). - * The AKAMAICDN target must be preconfigured in the Akamai network. - * - * @see https://dnscontrol.org/js#AKAMAICDN - */ -declare function AKAMAICDN(name: string, target: string, ...modifiers: RecordModifier[]): DomainModifier; - /** * ALIAS is a virtual record type that points a record at another record. It is analogous to a CNAME, but is usually resolved at request-time and served as an A record. Unlike CNAMEs, ALIAS records can be used at the zone apex (`@`) * @@ -293,53 +285,6 @@ declare const AUTODNSSEC_OFF: DomainModifier; */ declare const AUTODNSSEC_ON: DomainModifier; -/** - * AZURE_ALIAS is a Azure specific virtual record type that points a record at either another record or an Azure entity. - * It is analogous to a CNAME, but is usually resolved at request-time and served as an A record. - * Unlike CNAMEs, ALIAS records can be used at the zone apex (`@`) - * - * Unlike the regular ALIAS directive, AZURE_ALIAS is only supported on AZURE. - * Attempting to use AZURE_ALIAS on another provider than Azure will result in an error. - * - * The name should be the relative label for the domain. - * - * The type can be any of the following: - * * A - * * AAAA - * * CNAME - * - * Target should be the Azure Id representing the target. It starts `/subscription/`. The resource id can be found in https://resources.azure.com/. - * - * The Target can : - * - * * Point to a public IP resource from a DNS `A/AAAA` record set. - * You can create an A/AAAA record set and make it an alias record set to point to a public IP resource (standard or basic). - * The DNS record set changes automatically if the public IP address changes or is deleted. - * Dangling DNS records that point to incorrect IP addresses are avoided. - * There is a current limit of 20 alias records sets per resource. - * * Point to a Traffic Manager profile from a DNS `A/AAAA/CNAME` record set. - * You can create an A/AAAA or CNAME record set and use alias records to point it to a Traffic Manager profile. - * It's especially useful when you need to route traffic at a zone apex, as traditional CNAME records aren't supported for a zone apex. - * For example, say your Traffic Manager profile is myprofile.trafficmanager.net and your business DNS zone is contoso.com. - * You can create an alias record set of type A/AAAA for contoso.com (the zone apex) and point to myprofile.trafficmanager.net. - * * Point to an Azure Content Delivery Network (CDN) endpoint. - * This is useful when you create static websites using Azure storage and Azure CDN. - * * Point to another DNS record set within the same zone. - * Alias records can reference other record sets of the same type. - * For example, a DNS CNAME record set can be an alias to another CNAME record set. - * This arrangement is useful if you want some record sets to be aliases and some non-aliases. - * - * ```javascript - * D("example.com", REGISTRAR, DnsProvider("AZURE_DNS"), - * AZURE_ALIAS("foo", "A", "/subscriptions/726f8cd6-6459-4db4-8e6d-2cd2716904e2/resourceGroups/test/providers/Microsoft.Network/trafficManagerProfiles/testpp2"), // record for traffic manager - * AZURE_ALIAS("foo", "CNAME", "/subscriptions/726f8cd6-6459-4db4-8e6d-2cd2716904e2/resourceGroups/test/providers/Microsoft.Network/dnszones/example.com/A/quux."), // record in the same zone - * ); - * ``` - * - * @see https://dnscontrol.org/js#AZURE_ALIAS - */ -declare function AZURE_ALIAS(name: string, type: "A" | "AAAA" | "CNAME", target: string, ...modifiers: RecordModifier[]): DomainModifier; - /** * `CAA()` adds a CAA record to a domain. The name should be the relative label for the record. Use `@` for the domain apex. * @@ -365,100 +310,12 @@ declare function AZURE_ALIAS(name: string, type: "A" | "AAAA" | "CNAME", target: * ); * ``` * - * DNSControl contains a [`CAA_BUILDER`](../record/CAA_BUILDER.md) which can be used to simply create `CAA()` records for your domains. Instead of creating each CAA record individually, you can simply configure your report mail address, the authorized certificate authorities and the builder cares about the rest. + * DNSControl contains a [`CAA_BUILDER`](../record_modifier_functions/CAA_BUILDER.md) which can be used to simply create `CAA()` records for your domains. Instead of creating each CAA record individually, you can simply configure your report mail address, the authorized certificate authorities and the builder cares about the rest. * * @see https://dnscontrol.org/js#CAA */ declare function CAA(name: string, tag: "issue" | "issuewild" | "iodef", value: string, ...modifiers: RecordModifier[]): DomainModifier; -/** - * `CF_REDIRECT` uses Cloudflare-specific features ("Forwarding URL" Page Rules) to - * generate a HTTP 301 permanent redirect. - * - * If _any_ `CF_REDIRECT` or [`CF_TEMP_REDIRECT`](CF_TEMP_REDIRECT.md) functions are used then - * `dnscontrol` will manage _all_ "Forwarding URL" type Page Rules for the domain. - * Page Rule types other than "Forwarding URL” will be left alone. - * - * WARNING: Cloudflare does not currently fully document the Page Rules API and - * this interface is not extensively tested. Take precautions such as making - * backups and manually verifying `dnscontrol preview` output before running - * `dnscontrol push`. This is especially true when mixing Page Rules that are - * managed by DNSControl and those that aren't. - * - * HTTP 301 redirects are cached by browsers forever, usually ignoring any TTLs or - * other cache invalidation techniques. It should be used with great care. We - * suggest using a `CF_TEMP_REDIRECT` initially, then changing to a `CF_REDIRECT` - * only after sufficient time has elapsed to prove this is what you really want. - * - * This example redirects the bare (aka apex, or naked) domain to www: - * - * ```javascript - * D("foo.com", .... , - * CF_REDIRECT("mydomain.com/*", "https://www.mydomain.com/$1"), - * ); - * ``` - * - * @see https://dnscontrol.org/js#CF_REDIRECT - */ -declare function CF_REDIRECT(source: string, destination: string, ...modifiers: RecordModifier[]): DomainModifier; - -/** - * `CF_TEMP_REDIRECT` uses Cloudflare-specific features ("Forwarding URL" Page - * Rules) to generate a HTTP 302 temporary redirect. - * - * If _any_ [`CF_REDIRECT`](CF_REDIRECT.md) or `CF_TEMP_REDIRECT` functions are used then - * `dnscontrol` will manage _all_ "Forwarding URL" type Page Rules for the domain. - * Page Rule types other than "Forwarding URL” will be left alone. - * - * WARNING: Cloudflare does not currently fully document the Page Rules API and - * this interface is not extensively tested. Take precautions such as making - * backups and manually verifying `dnscontrol preview` output before running - * `dnscontrol push`. This is especially true when mixing Page Rules that are - * managed by DNSControl and those that aren't. - * - * ```javascript - * D("foo.com", .... , - * CF_TEMP_REDIRECT("example.mydomain.com/*", "https://otherplace.yourdomain.com/$1"), - * ); - * ``` - * - * @see https://dnscontrol.org/js#CF_TEMP_REDIRECT - */ -declare function CF_TEMP_REDIRECT(source: string, destination: string, ...modifiers: RecordModifier[]): DomainModifier; - -/** - * `CF_WORKER_ROUTE` uses the [Cloudflare Workers](https://developers.cloudflare.com/workers/) - * API to manage [worker routes](https://developers.cloudflare.com/workers/platform/routes) - * for a given domain. - * - * If _any_ `CF_WORKER_ROUTE` function is used then `dnscontrol` will manage _all_ - * Worker Routes for the domain. To be clear: this means it will delete existing routes that - * were created outside of DNSControl. - * - * WARNING: This interface is not extensively tested. Take precautions such as making - * backups and manually verifying `dnscontrol preview` output before running - * `dnscontrol push`. - * - * This example assigns the patterns `api.foo.com/*` and `foo.com/api/*` to a `my-worker` script: - * - * ```javascript - * D("foo.com", .... , - * CF_WORKER_ROUTE("api.foo.com/*", "my-worker"), - * CF_WORKER_ROUTE("foo.com/api/*", "my-worker"), - * ); - * ``` - * - * @see https://dnscontrol.org/js#CF_WORKER_ROUTE - */ -declare function CF_WORKER_ROUTE(pattern: string, script: string): DomainModifier; - -/** - * Documentation needed. - * - * @see https://dnscontrol.org/js#CLOUDNS_WR - */ -declare function CLOUDNS_WR(name: string, target: string, ...modifiers: RecordModifier[]): DomainModifier; - /** * CNAME adds a CNAME record to the domain. The name should be the relative label for the domain. * Using `@` or `*` for CNAME records is not recommended, as different providers support them differently. @@ -499,10 +356,10 @@ declare function CNAME(name: string, target: string, ...modifiers: RecordModifie declare function DS(name: string, keytag: number, algorithm: number, digesttype: number, digest: string, ...modifiers: RecordModifier[]): DomainModifier; /** - * DefaultTTL sets the TTL for all subsequent records following it in a domain that do not explicitly set one with [`TTL`](../record/TTL.md). If neither `DefaultTTL` or `TTL` exist for a record, - * the record will inherit the DNSControl global internal default of 300 seconds. See also [`DEFAULTS`](../global/DEFAULTS.md) to override the internal defaults. + * DefaultTTL sets the TTL for all subsequent records following it in a domain that do not explicitly set one with [`TTL`](/documentation/02_language_reference/record_modifier_functions/TTL.md). If neither `DefaultTTL` or `TTL` exist for a record, + * the record will inherit the DNSControl global internal default of 300 seconds. See also [`DEFAULTS`](/documentation/02_language_reference/top_level_functions/DEFAULTS.md) to override the internal defaults. * - * NS records are currently a special case, and do not inherit from `DefaultTTL`. See [`NAMESERVER_TTL`](../domain/NAMESERVER_TTL.md) to set a default TTL for all NS records. + * NS records are currently a special case, and do not inherit from `DefaultTTL`. See [`NAMESERVER_TTL`](/documentation/02_language_reference/domain_modifier_functions/NAMESERVER_TTL.md) to set a default TTL for all NS records. * * ```javascript * D('example.com', REGISTRAR, DnsProvider('R53'), @@ -512,7 +369,7 @@ declare function DS(name: string, keytag: number, algorithm: number, digesttype: * ); * ``` * - * The DefaultTTL duration is the same format as [`TTL`](../record/TTL.md), an integer number of seconds + * The DefaultTTL duration is the same format as [`TTL`](/documentation/02_language_reference/record_modifier_functions/TTL.md), an integer number of seconds * or a string with a unit such as `'4d'`. * * @see https://dnscontrol.org/js#DefaultTTL @@ -521,7 +378,7 @@ declare function DefaultTTL(ttl: Duration): DomainModifier; /** * DnsProvider indicates that the specified provider should be used to manage - * records for this domain. The name must match the name used with [NewDnsProvider](../global/NewDnsProvider.md). + * records for this domain. The name must match the name used with [NewDnsProvider](../top_level_functions/NewDnsProvider.md). * * The nsCount parameter determines how the nameservers will be managed from this provider. * @@ -742,10 +599,10 @@ declare function INCLUDE(domain: string): DomainModifier; * One must supply the `LOC()` js helper all parameters. If that seems like too * much work, see also helper functions: * - * * [`LOC_BUILDER_DD({})`](../record/LOC_BUILDER_DD.md) - build a `LOC` by supplying only **d**ecimal **d**egrees. - * * [`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 + * * [`LOC_BUILDER_DD({})`](../record_modifier_functions/LOC_BUILDER_DD.md) - build a `LOC` by supplying only **d**ecimal **d**egrees. + * * [`LOC_BUILDER_DMS_STR({})`](../record_modifier_functions/LOC_BUILDER_DMS_STR.md) - accepts DMS 33°51′31″S 151°12′51″E + * * [`LOC_BUILDER_DMM_STR({})`](../record_modifier_functions/LOC_BUILDER_DMM_STR.md) - accepts DMM 25.24°S 153.15°E + * * [`LOC_BUILDER_STR({})`](../record_modifier_functions/LOC_BUILDER_STR.md) - tries the cooordinate string in all `LOC_BUILDER_DM*_STR()` functions until one works * * ## Format ## * @@ -878,7 +735,7 @@ declare function NAMESERVER(name: string, ...modifiers: RecordModifier[]): Domai /** * NAMESERVER_TTL sets the TTL on the domain apex NS RRs defined by [`NAMESERVER`](NAMESERVER.md). * - * The value can be an integer or a string. See [`TTL`](../record/TTL.md) for examples. + * The value can be an integer or a string. See [`TTL`](/documentation/02_language_reference/record_modifier_functions/TTL.md) for examples. * * ```javascript * D('example.com', REGISTRAR, DnsProvider('R53'), @@ -900,7 +757,7 @@ declare function NAMESERVER(name: string, ...modifiers: RecordModifier[]): Domai * ); * ``` * - * To apply a default TTL to all other record types, see [`DefaultTTL`](../domain/DefaultTTL.md) + * To apply a default TTL to all other record types, see [`DefaultTTL`](/documentation/02_language_reference/domain_modifier_functions/DefaultTTL.md) * * @see https://dnscontrol.org/js#NAMESERVER_TTL */ @@ -1160,13 +1017,6 @@ declare const NO_PURGE: DomainModifier; */ declare function NS(name: string, target: string, ...modifiers: RecordModifier[]): DomainModifier; -/** - * Documentation needed. - * - * @see https://dnscontrol.org/js#NS1_URLFWD - */ -declare function NS1_URLFWD(name: string, target: string, ...modifiers: RecordModifier[]): DomainModifier; - /** * PTR adds a PTR record to the domain. * @@ -1211,7 +1061,7 @@ declare function NS1_URLFWD(name: string, target: string, ...modifiers: RecordMo * * `PTR('4.3',` // Assuming the domain is `2.1.in-addr.arpa` * * All magic is RFC2317-aware. We use the first format listed in the - * RFC for both [`REV()`](../global/REV.md) and `PTR()`. The format is + * RFC for both [`REV()`](../top_level_functions/REV.md) and `PTR()`. The format is * `FIRST/MASK.C.B.A.in-addr.arpa` where `FIRST` is the first IP address * of the zone, `MASK` is the netmask of the zone (25-31 inclusive), * and A, B, C are the first 3 octets of the IP address. For example @@ -1291,47 +1141,6 @@ declare function PTR(name: string, target: string, ...modifiers: RecordModifier[ */ declare const PURGE: DomainModifier; -/** - * `R53_ALIAS` is a Route53 specific virtual record type that points a record at either another record or an AWS entity (like a Cloudfront distribution, an ELB, etc...). It is analogous to a `CNAME`, but is usually resolved at request-time and served as an `A` record. Unlike `CNAME` records, `ALIAS` records can be used at the zone apex (`@`) - * - * Unlike the regular [`ALIAS`](ALIAS.md) directive, `R53_ALIAS` is only supported on Route53. Attempting to use `R53_ALIAS` on another provider than Route53 will result in an error. - * - * The name should be the relative label for the domain. - * - * Target should be a string representing the target. If it is a single label we will assume it is a relative name on the current domain. If it contains *any* dots, it should be a fully qualified domain name, ending with a `.`. - * - * The Target can be any of: - * - * * _CloudFront distribution_: in this case specify the domain name that CloudFront assigned when you created your distribution (note that your CloudFront distribution must include an alternate domain name that matches the record you're adding) - * * _Elastic Beanstalk environment_: specify the `CNAME` attribute for the environment. The environment must have a regionalized domain name. To get the `CNAME`, you can use either the [AWS Console](http://docs.aws.amazon.com/elasticbeanstalk/latest/dg/customdomains.html), [AWS Elastic Beanstalk API](http://docs.aws.amazon.com/elasticbeanstalk/latest/api/API_DescribeEnvironments.html), or the [AWS CLI](http://docs.aws.amazon.com/cli/latest/reference/elasticbeanstalk/describe-environments.html). - * * _ELB load balancer_: specify the DNS name that is associated with the load balancer. To get the DNS name you can use either the AWS Console (on the EC2 page, choose Load Balancers, select the right one, choose the description tab), [ELB API](http://docs.aws.amazon.com/elasticloadbalancing/latest/APIReference/API_DescribeLoadBalancers.html), the [AWS ELB CLI](http://docs.aws.amazon.com/cli/latest/reference/elb/describe-load-balancers.html), or the [AWS ELBv2 CLI](http://docs.aws.amazon.com/cli/latest/reference/elbv2/describe-load-balancers.html). - * * _S3 bucket_ (configured as website): specify the domain name of the Amazon S3 website endpoint in which you configured the bucket (for instance s3-website-us-east-2.amazonaws.com). For the available values refer to the [Amazon S3 Website Endpoints](http://docs.aws.amazon.com/general/latest/gr/rande.html#s3_region). - * * _Another Route53 record_: specify the value of the name of another record in the same hosted zone. - * - * For all the target type, excluding 'another record', you have to specify the `Zone ID` of the target. This is done by using the `R53_ZONE` record modifier. - * - * The zone id can be found depending on the target type: - * - * * _CloudFront distribution_: specify `Z2FDTNDATAQYW2` - * * _Elastic Beanstalk environment_: specify the hosted zone ID for the region in which the environment has been created. Refer to the [List of regions and hosted Zone IDs](http://docs.aws.amazon.com/general/latest/gr/rande.html#elasticbeanstalk_region). - * * _ELB load balancer_: specify the value of the hosted zone ID for the load balancer. You can find it in [the List of regions and hosted Zone IDs](http://docs.aws.amazon.com/general/latest/gr/rande.html#elb_region) - * * _S3 bucket_ (configured as website): specify the hosted zone ID for the region that you created the bucket in. You can find it in [the List of regions and hosted Zone IDs](http://docs.aws.amazon.com/general/latest/gr/rande.html#s3_region) - * * _Another Route 53 record_: you can either specify the correct zone id or do not specify anything and DNSControl will figure out the right zone id. (Note: Route53 alias can't reference a record in a different zone). - * - * ```javascript - * D('example.com', REGISTRAR, DnsProvider('ROUTE53'), - * R53_ALIAS('foo', 'A', 'bar'), // record in same zone - * R53_ALIAS('foo', 'A', 'bar', R53_ZONE('Z35SXDOTRQ7X7K')), // record in same zone, zone specified - * R53_ALIAS('foo', 'A', 'blahblah.elasticloadbalancing.us-west-1.amazonaws.com.', R53_ZONE('Z368ELLRRE2KJ0')), // a classic ELB in us-west-1 - * R53_ALIAS('foo', 'A', 'blahblah.elasticbeanstalk.us-west-2.amazonaws.com.', R53_ZONE('Z38NKT9BP95V3O')), // an Elastic Beanstalk environment in us-west-2 - * R53_ALIAS('foo', 'A', 'blahblah-bucket.s3-website-us-west-1.amazonaws.com.', R53_ZONE('Z2F56UZL2M1ACD')), // a website S3 Bucket in us-west-1 - * ); - * ``` - * - * @see https://dnscontrol.org/js#R53_ALIAS - */ -declare function R53_ALIAS(name: string, target: string, zone_idModifier: DomainModifier & RecordModifier): DomainModifier; - /** * `SOA` adds an `SOA` record to a domain. The name should be `@`. ns and mbox are strings. The other fields are unsigned 32-bit ints. * @@ -1496,7 +1305,7 @@ declare function TLSA(name: string, usage: number, selector: number, type: numbe * * #### How can you tell if a provider will support a particular `TXT()` record? * - * Include the `TXT()` record in a [`D()`](../global/D.md) as usual, along + * Include the `TXT()` record in a [`D()`](../top_level_functions/D.md) as usual, along * with the `DnsProvider()` for that provider. Run `dnscontrol check` to * see if any errors are produced. The check command does not talk to * the provider's API, thus permitting you to do this without having an @@ -1540,1200 +1349,1189 @@ declare function URL(name: string, target: string, ...modifiers: RecordModifier[ declare function URL301(name: string, ...modifiers: RecordModifier[]): DomainModifier; /** - * `D` adds a new Domain for DNSControl to manage. The first two arguments are required: the domain name (fully qualified `example.com` without a trailing dot), and the - * name of the registrar (as previously declared with [NewRegistrar](NewRegistrar.md)). Any number of additional arguments may be included to add DNS Providers with [DNSProvider](NewDnsProvider.md), - * add records with [A](../domain/A.md), [CNAME](../domain/CNAME.md), and so forth, or add metadata. + * DNSControl contains a `CAA_BUILDER` which can be used to simply create + * `CAA` records for your domains. Instead of creating each `CAA` record + * individually, you can simply configure your report mail address, the + * authorized certificate authorities and the builder cares about the rest. * - * Modifier arguments are processed according to type as follows: + * ## Example * - * - A function argument will be called with the domain object as it's only argument. Most of the [built-in modifier functions](https://docs.dnscontrol.org/language-reference/domain-modifiers) return such functions. - * - An object argument will be merged into the domain's metadata collection. - * - An array argument will have all of it's members evaluated recursively. This allows you to combine multiple common records or modifiers into a variable that can - * be used like a macro in multiple domains. + * For example you can use: * * ```javascript - * var REGISTRAR = NewRegistrar("name.com"); - * var r53 = NewDnsProvider("R53"); - * - * // simple domain - * D("example.com", REGISTRAR, DnsProvider(r53), - * A("@","1.2.3.4"), - * CNAME("test", "foo.example2.com.") - * ); - * - * // "macro" for records that can be mixed into any zone - * var GOOGLE_APPS_DOMAIN_MX = [ - * 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.'), - * ] - * - * D("example.com", REGISTRAR, DnsProvider(r53), - * A("@","1.2.3.4"), - * CNAME("test", "foo.example2.com."), - * GOOGLE_APPS_DOMAIN_MX - * ); + * CAA_BUILDER({ + * label: "@", + * iodef: "mailto:test@domain.tld", + * iodef_critical: true, + * issue: [ + * "letsencrypt.org", + * "comodoca.com", + * ], + * issuewild: "none", + * }) * ``` * - * # Split Horizon DNS + * The parameters are: * - * DNSControl supports Split Horizon DNS. Simply - * define the domain two or more times, each with - * their own unique parameters. + * * `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) * - * To differentiate the different domains, specify the domains as - * `domain.tld!tag`, such as `example.com!inside` and - * `example.com!outside`. + * `CAA_BUILDER()` returns multiple records (when configured as example above): * * ```javascript - * var REG = NewRegistrar("Third-Party"); - * var DNS_INSIDE = NewDnsProvider("Cloudflare"); - * var DNS_OUTSIDE = NewDnsProvider("bind"); - * - * D("example.com!inside", REG, DnsProvider(DNS_INSIDE), - * A("www", "10.10.10.10") - * ); - * - * D("example.com!outside", REG, DnsProvider(DNS_OUTSIDE), - * A("www", "20.20.20.20") - * ); - * - * D_EXTEND("example.com!inside", - * A("internal", "10.99.99.99") - * ); + * CAA("@", "iodef", "mailto:test@domain.tld", CAA_CRITICAL) + * CAA("@", "issue", "letsencrypt.org") + * CAA("@", "issue", "comodoca.com") + * CAA("@", "issuewild", ";") * ``` * - * A domain name without a `!` is assigned a tag that is the empty - * string. For example, `example.com` and `example.com!` are equivalent. - * However, we strongly recommend against using the empty tag, as it - * risks creating confusion. In other words, if you have `domain.tld` - * and `domain.tld!external` you now require humans to remember that - * `domain.tld` is the external one. I mean... the internal one. You - * may have noticed this mistake, but will your coworkers? Will you in - * six months? You get the idea. - * - * DNSControl command line flag `--domains` matches the full name (with the "!"). If you - * define domains `example.com!george` and `example.com!john` then: - * - * * `--domains=example.com` will not match either domain. - * * `--domains='example.com!george'` will match only match the first. - * * `--domains='example.com!george',example.com!john` will match both. - * - * NOTE: The quotes are required if your shell treats `!` as a special - * character, which is probably does. If you see an error that mentions - * `event not found` you probably forgot the quotes. - * - * @see https://dnscontrol.org/js#D + * @see https://dnscontrol.org/js#CAA_BUILDER */ -declare function D(name: string, registrar: string, ...modifiers: DomainModifier[]): void; +declare function CAA_BUILDER(opts: { label?: string; iodef: string; iodef_critical?: boolean; issue: string[]; issuewild: string }): RecordModifier; /** - * `DEFAULTS` allows you to declare a set of default arguments to apply to all subsequent domains. Subsequent calls to [`D`](D.md) will have these - * arguments passed as if they were the first modifiers in the argument list. + * DNSControl contains a `DMARC_BUILDER` which can be used to simply create + * DMARC policies for your domains. * * ## Example * - * We want to create backup zone files for all domains, but not actually register them. Also create a [`DefaultTTL`](../domain/DefaultTTL.md). - * The domain `example.com` will have the defaults set. + * ### Simple example * * ```javascript - * var COMMON = NewDnsProvider("foo"); - * DEFAULTS( - * DnsProvider(COMMON, 0), - * DefaultTTL('1d') - * ); - * - * D("example.com", - * REGISTRAR, - * DnsProvider("R53"), - * A("@","1.2.3.4") - * ); + * DMARC_BUILDER({ + * policy: 'reject', + * ruf: [ + * 'mailto:mailauth-reports@example.com', + * ], + * }) * ``` * - * If you want to clear the defaults, you can do the following. - * The domain `example2.com` will **not** have the defaults set. - * - * ```javascript - * DEFAULTS(); + * This yield the following record: * - * D("example2.com", - * REGISTRAR, - * DnsProvider("R53"), - * A("@","1.2.3.4") - * ); + * ```text + * @ IN TXT "v=DMARC1; p=reject; ruf=mailto:mailauth-reports@example.com" * ``` * - * @see https://dnscontrol.org/js#DEFAULTS - */ -declare function DEFAULTS(...modifiers: DomainModifier[]): void; - -/** - * `DOMAIN_ELSEWHERE()` is a helper macro that lets you easily indicate that - * a domain's zones are managed elsewhere. That is, it permits you easily delegate - * a domain to a hard-coded list of DNS servers. - * - * `DOMAIN_ELSEWHERE` is useful when you control a domain's registrar but not the - * DNS servers. For example, suppose you own a domain but the DNS servers are run - * by someone else, perhaps a SaaS product you've subscribed to or a DNS server - * that is run by your brother-in-law who doesn't trust you with the API keys that - * would let you maintain the domain using DNSControl. You need an easy way to - * point (delegate) the domain at a specific list of DNS servers. - * - * For example these two statements are equivalent: + * ### Advanced example * * ```javascript - * DOMAIN_ELSEWHERE("example.com", REG_NAMEDOTCOM, ["ns1.foo.com", "ns2.foo.com"]); + * 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', + * }); * ``` * * ```javascript - * D("example.com", REG_NAMEDOTCOM, - * NO_PURGE, - * NAMESERVER("ns1.foo.com"), - * NAMESERVER("ns2.foo.com") - * ); + * DMARC_BUILDER({ + * label: 'insecure', + * policy: 'none', + * ruf: [ + * 'mailto:mailauth-reports@example.com', + * ], + * failureOptions: { + * SPF: false, + * DKIM: true, + * }, + * }); * ``` * - * NOTE: The [`NO_PURGE`](../domain/NO_PURGE.md) is used out of abundance of caution but since no - * `DnsProvider()` statements exist, no updates would be performed. + * This yields the following records: * - * @see https://dnscontrol.org/js#DOMAIN_ELSEWHERE + * ```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. + * + * @see https://dnscontrol.org/js#DMARC_BUILDER */ -declare function DOMAIN_ELSEWHERE(name: string, registrar: string, nameserver_names: string[]): void; +declare function DMARC_BUILDER(opts: { 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 }): RecordModifier; /** - * `DOMAIN_ELSEWHERE_AUTO()` is similar to `DOMAIN_ELSEWHERE()` but instead of - * a hardcoded list of nameservers, a DnsProvider() is queried. + * `LOC_BUILDER_DD({})` actually takes an object with the following properties: * - * `DOMAIN_ELSEWHERE_AUTO` is useful when you control a domain's registrar but the - * DNS zones are managed by another system. Luckily you have enough access to that - * other system that you can query it to determine the zone's nameservers. + * - label (optional, defaults to `@`) + * - x (float32) + * - y (float32) + * - alt (float32, optional) + * - ttl (optional) * - * For example, suppose you own a domain but the DNS servers for it are in Azure. - * Further suppose that something in Azure maintains the zones (automatic or - * human). Azure picks the nameservers for the domains automatically, and that - * list may change occasionally. `DOMAIN_ELSEWHERE_AUTO` allows you to easily - * query Azure to determine the domain's delegations so that you do not need to - * hard-code them in your dnsconfig.js file. + * A helper to build [`LOC`](/documentation/02_language_reference/domain_modifier_functions/LOC.md) records. Supply four parameters instead of 12. * - * For example these two statements are equivalent: + * Internally assumes some defaults for [`LOC`](/documentation/02_language_reference/domain_modifier_functions/LOC.md) records. * - * ```javascript - * DOMAIN_ELSEWHERE_AUTO("example.com", REG_NAMEDOTCOM, DSP_AZURE); - * ``` + * 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` * * ```javascript - * D("example.com", REG_NAMEDOTCOM, - * NO_PURGE, - * DnsProvider(DSP_AZURE) + * D("example.com","none" + * , 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", + * }) * ); + * * ``` * - * NOTE: The [`NO_PURGE`](../domain/NO_PURGE.md) is used to prevent DNSControl from changing the records. + * Part of the series: + * * [`LOC()`](/documentation/02_language_reference/domain_modifier_functions/LOC.md) - build a `LOC` by supplying all 12 parameters + * * [`LOC_BUILDER_DD({})`](/documentation/02_language_reference/record_modifier_functions/LOC_BUILDER_DD.md) - accepts cartesian x, y + * * [`LOC_BUILDER_DMS_STR({})`](/documentation/02_language_reference/record_modifier_functions/LOC_BUILDER_DMS_STR.md) - accepts DMS 33°51′31″S 151°12′51″E + * * [`LOC_BUILDER_DMM_STR({})`](/documentation/02_language_reference/record_modifier_functions/LOC_BUILDER_DMM_STR.md) - accepts DMM 25.24°S 153.15°E + * * [`LOC_BUILDER_STR({})`](/documentation/02_language_reference/record_modifier_functions/LOC_BUILDER_STR.md) - tries the cooordinate string in all `LOC_BUILDER_DM*_STR()` functions until one works * - * @see https://dnscontrol.org/js#DOMAIN_ELSEWHERE_AUTO + * @see https://dnscontrol.org/js#LOC_BUILDER_DD */ -declare function DOMAIN_ELSEWHERE_AUTO(name: string, domain: string, registrar: string, dnsProvider: string): void; +declare function LOC_BUILDER_DD(opts: { label?: string; x: number; y: number; alt?: number; ttl?: Duration }): RecordModifier; /** - * `D_EXTEND` adds records (and metadata) to a domain previously defined - * by [`D()`](D.md). It can also be used to add subdomain records (and metadata) - * to a previously defined domain. + * `LOC_BUILDER_DMM({})` actually takes an object with the following properties: * - * The first argument is a domain name. If it exactly matches a - * previously defined domain, `D_EXTEND()` behaves the same as [`D()`](D.md), - * simply adding records as if they had been specified in the original - * [`D()`](D.md). + * - label (string, optional, defaults to `@`) + * - str (string) + * - alt (float32, optional) + * - ttl (optional) * - * If the domain name does not match an existing domain, but could be a - * (non-delegated) subdomain of an existing domain, the new records (and - * metadata) are added with the subdomain part appended to all record - * names (labels), and targets (as appropriate). See the examples below. + * A helper to build [`LOC`](../domain_modifier_functions/LOC.md) records. Supply three parameters instead of 12. * - * Matching the domain name to previously-defined domains is done using a - * `longest match` algorithm. If `domain.tld` and `sub.domain.tld` are - * defined as separate domains via separate [`D()`](D.md) statements, then - * `D_EXTEND('sub.sub.domain.tld', ...)` would match `sub.domain.tld`, - * not `domain.tld`. + * Internally assumes some defaults for [`LOC`](../domain_modifier_functions/LOC.md) records. * - * Some operators only act on an apex domain (e.g. - * [`CF_REDIRECT`](../domain/CF_REDIRECT.md) and [`CF_TEMP_REDIRECT`](../domain/CF_TEMP_REDIRECT.md)). Using them - * in a `D_EXTEND` subdomain may not be what you expect. + * 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` * * ```javascript - * D("domain.tld", REG, DnsProvider(DNS), - * A("@", "127.0.0.1"), // domain.tld - * A("www", "127.0.0.2"), // www.domain.tld - * CNAME("a", "b") // a.domain.tld -> b.domain.tld - * ); - * D_EXTEND("domain.tld", - * A("aaa", "127.0.0.3"), // aaa.domain.tld - * CNAME("c", "d") // c.domain.tld -> d.domain.tld - * ); - * D_EXTEND("sub.domain.tld", - * A("bbb", "127.0.0.4"), // bbb.sub.domain.tld - * A("ccc", "127.0.0.5"), // ccc.sub.domain.tld - * CNAME("e", "f") // e.sub.domain.tld -> f.sub.domain.tld - * ); - * D_EXTEND("sub.sub.domain.tld", - * A("ddd", "127.0.0.6"), // ddd.sub.sub.domain.tld - * CNAME("g", "h") // g.sub.sub.domain.tld -> h.sub.sub.domain.tld - * ); - * D_EXTEND("sub.domain.tld", - * A("@", "127.0.0.7"), // sub.domain.tld - * CNAME("i", "j") // i.sub.domain.tld -> j.sub.domain.tld + * D("example.com","none" + * LOC_BUILDER_STR({ + * label: "tasmania", + * str: '42°S 147°E', + * alt: 3, + * }) * ); - * ``` - * - * This will end up in the following modifications: (This output assumes the `--full` flag) * - * ```text - * ******************** Domain: domain.tld - * ----- Getting nameservers from: cloudflare - * ----- DNS Provider: cloudflare...7 corrections - * #1: CREATE A aaa.domain.tld 127.0.0.3 - * #2: CREATE A bbb.sub.domain.tld 127.0.0.4 - * #3: CREATE A ccc.sub.domain.tld 127.0.0.5 - * #4: CREATE A ddd.sub.sub.domain.tld 127.0.0.6 - * #5: CREATE A sub.domain.tld 127.0.0.7 - * #6: CREATE A www.domain.tld 127.0.0.2 - * #7: CREATE A domain.tld 127.0.0.1 - * #8: CREATE CNAME a.domain.tld b.domain.tld. - * #9: CREATE CNAME c.domain.tld d.domain.tld. - * #10: CREATE CNAME e.sub.domain.tld f.sub.domain.tld. - * #11: CREATE CNAME g.sub.sub.domain.tld h.sub.sub.domain.tld. - * #12: CREATE CNAME i.sub.domain.tld j.sub.domain.tld. * ``` * - * ProTips: `D_EXTEND()` permits you to create very complex and - * sophisticated configurations, but you shouldn't. Be nice to the next - * person that edits the file, who may not be as expert as yourself. - * Enhance readability by putting any `D_EXTEND()` statements immediately - * after the original [`D()`](D.md), like in above example. Avoid the temptation - * to obscure the addition of records to existing domains with randomly - * placed `D_EXTEND()` statements. Don't build up a domain using loops of - * `D_EXTEND()` statements. You'll be glad you didn't. + * Part of the series: + * * [`LOC()`](../domain_modifier_functions/LOC.md) - build a `LOC` by supplying all 12 parameters + * * [`LOC_BUILDER_DD({})`](../record_modifier_functions/LOC_BUILDER_DD.md) - accepts cartesian x, y + * * [`LOC_BUILDER_DMS_STR({})`](../record_modifier_functions/LOC_BUILDER_DMS_STR.md) - accepts DMS 33°51′31″S 151°12′51″E + * * [`LOC_BUILDER_DMM_STR({})`](../record_modifier_functions/LOC_BUILDER_DMM_STR.md) - accepts DMM 25.24°S 153.15°E + * * [`LOC_BUILDER_STR({})`](../record_modifier_functions/LOC_BUILDER_STR.md) - tries the cooordinate string in all `LOC_BUILDER_DM*_STR()` functions until one works * - * @see https://dnscontrol.org/js#D_EXTEND + * @see https://dnscontrol.org/js#LOC_BUILDER_DMM_STR */ -declare function D_EXTEND(name: string, ...modifiers: DomainModifier[]): void; +declare function LOC_BUILDER_DMM_STR(opts: { label?: string; str: string; alt?: number; ttl?: Duration }): RecordModifier; /** - * Converts an IPv4 address from string to an integer. This allows performing mathematical operations with the IP address. + * `LOC_BUILDER_DMS_STR({})` actually takes an object with the following properties: * - * ```javascript - * var addrA = IP('1.2.3.4') - * var addrB = addrA + 1 - * // addrB = 1.2.3.5 - * ``` + * - label (string, optional, defaults to `@`) + * - str (string) + * - alt (float32, optional) + * - ttl (optional) * - * NOTE: `IP()` does not accept IPv6 addresses (PRs gladly accepted!). IPv6 addresses are simply strings: + * A helper to build [`LOC`](../domain_modifier_functions/LOC.md) records. Supply three parameters instead of 12. + * + * Internally assumes some defaults for [`LOC`](../domain_modifier_functions/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` * * ```javascript - * // IPv4 Var - * var addrA1 = IP("1.2.3.4"); - * var addrA2 = "1.2.3.4"; + * D("example.com","none" + * LOC_BUILDER_DMS_STR({ + * label: "sydney-opera-house", + * str: '33°51′31″S 151°12′51″E', + * alt: 4, + * ttl: "5m", + * }) + * ); * - * // IPv6 Var - * var addrAAAA = "0:0:0:0:0:0:0:0"; * ``` * - * @see https://dnscontrol.org/js#IP + * Part of the series: + * * [`LOC()`](../domain_modifier_functions/LOC.md) - build a `LOC` by supplying all 12 parameters + * * [`LOC_BUILDER_DD({})`](../record_modifier_functions/LOC_BUILDER_DD.md) - accepts cartesian x, y + * * [`LOC_BUILDER_DMS_STR({})`](../record_modifier_functions/LOC_BUILDER_DMS_STR.md) - accepts DMS 33°51′31″S 151°12′51″E + * * [`LOC_BUILDER_DMM_STR({})`](../record_modifier_functions/LOC_BUILDER_DMM_STR.md) - accepts DMM 25.24°S 153.15°E + * * [`LOC_BUILDER_STR({})`](../record_modifier_functions/LOC_BUILDER_STR.md) - tries the cooordinate string in all `LOC_BUILDER_DM*_STR()` functions until one works + * + * @see https://dnscontrol.org/js#LOC_BUILDER_DMS_STR */ -declare function IP(ip: string): number; +declare function LOC_BUILDER_DMS_STR(opts: { label?: string; str: string; alt?: number; ttl?: Duration }): RecordModifier; /** - * NewDnsProvider activates a DNS Service Provider (DSP) specified in `creds.json`. - * A DSP stores a DNS zone's records and provides DNS service for the zone (i.e. - * answers on port 53 to queries related to the zone). + * `LOC_BUILDER_STR({})` actually takes an object with the following: properties. * - * * `name` must match the name of an entry in `creds.json`. - * * `type` specifies a valid DNS provider type identifier listed on the [provider page](../../providers.md). - * * Starting with [v3.16](../../v316.md), the type is optional. If it is absent, the `TYPE` field in `creds.json` is used instead. You can leave it out. (Thanks to JavaScript magic, you can leave it out even when there are more fields). - * * Starting with v4.0, specifying the type may be an error. Please add the `TYPE` field to `creds.json` and remove this parameter from `dnsconfig.js` to prepare. - * * `meta` is a way to send additional parameters to the provider. It is optional and only certain providers use it. See the [individual provider docs](../../providers.md) for details. + * - label (optional, defaults to `@`) + * - str (string) + * - alt (float32, optional) + * - ttl (optional) * - * This function will return an opaque string that should be assigned to a variable name for use in [D](D.md) directives. + * A helper to build [`LOC`](/documentation/02_language_reference/domain_modifier_functions/LOC.md) records. Supply three parameters instead of 12. * - * Prior to [v3.16](../../v316.md): + * Internally assumes some defaults for [`LOC`](/documentation/02_language_reference/domain_modifier_functions/LOC.md) records. * - * ```javascript - * var REG_MYNDC = NewRegistrar("mynamedotcom", "NAMEDOTCOM"); - * var DNS_MYAWS = NewDnsProvider("myaws", "ROUTE53"); - * - * D("example.com", REG_MYNDC, DnsProvider(DNS_MYAWS), - * A("@","1.2.3.4") - * ); - * ``` - * - * In [v3.16](../../v316.md) and later: + * Accepts a string and tries all `LOC_BUILDER_DM*_STR({})` methods: + * * [`LOC_BUILDER_DMS_STR({})`](/documentation/02_language_reference/record_modifier_functions/LOC_BUILDER_DMS_STR.md) - accepts DMS 33°51′31″S 151°12′51″E + * * [`LOC_BUILDER_DMM_STR({})`](/documentation/02_language_reference/record_modifier_functions/LOC_BUILDER_DMM_STR.md) - accepts DMM 25.24°S 153.15°E * * ```javascript - * var REG_MYNDC = NewRegistrar("mynamedotcom"); - * var DNS_MYAWS = NewDnsProvider("myaws"); - * - * D("example.com", REG_MYNDC, DnsProvider(DNS_MYAWS), - * A("@","1.2.3.4") + * D("example.com","none" + * , 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, + * }) * ); + * * ``` * - * @see https://dnscontrol.org/js#NewDnsProvider + * Part of the series: + * * [`LOC()`](/documentation/02_language_reference/domain_modifier_functions/LOC.md) - build a `LOC` by supplying all 12 parameters + * * [`LOC_BUILDER_DD({})`](/documentation/02_language_reference/record_modifier_functions/LOC_BUILDER_DD.md) - accepts cartesian x, y + * * [`LOC_BUILDER_DMS_STR({})`](/documentation/02_language_reference/record_modifier_functions/LOC_BUILDER_DMS_STR.md) - accepts DMS 33°51′31″S 151°12′51″E + * * [`LOC_BUILDER_DMM_STR({})`](/documentation/02_language_reference/record_modifier_functions/LOC_BUILDER_DMM_STR.md) - accepts DMM 25.24°S 153.15°E + * * [`LOC_BUILDER_STR({})`](/documentation/02_language_reference/record_modifier_functions/LOC_BUILDER_STR.md) - tries the cooordinate string in all `LOC_BUILDER_DM*_STR()` functions until one works + * + * @see https://dnscontrol.org/js#LOC_BUILDER_STR */ -declare function NewDnsProvider(name: string, type?: string, meta?: object): string; +declare function LOC_BUILDER_STR(opts: { label?: string; str: string; alt?: number; ttl?: Duration }): RecordModifier; /** - * NewRegistrar activates a Registrar Provider specified in `creds.json`. - * A registrar maintains the domain's registration and delegation (i.e. the - * nameservers for the domain). DNSControl only manages the delegation. + * DNSControl can optimize the SPF settings on a domain by flattening + * (inlining) includes and removing duplicates. DNSControl also makes + * it easier to document your SPF configuration. * - * * `name` must match the name of an entry in `creds.json`. - * * `type` specifies a valid DNS provider type identifier listed on the [provider page](../../providers.md). - * * Starting with [v3.16](../../v316.md), the type is optional. If it is absent, the `TYPE` field in `creds.json` is used instead. You can leave it out. (Thanks to JavaScript magic, you can leave it out even when there are more fields). - * * Starting with v4.0, specifying the type may be an error. Please add the `TYPE` field to `creds.json` and remove this parameter from `dnsconfig.js` to prepare. - * * `meta` is a way to send additional parameters to the provider. It is optional and only certain providers use it. See the [individual provider docs](../../providers.md) for details. + * WARNING: Flattening SPF includes is risky. Only flatten an SPF + * setting if it is absolutely needed to bring the number of "lookups" + * to be less than 10. In fact, it is debatable whether or not ISPs + * enforce the "10 lookup rule". * - * This function will return an opaque string that should be assigned to a variable name for use in [D](D.md) directives. + * ## The old way * - * Prior to [v3.16](../../v316.md): + * Here is an example of how SPF settings are normally done: * * ```javascript - * var REG_MYNDC = NewRegistrar("mynamedotcom", "NAMEDOTCOM"); - * var DNS_MYAWS = NewDnsProvider("myaws", "ROUTE53"); - * - * D("example.com", REG_MYNDC, DnsProvider(DNS_MYAWS), - * A("@","1.2.3.4") - * ); + * D("example.tld", REG, DNS, ... + * TXT("v=spf1 ip4:198.252.206.0/24 ip4:192.111.0.0/24 include:_spf.google.com include:mailgun.org include:spf-basic.fogcreek.com include:mail.zendesk.com include:servers.mcsv.net include:sendgrid.net include:450622.spf05.hubspotemail.net ~all") + * ) * ``` * - * In [v3.16](../../v316.md) and later: - * - * ```javascript - * var REG_MYNDC = NewRegistrar("mynamedotcom"); - * var DNS_MYAWS = NewDnsProvider("myaws"); + * This has a few problems: * - * D("example.com", REG_MYNDC, DnsProvider(DNS_MYAWS), - * A("@","1.2.3.4") - * ); - * ``` + * * No comments. It is difficult to add a comment. In particular, we want to be able to list which ticket requested each item in the SPF setting so that history is retained. + * * Ugly diffs. If you add an element to the SPF setting, the diff will show the entire line changed, which is difficult to read. + * * Too many lookups. The SPF RFC says that SPF settings should not require more than 10 DNS lookups. If we manually flatten (i.e. "inline") an include, we have to remember to check back to see if the settings have changed. Humans are not good at that kind of thing. * - * @see https://dnscontrol.org/js#NewRegistrar - */ -declare function NewRegistrar(name: string, type?: string, meta?: object): string; - -/** - * `PANIC` terminates the script and therefore DNSControl with an exit code of 1. This should be used if your script cannot gather enough information to generate records, for example when a HTTP request failed. + * ## The DNSControl way * * ```javascript - * PANIC("Something really bad has happened"); + * D("example.tld", REG, DSP, ... + * A("@", "10.2.2.2"), + * MX("@", "example.tld."), + * SPF_BUILDER({ + * label: "@", + * overflow: "_spf%d", + * raw: "_rawspf", + * ttl: "5m", + * parts: [ + * "v=spf1", + * "ip4:198.252.206.0/24", // ny-mail* + * "ip4:192.111.0.0/24", // co-mail* + * "include:_spf.google.com", // GSuite + * "include:mailgun.org", // Greenhouse.io + * "include:spf-basic.fogcreek.com", // Fogbugz + * "include:mail.zendesk.com", // Zenddesk + * "include:servers.mcsv.net", // MailChimp + * "include:sendgrid.net", // SendGrid + * "include:450622.spf05.hubspotemail.net", // Hubspot (Ticket# SREREQ-107) + * "~all" + * ], + * flatten: [ + * "spf-basic.fogcreek.com", // Rationale: Being deprecated. Low risk if it breaks. + * "450622.spf05.hubspotemail.net" // Rationale: Unlikely to change without warning. + * ] + * }), + * ); * ``` * - * @see https://dnscontrol.org/js#PANIC - */ -declare function PANIC(message: string): never; - -/** - * `REV` returns the reverse lookup domain for an IP network. For - * example `REV('1.2.3.0/24')` returns `3.2.1.in-addr.arpa.` and - * `REV('2001:db8:302::/48)` returns `2.0.3.0.8.b.d.0.1.0.0.2.ip6.arpa.`. - * This is used in [`D()`](D.md) functions to create reverse DNS lookup zones. - * - * This is a convenience function. You could specify `D('3.2.1.in-addr.arpa', - * ...` if you like to do things manually but why would you risk making - * typos? + * By using the `SPF_BUILDER()` we gain many benefits: * - * `REV` complies with RFC2317, "Classless in-addr.arpa delegation" - * for netmasks of size /25 through /31. - * While the RFC permits any format, we abide by the recommended format: - * `FIRST/MASK.C.B.A.in-addr.arpa` where `FIRST` is the first IP address - * of the zone, `MASK` is the netmask of the zone (25-31 inclusive), - * and A, B, C are the first 3 octets of the IP address. For example - * `172.20.18.130/27` is located in a zone named - * `128/27.18.20.172.in-addr.arpa` + * * Comments can appear next to the element they refer to. + * * Diffs will be shorter and more specific; therefore easier to read. + * * Automatic flattening. We can specify which includes should be flattened and DNSControl will do the work. It will even warn us if the includes change. * - * If the address does not include a "/" then `REV` assumes /32 for IPv4 addresses - * and /128 for IPv6 addresses. + * ## Syntax * - * Note that the lower bits (the ones outside the netmask) must be zeros. They are not - * zeroed out automatically. Thus, `REV('1.2.3.4/24')` is an error. This is done - * to catch typos. + * When you want to specify SPF settings for a domain, use the + * `SPF_BUILDER()` function. * * ```javascript - * D(REV('1.2.3.0/24'), REGISTRAR, DnsProvider(BIND), - * PTR("1", 'foo.example.com.'), - * PTR("2", 'bar.example.com.'), - * PTR("3", 'baz.example.com.'), - * // These take advantage of DNSControl's ability to generate the right name: - * PTR("1.2.3.10", 'ten.example.com.'), - * ); - * - * D(REV('2001:db8:302::/48'), REGISTRAR, DnsProvider(BIND), - * PTR("1.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0", 'foo.example.com.'), // 2001:db8:302::1 - * // These take advantage of DNSControl's ability to generate the right name: - * PTR("2001:db8:302::2", 'two.example.com.'), // 2.0.0... - * PTR("2001:db8:302::3", 'three.example.com.'), // 3.0.0... + * D("example.tld", REG, DSP, ... + * ... + * ... + * ... + * SPF_BUILDER({ + * label: "@", + * overflow: "_spf%d", // Delete this line if you don't want big strings split. + * overhead1: "20", // There are 20 bytes of other TXT records on this domain. Compensate for this. + * raw: "_rawspf", // Delete this line if the default is sufficient. + * parts: [ + * "v=spf1", + * // fill in your SPF items here + * "~all" + * ], + * flatten: [ + * // fill in any domains to inline. + * ] + * }), + * ... + * ... * ); * ``` * - * In the future we plan on adding a flag to [`A()`](../domain/A.md)which will insert - * the correct PTR() record in the appropriate `D(REV())` domain (i.e. `.arpa` domain) has been - * defined. - * - * @see https://dnscontrol.org/js#REV - */ -declare function REV(address: string): string; - -/** - * `getConfiguredDomains` getConfiguredDomains is a helper function that returns the domain names - * configured at the time the function is called. Calling this function early or later in - * `dnsconfig.js` may return different results. Typical usage is to iterate over all - * domains at the end of your configuration file. + * The parameters are: * - * Example for adding records to all configured domains: - * ```javascript - * var domains = getConfiguredDomains(); - * for(i = 0; i < domains.length; i++) { - * D_EXTEND(domains[i], - * TXT('_important', 'BLA') // I know, not really creative. - * ) - * } - * ``` + * * `label:` The label of the first TXT record. (Optional. Default: `"@"`) + * * `overflow:` If set, SPF strings longer than 255 chars will be split into multiple TXT records. The value of this setting determines the template for what the additional labels will be named. If not set, no splitting will occur and DNSControl may generate TXT strings that are too long. + * * `overhead1:` "Overhead for the 1st TXT record". When calculating the max length of each TXT record, reduce the maximum for the first TXT record in the chain by this amount. + * * `raw:` The label of the unaltered SPF settings. Setting to an empty string `''` will disable this. (Optional. Default: `"_rawspf"`) + * * `ttl:` This allows setting a specific TTL on this SPF record. (Optional. Default: using default record TTL) + * * `txtMaxSize` The maximum size for each TXT record. Values over 255 will result in [multiple strings][multi-string]. General recommendation is to [not go higher than 450][record-size] so that DNS responses will still fit in a UDP packet. (Optional. Default: `"255"`) + * * `parts:` The individual parts of the SPF settings. + * * `flatten:` Which includes should be inlined. For safety purposes the flattening is done on an opt-in basis. If `"*"` is listed, all includes will be flattened... this might create more problems than is solves due to length limitations. * - * This will end up in following modifications: (All output assumes the `--full` flag) + * [multi-string]: https://tools.ietf.org/html/rfc4408#section-3.1.3 + * [record-size]: https://tools.ietf.org/html/rfc4408#section-3.1.4 * - * ```text - * ******************** Domain: domain1.tld - * ----- Getting nameservers from: registrar - * ----- DNS Provider: registrar...2 corrections - * #1: CREATE TXT _important.domain1.tld "BLA" ttl=43200 - * #2: REFRESH zone domain1.tld + * `SPF_BUILDER()` returns multiple `TXT()` records: * - * ******************** Domain: domain2.tld - * ----- Getting nameservers from: registrar - * ----- DNS Provider: registrar...2 corrections - * #1: CREATE TXT _important.domain2.tld "BLA" ttl=43200 - * #2: REFRESH zone domain2.tld - * ``` + * * `TXT("@", "v=spf1 .... ~all")` + * * This is the optimized configuration. + * * `TXT("_spf1", "...")` + * * If the optimizer needs to split a long string across multiple TXT records, the additional TXT records will have labels `_spf1`, `_spf2`, `_spf3`, etc. + * * `TXT("_rawspf", "v=spf1 .... ~all")` + * * This is the unaltered SPF configuration. This is purely for debugging purposes and is not used by any email or anti-spam system. It is only generated if flattening is requested. * - * Example for adding DMARC report records: + * We recommend first using this without any flattening. Make sure + * `dnscontrol preview` works as expected. Once that is done, add the + * flattening required to reduce the number of lookups to 10 or less. * - * This example might be more useful, specially for configuring the DMARC report records. According to DMARC RFC you need to specify `domain2.tld._report.dmarc.domain1.tld` to allow `domain2.tld` to send aggregate/forensic email reports to `domain1.tld`. This can be used to do this in an easy way, without using the wildcard from the RFC. + * To count the number of lookups, you can use our interactive SPF + * debugger at [https://stackexchange.github.io/dnscontrol/flattener/index.html](https://stackexchange.github.io/dnscontrol/flattener/index.html) * - * ```javascript - * var domains = getConfiguredDomains(); - * for(i = 0; i < domains.length; i++) { - * D_EXTEND("domain1.tld", - * TXT(domains[i] + '._report._dmarc', 'v=DMARC1') - * ); - * } - * ``` + * # The first in a chain is special * - * This will end up in following modifications: + * When generating the chain of SPF + * records, each one is max length 255. For the first item in + * the chain, the max is 255 - "overhead1". Setting this to 255 or + * higher has undefined behavior. * - * ```text - * ******************** Domain: domain2.tld - * ----- Getting nameservers from: registrar - * ----- DNS Provider: registrar...4 corrections - * #1: CREATE TXT domain1.tld._report._dmarc.domain2.tld "v=DMARC1" ttl=43200 - * #2: CREATE TXT domain3.tld._report._dmarc.domain2.tld "v=DMARC1" ttl=43200 - * #3: CREATE TXT domain4.tld._report._dmarc.domain2.tld "v=DMARC1" ttl=43200 - * #4: REFRESH zone domain2.tld - * ``` + * Why is this useful? * - * @see https://dnscontrol.org/js#getConfiguredDomains - */ -declare function getConfiguredDomains(): string[]; - -/** - * `require_glob()` can recursively load `.js` files, optionally non-recursive as well. + * Some sites desire having all DNS queries fit in a single packet so + * that UDP, not TCP, can be used to satisfy all requests. That means all + * responses have to be relatively small. * - * Possible parameters are: + * When an SPF system does a "TXT" lookup, it gets SPF and non-SPF + * records. This makes the first link in the chain extra large. * - * - Path as string, where you would like to start including files. Mandatory. Pattern matching possible, see [GoLand path/filepath/#Match docs](https://golang.org/pkg/path/filepath/#Match). - * - If being recursive. This is a boolean if the search should be recursive or not. Define either `true` or `false`. Default is `true`. + * The bottom line is that if you want the TXT records to fit in a UDP + * packet, keep increasing the value of `overhead1` until the packet + * is no longer truncated. * - * Example to load `.js` files recursively: + * Example: * - * ```javascript - * require_glob("./domains/"); + * ```shell + * dig +short whatexit.org txt | wc -c + * 118 * ``` * - * Example to load `.js` files only in `domains/`: + * Setting `overhead1` to 118 should be sufficient. * - * ```javascript - * require_glob("./domains/", false); + * ```shell + * dig +short stackoverflow.com txt | wc -c + * 582 * ``` * - * One more important thing to note: `require_glob()` is as smart as `require()` is. It loads files always relative to the JavaScript - * file where it's being executed in. Let's go with an example, as it describes it better: + * Since 582 is bigger than 255, it might not be possible to achieve the + * goal. Any value larger than 255 will disable all flattening. Try + * 170, then 180, 190 until you get the desired results. * - * ```javascript - * require("domains/index.js"); - * ``` + * A validator such as + * [https://www.kitterman.com/spf/validate.html](https://www.kitterman.com/spf/validate.html) + * will tell you if the queries are being truncated and TCP was required + * to get the entire record. (Sadly it caches heavily.) * - * ```javascript - * require_glob("./user1/"); + * ## Notes about the `spfcache.json` + * + * DNSControl keeps a cache of the DNS lookups performed during + * optimization. The cache is maintained so that the optimizer does + * not produce different results depending on the ups and downs of + * other people's DNS servers. This makes it possible to do `dnscontrol + * push` even if your or third-party DNS servers are down. + * + * The DNS cache is kept in a file called `spfcache.json`. If it needs + * to be updated, the proper data will be written to a file called + * `spfcache.updated.json` and instructions such as the ones below + * will be output telling you exactly what to do: + * + * ```shell + * dnscontrol preview + * 1 Validation errors: + * WARNING: 2 spf record lookups are out of date with cache (_spf.google.com,_netblocks3.google.com). + * Wrote changes to spfcache.updated.json. Please rename and commit: + * $ mv spfcache.updated.json spfcache.json + * $ git commit spfcache.json * ``` * - * This will now load files being present underneath `./domains/user1/` and **NOT** at below `./domains/`, as `require_glob()` - * is called in the subfolder `domains/`. + * In this case, you are being asked to replace `spfcache.json` with + * the newly generated data in `spfcache.updated.json`. * - * @see https://dnscontrol.org/js#require_glob - */ -declare function require_glob(path: string, recursive: boolean): void; - -/** - * 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. + * Needing to do this kind of update is considered a validation error + * and will block `dnscontrol push` from running. * - * ## Example + * Note: The instructions are hardcoded strings. The filenames will + * not change. * - * For example you can use: + * Note: The instructions assume you use git. If you use something + * else, please do the appropriate equivalent command. * - * ```javascript - * CAA_BUILDER({ - * label: "@", - * iodef: "mailto:test@domain.tld", - * iodef_critical: true, - * issue: [ - * "letsencrypt.org", - * "comodoca.com", - * ], - * issuewild: "none", - * }) - * ``` + * ## Caveats * - * The parameters are: + * 1. DNSControl 'gives up' if it sees SPF records it can't understand. + * This includes: syntax errors, features that our spflib doesn't know + * about, overly complex SPF settings, and anything else that we we + * didn't feel like implementing. * - * * `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) + * 2. The TXT record that is generated may exceed DNS limits. dnscontrol + * will not generate a single TXT record that exceeds DNS limits, but + * it ignores the fact that there may be other TXT records on the same + * label. For example, suppose it generates a TXT record on the bare + * domain (stackoverflow.com) that is 250 bytes long. That's fine and + * doesn't require a continuation record. However if there is another + * TXT record (not an SPF record, perhaps a TXT record used to verify + * domain ownership), the total packet size of all the TXT records + * could exceed 512 bytes, and will require EDNS or a TCP request. * - * `CAA_BUILDER()` returns multiple records (when configured as example above): + * 3. DNSControl does not warn if the number of lookups exceeds 10. + * We hope to implement this some day. * - * ```javascript - * CAA("@", "iodef", "mailto:test@domain.tld", CAA_CRITICAL) - * CAA("@", "issue", "letsencrypt.org") - * CAA("@", "issue", "comodoca.com") - * CAA("@", "issuewild", ";") - * ``` + * 4. The `redirect=` directive is only partially implemented. We only + * handle the case where redirect is the last item in the SPF record. + * In which case, it is equivalent to `include:`. * - * @see https://dnscontrol.org/js#CAA_BUILDER - */ -declare function CAA_BUILDER(opts: { label?: string; iodef: string; iodef_critical?: boolean; issue: string[]; issuewild: string }): RecordModifier; - -/** - * DNSControl contains a `DMARC_BUILDER` which can be used to simply create - * DMARC policies for your domains. + * ## Advanced Technique: Interactive SPF Debugger * - * ## Example + * DNSControl includes an experimental system for viewing + * SPF settings: * - * ### Simple example + * [https://stackexchange.github.io/dnscontrol/flattener/index.html](https://stackexchange.github.io/dnscontrol/flattener/index.html) * - * ```javascript - * DMARC_BUILDER({ - * policy: 'reject', - * ruf: [ - * 'mailto:mailauth-reports@example.com', - * ], - * }) - * ``` + * You can also run this locally (it is self-contained) by opening + * `dnscontrol/docs/flattener/index.html` in your browser. * - * This yield the following record: + * You can use this to determine the minimal number of domains you + * need to flatten to have fewer than 10 lookups. * - * ```text - * @ IN TXT "v=DMARC1; p=reject; ruf=mailto:mailauth-reports@example.com" - * ``` + * The output is as follows: * - * ### Advanced example + * 1. The top part lists the domain as it current is configured, how + * many lookups it requires, and includes a checkbox for each item + * that could be flattened. * - * ```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', - * }); - * ``` + * 2. Fully flattened: This section shows the SPF configuration if you + * fully flatten it. i.e. This is what it would look like if all the + * checkboxes were checked. Note that this result is likely to be + * longer than 255 bytes, the limit for a single TXT string. + * + * 3. Fully flattened split: This takes the "fully flattened" result + * and splits it into multiple DNS records. To continue to the next + * record an include is added. + * + * ## Advanced Technique: Define once, use many + * + * In some situations we define an SPF setting once and want to re-use + * it on many domains. Here's how to do this: * * ```javascript - * DMARC_BUILDER({ - * label: 'insecure', - * policy: 'none', - * ruf: [ - * 'mailto:mailauth-reports@example.com', + * var SPF_MYSETTINGS = SPF_BUILDER({ + * label: "@", + * overflow: "_spf%d", + * raw: "_rawspf", + * parts: [ + * "v=spf1", + * ... + * "~all" * ], - * failureOptions: { - * SPF: false, - * DKIM: true, - * }, + * flatten: [ + * ... + * ] * }); - * ``` * - * This yields the following records: + * D("example.tld", REG, DSP, ... + * SPF_MYSETTINGS + * ); * - * ```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" + * D("example2.tld", REG, DSP, ... + * SPF_MYSETTINGS + * ); * ``` * - * ### 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. - * - * @see https://dnscontrol.org/js#DMARC_BUILDER + * @see https://dnscontrol.org/js#SPF_BUILDER */ -declare function DMARC_BUILDER(opts: { 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 }): RecordModifier; +declare function SPF_BUILDER(opts: { label?: string; overflow?: string; overhead1?: string; raw?: string; ttl?: Duration; txtMaxSize: string[]; parts?: number; flatten?: string[] }): RecordModifier; /** - * `LOC_BUILDER_DD({})` actually takes an object with the following properties: + * TTL sets the TTL for a single record only. This will take precedence + * over the domain's [DefaultTTL](/documentation/02_language_reference/domain_modifier_functions/DefaultTTL.md) if supplied. * - * - 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 value can be: * - * The White House: - * `38.89775977858357, -77.03655125982903` + * * An integer (number of seconds). Example: `600` + * * A string: Integer with single-letter unit: Example: `5m` + * * The unit denotes: + * * s (seconds) + * * m (minutes) + * * h (hours) + * * d (days) + * * w (weeks) + * * n (nonths) (30 days in a nonth) + * * y (years) (If you set a TTL to a year, we assume you also do crossword puzzles in pen. Show off!) + * * If no unit is specified, the default is seconds. + * * We highly recommend using units instead of the number of seconds. Would your coworkers understand your intention better if you wrote `14400` or `'4h'`? * * ```javascript - * D("example.com","none" - * , 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", - * }) + * D('example.com', REGISTRAR, DnsProvider('R53'), + * DefaultTTL(2000), + * A('@','1.2.3.4'), // uses default + * A('foo', '2.3.4.5', TTL(500)), // overrides default + * A('demo1', '3.4.5.11', TTL('5d')), // 5 days + * A('demo2', '3.4.5.12', TTL('5w')), // 5 weeks * ); - * * ``` * - * 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 - * - * @see https://dnscontrol.org/js#LOC_BUILDER_DD + * @see https://dnscontrol.org/js#TTL */ -declare function LOC_BUILDER_DD(opts: { label?: string; x: number; y: number; alt?: number; ttl?: Duration }): RecordModifier; +declare function TTL(ttl: Duration): RecordModifier; /** - * `LOC_BUILDER_DMM({})` actually takes an object with the following properties: + * `D` adds a new Domain for DNSControl to manage. The first two arguments are required: the domain name (fully qualified `example.com` without a trailing dot), and the + * name of the registrar (as previously declared with [NewRegistrar](NewRegistrar.md)). Any number of additional arguments may be included to add DNS Providers with [DNSProvider](NewDnsProvider.md), + * add records with [A](/documentation/02_language_reference/domain_modifier_functions/A.md), [CNAME](/documentation/02_language_reference/domain_modifier_functions/CNAME.md), and so forth, or add metadata. * - * - label (string, optional, defaults to `@`) - * - str (string) - * - alt (float32, optional) - * - ttl (optional) + * Modifier arguments are processed according to type as follows: * - * A helper to build [`LOC`](../domain/LOC.md) records. Supply three parameters instead of 12. + * - A function argument will be called with the domain object as it's only argument. Most of the [built-in modifier functions](https://docs.dnscontrol.org/language-reference/domain-modifiers) return such functions. + * - An object argument will be merged into the domain's metadata collection. + * - An array argument will have all of it's members evaluated recursively. This allows you to combine multiple common records or modifiers into a variable that can + * be used like a macro in multiple domains. * - * Internally assumes some defaults for [`LOC`](../domain/LOC.md) records. + * ```javascript + * var REGISTRAR = NewRegistrar("name.com"); + * var r53 = NewDnsProvider("R53"); * - * Accepts a string with decimal minutes (DMM) coordinates in the form: 25.24°S 153.15°E + * // simple domain + * D("example.com", REGISTRAR, DnsProvider(r53), + * A("@","1.2.3.4"), + * CNAME("test", "foo.example2.com.") + * ); * - * 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` + * // "macro" for records that can be mixed into any zone + * var GOOGLE_APPS_DOMAIN_MX = [ + * 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.'), + * ] * - * ```javascript - * D("example.com","none" - * LOC_BUILDER_STR({ - * label: "tasmania", - * str: '42°S 147°E', - * alt: 3, - * }) + * D("example.com", REGISTRAR, DnsProvider(r53), + * A("@","1.2.3.4"), + * CNAME("test", "foo.example2.com."), + * GOOGLE_APPS_DOMAIN_MX * ); - * * ``` * - * 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 - * - * @see https://dnscontrol.org/js#LOC_BUILDER_DMM_STR - */ -declare function LOC_BUILDER_DMM_STR(opts: { label?: string; str: string; alt?: number; ttl?: Duration }): RecordModifier; - -/** - * `LOC_BUILDER_DMS_STR({})` actually takes an object with the following properties: - * - * - label (string, optional, defaults to `@`) - * - str (string) - * - alt (float32, optional) - * - ttl (optional) + * # Split Horizon DNS * - * A helper to build [`LOC`](../domain/LOC.md) records. Supply three parameters instead of 12. + * DNSControl supports Split Horizon DNS. Simply + * define the domain two or more times, each with + * their own unique parameters. * - * Internally assumes some defaults for [`LOC`](../domain/LOC.md) records. + * To differentiate the different domains, specify the domains as + * `domain.tld!tag`, such as `example.com!inside` and + * `example.com!outside`. * - * Accepts a string with degrees, minutes, and seconds (DMS) coordinates in the form: 41°24'12.2"N 2°10'26.5"E + * ```javascript + * var REG = NewRegistrar("Third-Party"); + * var DNS_INSIDE = NewDnsProvider("Cloudflare"); + * var DNS_OUTSIDE = NewDnsProvider("bind"); * - * 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` + * D("example.com!inside", REG, DnsProvider(DNS_INSIDE), + * A("www", "10.10.10.10") + * ); * - * ```javascript - * D("example.com","none" - * LOC_BUILDER_DMS_STR({ - * label: "sydney-opera-house", - * str: '33°51′31″S 151°12′51″E', - * alt: 4, - * ttl: "5m", - * }) + * D("example.com!outside", REG, DnsProvider(DNS_OUTSIDE), + * A("www", "20.20.20.20") * ); * + * D_EXTEND("example.com!inside", + * A("internal", "10.99.99.99") + * ); * ``` * - * 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 + * A domain name without a `!` is assigned a tag that is the empty + * string. For example, `example.com` and `example.com!` are equivalent. + * However, we strongly recommend against using the empty tag, as it + * risks creating confusion. In other words, if you have `domain.tld` + * and `domain.tld!external` you now require humans to remember that + * `domain.tld` is the external one. I mean... the internal one. You + * may have noticed this mistake, but will your coworkers? Will you in + * six months? You get the idea. * - * @see https://dnscontrol.org/js#LOC_BUILDER_DMS_STR + * DNSControl command line flag `--domains` matches the full name (with the "!"). If you + * define domains `example.com!george` and `example.com!john` then: + * + * * `--domains=example.com` will not match either domain. + * * `--domains='example.com!george'` will match only match the first. + * * `--domains='example.com!george',example.com!john` will match both. + * + * NOTE: The quotes are required if your shell treats `!` as a special + * character, which is probably does. If you see an error that mentions + * `event not found` you probably forgot the quotes. + * + * @see https://dnscontrol.org/js#D */ -declare function LOC_BUILDER_DMS_STR(opts: { label?: string; str: string; alt?: number; ttl?: Duration }): RecordModifier; +declare function D(name: string, registrar: string, ...modifiers: DomainModifier[]): void; /** - * `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. + * `DEFAULTS` allows you to declare a set of default arguments to apply to all subsequent domains. Subsequent calls to [`D`](D.md) will have these + * arguments passed as if they were the first modifiers in the argument list. * - * Internally assumes some defaults for [`LOC`](../domain/LOC.md) records. + * ## Example * - * 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 + * We want to create backup zone files for all domains, but not actually register them. Also create a [`DefaultTTL`](/documentation/02_language_reference/domain_modifier_functions/DefaultTTL.md). + * The domain `example.com` will have the defaults set. * * ```javascript - * D("example.com","none" - * , 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, - * }) + * var COMMON = NewDnsProvider("foo"); + * DEFAULTS( + * DnsProvider(COMMON, 0), + * DefaultTTL('1d') * ); * + * D("example.com", + * REGISTRAR, + * DnsProvider("R53"), + * A("@","1.2.3.4") + * ); * ``` * - * 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 - * - * @see https://dnscontrol.org/js#LOC_BUILDER_STR - */ -declare function LOC_BUILDER_STR(opts: { label?: string; str: string; alt?: number; ttl?: Duration }): RecordModifier; - -/** - * R53_ZONE lets you specify the AWS Zone ID for an entire domain (D()) or a specific R53_ALIAS() record. + * If you want to clear the defaults, you can do the following. + * The domain `example2.com` will **not** have the defaults set. * - * When used with D(), it sets the zone id of the domain. This can be used to differentiate between split horizon domains in public and private zones. + * ```javascript + * DEFAULTS(); * - * When used with R53_ALIAS() it sets the required Route53 hosted zone id in a R53_ALIAS record. See [R53_ALIAS's documentation](../domain/R53_ALIAS.md) for details. + * D("example2.com", + * REGISTRAR, + * DnsProvider("R53"), + * A("@","1.2.3.4") + * ); + * ``` * - * @see https://dnscontrol.org/js#R53_ZONE + * @see https://dnscontrol.org/js#DEFAULTS */ -declare function R53_ZONE(zone_id: string): DomainModifier & RecordModifier; +declare function DEFAULTS(...modifiers: DomainModifier[]): void; /** - * DNSControl can optimize the SPF settings on a domain by flattening - * (inlining) includes and removing duplicates. DNSControl also makes - * it easier to document your SPF configuration. - * - * WARNING: Flattening SPF includes is risky. Only flatten an SPF - * setting if it is absolutely needed to bring the number of "lookups" - * to be less than 10. In fact, it is debatable whether or not ISPs - * enforce the "10 lookup rule". + * `DOMAIN_ELSEWHERE()` is a helper macro that lets you easily indicate that + * a domain's zones are managed elsewhere. That is, it permits you easily delegate + * a domain to a hard-coded list of DNS servers. * - * ## The old way + * `DOMAIN_ELSEWHERE` is useful when you control a domain's registrar but not the + * DNS servers. For example, suppose you own a domain but the DNS servers are run + * by someone else, perhaps a SaaS product you've subscribed to or a DNS server + * that is run by your brother-in-law who doesn't trust you with the API keys that + * would let you maintain the domain using DNSControl. You need an easy way to + * point (delegate) the domain at a specific list of DNS servers. * - * Here is an example of how SPF settings are normally done: + * For example these two statements are equivalent: * * ```javascript - * D("example.tld", REG, DNS, ... - * TXT("v=spf1 ip4:198.252.206.0/24 ip4:192.111.0.0/24 include:_spf.google.com include:mailgun.org include:spf-basic.fogcreek.com include:mail.zendesk.com include:servers.mcsv.net include:sendgrid.net include:450622.spf05.hubspotemail.net ~all") - * ) + * DOMAIN_ELSEWHERE("example.com", REG_NAMEDOTCOM, ["ns1.foo.com", "ns2.foo.com"]); * ``` * - * This has a few problems: - * - * * No comments. It is difficult to add a comment. In particular, we want to be able to list which ticket requested each item in the SPF setting so that history is retained. - * * Ugly diffs. If you add an element to the SPF setting, the diff will show the entire line changed, which is difficult to read. - * * Too many lookups. The SPF RFC says that SPF settings should not require more than 10 DNS lookups. If we manually flatten (i.e. "inline") an include, we have to remember to check back to see if the settings have changed. Humans are not good at that kind of thing. + * ```javascript + * D("example.com", REG_NAMEDOTCOM, + * NO_PURGE, + * NAMESERVER("ns1.foo.com"), + * NAMESERVER("ns2.foo.com") + * ); + * ``` * - * ## The DNSControl way + * NOTE: The [`NO_PURGE`](/documentation/02_language_reference/domain_modifier_functions/NO_PURGE.md) is used out of abundance of caution but since no + * `DnsProvider()` statements exist, no updates would be performed. + * + * @see https://dnscontrol.org/js#DOMAIN_ELSEWHERE + */ +declare function DOMAIN_ELSEWHERE(name: string, registrar: string, nameserver_names: string[]): void; + +/** + * `DOMAIN_ELSEWHERE_AUTO()` is similar to `DOMAIN_ELSEWHERE()` but instead of + * a hardcoded list of nameservers, a DnsProvider() is queried. + * + * `DOMAIN_ELSEWHERE_AUTO` is useful when you control a domain's registrar but the + * DNS zones are managed by another system. Luckily you have enough access to that + * other system that you can query it to determine the zone's nameservers. + * + * For example, suppose you own a domain but the DNS servers for it are in Azure. + * Further suppose that something in Azure maintains the zones (automatic or + * human). Azure picks the nameservers for the domains automatically, and that + * list may change occasionally. `DOMAIN_ELSEWHERE_AUTO` allows you to easily + * query Azure to determine the domain's delegations so that you do not need to + * hard-code them in your dnsconfig.js file. + * + * For example these two statements are equivalent: * * ```javascript - * D("example.tld", REG, DSP, ... - * A("@", "10.2.2.2"), - * MX("@", "example.tld."), - * SPF_BUILDER({ - * label: "@", - * overflow: "_spf%d", - * raw: "_rawspf", - * ttl: "5m", - * parts: [ - * "v=spf1", - * "ip4:198.252.206.0/24", // ny-mail* - * "ip4:192.111.0.0/24", // co-mail* - * "include:_spf.google.com", // GSuite - * "include:mailgun.org", // Greenhouse.io - * "include:spf-basic.fogcreek.com", // Fogbugz - * "include:mail.zendesk.com", // Zenddesk - * "include:servers.mcsv.net", // MailChimp - * "include:sendgrid.net", // SendGrid - * "include:450622.spf05.hubspotemail.net", // Hubspot (Ticket# SREREQ-107) - * "~all" - * ], - * flatten: [ - * "spf-basic.fogcreek.com", // Rationale: Being deprecated. Low risk if it breaks. - * "450622.spf05.hubspotemail.net" // Rationale: Unlikely to change without warning. - * ] - * }), + * DOMAIN_ELSEWHERE_AUTO("example.com", REG_NAMEDOTCOM, DSP_AZURE); + * ``` + * + * ```javascript + * D("example.com", REG_NAMEDOTCOM, + * NO_PURGE, + * DnsProvider(DSP_AZURE) * ); * ``` * - * By using the `SPF_BUILDER()` we gain many benefits: + * NOTE: The [`NO_PURGE`](/documentation/02_language_reference/domain_modifier_functions/NO_PURGE.md) is used to prevent DNSControl from changing the records. * - * * Comments can appear next to the element they refer to. - * * Diffs will be shorter and more specific; therefore easier to read. - * * Automatic flattening. We can specify which includes should be flattened and DNSControl will do the work. It will even warn us if the includes change. + * @see https://dnscontrol.org/js#DOMAIN_ELSEWHERE_AUTO + */ +declare function DOMAIN_ELSEWHERE_AUTO(name: string, domain: string, registrar: string, dnsProvider: string): void; + +/** + * `D_EXTEND` adds records (and metadata) to a domain previously defined + * by [`D()`](D.md). It can also be used to add subdomain records (and metadata) + * to a previously defined domain. * - * ## Syntax + * The first argument is a domain name. If it exactly matches a + * previously defined domain, `D_EXTEND()` behaves the same as [`D()`](D.md), + * simply adding records as if they had been specified in the original + * [`D()`](D.md). * - * When you want to specify SPF settings for a domain, use the - * `SPF_BUILDER()` function. + * If the domain name does not match an existing domain, but could be a + * (non-delegated) subdomain of an existing domain, the new records (and + * metadata) are added with the subdomain part appended to all record + * names (labels), and targets (as appropriate). See the examples below. + * + * Matching the domain name to previously-defined domains is done using a + * `longest match` algorithm. If `domain.tld` and `sub.domain.tld` are + * defined as separate domains via separate [`D()`](D.md) statements, then + * `D_EXTEND('sub.sub.domain.tld', ...)` would match `sub.domain.tld`, + * not `domain.tld`. + * + * Some operators only act on an apex domain (e.g. + * [`CF_REDIRECT`](/documentation/02_language_reference/domain_modifier_functions/service_provider_specific/cloudflare_dns/CF_REDIRECT.md) and [`CF_TEMP_REDIRECT`](/documentation/02_language_reference/domain_modifier_functions/service_provider_specific/cloudflare_dns/CF_TEMP_REDIRECT.md)). Using them + * in a `D_EXTEND` subdomain may not be what you expect. * * ```javascript - * D("example.tld", REG, DSP, ... - * ... - * ... - * ... - * SPF_BUILDER({ - * label: "@", - * overflow: "_spf%d", // Delete this line if you don't want big strings split. - * overhead1: "20", // There are 20 bytes of other TXT records on this domain. Compensate for this. - * raw: "_rawspf", // Delete this line if the default is sufficient. - * parts: [ - * "v=spf1", - * // fill in your SPF items here - * "~all" - * ], - * flatten: [ - * // fill in any domains to inline. - * ] - * }), - * ... - * ... + * D("domain.tld", REG, DnsProvider(DNS), + * A("@", "127.0.0.1"), // domain.tld + * A("www", "127.0.0.2"), // www.domain.tld + * CNAME("a", "b") // a.domain.tld -> b.domain.tld + * ); + * D_EXTEND("domain.tld", + * A("aaa", "127.0.0.3"), // aaa.domain.tld + * CNAME("c", "d") // c.domain.tld -> d.domain.tld + * ); + * D_EXTEND("sub.domain.tld", + * A("bbb", "127.0.0.4"), // bbb.sub.domain.tld + * A("ccc", "127.0.0.5"), // ccc.sub.domain.tld + * CNAME("e", "f") // e.sub.domain.tld -> f.sub.domain.tld + * ); + * D_EXTEND("sub.sub.domain.tld", + * A("ddd", "127.0.0.6"), // ddd.sub.sub.domain.tld + * CNAME("g", "h") // g.sub.sub.domain.tld -> h.sub.sub.domain.tld + * ); + * D_EXTEND("sub.domain.tld", + * A("@", "127.0.0.7"), // sub.domain.tld + * CNAME("i", "j") // i.sub.domain.tld -> j.sub.domain.tld * ); * ``` * - * The parameters are: - * - * * `label:` The label of the first TXT record. (Optional. Default: `"@"`) - * * `overflow:` If set, SPF strings longer than 255 chars will be split into multiple TXT records. The value of this setting determines the template for what the additional labels will be named. If not set, no splitting will occur and DNSControl may generate TXT strings that are too long. - * * `overhead1:` "Overhead for the 1st TXT record". When calculating the max length of each TXT record, reduce the maximum for the first TXT record in the chain by this amount. - * * `raw:` The label of the unaltered SPF settings. Setting to an empty string `''` will disable this. (Optional. Default: `"_rawspf"`) - * * `ttl:` This allows setting a specific TTL on this SPF record. (Optional. Default: using default record TTL) - * * `txtMaxSize` The maximum size for each TXT record. Values over 255 will result in [multiple strings][multi-string]. General recommendation is to [not go higher than 450][record-size] so that DNS responses will still fit in a UDP packet. (Optional. Default: `"255"`) - * * `parts:` The individual parts of the SPF settings. - * * `flatten:` Which includes should be inlined. For safety purposes the flattening is done on an opt-in basis. If `"*"` is listed, all includes will be flattened... this might create more problems than is solves due to length limitations. + * This will end up in the following modifications: (This output assumes the `--full` flag) * - * [multi-string]: https://tools.ietf.org/html/rfc4408#section-3.1.3 - * [record-size]: https://tools.ietf.org/html/rfc4408#section-3.1.4 + * ```text + * ******************** Domain: domain.tld + * ----- Getting nameservers from: cloudflare + * ----- DNS Provider: cloudflare...7 corrections + * #1: CREATE A aaa.domain.tld 127.0.0.3 + * #2: CREATE A bbb.sub.domain.tld 127.0.0.4 + * #3: CREATE A ccc.sub.domain.tld 127.0.0.5 + * #4: CREATE A ddd.sub.sub.domain.tld 127.0.0.6 + * #5: CREATE A sub.domain.tld 127.0.0.7 + * #6: CREATE A www.domain.tld 127.0.0.2 + * #7: CREATE A domain.tld 127.0.0.1 + * #8: CREATE CNAME a.domain.tld b.domain.tld. + * #9: CREATE CNAME c.domain.tld d.domain.tld. + * #10: CREATE CNAME e.sub.domain.tld f.sub.domain.tld. + * #11: CREATE CNAME g.sub.sub.domain.tld h.sub.sub.domain.tld. + * #12: CREATE CNAME i.sub.domain.tld j.sub.domain.tld. + * ``` * - * `SPF_BUILDER()` returns multiple `TXT()` records: + * ProTips: `D_EXTEND()` permits you to create very complex and + * sophisticated configurations, but you shouldn't. Be nice to the next + * person that edits the file, who may not be as expert as yourself. + * Enhance readability by putting any `D_EXTEND()` statements immediately + * after the original [`D()`](D.md), like in above example. Avoid the temptation + * to obscure the addition of records to existing domains with randomly + * placed `D_EXTEND()` statements. Don't build up a domain using loops of + * `D_EXTEND()` statements. You'll be glad you didn't. * - * * `TXT("@", "v=spf1 .... ~all")` - * * This is the optimized configuration. - * * `TXT("_spf1", "...")` - * * If the optimizer needs to split a long string across multiple TXT records, the additional TXT records will have labels `_spf1`, `_spf2`, `_spf3`, etc. - * * `TXT("_rawspf", "v=spf1 .... ~all")` - * * This is the unaltered SPF configuration. This is purely for debugging purposes and is not used by any email or anti-spam system. It is only generated if flattening is requested. + * @see https://dnscontrol.org/js#D_EXTEND + */ +declare function D_EXTEND(name: string, ...modifiers: DomainModifier[]): void; + +/** + * Converts an IPv4 address from string to an integer. This allows performing mathematical operations with the IP address. * - * We recommend first using this without any flattening. Make sure - * `dnscontrol preview` works as expected. Once that is done, add the - * flattening required to reduce the number of lookups to 10 or less. + * ```javascript + * var addrA = IP('1.2.3.4') + * var addrB = addrA + 1 + * // addrB = 1.2.3.5 + * ``` * - * To count the number of lookups, you can use our interactive SPF - * debugger at [https://stackexchange.github.io/dnscontrol/flattener/index.html](https://stackexchange.github.io/dnscontrol/flattener/index.html) + * NOTE: `IP()` does not accept IPv6 addresses (PRs gladly accepted!). IPv6 addresses are simply strings: * - * # The first in a chain is special + * ```javascript + * // IPv4 Var + * var addrA1 = IP("1.2.3.4"); + * var addrA2 = "1.2.3.4"; * - * When generating the chain of SPF - * records, each one is max length 255. For the first item in - * the chain, the max is 255 - "overhead1". Setting this to 255 or - * higher has undefined behavior. + * // IPv6 Var + * var addrAAAA = "0:0:0:0:0:0:0:0"; + * ``` * - * Why is this useful? + * @see https://dnscontrol.org/js#IP + */ +declare function IP(ip: string): number; + +/** + * NewDnsProvider activates a DNS Service Provider (DSP) specified in `creds.json`. + * A DSP stores a DNS zone's records and provides DNS service for the zone (i.e. + * answers on port 53 to queries related to the zone). * - * Some sites desire having all DNS queries fit in a single packet so - * that UDP, not TCP, can be used to satisfy all requests. That means all - * responses have to be relatively small. + * * `name` must match the name of an entry in `creds.json`. + * * `type` specifies a valid DNS provider type identifier listed on the [provider page](../../providers.md). + * * Starting with [v3.16](../../v316.md), the type is optional. If it is absent, the `TYPE` field in `creds.json` is used instead. You can leave it out. (Thanks to JavaScript magic, you can leave it out even when there are more fields). + * * Starting with v4.0, specifying the type may be an error. Please add the `TYPE` field to `creds.json` and remove this parameter from `dnsconfig.js` to prepare. + * * `meta` is a way to send additional parameters to the provider. It is optional and only certain providers use it. See the [individual provider docs](../../providers.md) for details. * - * When an SPF system does a "TXT" lookup, it gets SPF and non-SPF - * records. This makes the first link in the chain extra large. + * This function will return an opaque string that should be assigned to a variable name for use in [D](D.md) directives. * - * The bottom line is that if you want the TXT records to fit in a UDP - * packet, keep increasing the value of `overhead1` until the packet - * is no longer truncated. + * Prior to [v3.16](../../v316.md): * - * Example: + * ```javascript + * var REG_MYNDC = NewRegistrar("mynamedotcom", "NAMEDOTCOM"); + * var DNS_MYAWS = NewDnsProvider("myaws", "ROUTE53"); * - * ```shell - * dig +short whatexit.org txt | wc -c - * 118 + * D("example.com", REG_MYNDC, DnsProvider(DNS_MYAWS), + * A("@","1.2.3.4") + * ); * ``` * - * Setting `overhead1` to 118 should be sufficient. + * In [v3.16](../../v316.md) and later: * - * ```shell - * dig +short stackoverflow.com txt | wc -c - * 582 + * ```javascript + * var REG_MYNDC = NewRegistrar("mynamedotcom"); + * var DNS_MYAWS = NewDnsProvider("myaws"); + * + * D("example.com", REG_MYNDC, DnsProvider(DNS_MYAWS), + * A("@","1.2.3.4") + * ); * ``` * - * Since 582 is bigger than 255, it might not be possible to achieve the - * goal. Any value larger than 255 will disable all flattening. Try - * 170, then 180, 190 until you get the desired results. + * @see https://dnscontrol.org/js#NewDnsProvider + */ +declare function NewDnsProvider(name: string, type?: string, meta?: object): string; + +/** + * NewRegistrar activates a Registrar Provider specified in `creds.json`. + * A registrar maintains the domain's registration and delegation (i.e. the + * nameservers for the domain). DNSControl only manages the delegation. * - * A validator such as - * [https://www.kitterman.com/spf/validate.html](https://www.kitterman.com/spf/validate.html) - * will tell you if the queries are being truncated and TCP was required - * to get the entire record. (Sadly it caches heavily.) + * * `name` must match the name of an entry in `creds.json`. + * * `type` specifies a valid DNS provider type identifier listed on the [provider page](../../providers.md). + * * Starting with [v3.16](../../v316.md), the type is optional. If it is absent, the `TYPE` field in `creds.json` is used instead. You can leave it out. (Thanks to JavaScript magic, you can leave it out even when there are more fields). + * * Starting with v4.0, specifying the type may be an error. Please add the `TYPE` field to `creds.json` and remove this parameter from `dnsconfig.js` to prepare. + * * `meta` is a way to send additional parameters to the provider. It is optional and only certain providers use it. See the [individual provider docs](../../providers.md) for details. * - * ## Notes about the `spfcache.json` + * This function will return an opaque string that should be assigned to a variable name for use in [D](D.md) directives. * - * DNSControl keeps a cache of the DNS lookups performed during - * optimization. The cache is maintained so that the optimizer does - * not produce different results depending on the ups and downs of - * other people's DNS servers. This makes it possible to do `dnscontrol - * push` even if your or third-party DNS servers are down. + * Prior to [v3.16](../../v316.md): * - * The DNS cache is kept in a file called `spfcache.json`. If it needs - * to be updated, the proper data will be written to a file called - * `spfcache.updated.json` and instructions such as the ones below - * will be output telling you exactly what to do: + * ```javascript + * var REG_MYNDC = NewRegistrar("mynamedotcom", "NAMEDOTCOM"); + * var DNS_MYAWS = NewDnsProvider("myaws", "ROUTE53"); * - * ```shell - * dnscontrol preview - * 1 Validation errors: - * WARNING: 2 spf record lookups are out of date with cache (_spf.google.com,_netblocks3.google.com). - * Wrote changes to spfcache.updated.json. Please rename and commit: - * $ mv spfcache.updated.json spfcache.json - * $ git commit spfcache.json + * D("example.com", REG_MYNDC, DnsProvider(DNS_MYAWS), + * A("@","1.2.3.4") + * ); * ``` * - * In this case, you are being asked to replace `spfcache.json` with - * the newly generated data in `spfcache.updated.json`. + * In [v3.16](../../v316.md) and later: * - * Needing to do this kind of update is considered a validation error - * and will block `dnscontrol push` from running. + * ```javascript + * var REG_MYNDC = NewRegistrar("mynamedotcom"); + * var DNS_MYAWS = NewDnsProvider("myaws"); * - * Note: The instructions are hardcoded strings. The filenames will - * not change. + * D("example.com", REG_MYNDC, DnsProvider(DNS_MYAWS), + * A("@","1.2.3.4") + * ); + * ``` * - * Note: The instructions assume you use git. If you use something - * else, please do the appropriate equivalent command. + * @see https://dnscontrol.org/js#NewRegistrar + */ +declare function NewRegistrar(name: string, type?: string, meta?: object): string; + +/** + * `PANIC` terminates the script and therefore DNSControl with an exit code of 1. This should be used if your script cannot gather enough information to generate records, for example when a HTTP request failed. * - * ## Caveats + * ```javascript + * PANIC("Something really bad has happened"); + * ``` * - * 1. DNSControl 'gives up' if it sees SPF records it can't understand. - * This includes: syntax errors, features that our spflib doesn't know - * about, overly complex SPF settings, and anything else that we we - * didn't feel like implementing. + * @see https://dnscontrol.org/js#PANIC + */ +declare function PANIC(message: string): never; + +/** + * `REV` returns the reverse lookup domain for an IP network. For + * example `REV('1.2.3.0/24')` returns `3.2.1.in-addr.arpa.` and + * `REV('2001:db8:302::/48)` returns `2.0.3.0.8.b.d.0.1.0.0.2.ip6.arpa.`. + * This is used in [`D()`](D.md) functions to create reverse DNS lookup zones. * - * 2. The TXT record that is generated may exceed DNS limits. dnscontrol - * will not generate a single TXT record that exceeds DNS limits, but - * it ignores the fact that there may be other TXT records on the same - * label. For example, suppose it generates a TXT record on the bare - * domain (stackoverflow.com) that is 250 bytes long. That's fine and - * doesn't require a continuation record. However if there is another - * TXT record (not an SPF record, perhaps a TXT record used to verify - * domain ownership), the total packet size of all the TXT records - * could exceed 512 bytes, and will require EDNS or a TCP request. + * This is a convenience function. You could specify `D('3.2.1.in-addr.arpa', + * ...` if you like to do things manually but why would you risk making + * typos? * - * 3. DNSControl does not warn if the number of lookups exceeds 10. - * We hope to implement this some day. + * `REV` complies with RFC2317, "Classless in-addr.arpa delegation" + * for netmasks of size /25 through /31. + * While the RFC permits any format, we abide by the recommended format: + * `FIRST/MASK.C.B.A.in-addr.arpa` where `FIRST` is the first IP address + * of the zone, `MASK` is the netmask of the zone (25-31 inclusive), + * and A, B, C are the first 3 octets of the IP address. For example + * `172.20.18.130/27` is located in a zone named + * `128/27.18.20.172.in-addr.arpa` * - * 4. The `redirect=` directive is only partially implemented. We only - * handle the case where redirect is the last item in the SPF record. - * In which case, it is equivalent to `include:`. + * If the address does not include a "/" then `REV` assumes /32 for IPv4 addresses + * and /128 for IPv6 addresses. * - * ## Advanced Technique: Interactive SPF Debugger + * Note that the lower bits (the ones outside the netmask) must be zeros. They are not + * zeroed out automatically. Thus, `REV('1.2.3.4/24')` is an error. This is done + * to catch typos. * - * DNSControl includes an experimental system for viewing - * SPF settings: + * ```javascript + * D(REV('1.2.3.0/24'), REGISTRAR, DnsProvider(BIND), + * PTR("1", 'foo.example.com.'), + * PTR("2", 'bar.example.com.'), + * PTR("3", 'baz.example.com.'), + * // These take advantage of DNSControl's ability to generate the right name: + * PTR("1.2.3.10", 'ten.example.com.'), + * ); * - * [https://stackexchange.github.io/dnscontrol/flattener/index.html](https://stackexchange.github.io/dnscontrol/flattener/index.html) + * D(REV('2001:db8:302::/48'), REGISTRAR, DnsProvider(BIND), + * PTR("1.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0", 'foo.example.com.'), // 2001:db8:302::1 + * // These take advantage of DNSControl's ability to generate the right name: + * PTR("2001:db8:302::2", 'two.example.com.'), // 2.0.0... + * PTR("2001:db8:302::3", 'three.example.com.'), // 3.0.0... + * ); + * ``` * - * You can also run this locally (it is self-contained) by opening - * `dnscontrol/docs/flattener/index.html` in your browser. + * In the future we plan on adding a flag to [`A()`](/documentation/02_language_reference/domain_modifier_functions/A.md)which will insert + * the correct PTR() record in the appropriate `D(REV())` domain (i.e. `.arpa` domain) has been + * defined. * - * You can use this to determine the minimal number of domains you - * need to flatten to have fewer than 10 lookups. + * @see https://dnscontrol.org/js#REV + */ +declare function REV(address: string): string; + +/** + * `getConfiguredDomains` getConfiguredDomains is a helper function that returns the domain names + * configured at the time the function is called. Calling this function early or later in + * `dnsconfig.js` may return different results. Typical usage is to iterate over all + * domains at the end of your configuration file. * - * The output is as follows: + * Example for adding records to all configured domains: + * ```javascript + * var domains = getConfiguredDomains(); + * for(i = 0; i < domains.length; i++) { + * D_EXTEND(domains[i], + * TXT('_important', 'BLA') // I know, not really creative. + * ) + * } + * ``` * - * 1. The top part lists the domain as it current is configured, how - * many lookups it requires, and includes a checkbox for each item - * that could be flattened. + * This will end up in following modifications: (All output assumes the `--full` flag) * - * 2. Fully flattened: This section shows the SPF configuration if you - * fully flatten it. i.e. This is what it would look like if all the - * checkboxes were checked. Note that this result is likely to be - * longer than 255 bytes, the limit for a single TXT string. + * ```text + * ******************** Domain: domain1.tld + * ----- Getting nameservers from: registrar + * ----- DNS Provider: registrar...2 corrections + * #1: CREATE TXT _important.domain1.tld "BLA" ttl=43200 + * #2: REFRESH zone domain1.tld * - * 3. Fully flattened split: This takes the "fully flattened" result - * and splits it into multiple DNS records. To continue to the next - * record an include is added. + * ******************** Domain: domain2.tld + * ----- Getting nameservers from: registrar + * ----- DNS Provider: registrar...2 corrections + * #1: CREATE TXT _important.domain2.tld "BLA" ttl=43200 + * #2: REFRESH zone domain2.tld + * ``` * - * ## Advanced Technique: Define once, use many + * Example for adding DMARC report records: * - * In some situations we define an SPF setting once and want to re-use - * it on many domains. Here's how to do this: + * This example might be more useful, specially for configuring the DMARC report records. According to DMARC RFC you need to specify `domain2.tld._report.dmarc.domain1.tld` to allow `domain2.tld` to send aggregate/forensic email reports to `domain1.tld`. This can be used to do this in an easy way, without using the wildcard from the RFC. * * ```javascript - * var SPF_MYSETTINGS = SPF_BUILDER({ - * label: "@", - * overflow: "_spf%d", - * raw: "_rawspf", - * parts: [ - * "v=spf1", - * ... - * "~all" - * ], - * flatten: [ - * ... - * ] - * }); + * var domains = getConfiguredDomains(); + * for(i = 0; i < domains.length; i++) { + * D_EXTEND("domain1.tld", + * TXT(domains[i] + '._report._dmarc', 'v=DMARC1') + * ); + * } + * ``` * - * D("example.tld", REG, DSP, ... - * SPF_MYSETTINGS - * ); + * This will end up in following modifications: * - * D("example2.tld", REG, DSP, ... - * SPF_MYSETTINGS - * ); + * ```text + * ******************** Domain: domain2.tld + * ----- Getting nameservers from: registrar + * ----- DNS Provider: registrar...4 corrections + * #1: CREATE TXT domain1.tld._report._dmarc.domain2.tld "v=DMARC1" ttl=43200 + * #2: CREATE TXT domain3.tld._report._dmarc.domain2.tld "v=DMARC1" ttl=43200 + * #3: CREATE TXT domain4.tld._report._dmarc.domain2.tld "v=DMARC1" ttl=43200 + * #4: REFRESH zone domain2.tld * ``` * - * @see https://dnscontrol.org/js#SPF_BUILDER + * @see https://dnscontrol.org/js#getConfiguredDomains */ -declare function SPF_BUILDER(opts: { label?: string; overflow?: string; overhead1?: string; raw?: string; ttl?: Duration; txtMaxSize: string[]; parts?: number; flatten?: string[] }): RecordModifier; +declare function getConfiguredDomains(): string[]; /** - * TTL sets the TTL for a single record only. This will take precedence - * over the domain's [DefaultTTL](../domain/DefaultTTL.md) if supplied. + * `require_glob()` can recursively load `.js` files, optionally non-recursive as well. * - * The value can be: + * Possible parameters are: * - * * An integer (number of seconds). Example: `600` - * * A string: Integer with single-letter unit: Example: `5m` - * * The unit denotes: - * * s (seconds) - * * m (minutes) - * * h (hours) - * * d (days) - * * w (weeks) - * * n (nonths) (30 days in a nonth) - * * y (years) (If you set a TTL to a year, we assume you also do crossword puzzles in pen. Show off!) - * * If no unit is specified, the default is seconds. - * * We highly recommend using units instead of the number of seconds. Would your coworkers understand your intention better if you wrote `14400` or `'4h'`? + * - Path as string, where you would like to start including files. Mandatory. Pattern matching possible, see [GoLand path/filepath/#Match docs](https://golang.org/pkg/path/filepath/#Match). + * - If being recursive. This is a boolean if the search should be recursive or not. Define either `true` or `false`. Default is `true`. + * + * Example to load `.js` files recursively: * * ```javascript - * D('example.com', REGISTRAR, DnsProvider('R53'), - * DefaultTTL(2000), - * A('@','1.2.3.4'), // uses default - * A('foo', '2.3.4.5', TTL(500)), // overrides default - * A('demo1', '3.4.5.11', TTL('5d')), // 5 days - * A('demo2', '3.4.5.12', TTL('5w')), // 5 weeks - * ); + * require_glob("./domains/"); * ``` * - * @see https://dnscontrol.org/js#TTL + * Example to load `.js` files only in `domains/`: + * + * ```javascript + * require_glob("./domains/", false); + * ``` + * + * One more important thing to note: `require_glob()` is as smart as `require()` is. It loads files always relative to the JavaScript + * file where it's being executed in. Let's go with an example, as it describes it better: + * + * ```javascript + * require("domains/index.js"); + * ``` + * + * ```javascript + * require_glob("./user1/"); + * ``` + * + * This will now load files being present underneath `./domains/user1/` and **NOT** at below `./domains/`, as `require_glob()` + * is called in the subfolder `domains/`. + * + * @see https://dnscontrol.org/js#require_glob */ -declare function TTL(ttl: Duration): RecordModifier; +declare function require_glob(path: string, recursive: boolean): void; diff --git a/documentation/SUMMARY.md b/documentation/SUMMARY.md index 5f86278b0c..a6c5b3e8d2 100644 --- a/documentation/SUMMARY.md +++ b/documentation/SUMMARY.md @@ -9,133 +9,132 @@ * [Migrating zones to DNSControl](migrating.md) * [TypeScript autocomplete and type checking](typescript.md) -## Language Reference -* [JavaScript DSL](js.md) -* Top Level Functions - * [D](functions/global/D.md) - * [DEFAULTS](functions/global/DEFAULTS.md) - * [DOMAIN_ELSEWHERE](functions/global/DOMAIN_ELSEWHERE.md) - * [DOMAIN_ELSEWHERE_AUTO](functions/global/DOMAIN_ELSEWHERE_AUTO.md) - * [D_EXTEND](functions/global/D_EXTEND.md) - * [FETCH](functions/global/FETCH.md) - * [IP](functions/global/IP.md) - * [NewDnsProvider](functions/global/NewDnsProvider.md) - * [NewRegistrar](functions/global/NewRegistrar.md) - * [PANIC](functions/global/PANIC.md) - * [REV](functions/global/REV.md) - * [getConfiguredDomains](functions/global/getConfiguredDomains.md) - * [require](functions/global/require.md) - * [require_glob](functions/global/require_glob.md) -* Domain Modifiers - * [A](functions/domain/A.md) - * [AAAA](functions/domain/AAAA.md) - * [ALIAS](functions/domain/ALIAS.md) - * [AUTODNSSEC_OFF](functions/domain/AUTODNSSEC_OFF.md) - * [AUTODNSSEC_ON](functions/domain/AUTODNSSEC_ON.md) - * [CAA](functions/domain/CAA.md) - * [CNAME](functions/domain/CNAME.md) - * [DS](functions/domain/DS.md) - * [DefaultTTL](functions/domain/DefaultTTL.md) - * [DnsProvider](functions/domain/DnsProvider.md) - * [FRAME](functions/domain/FRAME.md) - * [IGNORE](functions/domain/IGNORE.md) - * [IGNORE_NAME](functions/domain/IGNORE_NAME.md) - * [IGNORE_TARGET](functions/domain/IGNORE_TARGET.md) - * [IMPORT_TRANSFORM](functions/domain/IMPORT_TRANSFORM.md) - * [INCLUDE](functions/domain/INCLUDE.md) - * [LOC](functions/domain/LOC.md) - * [MX](functions/domain/MX.md) - * [NAMESERVER](functions/domain/NAMESERVER.md) - * [NAMESERVER_TTL](functions/domain/NAMESERVER_TTL.md) - * [NAPTR](functions/domain/NAPTR.md) - * [NO_PURGE](functions/domain/NO_PURGE.md) - * [NS](functions/domain/NS.md) - * [PTR](functions/domain/PTR.md) - * [PURGE](functions/domain/PURGE.md) - * [SOA](functions/domain/SOA.md) - * [SRV](functions/domain/SRV.md) - * [SSHFP](functions/domain/SSHFP.md) - * [TLSA](functions/domain/TLSA.md) - * [TXT](functions/domain/TXT.md) - * [URL](functions/domain/URL.md) - * [URL301](functions/domain/URL301.md) - * Service Provider specific - * Akamai Edge Dns - * [AKAMAICDN](functions/domain/AKAMAICDN.md) - * Amazon Route 53 - * [R53_ALIAS](functions/domain/R53_ALIAS.md) - * Azure DNS - * [AZURE_ALIAS](functions/domain/AZURE_ALIAS.md) - * Cloudflare DNS - * [CF_REDIRECT](functions/domain/CF_REDIRECT.md) - * [CF_TEMP_REDIRECT](functions/domain/CF_TEMP_REDIRECT.md) - * [CF_WORKER_ROUTE](functions/domain/CF_WORKER_ROUTE.md) - * ClouDNS - * [CLOUDNS_WR](functions/domain/CLOUDNS_WR.md) - * NS1 - * [NS1_URLFWD](functions/domain/NS1_URLFWD.md) -* Record Modifiers - * [CAA_BUILDER](functions/record/CAA_BUILDER.md) - * [DMARC_BUILDER](functions/record/DMARC_BUILDER.md) - * [LOC_BUILDER_DD](functions/record/LOC_BUILDER_DD.md) - * [LOC_BUILDER_DMM_STR](functions/record/LOC_BUILDER_DMM_STR.md) - * [LOC_BUILDER_DMS_STR](functions/record/LOC_BUILDER_DMS_STR.md) - * [LOC_BUILDER_STR](functions/record/LOC_BUILDER_STR.md) - * [SPF_BUILDER](functions/record/SPF_BUILDER.md) - * [TTL](functions/record/TTL.md) - * Service Provider specific - * Amazon Route 53 - * [R53_ZONE](functions/record/R53_ZONE.md) +## Language Reference + * [JavaScript DSL](language_reference/JavaScript_DSL.md) + * Domain Modifier Functions + * [A](language_reference/domain_modifier_functions/A.md) + * [AAAA](language_reference/domain_modifier_functions/AAAA.md) + * [ALIAS](language_reference/domain_modifier_functions/ALIAS.md) + * [AUTODNSSEC_OFF](language_reference/domain_modifier_functions/AUTODNSSEC_OFF.md) + * [AUTODNSSEC_ON](language_reference/domain_modifier_functions/AUTODNSSEC_ON.md) + * [CAA](language_reference/domain_modifier_functions/CAA.md) + * [CNAME](language_reference/domain_modifier_functions/CNAME.md) + * [DefaultTTL](language_reference/domain_modifier_functions/DefaultTTL.md) + * [DnsProvider](language_reference/domain_modifier_functions/DnsProvider.md) + * [DS](language_reference/domain_modifier_functions/DS.md) + * [FRAME](language_reference/domain_modifier_functions/FRAME.md) + * [IGNORE](language_reference/domain_modifier_functions/IGNORE.md) + * [IGNORE_NAME](language_reference/domain_modifier_functions/IGNORE_NAME.md) + * [IGNORE_TARGET](language_reference/domain_modifier_functions/IGNORE_TARGET.md) + * [IMPORT_TRANSFORM](language_reference/domain_modifier_functions/IMPORT_TRANSFORM.md) + * [INCLUDE](language_reference/domain_modifier_functions/INCLUDE.md) + * [LOC](language_reference/domain_modifier_functions/LOC.md) + * [MX](language_reference/domain_modifier_functions/MX.md) + * [NAMESERVER](language_reference/domain_modifier_functions/NAMESERVER.md) + * [NAMESERVER_TTL](language_reference/domain_modifier_functions/NAMESERVER_TTL.md) + * [NAPTR](language_reference/domain_modifier_functions/NAPTR.md) + * [NO_PURGE](language_reference/domain_modifier_functions/NO_PURGE.md) + * [NS](language_reference/domain_modifier_functions/NS.md) + * [PTR](language_reference/domain_modifier_functions/PTR.md) + * [PURGE](language_reference/domain_modifier_functions/PURGE.md) + * [SOA](language_reference/domain_modifier_functions/SOA.md) + * [SRV](language_reference/domain_modifier_functions/SRV.md) + * [SSHFP](language_reference/domain_modifier_functions/SSHFP.md) + * [TLSA](language_reference/domain_modifier_functions/TLSA.md) + * [TXT](language_reference/domain_modifier_functions/TXT.md) + * [URL](language_reference/domain_modifier_functions/URL.md) + * [URL301](language_reference/domain_modifier_functions/URL301.md) + * Service Provider Specific + * Akamai Edge Dns + * [AKAMAICDN](language_reference/domain_modifier_functions/service_provider_specific/akamai_edge_dns/AKAMAICDN.md) + * Amazon Route 53 + * [R53_ALIAS](language_reference/domain_modifier_functions/service_provider_specific/amazon_route_53/R53_ALIAS.md) + * Azure Dns + * [AZURE_ALIAS](language_reference/domain_modifier_functions/service_provider_specific/azure_dns/AZURE_ALIAS.md) + * Cloudflare Dns + * [CF_REDIRECT](language_reference/domain_modifier_functions/service_provider_specific/cloudflare_dns/CF_REDIRECT.md) + * [CF_TEMP_REDIRECT](language_reference/domain_modifier_functions/service_provider_specific/cloudflare_dns/CF_TEMP_REDIRECT.md) + * [CF_WORKER_ROUTE](language_reference/domain_modifier_functions/service_provider_specific/cloudflare_dns/CF_WORKER_ROUTE.md) + * ClouDNS + * [CLOUDNS_WR](language_reference/domain_modifier_functions/service_provider_specific/ClouDNS/CLOUDNS_WR.md) + * NS1 + * [NS1_URLFWD](language_reference/domain_modifier_functions/service_provider_specific/NS1/NS1_URLFWD.md) + * Record Modifier Functions + * [CAA_BUILDER](language_reference/record_modifier_functions/CAA_BUILDER.md) + * [DMARC_BUILDER](language_reference/record_modifier_functions/DMARC_BUILDER.md) + * [LOC_BUILDER_DD](language_reference/record_modifier_functions/LOC_BUILDER_DD.md) + * [LOC_BUILDER_DMM_STR](language_reference/record_modifier_functions/LOC_BUILDER_DMM_STR.md) + * [LOC_BUILDER_DMS_STR](language_reference/record_modifier_functions/LOC_BUILDER_DMS_STR.md) + * [LOC_BUILDER_STR](language_reference/record_modifier_functions/LOC_BUILDER_STR.md) + * [SPF_BUILDER](language_reference/record_modifier_functions/SPF_BUILDER.md) + * [TTL](language_reference/record_modifier_functions/TTL.md) + * Service Provider Specific + * Amazon Route 53 + * [R53_ZONE](language_reference/record_modifier_functions/service_provider_specific/amazon_route_53/R53_ZONE.md) + * Top Level Functions + * [D](language_reference/top_level_functions/D.md) + * [D_EXTEND](language_reference/top_level_functions/D_EXTEND.md) + * [DEFAULTS](language_reference/top_level_functions/DEFAULTS.md) + * [DOMAIN_ELSEWHERE](language_reference/top_level_functions/DOMAIN_ELSEWHERE.md) + * [DOMAIN_ELSEWHERE_AUTO](language_reference/top_level_functions/DOMAIN_ELSEWHERE_AUTO.md) + * [FETCH](language_reference/top_level_functions/FETCH.md) + * [getConfiguredDomains](language_reference/top_level_functions/getConfiguredDomains.md) + * [IP](language_reference/top_level_functions/IP.md) + * [NewDnsProvider](language_reference/top_level_functions/NewDnsProvider.md) + * [NewRegistrar](language_reference/top_level_functions/NewRegistrar.md) + * [PANIC](language_reference/top_level_functions/PANIC.md) + * [require](language_reference/top_level_functions/require.md) + * [require_glob](language_reference/top_level_functions/require_glob.md) + * [REV](language_reference/top_level_functions/REV.md) * [Why CNAME/MX/NS targets require a "dot"](why-the-dot.md) -## Service Providers -* [Providers](providers.md) - * [Akamai Edge DNS](providers/akamaiedgedns.md) - * [Amazon Route 53](providers/route53.md) - * [AutoDNS](providers/autodns.md) - * [AXFR+DDNS](providers/axfrddns.md) - * [Azure DNS](providers/azure_dns.md) - * [BIND](providers/bind.md) - * [Cloudflare](providers/cloudflareapi.md) - * [ClouDNS](providers/cloudns.md) - * [CSC Global](providers/cscglobal.md) - * [deSEC](providers/desec.md) - * [DigitalOcean](providers/digitalocean.md) - * [DNS Made Simple](providers/dnsmadeeasy.md) - * [DNSimple](providers/dnsimple.md) - * [DNS-over-HTTPS](providers/dnsoverhttps.md) - * [DOMAINNAMESHOP](providers/domainnameshop.md) - * [easyname](providers/easyname.md) - * [Gandi_v5](providers/gandi_v5.md) - * [Gcore](providers/gcore.md) - * [Google Cloud DNS](providers/gcloud.md) - * [Hetzner DNS Console](providers/hetzner.md) - * [HEXONET](providers/hexonet.md) - * [hosting.de](providers/hostingde.md) - * [Hurricane Electric DNS](providers/hedns.md) - * [Internet.bs](providers/internetbs.md) - * [INWX](providers/inwx.md) - * [Linode](providers/linode.md) - * [Loopia](providers/loopia.md) - * [LuaDNS](providers/luadns.md) - * [Microsoft DNS Server on Microsoft Windows Server](providers/msdns.md) - * [Namecheap](providers/namecheap.md) - * [Name.com](providers/namedotcom.md) - * [Netcup](providers/netcup.md) - * [Netlify](providers/netlify.md) - * [NS1](providers/ns1.md) - * [Oracle Cloud](providers/oracle.md) - * [OVH](providers/ovh.md) - * [Packetframe](providers/packetframe.md) - * [Porkbun](providers/porkbun.md) - * [PowerDNS](providers/powerdns.md) - * [RWTH DNS-Admin](providers/rwth.md) - * [SoftLayer DNS](providers/softlayer.md) - * [TransIP](providers/transip.md) - * [Vultr](providers/vultr.md) +## Service Providers + * [Providers](service_providers/providers.md) + * [Autodns](service_providers/providers/autodns.md) + * [Axfrddns](service_providers/providers/axfrddns.md) + * [Azure Dns](service_providers/providers/azure_dns.md) + * [Bind](service_providers/providers/bind.md) + * [Cloudflareapi](service_providers/providers/cloudflareapi.md) + * [Cloudns](service_providers/providers/cloudns.md) + * [Cscglobal](service_providers/providers/cscglobal.md) + * [Desec](service_providers/providers/desec.md) + * [Digitalocean](service_providers/providers/digitalocean.md) + * [Dnsimple](service_providers/providers/dnsimple.md) + * [Dnsmadeeasy](service_providers/providers/dnsmadeeasy.md) + * [Dnsoverhttps](service_providers/providers/dnsoverhttps.md) + * [Domainnameshop](service_providers/providers/domainnameshop.md) + * [Easyname](service_providers/providers/easyname.md) + * [Gandi V5](service_providers/providers/gandi_v5.md) + * [Gcloud](service_providers/providers/gcloud.md) + * [Gcore](service_providers/providers/gcore.md) + * [Hedns](service_providers/providers/hedns.md) + * [Hetzner](service_providers/providers/hetzner.md) + * [Hexonet](service_providers/providers/hexonet.md) + * [Hostingde](service_providers/providers/hostingde.md) + * [Internetbs](service_providers/providers/internetbs.md) + * [Inwx](service_providers/providers/inwx.md) + * [Linode](service_providers/providers/linode.md) + * [Loopia](service_providers/providers/loopia.md) + * [Luadns](service_providers/providers/luadns.md) + * [Msdns](service_providers/providers/msdns.md) + * [Namecheap](service_providers/providers/namecheap.md) + * [Namedotcom](service_providers/providers/namedotcom.md) + * [Netcup](service_providers/providers/netcup.md) + * [Netlify](service_providers/providers/netlify.md) + * [Ns1](service_providers/providers/ns1.md) + * [Oracle](service_providers/providers/oracle.md) + * [Ovh](service_providers/providers/ovh.md) + * [Packetframe](service_providers/providers/packetframe.md) + * [Porkbun](service_providers/providers/porkbun.md) + * [Powerdns](service_providers/providers/powerdns.md) + * [Route53](service_providers/providers/route53.md) + * [Rwth](service_providers/providers/rwth.md) + * [Softlayer](service_providers/providers/softlayer.md) + * [Transip](service_providers/providers/transip.md) + * [Vultr](service_providers/providers/vultr.md) ## Commands From 22ba828e242d5cd83020089118ea63dd03f4ad4f Mon Sep 17 00:00:00 2001 From: Paul Date: Sun, 26 Mar 2023 01:28:49 +0100 Subject: [PATCH 5/9] Autofix Markdown Links for files in a folder --- build/generate/docuLocalLinkRectifier.go | 142 +++++++++++++++++++++++ build/generate/generate.go | 3 + main.go | 2 +- 3 files changed, 146 insertions(+), 1 deletion(-) create mode 100644 build/generate/docuLocalLinkRectifier.go diff --git a/build/generate/docuLocalLinkRectifier.go b/build/generate/docuLocalLinkRectifier.go new file mode 100644 index 0000000000..9505fc8140 --- /dev/null +++ b/build/generate/docuLocalLinkRectifier.go @@ -0,0 +1,142 @@ +package main + +import ( + "bufio" + "io/ioutil" + "os" + "path/filepath" + "regexp" + "strings" +) + +func walkFolderForFilesToReplaceAllFileLinks(root, ext string) error { + var files []string + err := filepath.Walk(root, func(path string, info os.FileInfo, err error) error { + if err != nil { + return err + } + + if info.IsDir() { + return nil + } + + if filepath.Ext(path) == ext { + files = append(files, path) + } + + return nil + }) + + if err != nil { + return err + } + + for _, file := range files { + // fmt.Printf("==%s==\n", file) + err := processFileForLinks(root, file, files) + if err != nil { + return err + } + } + + return err +} + +// processFileForLinks searches and replaces markdown links that refer to a +// file of identical name also in the folder heirarchy somewhere. +func processFileForLinks(root, path string, files []string) error { + dirtyFlag := false + file, err := os.Open(path) + if err != nil { + return err + } + fileinfo, err := file.Stat() + if fileinfo.Size() == 0 { + file.Close() + return nil + } + if err != nil { + return err + } + + defer file.Close() + + currentFileFolder := filepath.Dir(path) + scanner := bufio.NewScanner(file) + newLines := []string{} + + for scanner.Scan() { + line := scanner.Text() + // look for markdown link [...](...) pattern: + linkRegex := regexp.MustCompile(`\[([^\]]+)\]\(([^)]+)\)`) + + linkMatchPositions := linkRegex.FindAllStringSubmatchIndex(line, -1) + if linkMatchPositions != nil { + dirtyFlag = true + + var replacementline string + matchStart := 0 + + for x, match := range linkMatchPositions { + replacementline += line[matchStart:linkMatchPositions[x][0]] + linkText := line[match[2]:match[3]] //link ref + linkPath := line[match[4]:match[5]] //link to .md + + linkFilename := filepath.Base(linkPath) + linkFilepath := getLinkFilepathFromFileList(files, linkFilename) + if linkFilepath != "" { + //if the linked file is found within the list of files from of our folder walk, rewrite the link. + + // build a path to the linked file from the currently open file + linkPathRelToCurrentFile, err := filepath.Rel(currentFileFolder, linkFilepath) + if err != nil { + return err + } + if filepath.Dir(linkFilepath) == currentFileFolder { + //[current file] and [file target of the current link] are in the same folder: link with no path prefix. + // fmt.Printf("Test result same folder:[%s](%s)\n", linkText, linkFilename) + replacementline += "[" + linkText + "](" + linkFilename + ")" + } else { + //[current file] and [file target of the current link] are in different folders: link with relative path prefix. + // fmt.Printf("Test result different folder:[%s](%s)\n", linkText, linkPathRelToCurrentFile) //, linkFilename) + replacementline += "[" + linkText + "](" + linkPathRelToCurrentFile + ")" + } + } else { + replacementline += "[" + linkText + "](" + linkPath + ")" + } + + // Update the start index for the next match (could be multiple links per line) + matchStart = match[5] + 1 + } + if len(line)-matchStart > 0 { + replacementline += line[matchStart:] + } + // fmt.Printf("replacementline: %s\n", replacementline) + line = replacementline + } + newLines = append(newLines, line) + } + + if err := scanner.Err(); err != nil { + return err + } + + newContent := strings.Join(newLines, "\n") + "\n" + if dirtyFlag { + err = ioutil.WriteFile(path, []byte(newContent), 0644) + if err != nil { + return err + } + } + + return nil +} + +func getLinkFilepathFromFileList(files []string, filename string) string { + for _, file := range files { + if filepath.Base(file) == filepath.Base(filename) { + return file + } + } + return "" +} diff --git a/build/generate/generate.go b/build/generate/generate.go index 12eed0d34a..8d5973c437 100644 --- a/build/generate/generate.go +++ b/build/generate/generate.go @@ -26,4 +26,7 @@ func main() { if err := generateDocuTOC("documentation", "SUMMARY.md", "service_providers", providerStartMarker, providerEndMarker); err != nil { log.Print(err) } + if err := walkFolderForFilesToReplaceAllFileLinks("documentation/language_reference", ".md"); err != nil { + log.Print(err) + } } diff --git a/main.go b/main.go index 26b52d8f60..2484470b03 100644 --- a/main.go +++ b/main.go @@ -12,7 +12,7 @@ import ( "github.com/fatih/color" ) -//go:generate go run build/generate/generate.go build/generate/featureMatrix.go build/generate/functionTypes.go build/generate/dtsFile.go build/generate/docuTOC.go +//go:generate go run build/generate/generate.go build/generate/featureMatrix.go build/generate/functionTypes.go build/generate/dtsFile.go build/generate/docuTOC.go build/generate/docuLocalLinkRectifier.go // Version management. Goals: // 1. Someone who just does "go get" has at least some information. From ce61da5d1e921306c9a5594132e5ac4c95156366 Mon Sep 17 00:00:00 2001 From: Paul Date: Fri, 24 Mar 2023 05:41:09 +0100 Subject: [PATCH 6/9] Amend links --- commands/types/dnscontrol.d.ts | 74 +++++++-------- .../domain_modifier_functions/DefaultTTL.md | 8 +- .../NAMESERVER_TTL.md | 4 +- .../LOC_BUILDER_DD.md | 14 +-- .../LOC_BUILDER_DMM_STR.md | 14 +-- .../LOC_BUILDER_DMS_STR.md | 8 +- .../LOC_BUILDER_STR.md | 18 ++-- .../record_modifier_functions/TTL.md | 2 +- .../amazon_route_53/R53_ZONE.md | 2 +- .../top_level_functions/D.md | 2 +- .../top_level_functions/DEFAULTS.md | 2 +- .../top_level_functions/DOMAIN_ELSEWHERE.md | 2 +- .../DOMAIN_ELSEWHERE_AUTO.md | 2 +- .../top_level_functions/D_EXTEND.md | 2 +- .../top_level_functions/REV.md | 2 +- documentation/service_providers/providers.md | 94 +++++++++---------- 16 files changed, 125 insertions(+), 125 deletions(-) diff --git a/commands/types/dnscontrol.d.ts b/commands/types/dnscontrol.d.ts index fcbe000bb5..3813b3d164 100644 --- a/commands/types/dnscontrol.d.ts +++ b/commands/types/dnscontrol.d.ts @@ -356,10 +356,10 @@ declare function CNAME(name: string, target: string, ...modifiers: RecordModifie declare function DS(name: string, keytag: number, algorithm: number, digesttype: number, digest: string, ...modifiers: RecordModifier[]): DomainModifier; /** - * DefaultTTL sets the TTL for all subsequent records following it in a domain that do not explicitly set one with [`TTL`](/documentation/02_language_reference/record_modifier_functions/TTL.md). If neither `DefaultTTL` or `TTL` exist for a record, - * the record will inherit the DNSControl global internal default of 300 seconds. See also [`DEFAULTS`](/documentation/02_language_reference/top_level_functions/DEFAULTS.md) to override the internal defaults. + * DefaultTTL sets the TTL for all subsequent records following it in a domain that do not explicitly set one with [`TTL`](../record_modifier_functions/TTL.md). If neither `DefaultTTL` or `TTL` exist for a record, + * the record will inherit the DNSControl global internal default of 300 seconds. See also [`DEFAULTS`](../top_level_functions/DEFAULTS.md) to override the internal defaults. * - * NS records are currently a special case, and do not inherit from `DefaultTTL`. See [`NAMESERVER_TTL`](/documentation/02_language_reference/domain_modifier_functions/NAMESERVER_TTL.md) to set a default TTL for all NS records. + * NS records are currently a special case, and do not inherit from `DefaultTTL`. See [`NAMESERVER_TTL`](NAMESERVER_TTL.md) to set a default TTL for all NS records. * * ```javascript * D('example.com', REGISTRAR, DnsProvider('R53'), @@ -369,7 +369,7 @@ declare function DS(name: string, keytag: number, algorithm: number, digesttype: * ); * ``` * - * The DefaultTTL duration is the same format as [`TTL`](/documentation/02_language_reference/record_modifier_functions/TTL.md), an integer number of seconds + * The DefaultTTL duration is the same format as [`TTL`](../record_modifier_functions/TTL.md), an integer number of seconds * or a string with a unit such as `'4d'`. * * @see https://dnscontrol.org/js#DefaultTTL @@ -735,7 +735,7 @@ declare function NAMESERVER(name: string, ...modifiers: RecordModifier[]): Domai /** * NAMESERVER_TTL sets the TTL on the domain apex NS RRs defined by [`NAMESERVER`](NAMESERVER.md). * - * The value can be an integer or a string. See [`TTL`](/documentation/02_language_reference/record_modifier_functions/TTL.md) for examples. + * The value can be an integer or a string. See [`TTL`](../record_modifier_functions/TTL.md) for examples. * * ```javascript * D('example.com', REGISTRAR, DnsProvider('R53'), @@ -757,7 +757,7 @@ declare function NAMESERVER(name: string, ...modifiers: RecordModifier[]): Domai * ); * ``` * - * To apply a default TTL to all other record types, see [`DefaultTTL`](/documentation/02_language_reference/domain_modifier_functions/DefaultTTL.md) + * To apply a default TTL to all other record types, see [`DefaultTTL`](DefaultTTL.md) * * @see https://dnscontrol.org/js#NAMESERVER_TTL */ @@ -1491,9 +1491,9 @@ declare function DMARC_BUILDER(opts: { label?: string; version?: string; policy: * - alt (float32, optional) * - ttl (optional) * - * A helper to build [`LOC`](/documentation/02_language_reference/domain_modifier_functions/LOC.md) records. Supply four parameters instead of 12. + * A helper to build [`LOC`](../domain_modifier_functions/LOC.md) records. Supply four parameters instead of 12. * - * Internally assumes some defaults for [`LOC`](/documentation/02_language_reference/domain_modifier_functions/LOC.md) records. + * Internally assumes some defaults for [`LOC`](../domain_modifier_functions/LOC.md) records. * * The cartesian coordinates are decimal degrees, like you typically find in e.g. Google Maps. * @@ -1531,11 +1531,11 @@ declare function DMARC_BUILDER(opts: { label?: string; version?: string; policy: * ``` * * Part of the series: - * * [`LOC()`](/documentation/02_language_reference/domain_modifier_functions/LOC.md) - build a `LOC` by supplying all 12 parameters - * * [`LOC_BUILDER_DD({})`](/documentation/02_language_reference/record_modifier_functions/LOC_BUILDER_DD.md) - accepts cartesian x, y - * * [`LOC_BUILDER_DMS_STR({})`](/documentation/02_language_reference/record_modifier_functions/LOC_BUILDER_DMS_STR.md) - accepts DMS 33°51′31″S 151°12′51″E - * * [`LOC_BUILDER_DMM_STR({})`](/documentation/02_language_reference/record_modifier_functions/LOC_BUILDER_DMM_STR.md) - accepts DMM 25.24°S 153.15°E - * * [`LOC_BUILDER_STR({})`](/documentation/02_language_reference/record_modifier_functions/LOC_BUILDER_STR.md) - tries the cooordinate string in all `LOC_BUILDER_DM*_STR()` functions until one works + * * [`LOC()`](../domain_modifier_functions/LOC.md) - build a `LOC` by supplying all 12 parameters + * * [`LOC_BUILDER_DD({})`](LOC_BUILDER_DD.md) - accepts cartesian x, y + * * [`LOC_BUILDER_DMS_STR({})`](LOC_BUILDER_DMS_STR.md) - accepts DMS 33°51′31″S 151°12′51″E + * * [`LOC_BUILDER_DMM_STR({})`](LOC_BUILDER_DMM_STR.md) - accepts DMM 25.24°S 153.15°E + * * [`LOC_BUILDER_STR({})`](LOC_BUILDER_STR.md) - tries the cooordinate string in all `LOC_BUILDER_DM*_STR()` functions until one works * * @see https://dnscontrol.org/js#LOC_BUILDER_DD */ @@ -1574,10 +1574,10 @@ declare function LOC_BUILDER_DD(opts: { label?: string; x: number; y: number; al * * Part of the series: * * [`LOC()`](../domain_modifier_functions/LOC.md) - build a `LOC` by supplying all 12 parameters - * * [`LOC_BUILDER_DD({})`](../record_modifier_functions/LOC_BUILDER_DD.md) - accepts cartesian x, y - * * [`LOC_BUILDER_DMS_STR({})`](../record_modifier_functions/LOC_BUILDER_DMS_STR.md) - accepts DMS 33°51′31″S 151°12′51″E - * * [`LOC_BUILDER_DMM_STR({})`](../record_modifier_functions/LOC_BUILDER_DMM_STR.md) - accepts DMM 25.24°S 153.15°E - * * [`LOC_BUILDER_STR({})`](../record_modifier_functions/LOC_BUILDER_STR.md) - tries the cooordinate string in all `LOC_BUILDER_DM*_STR()` functions until one works + * * [`LOC_BUILDER_DD({})`](LOC_BUILDER_DD.md) - accepts cartesian x, y + * * [`LOC_BUILDER_DMS_STR({})`](LOC_BUILDER_DMS_STR.md) - accepts DMS 33°51′31″S 151°12′51″E + * * [`LOC_BUILDER_DMM_STR({})`](LOC_BUILDER_DMM_STR.md) - accepts DMM 25.24°S 153.15°E + * * [`LOC_BUILDER_STR({})`](LOC_BUILDER_STR.md) - tries the cooordinate string in all `LOC_BUILDER_DM*_STR()` functions until one works * * @see https://dnscontrol.org/js#LOC_BUILDER_DMM_STR */ @@ -1617,10 +1617,10 @@ declare function LOC_BUILDER_DMM_STR(opts: { label?: string; str: string; alt?: * * Part of the series: * * [`LOC()`](../domain_modifier_functions/LOC.md) - build a `LOC` by supplying all 12 parameters - * * [`LOC_BUILDER_DD({})`](../record_modifier_functions/LOC_BUILDER_DD.md) - accepts cartesian x, y - * * [`LOC_BUILDER_DMS_STR({})`](../record_modifier_functions/LOC_BUILDER_DMS_STR.md) - accepts DMS 33°51′31″S 151°12′51″E - * * [`LOC_BUILDER_DMM_STR({})`](../record_modifier_functions/LOC_BUILDER_DMM_STR.md) - accepts DMM 25.24°S 153.15°E - * * [`LOC_BUILDER_STR({})`](../record_modifier_functions/LOC_BUILDER_STR.md) - tries the cooordinate string in all `LOC_BUILDER_DM*_STR()` functions until one works + * * [`LOC_BUILDER_DD({})`](LOC_BUILDER_DD.md) - accepts cartesian x, y + * * [`LOC_BUILDER_DMS_STR({})`](LOC_BUILDER_DMS_STR.md) - accepts DMS 33°51′31″S 151°12′51″E + * * [`LOC_BUILDER_DMM_STR({})`](LOC_BUILDER_DMM_STR.md) - accepts DMM 25.24°S 153.15°E + * * [`LOC_BUILDER_STR({})`](LOC_BUILDER_STR.md) - tries the cooordinate string in all `LOC_BUILDER_DM*_STR()` functions until one works * * @see https://dnscontrol.org/js#LOC_BUILDER_DMS_STR */ @@ -1634,13 +1634,13 @@ declare function LOC_BUILDER_DMS_STR(opts: { label?: string; str: string; alt?: * - alt (float32, optional) * - ttl (optional) * - * A helper to build [`LOC`](/documentation/02_language_reference/domain_modifier_functions/LOC.md) records. Supply three parameters instead of 12. + * A helper to build [`LOC`](../domain_modifier_functions/LOC.md) records. Supply three parameters instead of 12. * - * Internally assumes some defaults for [`LOC`](/documentation/02_language_reference/domain_modifier_functions/LOC.md) records. + * Internally assumes some defaults for [`LOC`](../domain_modifier_functions/LOC.md) records. * * Accepts a string and tries all `LOC_BUILDER_DM*_STR({})` methods: - * * [`LOC_BUILDER_DMS_STR({})`](/documentation/02_language_reference/record_modifier_functions/LOC_BUILDER_DMS_STR.md) - accepts DMS 33°51′31″S 151°12′51″E - * * [`LOC_BUILDER_DMM_STR({})`](/documentation/02_language_reference/record_modifier_functions/LOC_BUILDER_DMM_STR.md) - accepts DMM 25.24°S 153.15°E + * * [`LOC_BUILDER_DMS_STR({})`](LOC_BUILDER_DMS_STR.md) - accepts DMS 33°51′31″S 151°12′51″E + * * [`LOC_BUILDER_DMM_STR({})`](LOC_BUILDER_DMM_STR.md) - accepts DMM 25.24°S 153.15°E * * ```javascript * D("example.com","none" @@ -1664,11 +1664,11 @@ declare function LOC_BUILDER_DMS_STR(opts: { label?: string; str: string; alt?: * ``` * * Part of the series: - * * [`LOC()`](/documentation/02_language_reference/domain_modifier_functions/LOC.md) - build a `LOC` by supplying all 12 parameters - * * [`LOC_BUILDER_DD({})`](/documentation/02_language_reference/record_modifier_functions/LOC_BUILDER_DD.md) - accepts cartesian x, y - * * [`LOC_BUILDER_DMS_STR({})`](/documentation/02_language_reference/record_modifier_functions/LOC_BUILDER_DMS_STR.md) - accepts DMS 33°51′31″S 151°12′51″E - * * [`LOC_BUILDER_DMM_STR({})`](/documentation/02_language_reference/record_modifier_functions/LOC_BUILDER_DMM_STR.md) - accepts DMM 25.24°S 153.15°E - * * [`LOC_BUILDER_STR({})`](/documentation/02_language_reference/record_modifier_functions/LOC_BUILDER_STR.md) - tries the cooordinate string in all `LOC_BUILDER_DM*_STR()` functions until one works + * * [`LOC()`](../domain_modifier_functions/LOC.md) - build a `LOC` by supplying all 12 parameters + * * [`LOC_BUILDER_DD({})`](LOC_BUILDER_DD.md) - accepts cartesian x, y + * * [`LOC_BUILDER_DMS_STR({})`](LOC_BUILDER_DMS_STR.md) - accepts DMS 33°51′31″S 151°12′51″E + * * [`LOC_BUILDER_DMM_STR({})`](LOC_BUILDER_DMM_STR.md) - accepts DMM 25.24°S 153.15°E + * * [`LOC_BUILDER_STR({})`](LOC_BUILDER_STR.md) - tries the cooordinate string in all `LOC_BUILDER_DM*_STR()` functions until one works * * @see https://dnscontrol.org/js#LOC_BUILDER_STR */ @@ -1961,7 +1961,7 @@ declare function SPF_BUILDER(opts: { label?: string; overflow?: string; overhead /** * TTL sets the TTL for a single record only. This will take precedence - * over the domain's [DefaultTTL](/documentation/02_language_reference/domain_modifier_functions/DefaultTTL.md) if supplied. + * over the domain's [DefaultTTL](../domain_modifier_functions/DefaultTTL.md) if supplied. * * The value can be: * @@ -1995,7 +1995,7 @@ declare function TTL(ttl: Duration): RecordModifier; /** * `D` adds a new Domain for DNSControl to manage. The first two arguments are required: the domain name (fully qualified `example.com` without a trailing dot), and the * name of the registrar (as previously declared with [NewRegistrar](NewRegistrar.md)). Any number of additional arguments may be included to add DNS Providers with [DNSProvider](NewDnsProvider.md), - * add records with [A](/documentation/02_language_reference/domain_modifier_functions/A.md), [CNAME](/documentation/02_language_reference/domain_modifier_functions/CNAME.md), and so forth, or add metadata. + * add records with [A](../domain_modifier_functions/A.md), [CNAME](../domain_modifier_functions/CNAME.md), and so forth, or add metadata. * * Modifier arguments are processed according to type as follows: * @@ -2088,7 +2088,7 @@ declare function D(name: string, registrar: string, ...modifiers: DomainModifier * * ## Example * - * We want to create backup zone files for all domains, but not actually register them. Also create a [`DefaultTTL`](/documentation/02_language_reference/domain_modifier_functions/DefaultTTL.md). + * We want to create backup zone files for all domains, but not actually register them. Also create a [`DefaultTTL`](../domain_modifier_functions/DefaultTTL.md). * The domain `example.com` will have the defaults set. * * ```javascript @@ -2148,7 +2148,7 @@ declare function DEFAULTS(...modifiers: DomainModifier[]): void; * ); * ``` * - * NOTE: The [`NO_PURGE`](/documentation/02_language_reference/domain_modifier_functions/NO_PURGE.md) is used out of abundance of caution but since no + * NOTE: The [`NO_PURGE`](../domain_modifier_functions/NO_PURGE.md) is used out of abundance of caution but since no * `DnsProvider()` statements exist, no updates would be performed. * * @see https://dnscontrol.org/js#DOMAIN_ELSEWHERE @@ -2183,7 +2183,7 @@ declare function DOMAIN_ELSEWHERE(name: string, registrar: string, nameserver_na * ); * ``` * - * NOTE: The [`NO_PURGE`](/documentation/02_language_reference/domain_modifier_functions/NO_PURGE.md) is used to prevent DNSControl from changing the records. + * NOTE: The [`NO_PURGE`](../domain_modifier_functions/NO_PURGE.md) is used to prevent DNSControl from changing the records. * * @see https://dnscontrol.org/js#DOMAIN_ELSEWHERE_AUTO */ @@ -2211,7 +2211,7 @@ declare function DOMAIN_ELSEWHERE_AUTO(name: string, domain: string, registrar: * not `domain.tld`. * * Some operators only act on an apex domain (e.g. - * [`CF_REDIRECT`](/documentation/02_language_reference/domain_modifier_functions/service_provider_specific/cloudflare_dns/CF_REDIRECT.md) and [`CF_TEMP_REDIRECT`](/documentation/02_language_reference/domain_modifier_functions/service_provider_specific/cloudflare_dns/CF_TEMP_REDIRECT.md)). Using them + * [`CF_REDIRECT`](../domain_modifier_functions/service_provider_specific/cloudflare_dns/CF_REDIRECT.md) and [`CF_TEMP_REDIRECT`](../domain_modifier_functions/service_provider_specific/cloudflare_dns/CF_TEMP_REDIRECT.md)). Using them * in a `D_EXTEND` subdomain may not be what you expect. * * ```javascript @@ -2428,7 +2428,7 @@ declare function PANIC(message: string): never; * ); * ``` * - * In the future we plan on adding a flag to [`A()`](/documentation/02_language_reference/domain_modifier_functions/A.md)which will insert + * In the future we plan on adding a flag to [`A()`](../domain_modifier_functions/A.md)which will insert * the correct PTR() record in the appropriate `D(REV())` domain (i.e. `.arpa` domain) has been * defined. * diff --git a/documentation/language_reference/domain_modifier_functions/DefaultTTL.md b/documentation/language_reference/domain_modifier_functions/DefaultTTL.md index 1b45326b78..c36f88830d 100644 --- a/documentation/language_reference/domain_modifier_functions/DefaultTTL.md +++ b/documentation/language_reference/domain_modifier_functions/DefaultTTL.md @@ -6,10 +6,10 @@ parameter_types: ttl: Duration --- -DefaultTTL sets the TTL for all subsequent records following it in a domain that do not explicitly set one with [`TTL`](../record/TTL.md). If neither `DefaultTTL` or `TTL` exist for a record, -the record will inherit the DNSControl global internal default of 300 seconds. See also [`DEFAULTS`](../global/DEFAULTS.md) to override the internal defaults. +DefaultTTL sets the TTL for all subsequent records following it in a domain that do not explicitly set one with [`TTL`](../record_modifier_functions/TTL.md). If neither `DefaultTTL` or `TTL` exist for a record, +the record will inherit the DNSControl global internal default of 300 seconds. See also [`DEFAULTS`](../top_level_functions/DEFAULTS.md) to override the internal defaults. -NS records are currently a special case, and do not inherit from `DefaultTTL`. See [`NAMESERVER_TTL`](../domain/NAMESERVER_TTL.md) to set a default TTL for all NS records. +NS records are currently a special case, and do not inherit from `DefaultTTL`. See [`NAMESERVER_TTL`](NAMESERVER_TTL.md) to set a default TTL for all NS records. {% code title="dnsconfig.js" %} @@ -22,5 +22,5 @@ D('example.com', REGISTRAR, DnsProvider('R53'), ``` {% endcode %} -The DefaultTTL duration is the same format as [`TTL`](../record/TTL.md), an integer number of seconds +The DefaultTTL duration is the same format as [`TTL`](../record_modifier_functions/TTL.md), an integer number of seconds or a string with a unit such as `'4d'`. diff --git a/documentation/language_reference/domain_modifier_functions/NAMESERVER_TTL.md b/documentation/language_reference/domain_modifier_functions/NAMESERVER_TTL.md index 9cde93409f..d485d21740 100644 --- a/documentation/language_reference/domain_modifier_functions/NAMESERVER_TTL.md +++ b/documentation/language_reference/domain_modifier_functions/NAMESERVER_TTL.md @@ -10,7 +10,7 @@ parameter_types: NAMESERVER_TTL sets the TTL on the domain apex NS RRs defined by [`NAMESERVER`](NAMESERVER.md). -The value can be an integer or a string. See [`TTL`](/documentation/02_language_reference/record_modifier_functions/TTL.md) for examples. +The value can be an integer or a string. See [`TTL`](../record_modifier_functions/TTL.md) for examples. {% code title="dnsconfig.js" %} ```javascript @@ -36,4 +36,4 @@ D('example.com', REGISTRAR, DnsProvider('xyz'), ``` {% endcode %} -To apply a default TTL to all other record types, see [`DefaultTTL`](/documentation/02_language_reference/domain_modifier_functions/DefaultTTL.md) +To apply a default TTL to all other record types, see [`DefaultTTL`](DefaultTTL.md) diff --git a/documentation/language_reference/record_modifier_functions/LOC_BUILDER_DD.md b/documentation/language_reference/record_modifier_functions/LOC_BUILDER_DD.md index 512dbedcfa..6bf9b88bc3 100644 --- a/documentation/language_reference/record_modifier_functions/LOC_BUILDER_DD.md +++ b/documentation/language_reference/record_modifier_functions/LOC_BUILDER_DD.md @@ -23,9 +23,9 @@ parameter_types: - alt (float32, optional) - ttl (optional) -A helper to build [`LOC`](../domain/LOC.md) records. Supply four parameters instead of 12. +A helper to build [`LOC`](../domain_modifier_functions/LOC.md) records. Supply four parameters instead of 12. -Internally assumes some defaults for [`LOC`](../domain/LOC.md) records. +Internally assumes some defaults for [`LOC`](../domain_modifier_functions/LOC.md) records. The cartesian coordinates are decimal degrees, like you typically find in e.g. Google Maps. @@ -68,8 +68,8 @@ D("example.com","none" 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 + * [`LOC()`](../domain_modifier_functions/LOC.md) - build a `LOC` by supplying all 12 parameters + * [`LOC_BUILDER_DD({})`](LOC_BUILDER_DD.md) - accepts cartesian x, y + * [`LOC_BUILDER_DMS_STR({})`](LOC_BUILDER_DMS_STR.md) - accepts DMS 33°51′31″S 151°12′51″E + * [`LOC_BUILDER_DMM_STR({})`](LOC_BUILDER_DMM_STR.md) - accepts DMM 25.24°S 153.15°E + * [`LOC_BUILDER_STR({})`](LOC_BUILDER_STR.md) - tries the cooordinate string in all `LOC_BUILDER_DM*_STR()` functions until one works diff --git a/documentation/language_reference/record_modifier_functions/LOC_BUILDER_DMM_STR.md b/documentation/language_reference/record_modifier_functions/LOC_BUILDER_DMM_STR.md index a09edc203b..398ddd1628 100644 --- a/documentation/language_reference/record_modifier_functions/LOC_BUILDER_DMM_STR.md +++ b/documentation/language_reference/record_modifier_functions/LOC_BUILDER_DMM_STR.md @@ -20,9 +20,9 @@ parameter_types: - alt (float32, optional) - ttl (optional) -A helper to build [`LOC`](../domain/LOC.md) records. Supply three parameters instead of 12. +A helper to build [`LOC`](../domain_modifier_functions/LOC.md) records. Supply three parameters instead of 12. -Internally assumes some defaults for [`LOC`](../domain/LOC.md) records. +Internally assumes some defaults for [`LOC`](../domain_modifier_functions/LOC.md) records. Accepts a string with decimal minutes (DMM) coordinates in the form: 25.24°S 153.15°E @@ -48,8 +48,8 @@ D("example.com","none" 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 + * [`LOC()`](../domain_modifier_functions/LOC.md) - build a `LOC` by supplying all 12 parameters + * [`LOC_BUILDER_DD({})`](LOC_BUILDER_DD.md) - accepts cartesian x, y + * [`LOC_BUILDER_DMS_STR({})`](LOC_BUILDER_DMS_STR.md) - accepts DMS 33°51′31″S 151°12′51″E + * [`LOC_BUILDER_DMM_STR({})`](LOC_BUILDER_DMM_STR.md) - accepts DMM 25.24°S 153.15°E + * [`LOC_BUILDER_STR({})`](LOC_BUILDER_STR.md) - tries the cooordinate string in all `LOC_BUILDER_DM*_STR()` functions until one works diff --git a/documentation/language_reference/record_modifier_functions/LOC_BUILDER_DMS_STR.md b/documentation/language_reference/record_modifier_functions/LOC_BUILDER_DMS_STR.md index 53be6ff54f..33050df177 100644 --- a/documentation/language_reference/record_modifier_functions/LOC_BUILDER_DMS_STR.md +++ b/documentation/language_reference/record_modifier_functions/LOC_BUILDER_DMS_STR.md @@ -50,7 +50,7 @@ D("example.com","none" Part of the series: * [`LOC()`](../domain_modifier_functions/LOC.md) - build a `LOC` by supplying all 12 parameters - * [`LOC_BUILDER_DD({})`](../record_modifier_functions/LOC_BUILDER_DD.md) - accepts cartesian x, y - * [`LOC_BUILDER_DMS_STR({})`](../record_modifier_functions/LOC_BUILDER_DMS_STR.md) - accepts DMS 33°51′31″S 151°12′51″E - * [`LOC_BUILDER_DMM_STR({})`](../record_modifier_functions/LOC_BUILDER_DMM_STR.md) - accepts DMM 25.24°S 153.15°E - * [`LOC_BUILDER_STR({})`](../record_modifier_functions/LOC_BUILDER_STR.md) - tries the cooordinate string in all `LOC_BUILDER_DM*_STR()` functions until one works + * [`LOC_BUILDER_DD({})`](LOC_BUILDER_DD.md) - accepts cartesian x, y + * [`LOC_BUILDER_DMS_STR({})`](LOC_BUILDER_DMS_STR.md) - accepts DMS 33°51′31″S 151°12′51″E + * [`LOC_BUILDER_DMM_STR({})`](LOC_BUILDER_DMM_STR.md) - accepts DMM 25.24°S 153.15°E + * [`LOC_BUILDER_STR({})`](LOC_BUILDER_STR.md) - tries the cooordinate string in all `LOC_BUILDER_DM*_STR()` functions until one works diff --git a/documentation/language_reference/record_modifier_functions/LOC_BUILDER_STR.md b/documentation/language_reference/record_modifier_functions/LOC_BUILDER_STR.md index 78a1cb3f04..54e18561d1 100644 --- a/documentation/language_reference/record_modifier_functions/LOC_BUILDER_STR.md +++ b/documentation/language_reference/record_modifier_functions/LOC_BUILDER_STR.md @@ -20,14 +20,14 @@ parameter_types: - alt (float32, optional) - ttl (optional) -A helper to build [`LOC`](../domain/LOC.md) records. Supply three parameters instead of 12. +A helper to build [`LOC`](../domain_modifier_functions/LOC.md) records. Supply three parameters instead of 12. -Internally assumes some defaults for [`LOC`](../domain/LOC.md) records. +Internally assumes some defaults for [`LOC`](../domain_modifier_functions/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 + * [`LOC_BUILDER_DMS_STR({})`](LOC_BUILDER_DMS_STR.md) - accepts DMS 33°51′31″S 151°12′51″E + * [`LOC_BUILDER_DMM_STR({})`](LOC_BUILDER_DMM_STR.md) - accepts DMM 25.24°S 153.15°E {% code title="dnsconfig.js" %} @@ -55,8 +55,8 @@ D("example.com","none" 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 + * [`LOC()`](../domain_modifier_functions/LOC.md) - build a `LOC` by supplying all 12 parameters + * [`LOC_BUILDER_DD({})`](LOC_BUILDER_DD.md) - accepts cartesian x, y + * [`LOC_BUILDER_DMS_STR({})`](LOC_BUILDER_DMS_STR.md) - accepts DMS 33°51′31″S 151°12′51″E + * [`LOC_BUILDER_DMM_STR({})`](LOC_BUILDER_DMM_STR.md) - accepts DMM 25.24°S 153.15°E + * [`LOC_BUILDER_STR({})`](LOC_BUILDER_STR.md) - tries the cooordinate string in all `LOC_BUILDER_DM*_STR()` functions until one works diff --git a/documentation/language_reference/record_modifier_functions/TTL.md b/documentation/language_reference/record_modifier_functions/TTL.md index 51e9186440..fbf72b7dee 100644 --- a/documentation/language_reference/record_modifier_functions/TTL.md +++ b/documentation/language_reference/record_modifier_functions/TTL.md @@ -7,7 +7,7 @@ parameter_types: --- TTL sets the TTL for a single record only. This will take precedence -over the domain's [DefaultTTL](/documentation/02_language_reference/domain_modifier_functions/DefaultTTL.md) if supplied. +over the domain's [DefaultTTL](../domain_modifier_functions/DefaultTTL.md) if supplied. The value can be: diff --git a/documentation/language_reference/record_modifier_functions/service_provider_specific/amazon_route_53/R53_ZONE.md b/documentation/language_reference/record_modifier_functions/service_provider_specific/amazon_route_53/R53_ZONE.md index 0347007591..84f3b5823d 100644 --- a/documentation/language_reference/record_modifier_functions/service_provider_specific/amazon_route_53/R53_ZONE.md +++ b/documentation/language_reference/record_modifier_functions/service_provider_specific/amazon_route_53/R53_ZONE.md @@ -12,4 +12,4 @@ R53_ZONE lets you specify the AWS Zone ID for an entire domain (D()) or a specif When used with D(), it sets the zone id of the domain. This can be used to differentiate between split horizon domains in public and private zones. -When used with R53_ALIAS() it sets the required Route53 hosted zone id in a R53_ALIAS record. See [R53_ALIAS's documentation](02_language_reference/domain_modifier_functions/service_provider_specific/amazon_route_53/R53_ALIAS.md) for details. +When used with R53_ALIAS() it sets the required Route53 hosted zone id in a R53_ALIAS record. See [R53_ALIAS's documentation](../../../domain_modifier_functions/service_provider_specific/amazon_route_53/R53_ALIAS.md) for details. diff --git a/documentation/language_reference/top_level_functions/D.md b/documentation/language_reference/top_level_functions/D.md index 913e5f5f33..a15ec10017 100644 --- a/documentation/language_reference/top_level_functions/D.md +++ b/documentation/language_reference/top_level_functions/D.md @@ -12,7 +12,7 @@ parameter_types: `D` adds a new Domain for DNSControl to manage. The first two arguments are required: the domain name (fully qualified `example.com` without a trailing dot), and the name of the registrar (as previously declared with [NewRegistrar](NewRegistrar.md)). Any number of additional arguments may be included to add DNS Providers with [DNSProvider](NewDnsProvider.md), -add records with [A](/documentation/02_language_reference/domain_modifier_functions/A.md), [CNAME](/documentation/02_language_reference/domain_modifier_functions/CNAME.md), and so forth, or add metadata. +add records with [A](../domain_modifier_functions/A.md), [CNAME](../domain_modifier_functions/CNAME.md), and so forth, or add metadata. Modifier arguments are processed according to type as follows: diff --git a/documentation/language_reference/top_level_functions/DEFAULTS.md b/documentation/language_reference/top_level_functions/DEFAULTS.md index 28d073167f..a2661795ea 100644 --- a/documentation/language_reference/top_level_functions/DEFAULTS.md +++ b/documentation/language_reference/top_level_functions/DEFAULTS.md @@ -11,7 +11,7 @@ arguments passed as if they were the first modifiers in the argument list. ## Example -We want to create backup zone files for all domains, but not actually register them. Also create a [`DefaultTTL`](/documentation/02_language_reference/domain_modifier_functions/DefaultTTL.md). +We want to create backup zone files for all domains, but not actually register them. Also create a [`DefaultTTL`](../domain_modifier_functions/DefaultTTL.md). The domain `example.com` will have the defaults set. {% code title="dnsconfig.js" %} diff --git a/documentation/language_reference/top_level_functions/DOMAIN_ELSEWHERE.md b/documentation/language_reference/top_level_functions/DOMAIN_ELSEWHERE.md index f3adfb1966..ee5c80d0e6 100644 --- a/documentation/language_reference/top_level_functions/DOMAIN_ELSEWHERE.md +++ b/documentation/language_reference/top_level_functions/DOMAIN_ELSEWHERE.md @@ -40,6 +40,6 @@ D("example.com", REG_NAMEDOTCOM, {% endcode %} {% hint style="info" %} -**NOTE**: The [`NO_PURGE`](/documentation/02_language_reference/domain_modifier_functions/NO_PURGE.md) is used out of abundance of caution but since no +**NOTE**: The [`NO_PURGE`](../domain_modifier_functions/NO_PURGE.md) is used out of abundance of caution but since no `DnsProvider()` statements exist, no updates would be performed. {% endhint %} diff --git a/documentation/language_reference/top_level_functions/DOMAIN_ELSEWHERE_AUTO.md b/documentation/language_reference/top_level_functions/DOMAIN_ELSEWHERE_AUTO.md index 48134c922c..2908c53a02 100644 --- a/documentation/language_reference/top_level_functions/DOMAIN_ELSEWHERE_AUTO.md +++ b/documentation/language_reference/top_level_functions/DOMAIN_ELSEWHERE_AUTO.md @@ -44,5 +44,5 @@ D("example.com", REG_NAMEDOTCOM, {% endcode %} {% hint style="info" %} -**NOTE**: The [`NO_PURGE`](/documentation/02_language_reference/domain_modifier_functions/NO_PURGE.md) is used to prevent DNSControl from changing the records. +**NOTE**: The [`NO_PURGE`](../domain_modifier_functions/NO_PURGE.md) is used to prevent DNSControl from changing the records. {% endhint %} diff --git a/documentation/language_reference/top_level_functions/D_EXTEND.md b/documentation/language_reference/top_level_functions/D_EXTEND.md index ea67a8afdc..70b9253a00 100644 --- a/documentation/language_reference/top_level_functions/D_EXTEND.md +++ b/documentation/language_reference/top_level_functions/D_EXTEND.md @@ -29,7 +29,7 @@ defined as separate domains via separate [`D()`](D.md) statements, then not `domain.tld`. Some operators only act on an apex domain (e.g. -[`CF_REDIRECT`](/documentation/02_language_reference/domain_modifier_functions/service_provider_specific/cloudflare_dns/CF_REDIRECT.md) and [`CF_TEMP_REDIRECT`](/documentation/02_language_reference/domain_modifier_functions/service_provider_specific/cloudflare_dns/CF_TEMP_REDIRECT.md)). Using them +[`CF_REDIRECT`](../domain_modifier_functions/service_provider_specific/cloudflare_dns/CF_REDIRECT.md) and [`CF_TEMP_REDIRECT`](../domain_modifier_functions/service_provider_specific/cloudflare_dns/CF_TEMP_REDIRECT.md)). Using them in a `D_EXTEND` subdomain may not be what you expect. {% code title="dnsconfig.js" %} diff --git a/documentation/language_reference/top_level_functions/REV.md b/documentation/language_reference/top_level_functions/REV.md index f1ab8e2958..d62f1d9356 100644 --- a/documentation/language_reference/top_level_functions/REV.md +++ b/documentation/language_reference/top_level_functions/REV.md @@ -51,6 +51,6 @@ D(REV('2001:db8:302::/48'), REGISTRAR, DnsProvider(BIND), ``` {% endcode %} -In the future we plan on adding a flag to [`A()`](/documentation/02_language_reference/domain_modifier_functions/A.md)which will insert +In the future we plan on adding a flag to [`A()`](../domain_modifier_functions/A.md)which will insert the correct PTR() record in the appropriate `D(REV())` domain (i.e. `.arpa` domain) has been defined. diff --git a/documentation/service_providers/providers.md b/documentation/service_providers/providers.md index cbbbc7c6d1..7d03c33d47 100644 --- a/documentation/service_providers/providers.md +++ b/documentation/service_providers/providers.md @@ -12,53 +12,53 @@ a provider that supports it, we'd love your contribution to ensure it works corr If a feature is definitively not supported for whatever reason, we would also like a PR to clarify why it is not supported, and fill in this entire matrix. -| Provider name | Official Support | DNS Provider | Registrar | [`ALIAS`](functions/domain/ALIAS.md) | [`CAA`](functions/domain/CAA.md) | [`AUTODNSSEC`](functions/domain/AUTODNSSEC_ON.md) | [`LOC`](functions/domain/LOC.md) | [`NAPTR`](functions/domain/NAPTR.md) | [`PTR`](functions/domain/PTR.md) | [`SOA`](functions/domain/SOA.md) | [`SRV`](functions/domain/SRV.md) | [`SSHFP`](functions/domain/SSHFP.md) | [`TLSA`](functions/domain/TLSA.md) | [`DS`](functions/domain/DS.md) | dual host | create-domains | [`NO_PURGE`](functions/domain/NO_PURGE.md) | get-zones | -| ------------- | ---------------- | ------------ | --------- | ------------------------------------ | -------------------------------- | ------------------------------------------------- | -------------------------------- | ------------------------------------ | -------------------------------- | -------------------------------- | -------------------------------- | ------------------------------------ | ---------------------------------- | ------------------------------ | --------- | -------------- | ------------------------------------------ | --------- | -| [`AKAMAIEDGEDNS`](providers/akamaiedgedns.md) | ❌ | ✅ | ❌ | ❌ | ✅ | ✅ | ❔ | ✅ | ✅ | ❌ | ✅ | ✅ | ✅ | ❌ | ✅ | ✅ | ❌ | ✅ | -| [`AUTODNS`](providers/autodns.md) | ❌ | ✅ | ❌ | ✅ | ❌ | ❔ | ❔ | ❔ | ❌ | ❔ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ | ✅ | -| [`AXFRDDNS`](providers/axfrddns.md) | ❌ | ✅ | ❌ | ❔ | ✅ | ✅ | ❔ | ✅ | ✅ | ❔ | ✅ | ✅ | ✅ | ❔ | ❌ | ❌ | ❌ | ❌ | -| [`AZURE_DNS`](providers/azure_dns.md) | ✅ | ✅ | ❌ | ❌ | ✅ | ❔ | ❌ | ❌ | ✅ | ❔ | ✅ | ❌ | ❌ | ❔ | ✅ | ✅ | ✅ | ✅ | -| [`BIND`](providers/bind.md) | ✅ | ✅ | ❌ | ❔ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ | ✅ | -| [`CLOUDFLAREAPI`](providers/cloudflareapi.md) | ✅ | ✅ | ❌ | ✅ | ✅ | ❔ | ❌ | ❔ | ✅ | ❔ | ✅ | ✅ | ✅ | ❔ | ❌ | ✅ | ✅ | ✅ | -| [`CLOUDNS`](providers/cloudns.md) | ❌ | ✅ | ❌ | ✅ | ✅ | ❔ | ❌ | ❔ | ✅ | ❔ | ✅ | ✅ | ✅ | ❔ | ❔ | ✅ | ✅ | ✅ | -| [`CSCGLOBAL`](providers/cscglobal.md) | ✅ | ✅ | ✅ | ❔ | ✅ | ❔ | ❔ | ❔ | ❔ | ❔ | ✅ | ❔ | ❔ | ❔ | ❔ | ❌ | ✅ | ✅ | -| [`DESEC`](providers/desec.md) | ❌ | ✅ | ❌ | ❔ | ✅ | ✅ | ❔ | ✅ | ✅ | ❔ | ✅ | ✅ | ✅ | ✅ | ❔ | ✅ | ✅ | ✅ | -| [`DIGITALOCEAN`](providers/digitalocean.md) | ❌ | ✅ | ❌ | ❔ | ✅ | ❔ | ❌ | ❔ | ❔ | ❔ | ✅ | ❔ | ❔ | ❔ | ❔ | ✅ | ✅ | ✅ | -| [`DNSIMPLE`](providers/dnsimple.md) | ❌ | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ | ✅ | ✅ | ❔ | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ | ✅ | ✅ | -| [`DNSMADEEASY`](providers/dnsmadeeasy.md) | ❌ | ✅ | ❌ | ✅ | ✅ | ❔ | ❌ | ❔ | ✅ | ❔ | ✅ | ❌ | ❌ | ❌ | ✅ | ✅ | ✅ | ✅ | -| [`DNSOVERHTTPS`](providers/dnsoverhttps.md) | ❌ | ❌ | ✅ | ❔ | ❔ | ❔ | ❔ | ❔ | ❔ | ❔ | ❔ | ❔ | ❔ | ❔ | ❔ | ❌ | ✅ | ❔ | -| [`DOMAINNAMESHOP`](providers/domainnameshop.md) | ❌ | ✅ | ❌ | ❔ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ | ❔ | ❔ | ❔ | ❔ | ✅ | ❔ | -| [`EASYNAME`](providers/easyname.md) | ❌ | ❌ | ✅ | ❔ | ❔ | ❔ | ❔ | ❔ | ❔ | ❔ | ❔ | ❔ | ❔ | ❔ | ❔ | ❌ | ✅ | ❔ | -| [`EXOSCALE`](providers/exoscale.md) | ❌ | ✅ | ❌ | ✅ | ✅ | ❔ | ❌ | ❔ | ✅ | ❔ | ✅ | ❔ | ❌ | ❔ | ❌ | ❌ | ✅ | ❔ | -| [`GANDI_V5`](providers/gandi_v5.md) | ❌ | ✅ | ✅ | ✅ | ✅ | ❔ | ❌ | ❔ | ✅ | ❔ | ✅ | ✅ | ✅ | ❌ | ❔ | ❌ | ❌ | ✅ | -| [`GCLOUD`](providers/gcloud.md) | ✅ | ✅ | ❌ | ✅ | ✅ | ❔ | ❌ | ❔ | ✅ | ❔ | ✅ | ✅ | ✅ | ❔ | ✅ | ✅ | ✅ | ✅ | -| [`GCORE`](providers/gcore.md) | ❌ | ✅ | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ | ❔ | ✅ | ❌ | ❌ | ❌ | ✅ | ✅ | ✅ | ✅ | -| [`HEDNS`](providers/hedns.md) | ❌ | ✅ | ❌ | ✅ | ✅ | ❌ | ✅ | ✅ | ✅ | ❌ | ✅ | ✅ | ❌ | ❌ | ✅ | ✅ | ✅ | ✅ | -| [`HETZNER`](providers/hetzner.md) | ❌ | ✅ | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | -| [`HEXONET`](providers/hexonet.md) | ❌ | ✅ | ✅ | ❌ | ✅ | ❔ | ❔ | ❔ | ✅ | ❔ | ✅ | ❔ | ✅ | ❔ | ✅ | ✅ | ✅ | ❔ | -| [`HOSTINGDE`](providers/hostingde.md) | ❌ | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | -| [`INTERNETBS`](providers/internetbs.md) | ❌ | ❌ | ✅ | ❔ | ❔ | ❔ | ❔ | ❔ | ❔ | ❔ | ❔ | ❔ | ❔ | ❔ | ❔ | ❌ | ✅ | ❔ | -| [`INWX`](providers/inwx.md) | ❌ | ✅ | ✅ | ❌ | ✅ | ❔ | ❔ | ✅ | ✅ | ❔ | ✅ | ✅ | ✅ | ❔ | ✅ | ✅ | ✅ | ✅ | -| [`LINODE`](providers/linode.md) | ❌ | ✅ | ❌ | ❔ | ✅ | ❔ | ❌ | ❔ | ❔ | ❔ | ❔ | ❔ | ❔ | ❔ | ❌ | ❌ | ✅ | ✅ | -| [`LOOPIA`](providers/loopia.md) | ❌ | ✅ | ✅ | ❌ | ✅ | ❌ | ✅ | ✅ | ❌ | ❌ | ✅ | ✅ | ✅ | ❌ | ✅ | ❌ | ✅ | ✅ | -| [`LUADNS`](providers/luadns.md) | ❌ | ✅ | ❌ | ✅ | ✅ | ❔ | ❌ | ❔ | ✅ | ❔ | ✅ | ✅ | ✅ | ❔ | ✅ | ✅ | ✅ | ✅ | -| [`MSDNS`](providers/msdns.md) | ✅ | ✅ | ❌ | ❌ | ❌ | ❔ | ❌ | ✅ | ✅ | ❔ | ✅ | ❔ | ❔ | ❔ | ❌ | ❌ | ✅ | ✅ | -| [`NAMECHEAP`](providers/namecheap.md) | ❌ | ✅ | ✅ | ✅ | ✅ | ❔ | ❌ | ❔ | ❌ | ❔ | ❌ | ❔ | ❌ | ❔ | ❌ | ❌ | ❌ | ✅ | -| [`NAMEDOTCOM`](providers/namedotcom.md) | ❌ | ✅ | ✅ | ✅ | ❔ | ❔ | ❌ | ❔ | ❌ | ❔ | ✅ | ❔ | ❔ | ❔ | ✅ | ❌ | ✅ | ✅ | -| [`NETCUP`](providers/netcup.md) | ❌ | ✅ | ❌ | ❔ | ✅ | ❔ | ❌ | ❔ | ❌ | ❔ | ✅ | ❔ | ❔ | ❔ | ❌ | ❌ | ✅ | ❌ | -| [`NETLIFY`](providers/netlify.md) | ❌ | ✅ | ❌ | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ | ❔ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ | ✅ | -| [`NS1`](providers/ns1.md) | ❌ | ✅ | ❌ | ✅ | ✅ | ✅ | ❌ | ✅ | ✅ | ❔ | ✅ | ❔ | ❔ | ✅ | ✅ | ✅ | ✅ | ✅ | -| [`OPENSRS`](providers/opensrs.md) | ❌ | ❌ | ✅ | ❔ | ❔ | ❔ | ❔ | ❔ | ❔ | ❔ | ❔ | ❔ | ❔ | ❔ | ❔ | ❌ | ✅ | ❔ | -| [`ORACLE`](providers/oracle.md) | ❌ | ✅ | ❌ | ✅ | ✅ | ❔ | ❔ | ✅ | ✅ | ❔ | ✅ | ✅ | ✅ | ❌ | ✅ | ✅ | ✅ | ✅ | -| [`OVH`](providers/ovh.md) | ❌ | ✅ | ✅ | ❌ | ✅ | ❔ | ❔ | ❔ | ❌ | ❔ | ✅ | ✅ | ✅ | ❔ | ✅ | ❌ | ✅ | ✅ | -| [`PACKETFRAME`](providers/packetframe.md) | ❌ | ✅ | ❌ | ❔ | ❔ | ❔ | ❔ | ❔ | ✅ | ❔ | ✅ | ❔ | ❔ | ❔ | ❌ | ❌ | ✅ | ❔ | -| [`PORKBUN`](providers/porkbun.md) | ❌ | ✅ | ❌ | ✅ | ❔ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ | ✅ | ❌ | ❌ | ❌ | ✅ | ✅ | -| [`POWERDNS`](providers/powerdns.md) | ❌ | ✅ | ❌ | ✅ | ✅ | ✅ | ❔ | ✅ | ✅ | ❔ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | -| [`ROUTE53`](providers/route53.md) | ✅ | ✅ | ✅ | ❌ | ✅ | ❔ | ❌ | ❔ | ✅ | ❔ | ✅ | ❔ | ❔ | ❔ | ✅ | ✅ | ✅ | ✅ | -| [`RWTH`](providers/rwth.md) | ❌ | ✅ | ❌ | ❌ | ✅ | ❔ | ❌ | ❌ | ✅ | ❔ | ✅ | ✅ | ❌ | ❔ | ❌ | ❌ | ✅ | ✅ | -| [`SOFTLAYER`](providers/softlayer.md) | ❌ | ✅ | ❌ | ❔ | ❔ | ❔ | ❌ | ❔ | ❔ | ❔ | ✅ | ❔ | ❔ | ❔ | ❔ | ❌ | ✅ | ❔ | -| [`TRANSIP`](providers/transip.md) | ❌ | ✅ | ❌ | ✅ | ✅ | ❌ | ❌ | ✅ | ❔ | ❔ | ✅ | ✅ | ✅ | ❌ | ❔ | ❌ | ✅ | ✅ | -| [`VULTR`](providers/vultr.md) | ❌ | ✅ | ❌ | ❌ | ✅ | ❔ | ❌ | ❔ | ❌ | ❔ | ✅ | ✅ | ❌ | ❔ | ❔ | ✅ | ✅ | ✅ | +| Provider name | Official Support | DNS Provider | Registrar | [`ALIAS`](../language_reference/domain_modifier_functions/ALIAS.md) | [`CAA`](../language_reference/domain_modifier_functions/CAA.md) | [`AUTODNSSEC`](../language_reference/domain_modifier_functions/AUTODNSSEC_ON.md) | [`LOC`](../language_reference/domain_modifier_functions/LOC.md) | [`NAPTR`](../language_reference/domain_modifier_functions/NAPTR.md) | [`PTR`](../language_reference/domain_modifier_functions/PTR.md) | [`SOA`](../language_reference/domain_modifier_functions/SOA.md) | [`SRV`](../language_reference/domain_modifier_functions/SRV.md) | [`SSHFP`](../language_reference/domain_modifier_functions/SSHFP.md) | [`TLSA`](../language_reference/domain_modifier_functions/TLSA.md) | [`DS`](../language_reference/domain_modifier_functions/DS.md) | dual host | create-domains | [`NO_PURGE`](../language_reference/domain_modifier_functions/NO_PURGE.md) | get-zones | +| ------------- | ---------------- | ------------ | --------- | ------------------------------------------------------------------- | --------------------------------------------------------------- | -------------------------------------------------------------------------------- | --------------------------------------------------------------- | ------------------------------------------------------------------- | --------------------------------------------------------------- | --------------------------------------------------------------- | --------------------------------------------------------------- | ------------------------------------------------------------------- | ----------------------------------------------------------------- | ------------------------------------------------------------- | --------- | -------------- | ------------------------------------------------------------------------- | --------- | +| [`AKAMAIEDGEDNS`](service_providers/akamaiedgedns.md) | ❌ | ✅ | ❌ | ❌ | ✅ | ✅ | ❔ | ✅ | ✅ | ❌ | ✅ | ✅ | ✅ | ❌ | ✅ | ✅ | ❌ | ✅ | +| [`AUTODNS`](service_providers/autodns.md) | ❌ | ✅ | ❌ | ✅ | ❌ | ❔ | ❔ | ❔ | ❌ | ❔ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ | ✅ | +| [`AXFRDDNS`](service_providers/axfrddns.md) | ❌ | ✅ | ❌ | ❔ | ✅ | ✅ | ❔ | ✅ | ✅ | ❔ | ✅ | ✅ | ✅ | ❔ | ❌ | ❌ | ❌ | ❌ | +| [`AZURE_DNS`](service_providers/azure_dns.md) | ✅ | ✅ | ❌ | ❌ | ✅ | ❔ | ❌ | ❌ | ✅ | ❔ | ✅ | ❌ | ❌ | ❔ | ✅ | ✅ | ✅ | ✅ | +| [`BIND`](service_providers/bind.md) | ✅ | ✅ | ❌ | ❔ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ | ✅ | +| [`CLOUDFLAREAPI`](service_providers/cloudflareapi.md) | ✅ | ✅ | ❌ | ✅ | ✅ | ❔ | ❌ | ❔ | ✅ | ❔ | ✅ | ✅ | ✅ | ❔ | ❌ | ✅ | ✅ | ✅ | +| [`CLOUDNS`](service_providers/cloudns.md) | ❌ | ✅ | ❌ | ✅ | ✅ | ❔ | ❌ | ❔ | ✅ | ❔ | ✅ | ✅ | ✅ | ❔ | ❔ | ✅ | ✅ | ✅ | +| [`CSCGLOBAL`](service_providers/cscglobal.md) | ✅ | ✅ | ✅ | ❔ | ✅ | ❔ | ❔ | ❔ | ❔ | ❔ | ✅ | ❔ | ❔ | ❔ | ❔ | ❌ | ✅ | ✅ | +| [`DESEC`](service_providers/desec.md) | ❌ | ✅ | ❌ | ❔ | ✅ | ✅ | ❔ | ✅ | ✅ | ❔ | ✅ | ✅ | ✅ | ✅ | ❔ | ✅ | ✅ | ✅ | +| [`DIGITALOCEAN`](service_providers/digitalocean.md) | ❌ | ✅ | ❌ | ❔ | ✅ | ❔ | ❌ | ❔ | ❔ | ❔ | ✅ | ❔ | ❔ | ❔ | ❔ | ✅ | ✅ | ✅ | +| [`DNSIMPLE`](service_providers/dnsimple.md) | ❌ | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ | ✅ | ✅ | ❔ | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ | ✅ | ✅ | +| [`DNSMADEEASY`](service_providers/dnsmadeeasy.md) | ❌ | ✅ | ❌ | ✅ | ✅ | ❔ | ❌ | ❔ | ✅ | ❔ | ✅ | ❌ | ❌ | ❌ | ✅ | ✅ | ✅ | ✅ | +| [`DNSOVERHTTPS`](service_providers/dnsoverhttps.md) | ❌ | ❌ | ✅ | ❔ | ❔ | ❔ | ❔ | ❔ | ❔ | ❔ | ❔ | ❔ | ❔ | ❔ | ❔ | ❌ | ✅ | ❔ | +| [`DOMAINNAMESHOP`](service_providers/domainnameshop.md) | ❌ | ✅ | ❌ | ❔ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ | ❔ | ❔ | ❔ | ❔ | ✅ | ❔ | +| [`EASYNAME`](service_providers/easyname.md) | ❌ | ❌ | ✅ | ❔ | ❔ | ❔ | ❔ | ❔ | ❔ | ❔ | ❔ | ❔ | ❔ | ❔ | ❔ | ❌ | ✅ | ❔ | +| [`EXOSCALE`](service_providers/exoscale.md) | ❌ | ✅ | ❌ | ✅ | ✅ | ❔ | ❌ | ❔ | ✅ | ❔ | ✅ | ❔ | ❌ | ❔ | ❌ | ❌ | ✅ | ❔ | +| [`GANDI_V5`](service_providers/gandi_v5.md) | ❌ | ✅ | ✅ | ✅ | ✅ | ❔ | ❌ | ❔ | ✅ | ❔ | ✅ | ✅ | ✅ | ❌ | ❔ | ❌ | ❌ | ✅ | +| [`GCLOUD`](service_providers/gcloud.md) | ✅ | ✅ | ❌ | ✅ | ✅ | ❔ | ❌ | ❔ | ✅ | ❔ | ✅ | ✅ | ✅ | ❔ | ✅ | ✅ | ✅ | ✅ | +| [`GCORE`](service_providers/gcore.md) | ❌ | ✅ | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ | ❔ | ✅ | ❌ | ❌ | ❌ | ✅ | ✅ | ✅ | ✅ | +| [`HEDNS`](service_providers/hedns.md) | ❌ | ✅ | ❌ | ✅ | ✅ | ❌ | ✅ | ✅ | ✅ | ❌ | ✅ | ✅ | ❌ | ❌ | ✅ | ✅ | ✅ | ✅ | +| [`HETZNER`](service_providers/hetzner.md) | ❌ | ✅ | ❌ | ❌ | ✅ | ❔ | ❌ | ❔ | ❌ | ❔ | ✅ | ❌ | ✅ | ❌ | ✅ | ✅ | ✅ | ✅ | +| [`HEXONET`](service_providers/hexonet.md) | ❌ | ✅ | ✅ | ❌ | ✅ | ❔ | ❔ | ❔ | ✅ | ❔ | ✅ | ❔ | ✅ | ❔ | ✅ | ✅ | ✅ | ❔ | +| [`HOSTINGDE`](service_providers/hostingde.md) | ❌ | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| [`INTERNETBS`](service_providers/internetbs.md) | ❌ | ❌ | ✅ | ❔ | ❔ | ❔ | ❔ | ❔ | ❔ | ❔ | ❔ | ❔ | ❔ | ❔ | ❔ | ❌ | ✅ | ❔ | +| [`INWX`](service_providers/inwx.md) | ❌ | ✅ | ✅ | ❌ | ✅ | ❔ | ❔ | ✅ | ✅ | ❔ | ✅ | ✅ | ✅ | ❔ | ✅ | ✅ | ✅ | ✅ | +| [`LINODE`](service_providers/linode.md) | ❌ | ✅ | ❌ | ❔ | ✅ | ❔ | ❌ | ❔ | ❔ | ❔ | ❔ | ❔ | ❔ | ❔ | ❌ | ❌ | ✅ | ✅ | +| [`LOOPIA`](service_providers/loopia.md) | ❌ | ✅ | ✅ | ❌ | ✅ | ❌ | ✅ | ✅ | ❌ | ❌ | ✅ | ✅ | ✅ | ❌ | ✅ | ❌ | ✅ | ✅ | +| [`LUADNS`](service_providers/luadns.md) | ❌ | ✅ | ❌ | ✅ | ✅ | ❔ | ❌ | ❔ | ✅ | ❔ | ✅ | ✅ | ✅ | ❔ | ✅ | ✅ | ✅ | ✅ | +| [`MSDNS`](service_providers/msdns.md) | ✅ | ✅ | ❌ | ❌ | ❌ | ❔ | ❌ | ✅ | ✅ | ❔ | ✅ | ❔ | ❔ | ❔ | ❌ | ❌ | ✅ | ✅ | +| [`NAMECHEAP`](service_providers/namecheap.md) | ❌ | ✅ | ✅ | ✅ | ✅ | ❔ | ❌ | ❔ | ❌ | ❔ | ❌ | ❔ | ❌ | ❔ | ❌ | ❌ | ❌ | ✅ | +| [`NAMEDOTCOM`](service_providers/namedotcom.md) | ❌ | ✅ | ✅ | ✅ | ❔ | ❔ | ❌ | ❔ | ❌ | ❔ | ✅ | ❔ | ❔ | ❔ | ✅ | ❌ | ✅ | ✅ | +| [`NETCUP`](service_providers/netcup.md) | ❌ | ✅ | ❌ | ❔ | ✅ | ❔ | ❌ | ❔ | ❌ | ❔ | ✅ | ❔ | ❔ | ❔ | ❌ | ❌ | ✅ | ❌ | +| [`NETLIFY`](service_providers/netlify.md) | ❌ | ✅ | ❌ | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ | ❔ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ | ✅ | +| [`NS1`](service_providers/ns1.md) | ❌ | ✅ | ❌ | ✅ | ✅ | ✅ | ❌ | ✅ | ✅ | ❔ | ✅ | ❔ | ❔ | ✅ | ✅ | ✅ | ✅ | ✅ | +| [`OPENSRS`](service_providers/opensrs.md) | ❌ | ❌ | ✅ | ❔ | ❔ | ❔ | ❔ | ❔ | ❔ | ❔ | ❔ | ❔ | ❔ | ❔ | ❔ | ❌ | ✅ | ❔ | +| [`ORACLE`](service_providers/oracle.md) | ❌ | ✅ | ❌ | ✅ | ✅ | ❔ | ❔ | ✅ | ✅ | ❔ | ✅ | ✅ | ✅ | ❌ | ✅ | ✅ | ✅ | ✅ | +| [`OVH`](service_providers/ovh.md) | ❌ | ✅ | ✅ | ❌ | ✅ | ❔ | ❔ | ❔ | ❌ | ❔ | ✅ | ✅ | ✅ | ❔ | ✅ | ❌ | ✅ | ✅ | +| [`PACKETFRAME`](service_providers/packetframe.md) | ❌ | ✅ | ❌ | ❔ | ❔ | ❔ | ❔ | ❔ | ✅ | ❔ | ✅ | ❔ | ❔ | ❔ | ❌ | ❌ | ✅ | ❔ | +| [`PORKBUN`](service_providers/porkbun.md) | ❌ | ✅ | ❌ | ✅ | ❔ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ | ✅ | ❌ | ❌ | ❌ | ✅ | ✅ | +| [`POWERDNS`](service_providers/powerdns.md) | ❌ | ✅ | ❌ | ✅ | ✅ | ✅ | ❔ | ✅ | ✅ | ❔ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| [`ROUTE53`](service_providers/route53.md) | ✅ | ✅ | ✅ | ❌ | ✅ | ❔ | ❌ | ❔ | ✅ | ❔ | ✅ | ❔ | ❔ | ❔ | ✅ | ✅ | ✅ | ✅ | +| [`RWTH`](service_providers/rwth.md) | ❌ | ✅ | ❌ | ❌ | ✅ | ❔ | ❌ | ❌ | ✅ | ❔ | ✅ | ✅ | ❌ | ❔ | ❌ | ❌ | ✅ | ✅ | +| [`SOFTLAYER`](service_providers/softlayer.md) | ❌ | ✅ | ❌ | ❔ | ❔ | ❔ | ❌ | ❔ | ❔ | ❔ | ✅ | ❔ | ❔ | ❔ | ❔ | ❌ | ✅ | ❔ | +| [`TRANSIP`](service_providers/transip.md) | ❌ | ✅ | ❌ | ✅ | ✅ | ❌ | ❌ | ✅ | ❔ | ❔ | ✅ | ✅ | ✅ | ❌ | ❔ | ❌ | ✅ | ✅ | +| [`VULTR`](service_providers/vultr.md) | ❌ | ✅ | ❌ | ❌ | ✅ | ❔ | ❌ | ❔ | ❌ | ❔ | ✅ | ✅ | ❌ | ❔ | ❔ | ✅ | ✅ | ✅ | ### Providers with "official support" From b310adaf65dfe2aa6f90507ae0379722c01f7016 Mon Sep 17 00:00:00 2001 From: Paul Date: Fri, 24 Mar 2023 20:28:51 +0100 Subject: [PATCH 7/9] Amend links (in all .md files) --- commands/types/dnscontrol.d.ts | 10 +++---- documentation/adding-new-rtypes.md | 26 +++++++++---------- documentation/bug-triage.md | 4 +-- documentation/byo-secrets.md | 2 +- documentation/code-tricks.md | 6 ++--- documentation/creds-json.md | 2 +- documentation/examples.md | 2 +- documentation/getting-started.md | 6 ++--- documentation/index.md | 8 +++--- .../domain_modifier_functions/SOA.md | 2 +- .../top_level_functions/NewDnsProvider.md | 4 +-- .../top_level_functions/NewRegistrar.md | 4 +-- documentation/nameservers.md | 2 +- documentation/writing-providers.md | 10 +++---- 14 files changed, 44 insertions(+), 44 deletions(-) diff --git a/commands/types/dnscontrol.d.ts b/commands/types/dnscontrol.d.ts index 3813b3d164..253fededeb 100644 --- a/commands/types/dnscontrol.d.ts +++ b/commands/types/dnscontrol.d.ts @@ -1159,7 +1159,7 @@ declare const PURGE: DomainModifier; * * Most providers automatically generate SOA records. They will ignore any `SOA()` statements. * * The mbox field should not be set to a real email address unless you love spam and hate your privacy. * - * There is more info about `SOA` in the documentation for the [BIND provider](../../providers/bind.md). + * There is more info about `SOA` in the documentation for the [BIND provider](../../service_providers/providers/bind.md). * * @see https://dnscontrol.org/js#SOA */ @@ -2302,10 +2302,10 @@ declare function IP(ip: string): number; * answers on port 53 to queries related to the zone). * * * `name` must match the name of an entry in `creds.json`. - * * `type` specifies a valid DNS provider type identifier listed on the [provider page](../../providers.md). + * * `type` specifies a valid DNS provider type identifier listed on the [provider page](../../service_providers/providers.md). * * Starting with [v3.16](../../v316.md), the type is optional. If it is absent, the `TYPE` field in `creds.json` is used instead. You can leave it out. (Thanks to JavaScript magic, you can leave it out even when there are more fields). * * Starting with v4.0, specifying the type may be an error. Please add the `TYPE` field to `creds.json` and remove this parameter from `dnsconfig.js` to prepare. - * * `meta` is a way to send additional parameters to the provider. It is optional and only certain providers use it. See the [individual provider docs](../../providers.md) for details. + * * `meta` is a way to send additional parameters to the provider. It is optional and only certain providers use it. See the [individual provider docs](../../service_providers/providers.md) for details. * * This function will return an opaque string that should be assigned to a variable name for use in [D](D.md) directives. * @@ -2341,10 +2341,10 @@ declare function NewDnsProvider(name: string, type?: string, meta?: object): str * nameservers for the domain). DNSControl only manages the delegation. * * * `name` must match the name of an entry in `creds.json`. - * * `type` specifies a valid DNS provider type identifier listed on the [provider page](../../providers.md). + * * `type` specifies a valid DNS provider type identifier listed on the [provider page](../../service_providers/providers.md). * * Starting with [v3.16](../../v316.md), the type is optional. If it is absent, the `TYPE` field in `creds.json` is used instead. You can leave it out. (Thanks to JavaScript magic, you can leave it out even when there are more fields). * * Starting with v4.0, specifying the type may be an error. Please add the `TYPE` field to `creds.json` and remove this parameter from `dnsconfig.js` to prepare. - * * `meta` is a way to send additional parameters to the provider. It is optional and only certain providers use it. See the [individual provider docs](../../providers.md) for details. + * * `meta` is a way to send additional parameters to the provider. It is optional and only certain providers use it. See the [individual provider docs](../../service_providers/providers.md) for details. * * This function will return an opaque string that should be assigned to a variable name for use in [D](D.md) directives. * diff --git a/documentation/adding-new-rtypes.md b/documentation/adding-new-rtypes.md index 4f68e9452a..f4c14a6e95 100644 --- a/documentation/adding-new-rtypes.md +++ b/documentation/adding-new-rtypes.md @@ -79,9 +79,9 @@ popd func matrixData() *FeatureMatrix { const ( ... - DomainModifierCaa = "[`CAA`](functions/domain/CAA.md)" - + DomainModifierFoo = "[`FOO`](functions/domain/FOO.md)" - DomainModifierLoc = "[`LOC`](functions/domain/LOC.md)" + DomainModifierCaa = "[`CAA`](language_reference/domain_modifier_functions/CAA.md)" + + DomainModifierFoo = "[`FOO`](language_reference/domain_modifier_functions/FOO.md)" + DomainModifierLoc = "[`LOC`](language_reference/domain_modifier_functions/LOC.md)" ... ) matrix := &FeatureMatrix{ @@ -153,7 +153,7 @@ example we removed `providers.CanUseCAA` from the Add a function to `pkg/js/helpers.js` for the new record type. This is the JavaScript file that defines `dnsconfig.js`'s functions like -[`A()`](functions/domain/A.md) and [`MX()`](functions/domain/MX.md). Look at the definition of `A`, `MX` and `CAA` for good +[`A()`](language_reference/domain_modifier_functions/A.md) and [`MX()`](language_reference/domain_modifier_functions/MX.md). Look at the definition of `A`, `MX` and `CAA` for good examples to use as a base. Please add the function alphabetically with the others. Also, please run @@ -306,24 +306,24 @@ Add the new file `FOO.md` to the documentation table of contents [`documentation ... * Domain Modifiers ... - * [DnsProvider](functions/domain/DnsProvider.md) -+ * [FOO](functions/domain/FOO.md) - * [FRAME](functions/domain/FRAME.md) + * [DnsProvider](language_reference/domain_modifier_functions/DnsProvider.md) ++ * [FOO](language_reference/domain_modifier_functions/FOO.md) + * [FRAME](language_reference/domain_modifier_functions/FRAME.md) ... * Service Provider specific ... * ClouDNS - * [CLOUDNS_WR](functions/domain/CLOUDNS_WR.md) + * [CLOUDNS_WR](language_reference/domain_modifier_functions/service_provider_specific/ClouDNS/CLOUDNS_WR.md) + * ASDF -+ * [NINJA_RECORD](function/domain/FOO_NINJA.md) ++ * [NINJA_RECORD](language_reference/domain_modifier_functions/service_provider_specific/XYZ/FOO_NINJA.md) * NS1 - * [NS1_URLFWD](functions/domain/NS1_URLFWD.md) + * [NS1_URLFWD](language_reference/domain_modifier_functions/service_provider_specific/NS1/NS1_URLFWD.md) ... * Record Modifiers ... - * [DMARC_BUILDER](functions/record/DMARC_BUILDER.md) -+ * [FOO_HELPER](functions/record/FOO_HELPER.md) - * [SPF_BUILDER](functions/record/SPF_BUILDER.md) + * [DMARC_BUILDER](language_reference/record_modifier_functions/DMARC_BUILDER.md) ++ * [FOO_HELPER](language_reference/record_modifier_functions/FOO_HELPER.md) + * [SPF_BUILDER](language_reference/record_modifier_functions/SPF_BUILDER.md) ... ``` {% endcode %} diff --git a/documentation/bug-triage.md b/documentation/bug-triage.md index ee6b6679a5..83a55533de 100644 --- a/documentation/bug-triage.md +++ b/documentation/bug-triage.md @@ -2,7 +2,7 @@ If an issue is related to a particular provider, assign it to the person responsible for the provider, as listed in -[Providers](providers.md)'s "Maintainers of +[Providers](service_providers/providers.md)'s "Maintainers of contributed providers". Otherwise leave it unassigned until someone grabs it. @@ -27,7 +27,7 @@ priority: 1. Respond to the issue with the message below 1. Close the issue -The [Providers](providers.md) page is generated +The [Providers](service_providers/providers.md) page is generated automatically from all the issues tagged `provider-request`: 1. "Requested providers: state=closed, tagged `provider-request` diff --git a/documentation/byo-secrets.md b/documentation/byo-secrets.md index 84813dc1f2..377f6c8981 100644 --- a/documentation/byo-secrets.md +++ b/documentation/byo-secrets.md @@ -155,7 +155,7 @@ HEXONET_UID: test.user ``` {% hint style="info" %} -**NOTE**: The above credentials are [known to the public](providers/hexonet.md). +**NOTE**: The above credentials are [known to the public](service_providers/providers/hexonet.md). {% endhint %} # Caveats diff --git a/documentation/code-tricks.md b/documentation/code-tricks.md index 71432758d1..48a0419c46 100644 --- a/documentation/code-tricks.md +++ b/documentation/code-tricks.md @@ -4,9 +4,9 @@ Problem: It is difficult to get CAA and other records exactly right. Solution: Use a "builder" to construct it for you. -* [CAA Builder](functions/record/CAA_BUILDER.md) -* [DMARC Builder](functions/record/DMARC_BUILDER.md) -* [SPF Optimizer](functions/record/SPF_BUILDER.md) +* [CAA Builder](language_reference/record_modifier_functions/CAA_BUILDER.md) +* [DMARC Builder](language_reference/record_modifier_functions/DMARC_BUILDER.md) +* [SPF Optimizer](language_reference/record_modifier_functions/SPF_BUILDER.md) # Repeat records in many domains (macros) diff --git a/documentation/creds-json.md b/documentation/creds-json.md index 19f6e6ef7b..03b926f297 100644 --- a/documentation/creds-json.md +++ b/documentation/creds-json.md @@ -167,7 +167,7 @@ invalid. Perhaps you meant to specify a `-` on a command-line tool? The fix is to change the `TYPE` subkey entry in `creds.json` from `-` to a valid service provider identifier, as listed -in [the service provider list](providers.md). +in [the service provider list](service_providers/providers.md). ## Using a different file name diff --git a/documentation/examples.md b/documentation/examples.md index 0e5b1262a8..e88fda155a 100644 --- a/documentation/examples.md +++ b/documentation/examples.md @@ -49,7 +49,7 @@ D('example.com', REG, DnsProvider('R53'), {% 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()`](language_reference/top_level_functions/IP.md) function doesn't currently support IPv6 (PRs welcome!). IPv6 addresses are strings. {% endhint %} {% code title="dnsconfig.js" %} ```javascript diff --git a/documentation/getting-started.md b/documentation/getting-started.md index b8a783bfce..992e73d4da 100644 --- a/documentation/getting-started.md +++ b/documentation/getting-started.md @@ -99,7 +99,7 @@ D('example.com', REG_NONE, DnsProvider(DNS_BIND), ``` {% endcode %} -Modify this file to match your particular providers and domains. See [the DNSConfig docs](language_reference/JavaScript_DSL.md) and [the provider docs](providers.md) for more details. +Modify this file to match your particular providers and domains. See [the DNSConfig docs](language_reference/JavaScript_DSL.md) and [the provider docs](service_providers/providers.md) for more details. Create a file called `creds.json` for storing provider configurations (API tokens and other account information). For example, to use both name.com and Cloudflare, you would have: @@ -292,7 +292,7 @@ $TTL 300 ``` You can change the "DEFAULT_NOT_SET" text by following the documentation -for the [BIND provider](providers/bind.md) to set +for the [BIND provider](service_providers/providers/bind.md) to set the "master" and "mbox" settings. Try that now. @@ -303,7 +303,7 @@ a real domain (or a test domain if you have one). Set up the provider: Add the providers's definition to `dnsconfig.js` and list any credentials in `creds.json`. Each provider is different. -See [the provider docs](providers.md) for +See [the provider docs](service_providers/providers.md) for specifics. Edit the domain: Add the `D()` entry for the domain, or repurpose diff --git a/documentation/index.md b/documentation/index.md index bd14d61707..89f4bc8d86 100644 --- a/documentation/index.md +++ b/documentation/index.md @@ -4,21 +4,21 @@ # Try It -Want to jump right in? Follow our [quick start tutorial](getting-started.md) on a new domain or [migrate](migrating.md) an existing one. Read the [language spec](02_language_reference/JavaScript_DSL.md) for more info. +Want to jump right in? Follow our [quick start tutorial](getting-started.md) on a new domain or [migrate](migrating.md) an existing one. Read the [language spec](language_reference/JavaScript_DSL.md) for more info. # Use It -Take advantage of the advanced features. Use macros and variables for easier updates. Upload your zones to [multiple DNS providers](providers.md). +Take advantage of the advanced features. Use macros and variables for easier updates. Upload your zones to [multiple DNS providers](service_providers/providers.md). {% hint style="success" %} * Maintain your DNS data as a high-level DS, with macros, and variables for easier updates. * Super extensible! Plug-in architecture makes adding new DNS providers and Registrars easy! * Eliminate vendor lock-in. Switch DNS providers easily, any time, with full fidelity. * Reduce points of failure: Easily maintain dual DNS providers and easily drop one that is down. -* Supports 35+ [DNS Providers](providers.md) including [BIND](providers/bind.md), [AWS Route 53](providers/route53.md), [Google DNS](providers/gcloud.md), and [name.com](providers/namedotcom.md). +* Supports 35+ [DNS Providers](service_providers/providers.md) including [BIND](service_providers/providers/bind.md), [AWS Route 53](service_providers/providers/route53.md), [Google DNS](service_providers/providers/gcloud.md), and [name.com](service_providers/providers/namedotcom.md). * [Apply CI/CD principles](ci-cd-gitlab.md) to DNS: Unit-tests, system-tests, automated deployment. * All the benefits of Git (or any VCS) for your DNS zone data. View history. Accept PRs. -* Optimize DNS with [SPF optimizer](functions/record/SPF_BUILDER.md). Detect too many lookups. Flatten includes. +* Optimize DNS with [SPF optimizer](language_reference/record_modifier_functions/SPF_BUILDER.md). Detect too many lookups. Flatten includes. * Runs on Linux, Windows, Mac, or any operating system supported by Go. * Enable/disable Cloudflare proxying (the "orange cloud" button) directly from your DNSControl files. * [Assign an IP address to a constant](examples.md#variables-for-common-ip-addresses) and use the variable name throughout the configuration. Need to change the IP address globally? Just change the variable and "recompile". diff --git a/documentation/language_reference/domain_modifier_functions/SOA.md b/documentation/language_reference/domain_modifier_functions/SOA.md index 8a97400fae..ba596384f3 100644 --- a/documentation/language_reference/domain_modifier_functions/SOA.md +++ b/documentation/language_reference/domain_modifier_functions/SOA.md @@ -39,4 +39,4 @@ when you are making it easier for spammers how to find you. * Most providers automatically generate SOA records. They will ignore any `SOA()` statements. * The mbox field should not be set to a real email address unless you love spam and hate your privacy. -There is more info about `SOA` in the documentation for the [BIND provider](../../providers/bind.md). +There is more info about `SOA` in the documentation for the [BIND provider](../../service_providers/providers/bind.md). diff --git a/documentation/language_reference/top_level_functions/NewDnsProvider.md b/documentation/language_reference/top_level_functions/NewDnsProvider.md index 4c9f394842..63466754a8 100644 --- a/documentation/language_reference/top_level_functions/NewDnsProvider.md +++ b/documentation/language_reference/top_level_functions/NewDnsProvider.md @@ -16,10 +16,10 @@ A DSP stores a DNS zone's records and provides DNS service for the zone (i.e. answers on port 53 to queries related to the zone). * `name` must match the name of an entry in `creds.json`. -* `type` specifies a valid DNS provider type identifier listed on the [provider page](../../providers.md). +* `type` specifies a valid DNS provider type identifier listed on the [provider page](../../service_providers/providers.md). * Starting with [v3.16](../../v316.md), the type is optional. If it is absent, the `TYPE` field in `creds.json` is used instead. You can leave it out. (Thanks to JavaScript magic, you can leave it out even when there are more fields). * Starting with v4.0, specifying the type may be an error. Please add the `TYPE` field to `creds.json` and remove this parameter from `dnsconfig.js` to prepare. -* `meta` is a way to send additional parameters to the provider. It is optional and only certain providers use it. See the [individual provider docs](../../providers.md) for details. +* `meta` is a way to send additional parameters to the provider. It is optional and only certain providers use it. See the [individual provider docs](../../service_providers/providers.md) for details. This function will return an opaque string that should be assigned to a variable name for use in [D](D.md) directives. diff --git a/documentation/language_reference/top_level_functions/NewRegistrar.md b/documentation/language_reference/top_level_functions/NewRegistrar.md index 1f0a897036..320a4fe28f 100644 --- a/documentation/language_reference/top_level_functions/NewRegistrar.md +++ b/documentation/language_reference/top_level_functions/NewRegistrar.md @@ -16,10 +16,10 @@ A registrar maintains the domain's registration and delegation (i.e. the nameservers for the domain). DNSControl only manages the delegation. * `name` must match the name of an entry in `creds.json`. -* `type` specifies a valid DNS provider type identifier listed on the [provider page](../../providers.md). +* `type` specifies a valid DNS provider type identifier listed on the [provider page](../../service_providers/providers.md). * Starting with [v3.16](../../v316.md), the type is optional. If it is absent, the `TYPE` field in `creds.json` is used instead. You can leave it out. (Thanks to JavaScript magic, you can leave it out even when there are more fields). * Starting with v4.0, specifying the type may be an error. Please add the `TYPE` field to `creds.json` and remove this parameter from `dnsconfig.js` to prepare. -* `meta` is a way to send additional parameters to the provider. It is optional and only certain providers use it. See the [individual provider docs](../../providers.md) for details. +* `meta` is a way to send additional parameters to the provider. It is optional and only certain providers use it. See the [individual provider docs](../../service_providers/providers.md) for details. This function will return an opaque string that should be assigned to a variable name for use in [D](D.md) directives. diff --git a/documentation/nameservers.md b/documentation/nameservers.md index e7f2e1a57e..f5555063c3 100644 --- a/documentation/nameservers.md +++ b/documentation/nameservers.md @@ -248,7 +248,7 @@ a notified if the delegation diverges. Why? Sometimes you just want to know if something changes! -See the [DNS-over-HTTPS Provider](providers/dnsoverhttps.md) documentation for more info. +See the [DNS-over-HTTPS Provider](service_providers/providers/dnsoverhttps.md) documentation for more info. {% code title="dnsconfig.js" %} ```javascript diff --git a/documentation/writing-providers.md b/documentation/writing-providers.md index 1daed5365d..cc5ad1c0bb 100644 --- a/documentation/writing-providers.md +++ b/documentation/writing-providers.md @@ -8,7 +8,7 @@ and the system takes care of the rest. Please do note that if you submit a new provider you will be assigned bugs related to the provider in the future (unless you designate someone else as the maintainer). More details -[here](providers.md). +[here](service_providers/providers.md). ## Overview @@ -77,7 +77,7 @@ Registrar if needed. If you have any questions, please discuss them in the GitHub issue related to the request for this provider. Please let us know what was confusing so we can update this document with advice for future -authors (or even better, update [this document](https://github.com/StackExchange/dnscontrol/blob/master/documentation/writing-providers.md) +authors (or even better, update [this document](writing-providers.md) yourself.) @@ -204,7 +204,7 @@ an automated way to test for this bug. The manual steps are here in ## Step 9: Update docs * Edit [README.md](https://github.com/StackExchange/dnscontrol): Add the provider to the bullet list. -* Edit [documentation/providers.md](https://github.com/StackExchange/dnscontrol/blob/master/documentation/providers.md): Add the provider to the provider list. +* Edit [documentation/providers.md](service_providers/providers.md): Add the provider to the provider list. * Create `documentation/providers/PROVIDERNAME.md`: Use one of the other files in that directory as a base. * Edit [OWNERS](https://github.com/StackExchange/dnscontrol/blob/master/OWNERS): Add the directory name and your GitHub username. @@ -296,9 +296,9 @@ Here are some last-minute things to check before you submit your PR. 2. Make sure all appropriate documentation is current. (See [Step 8](#step-8-manual-tests)) 3. Check that dependencies are current (See [Step 13](#step-13-dependencies)) 4. Re-run the integration test one last time (See [Step 7](#step-7-integration-test)) -5. Re-read the [maintainer's responsibilities](providers.md) bullet list. By submitting a provider you agree to maintain it, respond to bugs, perioidically re-run the integration test to verify nothing has broken, and if we don't hear from you for 2 months we may disable the provider. +5. Re-read the [maintainer's responsibilities](service_providers/providers.md) bullet list. By submitting a provider you agree to maintain it, respond to bugs, perioidically re-run the integration test to verify nothing has broken, and if we don't hear from you for 2 months we may disable the provider. ## Step 16: After the PR is merged 1. Remove the "provider-request" label from the PR. -2. Verify that [documentation/providers.md](providers.md) no longer shows the provider as "requested" +2. Verify that [documentation/providers.md](service_providers/providers.md) no longer shows the provider as "requested" From d8c390489d0b2405eb77db01578cf244261c76bf Mon Sep 17 00:00:00 2001 From: Paul Date: Fri, 24 Mar 2023 20:39:28 +0100 Subject: [PATCH 8/9] Amend adding new rtypes procedure. --- documentation/adding-new-rtypes.md | 33 ++++-------------------------- 1 file changed, 4 insertions(+), 29 deletions(-) diff --git a/documentation/adding-new-rtypes.md b/documentation/adding-new-rtypes.md index f4c14a6e95..3354c25029 100644 --- a/documentation/adding-new-rtypes.md +++ b/documentation/adding-new-rtypes.md @@ -291,7 +291,7 @@ tests, please ask! ## Step 8: Write documentation -Add a new Markdown file to `documentation/functions/domain`. Copy an existing file (`CNAME.md` is a good example). The section between the lines of `---` is called the front matter and it has the following keys: +Add a new Markdown file to `documentation/language_reference/domain_modifier_functions` (if the new record type is service provider specific, add it to the appropriate subfolder, creating the folder if it does not exist). Copy an existing file (`CNAME.md` is a good example). The section between the lines of `---` is called the front matter and it has the following keys: - `name`: The name of the record. This should match the file name and the name of the record in `helpers.js`. - `parameters`: A list of parameter names, in order. Feel free to use spaces in the name if necessary. Your last parameter should be `modifiers...` to allow arbitrary modifiers like `TTL` to be applied to your record. @@ -299,31 +299,6 @@ Add a new Markdown file to `documentation/functions/domain`. Copy an existing fi The rest of the file is the documentation. You can use Markdown syntax to format the text. -Add the new file `FOO.md` to the documentation table of contents [`documentation/SUMMARY.md`](SUMMARY.md#domain-modifiers), and/or to the [`Service Provider specific`](SUMMARY.md#service-provider-specific) section if you made a record specific to a provider, and to the [`Record Modifiers`](SUMMARY.md#record-modifiers) section if you created any `*_BUILDER` or `*_HELPER` or similar functions for the new record type: - -{% code title="documentation/SUMMARY.md" %} -```diff -... -* Domain Modifiers -... - * [DnsProvider](language_reference/domain_modifier_functions/DnsProvider.md) -+ * [FOO](language_reference/domain_modifier_functions/FOO.md) - * [FRAME](language_reference/domain_modifier_functions/FRAME.md) -... - * Service Provider specific -... - * ClouDNS - * [CLOUDNS_WR](language_reference/domain_modifier_functions/service_provider_specific/ClouDNS/CLOUDNS_WR.md) -+ * ASDF -+ * [NINJA_RECORD](language_reference/domain_modifier_functions/service_provider_specific/XYZ/FOO_NINJA.md) - * NS1 - * [NS1_URLFWD](language_reference/domain_modifier_functions/service_provider_specific/NS1/NS1_URLFWD.md) -... -* Record Modifiers -... - * [DMARC_BUILDER](language_reference/record_modifier_functions/DMARC_BUILDER.md) -+ * [FOO_HELPER](language_reference/record_modifier_functions/FOO_HELPER.md) - * [SPF_BUILDER](language_reference/record_modifier_functions/SPF_BUILDER.md) -... -``` -{% endcode %} +If you create any helper functions such as `FOO_BUILDER`, place the markdown files documenting them in their appropriate folder e.g. `documentation/language_reference/record_modifier_functions`. + +At the next run of `go generate ./...` - the documentation tables and links within the new markdown files should be automatically generated and refreshed. From 11d6dc296181d8870e29634cd52afc0b65bdb490 Mon Sep 17 00:00:00 2001 From: Paul Date: Tue, 4 Apr 2023 01:01:32 +0200 Subject: [PATCH 9/9] Refresh 2 --- documentation/service_providers/providers.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documentation/service_providers/providers.md b/documentation/service_providers/providers.md index 7d03c33d47..fde0bfee9f 100644 --- a/documentation/service_providers/providers.md +++ b/documentation/service_providers/providers.md @@ -34,7 +34,7 @@ If a feature is definitively not supported for whatever reason, we would also li | [`GCLOUD`](service_providers/gcloud.md) | ✅ | ✅ | ❌ | ✅ | ✅ | ❔ | ❌ | ❔ | ✅ | ❔ | ✅ | ✅ | ✅ | ❔ | ✅ | ✅ | ✅ | ✅ | | [`GCORE`](service_providers/gcore.md) | ❌ | ✅ | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ | ❔ | ✅ | ❌ | ❌ | ❌ | ✅ | ✅ | ✅ | ✅ | | [`HEDNS`](service_providers/hedns.md) | ❌ | ✅ | ❌ | ✅ | ✅ | ❌ | ✅ | ✅ | ✅ | ❌ | ✅ | ✅ | ❌ | ❌ | ✅ | ✅ | ✅ | ✅ | -| [`HETZNER`](service_providers/hetzner.md) | ❌ | ✅ | ❌ | ❌ | ✅ | ❔ | ❌ | ❔ | ❌ | ❔ | ✅ | ❌ | ✅ | ❌ | ✅ | ✅ | ✅ | ✅ | +| [`HETZNER`](service_providers/hetzner.md) | ❌ | ✅ | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | | [`HEXONET`](service_providers/hexonet.md) | ❌ | ✅ | ✅ | ❌ | ✅ | ❔ | ❔ | ❔ | ✅ | ❔ | ✅ | ❔ | ✅ | ❔ | ✅ | ✅ | ✅ | ❔ | | [`HOSTINGDE`](service_providers/hostingde.md) | ❌ | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | | [`INTERNETBS`](service_providers/internetbs.md) | ❌ | ❌ | ✅ | ❔ | ❔ | ❔ | ❔ | ❔ | ❔ | ❔ | ❔ | ❔ | ❔ | ❔ | ❔ | ❌ | ✅ | ❔ |