diff --git a/docs/_functions/domain/SSHFP.md b/docs/_functions/domain/SSHFP.md index d69916d0a..c68756345 100644 --- a/docs/_functions/domain/SSHFP.md +++ b/docs/_functions/domain/SSHFP.md @@ -11,6 +11,7 @@ parameters: SSHFP contains a fingerprint of a SSH server which can be validated before SSH clients are establishing the connection. **Algorithm** (type of the key) + | ID | Algorithm | |----|-----------| | 0 | reserved | @@ -20,6 +21,7 @@ SSHFP contains a fingerprint of a SSH server which can be validated before SSH c | 4 | ED25519 | **Type** (fingerprint format) + | ID | Algorithm | |----|-----------| | 0 | reserved | diff --git a/docs/_functions/domain/TXT.md b/docs/_functions/domain/TXT.md index 6fa9666ee..fe48bdedf 100644 --- a/docs/_functions/domain/TXT.md +++ b/docs/_functions/domain/TXT.md @@ -43,7 +43,7 @@ split into 255-octets chunks or the provider may report an error if it does not handle multiple strings. -### TXT record edge cases. +### TXT record edge cases Most providers do not support the full possibilities of what a TXT record can store. DNSControl can not handle all the edge cases diff --git a/docs/_functions/global/D_EXTEND.md b/docs/_functions/global/D_EXTEND.md index 58f10c536..ffffef589 100644 --- a/docs/_functions/global/D_EXTEND.md +++ b/docs/_functions/global/D_EXTEND.md @@ -29,8 +29,6 @@ Some operators only act on an apex domain (e.g. `CF_REDIRECT` and `CF_TEMP_REDIRECT`). Using them in a `D_EXTEND` subdomain may not be what you expect. -Example: - {% capture example %} ```js D("domain.tld", REG, DnsProvider(DNS), diff --git a/docs/_functions/global/NewDnsProvider.md b/docs/_functions/global/NewDnsProvider.md index daee279a8..218f894d5 100644 --- a/docs/_functions/global/NewDnsProvider.md +++ b/docs/_functions/global/NewDnsProvider.md @@ -7,7 +7,7 @@ parameters: return: string --- -NewDnsProvider activates a DNS Service Provider (DSP) specified in creds.json. +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). diff --git a/docs/_functions/global/require.md b/docs/_functions/global/require.md index a391cb85a..d05501a13 100644 --- a/docs/_functions/global/require.md +++ b/docs/_functions/global/require.md @@ -56,7 +56,6 @@ function includeK8Sdev() { {% include example.html content=example %} You can also use it to require JSON files and initialize variables with it: -For Example: {% capture example %} ```js diff --git a/docs/_functions/record/CAA_BUILDER.md b/docs/_functions/record/CAA_BUILDER.md index c66a84f8b..4a4ce62ae 100644 --- a/docs/_functions/record/CAA_BUILDER.md +++ b/docs/_functions/record/CAA_BUILDER.md @@ -46,4 +46,3 @@ The parameters are: * `CAA("@", "issue", "letsencrypt.org")` * `CAA("@", "issue", "comodoca.com")` * `CAA("@", "issuewild", ";")` -``` diff --git a/docs/_providers/dnsimple.md b/docs/_providers/dnsimple.md index 4874a865f..9e4471195 100644 --- a/docs/_providers/dnsimple.md +++ b/docs/_providers/dnsimple.md @@ -52,12 +52,12 @@ DNSControl depends on a DNSimple account access token. As of July 2022, the DNSimple DNS does not accept spaces in CAA records. Putting spaces in the record will result in a 400 Validation Failed error. -``` +```text 0 issue "letsencrypt.org; validationmethods=dns-01; accounturi=https://acme-v02.api.letsencrypt.org/acme/acct/1234" ``` Removing the spaces will work. -``` +```text 0 issue "letsencrypt.org;validationmethods=dns-01;accounturi=https://acme-v02.api.letsencrypt.org/acme/acct/1234" ``` diff --git a/docs/_providers/gandi_v5.md b/docs/_providers/gandi_v5.md index 09339198a..e82a00688 100644 --- a/docs/_providers/gandi_v5.md +++ b/docs/_providers/gandi_v5.md @@ -30,7 +30,7 @@ the URL on the portal. Log into the Gandi website, click on "organizations" in the leftnav, and click on the organization name. The URL will be something like: -``` +```text https://admin.gandi.net/organizations/[not this hex string]/PLTS/[sharing id]/profile ``` @@ -88,7 +88,7 @@ This is the error you'll see if your `apikey` in `creds.json` is wrong or invali #### Domain does not exist in profile -``` +```text WARNING: Domain 'example.com' does not exist in the 'secname' profile and will be added automatically. ``` diff --git a/docs/_providers/gcloud.md b/docs/_providers/gcloud.md index 7d789ba45..09e28c3be 100644 --- a/docs/_providers/gcloud.md +++ b/docs/_providers/gcloud.md @@ -44,7 +44,7 @@ Example: See [the Activation section](#activation) for some tips on obtaining these credentials. ### Using Application Default Credentials -If you prefer to authenticate using ADC you only need to specify `project_id` in your creds.json file. +If you prefer to authenticate using ADC you only need to specify `project_id` in your `creds.json` file. Example: diff --git a/docs/_providers/hetzner.md b/docs/_providers/hetzner.md index 790265a7c..414e80ab0 100644 --- a/docs/_providers/hetzner.md +++ b/docs/_providers/hetzner.md @@ -52,12 +52,12 @@ Create a new API Key in the As of June 2022, the Hetzner DNS Console API does not accept spaces in CAA records. -``` +```text 0 issue "letsencrypt.org; validationmethods=dns-01; accounturi=https://acme-v02.api.letsencrypt.org/acme/acct/1234" ``` Removing the spaces might still work for any consumer of the record. -``` +```text 0 issue "letsencrypt.org;validationmethods=dns-01;accounturi=https://acme-v02.api.letsencrypt.org/acme/acct/1234" ``` diff --git a/docs/_providers/namedotcom.md b/docs/_providers/namedotcom.md index c59d1c1a3..e5fa18296 100644 --- a/docs/_providers/namedotcom.md +++ b/docs/_providers/namedotcom.md @@ -82,7 +82,7 @@ In integration tests: * Wrong: `export NAMEDOTCOM_URL='api.name.com/api'` * Right: `export NAMEDOTCOM_URL='api.name.com'` -In production, the `apiurl` setting in creds.json is wrong. You can +In production, the `apiurl` setting in `creds.json` is wrong. You can simply leave this option out and use the default, which is correct. TODO(tlim): Improve the error message. (Volunteer needed!) @@ -98,7 +98,7 @@ When running integration tests, this error means you included the `https://` in the `NAMEDOTCOM_URL` variable. You meant to do something like `export NAMEDOTCOM_URL='api.name.com' instead. -In production, the `apiurl` setting in creds.json needs to be +In production, the `apiurl` setting in `creds.json` needs to be adjusted. You can simply leave this option out and use the default, which is correct. If you are using the EO&T system, leave the protocol (`http://`) off the URL. diff --git a/docs/_providers/route53.md b/docs/_providers/route53.md index 445b33077..e48a95367 100644 --- a/docs/_providers/route53.md +++ b/docs/_providers/route53.md @@ -48,7 +48,7 @@ Alternatively, this provider supports [named profiles](https://docs.aws.amazon.c export AWS_PROFILE=ZZZZZZZZ ``` -and provide a minimal entry in creds.json: +and provide a minimal entry in `creds.json`: Example: @@ -192,7 +192,7 @@ Creating r53 dns provider: NoCredentialProviders: no valid providers in chain. D For verbose messaging see aws.Config.CredentialsChainVerboseErrors ``` -This means that the creds.json entry isn't found. Either there is no entry, or the entry name doesn't match the first parameter in the `NewDnsProvider()` call. In the above example, note +This means that the `creds.json` entry isn't found. Either there is no entry, or the entry name doesn't match the first parameter in the `NewDnsProvider()` call. In the above example, note that the string `r53_main` is specified in `NewDnsProvider("r53_main")` and that is the exact key used in the creds file above. ### Invalid KeyId diff --git a/docs/adding-new-rtypes.md b/docs/adding-new-rtypes.md index f60b35665..d8851054b 100644 --- a/docs/adding-new-rtypes.md +++ b/docs/adding-new-rtypes.md @@ -112,7 +112,7 @@ Anywhere a rtype requires special handling has been marked with a comment that includes the string `#rtype_variations`. Search for this string and add your new type to this code. -## Step 5: Add a `parse_tests` test case. +## Step 5: Add a `parse_tests` test case Add at least one test case to the `pkg/js/parse_tests` directory. Test `013-mx.js` is a very simple one and is good for cloning. @@ -133,7 +133,7 @@ The tests also verify that for every "capability" there is a validation. This is explained in Step 2 (search for `TestCapabilitiesAreFiltered` or `MISSING`) -## Step 6: Add an `integrationTest` test case. +## Step 6: Add an `integrationTest` test case Add at least one test case to the `integrationTest/integration_test.go` file. Look for `func makeTests` and add the test to the end of this diff --git a/docs/ci-cd-gitlab.md b/docs/ci-cd-gitlab.md index cf49e61de..8902c83a3 100644 --- a/docs/ci-cd-gitlab.md +++ b/docs/ci-cd-gitlab.md @@ -19,7 +19,7 @@ This is based on: For convenience, both configuration files are shown below. - `dnsconfig.js` - ```javascript + ```js var PROVIDER_NONE = NewRegistrar('none'); var PROVIDER_TRANSIP = NewDnsProvider('transip', '-'); diff --git a/docs/creds-json.md b/docs/creds-json.md index dc2909b3a..c64d397e7 100644 --- a/docs/creds-json.md +++ b/docs/creds-json.md @@ -117,7 +117,7 @@ Usually this is to simply remove the second parameter to the function. Examples: -``` +```js OLD: var REG_THING = NewRegistrar("thing", "THING"); NEW: var REG_THING = NewRegistrar("thing"); diff --git a/docs/examples.md b/docs/examples.md index 00814c31a..8cb28f140 100644 --- a/docs/examples.md +++ b/docs/examples.md @@ -161,7 +161,7 @@ In this example we need a macro that can dynamically change for each domain. Suppose you have many domains that use Fastmail as an MX. Here's a macro that sets the MX records. -``` +```js var FASTMAIL_MX = [ MX('@', 10, 'in1-smtp.messagingengine.com.'), MX('@', 20, 'in2-smtp.messagingengine.com.'), @@ -173,7 +173,7 @@ that includes the domain name. We can't use a simple macro. Instead, we use a function that takes the domain name as a parameter to generate the right records dynamically. -``` +```js var FASTMAIL_DKIM = function(the_domain){ return [ CNAME('fm1._domainkey', 'fm1.' + the_domain + '.dkim.fmhosted.com.'), @@ -185,7 +185,7 @@ var FASTMAIL_DKIM = function(the_domain){ We can then use the macros as such: -``` +```js D("example.com", REG_NONE, DnsProvider(DSP_R53_MAIN), FASTMAIL_MX, FASTMAIL_DKIM('example.com') diff --git a/docs/getting-started.md b/docs/getting-started.md index 07dd00bd0..ca6060f7d 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -42,7 +42,7 @@ docker run --rm -it -v $(pwd)/dnsconfig.js:/dns/dnsconfig.js -v $(pwd)/creds.jso ``` -## 2. Create a place for the config files. +## 2. Create a place for the config files Create a directory where you'll be storing your configuration files. We highly recommend storing these files in a Git repo, but for @@ -99,7 +99,7 @@ For example, to use both name.com and Cloudflare, you would have: } ``` -Note: Do **not** store your creds.json file in Git unencrypted. +Note: Do **not** store your `creds.json` file in Git unencrypted. That is unsafe. Add `creds.json` to your `.gitignore` file as a precaution. This file should be encrypted using something @@ -152,17 +152,25 @@ and other formatting. There are a few different ways to check for typos: Python: - python -m json.tool creds.json +```bash +python -m json.tool creds.json +``` jq: - jq . < creds.json +```bash +jq . < creds.json +``` FYI: `creds.json` fields can be read from an environment variable. The field must begin with a `$` followed by the variable name. No other text. For example: - "apikey": "$GANDI_V5_APIKEY", +```json +{ + "apikey": "$GANDI_V5_APIKEY" +} +``` -## 5. Test the sample files. +## 5. Test the sample files Before you edit the sample files, verify that the system is working. @@ -176,8 +184,10 @@ exist. It should look something like this: -```text +```bash dnscontrol preview +``` +```text Initialized 1 registrars and 1 dns service providers. ******************** Domain: example.com ----- Getting nameservers from: bind @@ -195,6 +205,8 @@ previously exist. ```bash dnscontrol push +``` +```text Initialized 1 registrars and 1 dns service providers. ******************** Domain: example.com ----- Getting nameservers from: bind @@ -209,7 +221,7 @@ Done. 1 corrections. ``` -## 6. Make a change. +## 6. Make a change Try making a change to `dnsconfig.js`. For example, change the IP address of in `A('@', '1.2.3.4')` or add an additional A record. @@ -219,6 +231,8 @@ our change looks like this: ```bash dnscontrol preview +``` +```text Initialized 1 registrars and 1 dns service providers. ******************** Domain: example.com ----- Getting nameservers from: bind @@ -293,5 +307,5 @@ If you are going to use this in production, we highly recommend the following: * Store the configuration files in Git. * Encrypt the `creds.json` file before storing it in Git. Do NOT store API keys or other credentials without encrypting them. -* Use a CI/CD tool like Jenkins/CircleCI/GitHub Actions/etc. to automatically push DNS changes. -* Join the DNSControl community. File [issues and PRs](https://github.com/StackExchange/dnscontrol). +* Use a CI/CD tool like [Gitlab]({{site.github.url}}/ci-cd-gitlab), Jenkins, CircleCI, [GitHub Actions](https://github.com/StackExchange/dnscontrol#via-github-actions-gha), etc. to automatically push DNS changes. +* Join the DNSControl community. File [issues](https://github.com/StackExchange/dnscontrol/issues) and [PRs](https://github.com/StackExchange/dnscontrol/pulls). diff --git a/docs/migrating.md b/docs/migrating.md index f579510c0..f02b92226 100644 --- a/docs/migrating.md +++ b/docs/migrating.md @@ -106,21 +106,32 @@ If `dnscontrol get-zones` could have done a better job, please Here is an example series of commands that would be used to convert a zone. Lines that start with `#` are comments. - # Note this command uses ">>" to append to dnsconfig.js. Do - # not use ">" as that will erase the existing file. - dnscontrol get-zones --format=js --out=draft.js bind BIND foo.com - cat >>dnsconfig.js draft.js # Append to dnsconfig.js - # - dnscontrol preview - vim dnsconfig.js - # (repeat these two commands until all warnings/errors are resolved) - # - # When everything is as you wish, push the changes live: - dnscontrol push - # (this should be a no-op) - # - # Make any changes you do desire: - vim dnsconfig.js - dnscontrol preview - # (repeat until all warnings/errors are resolved) - dnscontrol push + +```bash +# Note this command uses ">>" to append to dnsconfig.js. Do not use ">" as that will erase the existing file. +dnscontrol get-zones --format=js --out=draft.js bind BIND foo.com +cat >>dnsconfig.js draft.js # Append to dnsconfig.js +dnscontrol preview +vim dnsconfig.js +``` + +Repeat these two commands until all warnings/errors are resolved. +When everything is as you wish, push the changes live: + +```bash +dnscontrol push +``` + + +Make any changes you do desire: + +```bash +vim dnsconfig.js +dnscontrol preview +``` + +Repeat until all warnings/errors are resolved. + +```bash +dnscontrol push +``` diff --git a/docs/testing-txt-records.md b/docs/testing-txt-records.md index 542b1eef6..f3b5fb0ed 100644 --- a/docs/testing-txt-records.md +++ b/docs/testing-txt-records.md @@ -55,7 +55,7 @@ Step 3: Preview When you do a `dnscontrol preview`, you should see changes for t1 and t2. -``` +```text #1: MODIFY TXT t1.example.com: ("test1" ttl=1) -> ("\"test1\"" ttl=1) #2: MODIFY TXT t2.example.com: ("\"test2\"" ttl=1) -> ("test2" ttl=1) ``` @@ -69,7 +69,7 @@ Step 3: Push Let's assume you DO see the changes. Push them using `dnscontrol push` then check the webui to see that the changes are correct. -``` +```text 2 corrections #1: MODIFY TXT t1.stackoverflow.help: ("test1" ttl=1) -> ("\"test1\"" ttl=1) SUCCESS! diff --git a/docs/v316.md b/docs/v316.md index a5b7537a2..7d957f1b1 100644 --- a/docs/v316.md +++ b/docs/v316.md @@ -90,7 +90,7 @@ out entirely starting in v4.0. For check-creds: -``` +```text Starting in v3.16 these forms are valid: dnscontrol check-creds myr53 dnscontrol check-creds myr53 - @@ -103,7 +103,7 @@ Starting in v4.0 this is the only valid form: For get-zones/get-zone: -``` +```text Starting in v3.16 these forms are valid: dnscontrol get-zones gmain GANDI_V5 example.comn other.com dnscontrol get-zones gmain - example.comn other.com @@ -167,7 +167,7 @@ Here are some examples: If you see something like... -``` +```text WARNING: For future compatibility, update the "namedotcom_main" entry in `creds.json` by adding: "TYPE": "NAMEDOTCOM", (See https://stackexchange.github.io/dnscontrol/creds-json#missing) ``` @@ -176,7 +176,7 @@ WARNING: For future compatibility, update the "namedotcom_main" entry in `creds. If you see something like... -``` +```text ERROR: Mismatch found! creds.json entry "namedotcom_main" has "TYPE" set to "ROUTE53" but dnsconfig.js specifies New*("namedotcom_main", "NAMEDOTCOM") (See https://stackexchange.github.io/dnscontrol/creds-json#mismatch) ``` @@ -185,7 +185,7 @@ ERROR: Mismatch found! creds.json entry "namedotcom_main" has "TYPE" set to "ROU After you correct some warnings, you may receive information messages like... -``` +```text INFO: In dnsconfig.js New*("namedotcom_main", "NAMEDOTCOM") can be simplified to New*("namedotcom_main") (See https://stackexchange.github.io/dnscontrol/creds-json#cleanup) ``` diff --git a/docs/writing-providers.md b/docs/writing-providers.md index 45d823577..5e77cc55e 100644 --- a/docs/writing-providers.md +++ b/docs/writing-providers.md @@ -163,7 +163,7 @@ Run the unit tests with this command: This is the most important kind of testing when adding a new provider. Integration tests use a test account and a real domain. -* Edit [integrationTest/providers.json](https://github.com/StackExchange/dnscontrol/blob/master/integrationTest/providers.json): Add the creds.json info required for this provider. +* Edit [integrationTest/providers.json](https://github.com/StackExchange/dnscontrol/blob/master/integrationTest/providers.json): Add the `creds.json` info required for this provider. For example, this will run the tests using BIND: @@ -282,7 +282,7 @@ for tips about managing modules and checking for outdated dependencies. -## Step 14: Check your work. +## Step 14: Check your work Here are some last-minute things to check before you submit your PR. diff --git a/integrationTest/readme.md b/integrationTest/readme.md index 4ddca09cd..2189ef1d7 100644 --- a/integrationTest/readme.md +++ b/integrationTest/readme.md @@ -8,7 +8,7 @@ For each step, it will run the config once and expect changes. It will run it ag ## Configuration -`providers.json` should have an object for each provider type under test. This is identical to the json expected in creds.json for dnscontrol, except it also has a "domain" field specified for the domain to test. The domain does not even need to be registered for most providers. Note that `providers.json` expects environment variables to be specified with the relevant info. +`providers.json` should have an object for each provider type under test. This is identical to the json expected in `creds.json` for dnscontrol, except it also has a "domain" field specified for the domain to test. The domain does not even need to be registered for most providers. Note that `providers.json` expects environment variables to be specified with the relevant info. ## Running a test diff --git a/providers/octodns/TESTING.md b/providers/octodns/TESTING.md index 986a905be..05cf24490 100644 --- a/providers/octodns/TESTING.md +++ b/providers/octodns/TESTING.md @@ -1,6 +1,6 @@ # Testing: -## Create the environment. +## Create the environment These variables are used in all other sections of this doc.