From 1ae265e5f6a87931434e099ac81b4f27ed78caae Mon Sep 17 00:00:00 2001 From: Tom Limoncelli Date: Wed, 27 Mar 2024 13:57:21 -0400 Subject: [PATCH] Add documentation for preview/push (#2884) --- documentation/SUMMARY.md | 9 ++- documentation/preview-push.md | 102 ++++++++++++++++++++++++++++++++++ 2 files changed, 108 insertions(+), 3 deletions(-) create mode 100644 documentation/preview-push.md diff --git a/documentation/SUMMARY.md b/documentation/SUMMARY.md index 5fc70355cc..8202c7b661 100644 --- a/documentation/SUMMARY.md +++ b/documentation/SUMMARY.md @@ -8,7 +8,6 @@ * [Examples](examples.md) * [Migrating zones to DNSControl](migrating.md) * [TypeScript autocomplete and type checking](typescript.md) -* [Disabling Colors](colors.md) ## Language Reference @@ -150,10 +149,14 @@ ## Commands -* [creds.json](creds-json.md) +* [preview/push](preview-push.md) * [check-creds](check-creds.md) -* [get-certs](get-certs.md) * [get-zones](get-zones.md) +* [get-certs](get-certs.md) +* [fmt](fmt.md) +* [creds.json](creds-json.md) +* [Global Flag](globalflags.md) +* [Disabling Colors](colors.md) ## Advanced features diff --git a/documentation/preview-push.md b/documentation/preview-push.md new file mode 100644 index 0000000000..5423169aa8 --- /dev/null +++ b/documentation/preview-push.md @@ -0,0 +1,102 @@ +# preview/push + +`preview` reads the dnsconfig.js file (or equivalent), determines what changes are to be made, and +prints them. `push` is the same but executes the changes. + +```text +Syntax: + +NAME: + dnscontrol preview - read live configuration and identify changes to be made, without applying them + +USAGE: + dnscontrol preview [command options] [arguments...] + +CATEGORY: + main + +OPTIONS: + --config value File containing dns config in javascript DSL (default: "dnsconfig.js") + --dev Use helpers.js from disk instead of embedded copy (default: false) + --variable value, -v value [ --variable value, -v value ] Add variable that is passed to JS + --ir value Read IR (json) directly from this file. Do not process DSL at all + --creds value Provider credentials JSON file (or !program to execute program that outputs json) (default: "creds.json") + --providers value Providers to enable (comma separated list); default is all. Can exclude individual providers from default by adding '"_exclude_from_defaults": "true"' to the credentials file for a provider + --domains value Comma separated list of domain names to include + --notify set to true to send notifications to configured destinations (default: false) + --expect-no-changes set to true for non-zero return code if there are changes (default: false) + --no-populate Use this flag to not auto-create non-existing zones at the provider (default: false) + --full Add headings, providers names, notifications of no changes, etc (default: false) + --bindserial value Force BIND serial numbers to this value (for reproducibility) (default: 0) + --report value (push) Generate a JSON-formatted report of the number of changes made. + --help, -h show help +``` + +`--config name` -- Specifies the name of the main configuration file, normally +`dnsconfig.js`. + +`--dev` -- Developer mode. Normally `helpers.js` is embedded in the dnscontrol +executable. With this flag, the local file `helpers.js` is read instead. + +`--v foo=bar` -- Sets the variable `foo` to the value `bar` prior to +interpreting the configuration file. Multiple `-v` options can be used. + +`--creds name` -- Specifies the name of the credentials file, normally +`creds.json`. Typically the file is read. If the executable bit is set, the +file is executed and the output is used as the configuration. (That feature may +or may not work on Windows.) If the filename begins with a `|` (for example: +`|runme.sh`) the `|` is removed and the remaining string is used as the name of +the program. + +`--providers name,name2` -- Specifies a comma-separated list of providers to +enable. The default is all providers. A provider can opt out of being in the +default list by `"_exclude_from_defaults": "true"` to the credentials entry for +that provider. In that case, the provider will only be activated if it is +included in `--providers`. + +`--domains value` -- Specifies a comma-separated list of domains to include. +Typically all domains are included in `preview`/`push`. Wildcards are not +permitted except `*` at the start of the entry. For example, `--domains +example.com,*.in-addr.arpa` would include `example.com` plus all reverse lookup +domains. + +`--notify` -- Enables sending notifications to the destinations configured in +`creds.json`. + +`--expect-no-changes` -- If set, a non-zero exit code is returned if there are +changes. Normally DNSControl sets the exit code based on whether or not there +were protocol errors or other reasons the program can not continue. With this +flag set, the exit code indicates if any changes were required. This is +typically used with `preview` to allow scripts to determine if changes would +happen if `push` was used. For example, one might want to run `dnscontrol +preview --expect-no-changes` daily to determine if changes have been made to +a domain outside of DNSControl. + +`--no-populate` -- Do not auto-create non-existing zones at the provider. +Normally non-existent zones are automatically created at a provider (unless the +provider does not implement zone creation). This flag disables that feature. + +`--full` -- Add headings, providers names, notifications of no changes, etc. to +the output. Normally the output of `preview`/`push` is extremely brief. This +makes the output more verbose. Useful for debugging. + +`--bindserial value` -- Force BIND serial numbers to this value. Normally the +BIND provider generates SOA serial numbers automatically. This flag forces the +serial number generator to output the value specified for all domains. This is +generally used for reproducibility in testing pipelines. + +`--report name` -- (`push` only!) Generate a machine-parseable report of +performed corrections in the file named `name`. If no name is specified, no +report is generated. + +## Experimental + +The `ppreview`/`ppush` subcommands are a preview of a future feature where zone +data is gathered concurrently. The commands will go away when +they replace the existing `preview`/`push` commands. + +`--cmode value` -- Concurrency mode. Specifies what kind of providers should be run concurrently. This flag onl + +* `default` -- Providers are run sequentially or concurrently depending on whether the provider is marked as having been tested to run concurrently. +* `none` -- All providers are run sequentially. This is the safest mode. It can be used if a concurrency bug is discovered. +* `all` -- This is unsafe. It runs all providers concurrently, even the ones that have not be validated to run concurrently. It is generally only used for demonstrating bugs.