Merge pull request #66 from keybase/david/update-docs-per-schlos

Update docs per feedback on Github issues

Author: ddworken

docker/Makefile

@@ -30,6 +30,13 @@ serve: env-file-exists ca-key-exists build
 	docker run -d --restart unless-stopped -v $(CURDIR)/example-keybaseca-volume:/mnt:rw ca:latest docker/entrypoint-server.sh
 	@echo "Started CA bot service in the background... Use `docker ps` and `docker logs` to monitor it"
 
+# Stop the service
+stop:
+	docker kill `docker ps -q --filter ancestor=ca`
+
+# Restart the service (useful if you updated env.sh)
+restart: stop serve
+
 # Wipe all data
 clean: confirm-clean reset-permissions
 	@# Sudo since it is likely owned by another use since it was written from a docker container

docs/getting_started.md

@@ -65,3 +65,10 @@ kssh root@server                        # If in {TEAM}.ssh.root_everywhere
 ```
 
 We recommend building kssh yourself and distributing the binary among your team (perhaps in Keybase Files!). 
+
+## Updating environment variables
+
+If you update any environment variables, it is necessary to restart the keybaseca service. This can be done 
+by running `make restart`. Note that it is not required to re-run `make generate`. 
+
+Note that this means `kssh` will not work for a brief period of time while the container restarts. 

docs/troubleshooting.md

@@ -3,6 +3,15 @@
 This file contains some general directions and thoughts on troubleshooting the code in this repo. This is not meant
 to be a comprehensive troubleshooting guide and is only a jumping off point. 
 
+## `make generate` refuses to overwrite an existing key
+
+In order to force `make generate` to overwrite the existing CA key (note that this will delete the existing CA
+key which means kssh will not work with any servers it currently works with), simply run:
+
+```
+FORCE_WRITE=true make generate
+```
+
 ## kssh is slow, but it works
 
 When kssh starts, it has to search every team you are in for a `kssh-client.config` file which specifies the information
@@ -31,8 +40,19 @@ user than you are using for kssh.
 
 ## SSH rejects the connection
 
-This likely means that you have not configured the SSH server correctly. Review the directions in README.md and ensure
-that you have followed the steps correctly ([sshca.md](./sshca.md) also has some additional information on how SSH CAs work that may
+This likely means that you have not configured the SSH server correctly. Confirm that on the SSH server you are trying to access:
+
+* `/etc/ssh/ca.pub` has an SSH public key in it
+* `/etc/ssh/auth_principals/username-of-ssh-user` has the name of your Keybase team in it (or multiple comma separated keybase teams)
+* `/etc/ssh/sshd_config` has the below two lines somewhere in it:
+
+```
+TrustedUserCAKeys /etc/ssh/ca.pub
+AuthorizedPrincipalsFile /etc/ssh/auth_principals/%u
+```
+
+If that all looks good, review the getting started directions and ensure that you have followed the steps correctly 
+([sshca.md](./sshca.md) also has some additional information on how SSH CAs work that may
 be helpful). If you would like to follow an example, see the code in the `tests/` directory which contains integration 
 tests (focus on Dockerfile-sshd for an example SSH server setup). If none of that works, the best strategy is to run
 SSH on the server on an alternate port and review the debug information. On the server run `/usr/sbin/sshd -dd -D -p 2222`
@@ -101,3 +121,8 @@ It may be useful to define aliases in your bashrc to simplify this:
 alias kscp='kssh --provision && scp -F ~/.ssh/kssh-config'
 alias krsync='kssh --provision && rsync -e "ssh -F $HOME/.ssh/kssh-config"'
 ```
+
+## Other
+
+For any other issues, please open a Github issue or ping @dworken on Keybase! We want to make this project as reliable
+as possible so please let us know if there are any ways we can improve the project. 

src/cmd/keybaseca/keybaseca.go

@@ -58,13 +58,8 @@ func main() {
 			Before: beforeAction,
 		},
 		{
-			Name:  "generate",
-			Usage: "Generate a new CA key",
-			Flags: []cli.Flag{
-				cli.BoolFlag{
-					Name: "overwrite-existing-key",
-				},
-			},
+			Name:   "generate",
+			Usage:  "Generate a new CA key",
 			Action: generateAction,
 			Before: beforeAction,
 		},
@@ -134,7 +129,7 @@ func generateAction(c *cli.Context) error {
 		return err
 	}
 	captureControlCToDeleteClientConfig(conf)
-	err = sshutils.Generate(conf, c.Bool("overwrite-existing-key") || os.Getenv("FORCE_WRITE") == "true")
+	err = sshutils.Generate(conf, strings.ToLower(os.Getenv("FORCE_WRITE")) == "true")
 	if err != nil {
 		return fmt.Errorf("Failed to generate a new key: %v", err)
 	}

src/keybaseca/sshutils/generate_test.go

@@ -19,7 +19,7 @@ func TestGenerateNewSSHKey(t *testing.T) {
 	require.NoError(t, err)
 
 	err = GenerateNewSSHKey(filename, false, false)
-	require.Errorf(t, err, "Refusing to overwrite existing key (try with --overwrite-existing-key or FORCE_WRITE=true if you're sure): "+filename)
+	require.Errorf(t, err, "Refusing to overwrite existing key (try with FORCE_WRITE=true if you're sure): "+filename)
 
 	err = GenerateNewSSHKey(filename, true, false)
 	require.NoError(t, err)

src/keybaseca/sshutils/sshutils.go

@@ -28,7 +28,7 @@ func GenerateNewSSHKey(filename string, overwrite bool, printPubKey bool) error
 				return err
 			}
 		} else {
-			return fmt.Errorf("Refusing to overwrite existing key (try with --overwrite-existing-key or FORCE_WRITE=true if you're sure): %s", filename)
+			return fmt.Errorf("Refusing to overwrite existing key (try with FORCE_WRITE=true if you're sure): %s", filename)
 		}
 	}
 

tests/bot-entrypoint.py

@@ -23,7 +23,7 @@ def load_env():
         ". %s\n"
         "bin/keybaseca --wipe-all-configs\n"
         "bin/keybaseca --wipe-logs || true\n"
-        "bin/keybaseca generate --overwrite-existing-key\n"
+        "FORCE_WRITE=true bin/keybaseca generate\n"
         # The output from this backup is tested in test_env_1.py
         "echo yes | bin/keybaseca backup > /shared/cakey.backup\n"
         # The output from this sign operation is tested in test_env_1.py