mirror/stackexchange-dnscontrol
1
0
Fork 0
mirror of https://github.com/StackExchange/dnscontrol.git synced 2024-05-11 05:55:12 +00:00
Code Issues Releases Activity

DOCS: Add missing docs for fmt, global flags, preview-push (#2886)

Browse Source 
Co-authored-by: Jeffrey Cafferata <jeffrey@jcid.nl>
This commit is contained in:
Tom Limoncelli
2024-04-01 20:44:26 -04:00
committed by GitHub
parent 5e211fcade
commit 293d5cb547
5 changed files with 167 additions and 60 deletions
Download Patch File Download Diff File Expand all files Collapse all files

15
documentation/creds-json.md
View File

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

50
documentation/fmt.md Normal file
View File

@ -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
```

42
documentation/globalflags.md Normal file
View File

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

115
documentation/preview-push.md
View File

@ -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.
* `--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.
`--v foo=bar` -- Sets the variable `foo` to the value `bar` prior to
interpreting the configuration file. Multiple `-v` options can be used.
* `--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`.
`--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.
* `--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.
`--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`.
* `--v foo=bar`
* Sets the variable `foo` to the value `bar` prior to
interpreting the configuration file. Multiple `-v` options can be used.
`--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`.
`--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.
* `--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.
* `--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.
* `--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.
* `--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.
* `--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
## 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.