Improve documentation

Author: Serhii Ponomarov

README.md

@@ -7,67 +7,72 @@ A lightweight SSH server frontend where authentication and connections
 are controlled with command handlers / shell scripts.
 
 ## Using sshfront
-```
-Usage: ./sshfront [options] <handler>
 
-  -a="": authentication hook. empty=allow all
-  -d=false: debug mode
-  -e=false: pass environment to handler
-  -h="0.0.0.0": ip to listen on
-  -k="~/.ssh/id_rsa": private host key path
-  -p="22": port to listen on
-```
+
+    Usage: ./sshfront [options] <handler>
+    
+      -a="": authentication hook. empty=allow all
+      -d=false: debug mode
+      -e=false: pass environment to handler
+      -h="0.0.0.0": ip to listen on
+      -k="~/.ssh/id_rsa": private host key path
+      -p="22": port to listen on
 
 
 #### handler $command...
 
- * `$command...` command line arguments specified to run by the SSH client
+`$command...` command line arguments specified to run by the SSH client
 
-The handler is a command that's used to handle all SSH connections. Output, stderr, and the exit code is returned to the client. If the client provides stdin, that's passed to the handler.
+The handler is a command that's used to handle all SSH connections.
+Output, stderr, and the exit code is returned to the client.
+If the client provides stdin, that's passed to the handler.
 
-If the authentication hook was specified, any output is parsed as environment variables and added to the handler environment. `$USER` is always the SSH user used to connect and `$SSH_ORIGINAL_COMMAND` is the command specified from the client if not interactive.
+If the authentication hook was specified, any output is parsed as environment variables and added to the handler environment.
+`$USER` is always the SSH user used to connect and `$SSH_ORIGINAL_COMMAND` is the command specified from the client if not interactive.
 
 #### auth-hook $user $key
 
  * `$user` argument is the name of the user being used to attempt the connection
  * `$key` argument is the public key data being provided for authentication
 
-The auth hook is a command used for authenticating incoming SSH connections. If it returns with exit status 0, the connection will be allowed, otherwise it will be denied. The output of auth hook must be empty, or key-value pairs in the form `KEY=value` separated by newlines, which will be added to the environment of connection handler.
+The auth hook is a command used for authenticating incoming SSH connections.
+If it returns with exit status 0, the connection will be allowed, otherwise it will be denied.
+The output of auth hook must be empty, or key-value pairs in the form `KEY=value` separated by newlines, which will be added to the environment of connection handler.
 
 The auth hook is optional, but if not specified then all connections are allowed.
 It is a good idea to always specify an auth hook.
 
+
+See example/authcheck auth hook that checks that the pub key is authorized. Usage:
+
+    sshfront -a example/authcheck
+
+
 ## Examples
 
 **Many of these bypass authentication and may allow remote execution, *do not* run this in production.**
 
 Echo server:
 
-```
-server$ sshfront $(which echo)
-client$ ssh $SERVER "hello world"
-hello world
-```
+    server$ sshfront $(which echo)
+    client$ ssh $SERVER "hello world"
+    hello world
 
 Echo host's environment to clients:
 
-```
-server$ sshfront -e $(env)
-client$ ssh $SERVER
-USER=root
-HOME=/root
-LANG=en_US.UTF-8
-...
-```
+    server$ sshfront -e $(env)
+    client$ ssh $SERVER
+    USER=root
+    HOME=/root
+    LANG=en_US.UTF-8
+    ...
 
 Bash server:
 
-```
-server$ sshfront $(which bash)
-client$ ssh $SERVER
-bash-4.3$ echo "this is a bash instance running on the server"
-this is a bash instance running on the server
-```
+    server$ sshfront $(which bash)
+    client$ ssh $SERVER
+    bash-4.3$ echo "this is a bash instance running on the server"
+    this is a bash instance running on the server
 
 
 ## Sponsors

example/authcheck

@@ -1,2 +1,3 @@
 #!/bin/bash
+# check that the user's pubkey is authorized
 grep "$2" "/home/$1/.ssh/authorized_keys" > /dev/null 2>&1

example/helloworld

@@ -1,6 +1,8 @@
 #!/bin/bash
-echo "Hello world: $@"
+echo "Execute command: $@"
+echo "Env vars:"
 env
+# if FD = 1 then this is an interactive shell
 if [[ -t 1 ]]; then
   exec bash
 fi

internal/handlers.go

@@ -67,8 +67,8 @@ func HandleAuth(conn ssh.ConnMetadata, key ssh.PublicKey) (*ssh.Permissions, err
 		}, nil
 	}
 
-	keydata := string(bytes.TrimSpace(ssh.MarshalAuthorizedKey(key)))
-	cmd, err := handlerCmd(*AuthHook, conn.User(), keydata)
+	pubKey := string(bytes.TrimSpace(ssh.MarshalAuthorizedKey(key)))
+	cmd, err := handlerCmd(*AuthHook, conn.User(), pubKey)
 	if err != nil {
 		return nil, err
 	}
@@ -192,6 +192,8 @@ func (h *sshHandler) handleEnv(req *ssh.Request) {
 	req.Reply(true, nil)
 }
 
+// handleExec when executed a command e.g.
+// ssh user@localhost -p 2222 'echo Hello'
 func (h *sshHandler) handleExec(req *ssh.Request) {
 	h.Lock()
 	defer h.Unlock()
@@ -234,6 +236,8 @@ func (h *sshHandler) handleExec(req *ssh.Request) {
 	h.Exit(cmd.Run())
 }
 
+// handlePty when executed a command e.g.
+// ssh user@localhost -p 2222
 func (h *sshHandler) handlePty(req *ssh.Request) {
 	h.Lock()
 	defer h.Unlock()
@@ -246,7 +250,8 @@ func (h *sshHandler) handlePty(req *ssh.Request) {
 
 	width, height, okSize := parsePtyRequest(req.Payload)
 
-	cmd, err := handlerCmd(flag.Arg(0))
+	scriptName := flag.Arg(0)
+	cmd, err := handlerCmd(scriptName)
 	if err != nil {
 		Debug("failed handler init:", err)
 		h.channel.Close()