From a7e0ec258d200e91cc42b7e82befd0622ca85039 Mon Sep 17 00:00:00 2001
From: Tom Limoncelli <tlimoncelli@stackexchange.com>
Date: Sat, 29 Feb 2020 09:07:05 -0500
Subject: [PATCH] Add check-creds subcommand (#665)

---
 commands/getZones.go      | 36 ++++++++++++++++++++++++++++++++++++
 docs/_providers/gcloud.md | 11 +++++++++++
 docs/check-creds.md       | 37 +++++++++++++++++++++++++++++++++++++
 docs/get-zones.md         |  7 ++++++-
 4 files changed, 90 insertions(+), 1 deletion(-)
 create mode 100644 docs/check-creds.md

diff --git a/commands/getZones.go b/commands/getZones.go
index 0772eb2d8..e8b497c3b 100644
--- a/commands/getZones.go
+++ b/commands/getZones.go
@@ -52,6 +52,42 @@ EXAMPLES:
 	}
 }())
 
+// check-creds foo bar
+// is the same as
+// get-zones --format=nameonly foo bar all
+var _ = cmd(catUtils, func() *cli.Command {
+	var args GetZoneArgs
+	return &cli.Command{
+		Name:  "check-creds",
+		Usage: "Do a small operation to verify credentials (stand-alone)",
+		Action: func(ctx *cli.Context) error {
+			if ctx.NArg() != 2 {
+				return cli.NewExitError("Arguments should be: credskey providername (Ex: r53 ROUTE53)", 1)
+
+			}
+			args.CredName = ctx.Args().Get(0)
+			args.ProviderName = ctx.Args().Get(1)
+			args.ZoneNames = []string{"all"}
+			args.OutputFormat = "nameonly"
+			return exit(GetZone(args))
+		},
+		Flags:     args.flags(),
+		UsageText: "dnscontrol check-creds [command options] credkey provider",
+		Description: `Do a trivia operation to verify credentials.  This is a stand-alone utility.
+
+If successful, a list of zones will be output. If not, hopefully you
+see verbose error messages.
+
+ARGUMENTS:
+   credkey:  The name used in creds.json (first parameter to NewDnsProvider() in dnsconfig.js)
+   provider: The name of the provider (second parameter to NewDnsProvider() in dnsconfig.js)
+
+EXAMPLES:
+   dnscontrol get-zones myr53 ROUTE53 
+   dnscontrol get-zones --out=/dev/null myr53 ROUTE53`,
+	}
+}())
+
 // GetZoneArgs args required for the create-domain subcommand.
 type GetZoneArgs struct {
 	GetCredentialsArgs          // Args related to creds.json
diff --git a/docs/_providers/gcloud.md b/docs/_providers/gcloud.md
index 280bf049d..d0ba842f0 100644
--- a/docs/_providers/gcloud.md
+++ b/docs/_providers/gcloud.md
@@ -69,3 +69,14 @@ currently no facility for creating a name server set.  You need special permissi
 will enable it on your account, responding with a list of names to use in the `name_server_set` field above.
 
 > `name_server_set` only applies on `create-domains` at the moment. Additional work needs to be done to support it during `push`
+
+# Debugging credentials
+
+You can test your `creds.json` entry with the command: `dnscontrol check-creds foo GCLOUD` where `foo` is the name of key used in `creds.json`.  Error messages you might see:
+
+* `googleapi: Error 403: Permission denied on resource project REDACTED., forbidden`
+  * Hint: `project_id` may be invalid.
+* `private key should be a PEM or plain PKCS1 or PKCS8; parse error:`
+  * Hint: `private_key` may be invalid.
+* `Response: {"error":"invalid_grant","error_description":"Invalid grant: account not found"}`
+  * Hint: `client_email` may be invalid.
diff --git a/docs/check-creds.md b/docs/check-creds.md
new file mode 100644
index 000000000..e5eca5b56
--- /dev/null
+++ b/docs/check-creds.md
@@ -0,0 +1,37 @@
+---
+layout: default
+title: Check-Creds subcommand
+---
+
+# check-creds
+
+This is a stand-alone utility to help verify entries in `creds.json`.
+
+The command does a trivia operation to verify credentials.  If
+successful, a list of zones will be output. If not, hopefully you see
+verbose error messages.
+
+Syntax:
+
+   dnscontrol check-creds [command options] credkey provider
+
+   --creds value   Provider credentials JSON file (default: "creds.json")
+   --out value     Instead of stdout, write to this file
+
+ARGUMENTS:
+   credkey:  The name used in creds.json (first parameter to NewDnsProvider() in dnsconfig.js)
+   provider: The name of the provider (second parameter to NewDnsProvider() in dnsconfig.js)
+
+EXAMPLES:
+   dnscontrol get-zones myr53 ROUTE53
+   dnscontrol get-zones --out=/dev/null myr53 ROUTE53
+
+# Example commands
+
+dnscontrol get-zone
+
+# Developer Note
+
+This command is not implemented for all providers.
+
+To add this to a provider, implement the get-zones subcommand
diff --git a/docs/get-zones.md b/docs/get-zones.md
index 5ac0ee1bf..a18770afc 100644
--- a/docs/get-zones.md
+++ b/docs/get-zones.md
@@ -78,7 +78,7 @@ go generate
 
 Find the `GetZoneRecords` function in the `*Provider.go` file.
 
-If currently returns `fmt.Errorf("not implemented")`.
+It currently returns `fmt.Errorf("not implemented")`.
 
 Instead, it should gather the records from the provider
 and return them as a list of RecordConfig structs.
@@ -99,3 +99,8 @@ will query the provider for the list of zones.
 (Technically what is happening is by implementing the `ListZones`
 function, you are completing the `ZoneLister` interface for that
 provider.)
+
+Implementing the `ListZones` function also activates the `check-creds`
+subcommand for that provider. Please add to the provider documentation
+a list of error messages that people might see if the credentials are
+invalid.  See `docs/_providers/gcloud.md` for examples.