From a9bd539175928646d12d01c5cd9c1f12db36c99f Mon Sep 17 00:00:00 2001
From: Erik Brakkee <erik@brakkee.org>
Date: Thu, 1 Aug 2024 20:53:52 +0200
Subject: [PATCH] Updated documentation: * remote shell usage for linux, cmd,
 and powershell * help of wsproxy.

---
 cmd/wsproxy/wsproxy.go           |  7 ++--
 pkg/agent/session/help.txt       |  3 ++
 pkg/server/templates/usage.templ | 58 +++++++++++++++++++++++++++++---
 3 files changed, 61 insertions(+), 7 deletions(-)

diff --git a/cmd/wsproxy/wsproxy.go b/cmd/wsproxy/wsproxy.go
index c38d894..143914d 100644
--- a/cmd/wsproxy/wsproxy.go
+++ b/cmd/wsproxy/wsproxy.go
@@ -51,13 +51,14 @@ func printHelp(msg string) {
 		"\n" +
 		"  ssh -oServerAliveInterval=10 -oProxyCommand='wsproxy ws[s]://<host>[:port]/client/<ID>' abc@localhost\n" +
 		"\n" +
-		"This latssh connect through wsproxy tocalhost\n" +
+		"The above ssh commmand connects to the converge server listening on the websocket through \n" +
+		"wsproxy. \n" +
 		"\n" +
 		"Options:\n" +
 		"\n" +
 		"--insecure:     Skip certificate validation when used over a secure connection.\n" +
-		"--raw:          Just use wsproxy as a raw stdio to websocket proxy, this disable messages\n" +
-		"                from the server.\n"
+		"--raw:          Just use wsproxy as a raw stdio to websocket proxy, this disables messages\n" +
+		"                from the server so the user will not get clear error messages.\n"
 	fmt.Fprintln(os.Stderr, usage)
 	os.Exit(1)
 }
diff --git a/pkg/agent/session/help.txt b/pkg/agent/session/help.txt
index 6b3b99c..d970786 100644
--- a/pkg/agent/session/help.txt
+++ b/pkg/agent/session/help.txt
@@ -2,7 +2,10 @@
 You can extend expiry of the session using
 
   {{ if eq .os "windows" -}}
+  # cmd
   echo > %agentdir%\.hold
+  # powershell
+  $null > $env:agentdir\.hold
   {{- else -}}
   touch $agentdir/.hold
   {{- end }}
diff --git a/pkg/server/templates/usage.templ b/pkg/server/templates/usage.templ
index ce3616f..bf7a704 100644
--- a/pkg/server/templates/usage.templ
+++ b/pkg/server/templates/usage.templ
@@ -48,7 +48,8 @@ templ Usage(secure string, host string, username string) {
                       </p>
 
                       <p>
-                          The agent has more options, download the agent and run it without arguments to
+                          The agent has more command-line options than shown here.
+                          Download the agent and run it without arguments to
                           see all options.
                       </p>
 
@@ -94,12 +95,61 @@ templ Usage(secure string, host string, username string) {
           `}sftp -oServerAliveInterval=10 -oPort=10000 { username }{"@localhost"}     {`
           `}</pre>
 
+                      <h2>Remote shell usage</h2>
+
+                      <p>
+                      The agent supports a --shells command-line option by which a comma-separated
+                      list of shells can be prepended to the default search path for shells, e.g.
+                      <code>--shells zsh,csh,sh</code> (linux) or <code>cmd,powershell</code> for
+                      windows.
+                      </p>
+
+                      <p>
+                      The agent sets a <coder>agentdir</coder> environment variable that points to
+                      the directory where the agent is running.
+                      </p>
+
+                      <h3>Linux</h3>
+
+                      <pre>{`
+            # cd back to the agent directory
+            cd $agentdir
+
+            # extend session lifetime
+            touch $agentdir/.hold
+                      `}</pre>
+
+                      <pre>
+                      </pre>
+
+                      <h3>Windows Command Prompt</h3>
+
+                      <pre>{`
+            # cd back to the agent directory
+            cd %agentdir%
+
+            # extend session lifetime
+            echo > %agentdir%\.hold
+                     `}</pre>
+
+                      <h3>Windows Powershell</h3>
+
+                      <pre>{`
+            # cd back to the agent directory
+            cd $env:agentdir
+
+            # extend session lifetime
+            $null > $env:agentdir\.hold
+                     `}</pre>
+
                       <h2>Authentication</h2>
 
                       <p>
-                          The <code>{ username }</code> user above the Converge server and
-                          communicated to the agent when the agent is started. This is the
-                          username that must be used when setting up an ssh connection.
+                          The <code>{ username }</code> user above is configured in the
+                          Converge server and is communicated to the agent when the agent is
+                          started as well as the password.
+                      </p>
+                      <p>
                           Another way to authenticate is through an .authorized_keys file in the
                           same directory as where the agent is started.