diff --git a/commands/commands.go b/commands/commands.go index b46355b4f9..23e46d0a7d 100644 --- a/commands/commands.go +++ b/commands/commands.go @@ -50,8 +50,9 @@ func Run(v string) int { app.Usage = "DNSControl is a compiler and DSL for managing dns zones" app.Flags = []cli.Flag{ &cli.BoolFlag{ - Name: "v", - Usage: "Enable detailed logging", + Name: "debug", + Aliases: []string{"v"}, + Usage: "Enable debug logging", Destination: &printer.DefaultPrinter.Verbose, }, &cli.BoolFlag{ diff --git a/documentation/creds-json.md b/documentation/creds-json.md index 8c2f1eff38..318fe9213a 100644 --- a/documentation/creds-json.md +++ b/documentation/creds-json.md @@ -225,13 +225,14 @@ An example of a template file containing Linode and Cloudflare API credentials i ``` {% endcode %} -## Don't store secrets in a Git repo! +## Don't store creds.json in a Git repo! -Do NOT store secrets in a Git repository. That is not secure. For example, -storing the example `cloudflare_tal` is insecure because anyone with access to -your Git repository or the history will know your apiuser is `REDACTED`. -Removing secrets accidentally stored in Git is very difficult. You'll probably -give up and re-create the repo and lose all history. +Do NOT store `creds.json` (or any secrets!) in a Git repository. That is not secure. -Instead, use environment variables as in the `hexonet` example above. Use +For example, storing the creds.json at the top of this document would be horribly insecure. +Anyone with access to your Git repository *or the history* will know your apiuser is `REDACTED`. +Removing secrets accidentally stored in Git is very difficult because you'll need to rewrite +the repo history. + +A better way is to use environment variables as in the `hexonet` example above. Use secure means to distribute the names and values of the environment variables. diff --git a/documentation/fmt.md b/documentation/fmt.md new file mode 100644 index 0000000000..1c7f5dcdc2 --- /dev/null +++ b/documentation/fmt.md @@ -0,0 +1,50 @@ +# fmt + +This is a stand-alone utility to pretty-format your `dnsconfig.js` configuration file. + +```shell +NAME: + dnscontrol fmt - [BETA] Format and prettify a given file + +USAGE: + dnscontrol fmt [command options] [arguments...] + +CATEGORY: + utility + +OPTIONS: + --input value, -i value Input file (default: "dnsconfig.js") + --output value, -o value Output file + --help, -h show help +``` + +## Examples + +By default the output goes to stdout: + +```shell +dnscontrol fmt >new-dnsconfig.js +``` + +You can also redirect the output via the `-o` option: + +```shell +dnscontrol fmt -o new-dnsconfig.js +``` + +The **safest** method involves making a backup first: + +```shell +cp dnsconfig.js dnsconfig.js.BACKUP +dnscontrol fmt -i dnsconfig.js.BACKUP -o dnsconfig.js +``` + +The **riskiest** method depends on the fact that DNSControl currently processes +the `-o` file after the input file is completely read. It makes no backups. +This is useful if Git is your backup mechanism. + +```shell +git commit -m'backup dnsconfig.js' dnsconfig.js +dnscontrol fmt -o dnsconfig.js +git diff -- dnsconfig.js +``` diff --git a/documentation/globalflags.md b/documentation/globalflags.md new file mode 100644 index 0000000000..67831fa579 --- /dev/null +++ b/documentation/globalflags.md @@ -0,0 +1,42 @@ +# Global Flags + +These flags are global. They affect all subcommands. + +```text + --debug, -v Enable detailed logging (default: false) + --allow-fetch Enable JS fetch(), dangerous on untrusted code! (default: false) + --disableordering Disables update reordering (default: false) + --no-colors Disable colors (default: false) + --help, -h show help +``` + +They must appear before the subcommand. + +**Right** + +{% hint style="success" %} +```shell +dnscontrol --no-colors preview +``` +{% endhint %} + +**Wrong** + +{% hint style="danger" %} +```shell +dnscontrol preview --no-colors +``` +{% endhint %} + +* `-debug` + * Enable debug output. (The `-v` alias is the original name for this flag. That alias will go away eventually.) + + +* `--allow-fetch` + * Enable the `fetch()` function in `dnsconfig.js` (or equivalent). It is disabled by default because it can be used for nefarious purposes. It is dangerous on untrusted code! Enable it only if you trust all the people editing dnsconfig.js. + +* `--disableordering` + * Disables update reordering. Normally DNSControl re-orders the updates done by `push`. This is usually only used to work around bugs in the reordering code. + +* `--no-colors` + * Disable colors. See [Disabling Colors](colors.md) for details. diff --git a/documentation/preview-push.md b/documentation/preview-push.md index 2390f35318..84968a0fd4 100644 --- a/documentation/preview-push.md +++ b/documentation/preview-push.md @@ -30,71 +30,84 @@ OPTIONS: --help, -h show help ``` -`--config name` -- Specifies the name of the main configuration file, normally +* `--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 +* `--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. + +* `--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. + +## ppreview/ppush + +{% hint style="info" %} +Starting in v4.9 +{% endhint %} The `ppreview`/`ppush` subcommands are a preview of a future feature where zone -data is gathered concurrently. The commands will go away when +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. +* `--cmode value` + * Concurrency mode. Specifies what kind of providers should be run concurrently. + * `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.