dnscontrol/documentation/preview-push.md

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.

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                                             Generate a JSON-formatted report of the number of changes.
   --help, -h                                                 show help

• --config name

  • Specifies the name of the main configuration file, normally dnsconfig.js.

• --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. See [creds.json][creds-json.md] for details.

• --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.

• --v foo=bar

  • Sets the variable foo to the value bar prior to interpreting the configuration file. Multiple -v options can be used.

• --notify

  • Enables sending notifications to the destinations configured in creds.json.

• --dev

  • Developer mode. Normally helpers.js is embedded in the dnscontrol executable. With this flag, the local file helpers.js is read instead.

• --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.

• --cmode value

  • Concurrency mode. See below.

• --report name

  • Write a machine-parseable report of corrections to the file named name. If no name is specified, no report is generated. See JSON Reports

cmode

The preview/push commands begin with a data-gathering phase that collects current configuration from providers and zones. This collection can be done sequentially or concurrently. Concurrently is significantly faster. However since concurrent mode is newer, not all providers have been tested and certified as being compatible with this mode. Therefore the --cmode flag can be used to control concurrency.

The --cmode value may be one of the following:

• legacy -- Use the older, sequential code. All data is gathered sequentially. This option and the related code will removed in release v4.16 (or later). Please test --cmode concurrent and report any bugs ASAP.
• concurrent -- Gathering is done either 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. While this is logically the same as legacy, it is implemented using the newer concurrent code, with concurrency disabled.
• 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.

The default value of --cmode will change over time:

• v4.14: --cmode legacy
• v4.15: --cmode concurrent
• v4.16 or later (target 1-Jan-2025): The --cmode legacy option will be removed, along with the old serial code.

ppreview/ppush

{% hint style="warning" %} These commands will go away in v4.16 or later. Starting in v4.14, please use preview/push with --cmode concurrent instead. {% endhint %}

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.