diff --git a/README.md b/README.md index 8adaf10c0..14ff591d8 100644 --- a/README.md +++ b/README.md @@ -182,9 +182,10 @@ See [dnscontrol-action](https://github.com/koenrh/dnscontrol-action) # Depreciation warnings (updated 2022-03-07) -* Let's Encrypt support is frozen and will be removed in early 2023. The "get-certs" command (renews certs via Let's Encrypt) has no maintainer. There are other projects that do a better job. If you don't use this feature, please do not start. If you do use this feature, please plan on migrating to something else. See discussion in https://github.com/StackExchange/dnscontrol/issues/1400 -* Call for new volunteer maintainers for CLOUDFLARE_API, GCLOUD, NAMEDOTCOM, ROUTE53, and SOFTLAYER. -* Provider ACTIVEDIRECTORY_PS is deprecated and will be removed soon. Use MSDNS instead. +* **ACME/Let's Encrypt support is frozen and will be removed after December 31, 2022.** The `get-certs` command (renews certs via Let's Encrypt) has no maintainer. There are other projects that do a better job. If you don't use this feature, please do not start. If you do use this feature, please plan on migrating to something else. See discussion in https://github.com/StackExchange/dnscontrol/issues/1400 +* **convertzone is frozen and will be removed after June 30, 2022.** The `convertzone` stand-alone program is replaced by the `get-zone` subcommand of DNSControl. It does everything `convertzone` did and more. +* **Provider ACTIVEDIRECTORY_PS is frozen and will be removed after June 30, 2022.** It is replaced by MSDNS which is 100% feature compatible and works better. (We believe nobody uses it.) +* **Call for new volunteer maintainers for CLOUDFLARE_API, GCLOUD, NAMEDOTCOM, ROUTE53, and SOFTLAYER.** These providers have no maintainer. Maintainers respond to PRs and fix bugs in a timely manner, and try to stay on top of protocol changes. # More info at our web site diff --git a/commands/commands.go b/commands/commands.go index 5edff829b..5253f3c7d 100644 --- a/commands/commands.go +++ b/commands/commands.go @@ -229,7 +229,7 @@ func (args *GetCredentialsArgs) flags() []cli.Flag { &cli.StringFlag{ Name: "creds", Destination: &args.CredsFile, - Usage: "Provider credentials JSON file", + Usage: "Provider credentials JSON file (or !program to execute program that outputs json)", Value: "creds.json", }, } diff --git a/commands/getZones.go b/commands/getZones.go index 9a8897457..4f3e98a1b 100644 --- a/commands/getZones.go +++ b/commands/getZones.go @@ -140,11 +140,11 @@ func GetZone(args GetZoneArgs) error { // Read it in: providerConfigs, err = config.LoadProviderConfigs(args.CredsFile) if err != nil { - return fmt.Errorf("failed GetZone lpc(%q): %w", args.CredsFile, err) + return fmt.Errorf("failed GetZone LoadProviderConfigs(%q): %w", args.CredsFile, err) } provider, err := providers.CreateDNSProvider(args.ProviderName, providerConfigs[args.CredName], nil) if err != nil { - return fmt.Errorf("failed GetZone cdp: %w", err) + return fmt.Errorf("failed GetZone CreateDNSProvider: %w", err) } // decide which zones we need to convert diff --git a/docs/creds-json.md b/docs/creds-json.md new file mode 100644 index 000000000..bcff1e406 --- /dev/null +++ b/docs/creds-json.md @@ -0,0 +1,67 @@ +--- +layout: default +title: creds.json file format +--- + +# creds.json + +When dnscontrol interacts with a provider, any API keys, credentials, or other +configuration parameters required are stored in `creds.json`. The file contains a set of key/value pairs for each configuration. That is, since a provider can be used multiple times with different credentials, the file contains a section for each set of credentials. + +Here's a sample file: + +```json +{ + "cloudflare_tal": { + "apikey": "REDACTED", + "apiuser": "REDACTED" + }, + "inside": { + "directory": "inzones", + "filenameformat": "db_%T%?_%D" + }, + "hexonet": { + "apilogin": "$HEXONET_APILOGIN", + "apipassword": "$HEXONET_APIPASSWORD", + "debugmode": "$HEXONET_DEBUGMODE", + "domain": "$HEXONET_DOMAIN" + } +} +``` + +# Format + +* Primary keys: (e.g. `cloudflare_tal`, `inside`, `hexonet`) + * ...refer to the first parameter in the `NewRegistrar()` or `NewDnsProvider()` functions in a dnsconfig.js file. + * ...may include any printable character except colon (`:`) + * Convention: all lower case, usually the name of the provider or the username at the provider or both. +* Subkeys: (e.g. `apikey`, `apiuser` and etc.) + * ...are whatever the provider specifies. + * ...can be credentials, secrets, or configuration settings. In the above examples the `inside` setting is configuration parameters for the BIND provider, not credentials. + * A missing subkey is not an error. The value is the empty string. +* Values: + * ...may include any JSON string value including the empty string. + * If a subkey starts with `$`, it is taken as an env variable. In the above example, `$HEXONET_APILOGIN` would be replaced by the value of the environment variable `HEXONET_APILOGIN` or the empty string if no such environment variable exists. + +# Using a different name + +The `--creds` flag allows you to specify a different file name. + +* Normally the file is read as a JSON file. +* Do not end the filename with `.yaml` or `.yml` as some day we hope to support YAML. +* Rather than specifying a file, you can specify a program to be run. The output of the program must be valid JSON and will be read the same way. + * If the name begins with `!`, the remainder of the name is taken to be the command to be run. + * If the name is a file that is executable (chmod `+x` bit), it is taken as the command to be run. + * Exceptions: The `x` bit is not checked if the filename ends with `.yaml`, `.yml` or `.json`. + * Windows: Executing an external script isn't supported. There's no code that prevents it from trying, but it isn't supported. + +# Don't store secrets 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. + +Instead, 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/docs/get-certs.md b/docs/get-certs.md index cd9646817..94eb64d47 100644 --- a/docs/get-certs.md +++ b/docs/get-certs.md @@ -5,6 +5,10 @@ title: Let's Encrypt Certificate generation # *Let's Encrypt* Certificate generation +**WARNING: This feature +is frozen and will be removed in early 2023. The "get-certs" command (renews certs via Let's Encrypt) has no maintainer. There are other projects that do a better job. If you don't use this feature, please do not start. If you do use this feature, please plan on migrating to something else. See discussion in [#1400](https://github.com/StackExchange/dnscontrol/issues/1400)** + + DNSControl will generate/renew Let's Encrypt certificates using DNS validation. It is not a complete certificate management system, but can perform the renewal steps for the system you create. If you diff --git a/docs/index.md b/docs/index.md index eba1aa4a1..b8ce439e4 100644 --- a/docs/index.md +++ b/docs/index.md @@ -94,6 +94,42 @@ title: DNSControl Migrating: Migrating zones to DNSControl + +

+ Commands +

+

+ DNSControl sub-commands and options. +

+ + +

@@ -116,9 +152,6 @@ title: DNSControl
  • CAA Builder: Build CAA records the easy way
    • -
  • - Let's Encrypt: Renew your SSL/TLS certs -

    • @@ -130,13 +163,13 @@ title: DNSControl