Split up the main page into different parts.
This commit is contained in:
parent
f7e94c21f9
commit
a4d5060163
45
cmd/templaterender/render.go
Normal file
45
cmd/templaterender/render.go
Normal file
@ -0,0 +1,45 @@
|
|||||||
|
package main
|
||||||
|
|
||||||
|
import (
|
||||||
|
"context"
|
||||||
|
"converge/pkg/templates"
|
||||||
|
"github.com/a-h/templ"
|
||||||
|
"os"
|
||||||
|
"path/filepath"
|
||||||
|
)
|
||||||
|
|
||||||
|
type RenderFunc func(secure string, host string, username string) templ.Component
|
||||||
|
|
||||||
|
type Params struct {
|
||||||
|
secure string
|
||||||
|
host string
|
||||||
|
username string
|
||||||
|
}
|
||||||
|
|
||||||
|
type Rendering struct {
|
||||||
|
params Params
|
||||||
|
render RenderFunc
|
||||||
|
}
|
||||||
|
|
||||||
|
func render(dir string, name string, params Params, render RenderFunc) {
|
||||||
|
fname := filepath.Join(dir, name)
|
||||||
|
f, err := os.Create(fname)
|
||||||
|
if err != nil {
|
||||||
|
panic(err)
|
||||||
|
}
|
||||||
|
defer f.Close()
|
||||||
|
|
||||||
|
render(params.secure, params.host, params.username).Render(context.Background(), f)
|
||||||
|
}
|
||||||
|
|
||||||
|
func main() {
|
||||||
|
dir := "html"
|
||||||
|
|
||||||
|
params := Params{
|
||||||
|
secure: "s",
|
||||||
|
host: "example.com",
|
||||||
|
username: "converge",
|
||||||
|
}
|
||||||
|
|
||||||
|
render(dir, "index.html", params, templates.Index)
|
||||||
|
}
|
||||||
44
pkg/templates/about.templ
Normal file
44
pkg/templates/about.templ
Normal file
@ -0,0 +1,44 @@
|
|||||||
|
package templates
|
||||||
|
|
||||||
|
templ About() {
|
||||||
|
<div>
|
||||||
|
<h1>About</h1>
|
||||||
|
<p>
|
||||||
|
Converge is a utility for troubleshooting builds on continuous integration servers.
|
||||||
|
It solves a common problem where the cause of job failure is difficult to determine.
|
||||||
|
This is complicated further by the fact that build jobs are usually run on a build
|
||||||
|
farm where there is no access to the build agents or in more modern envrionments when
|
||||||
|
jobs are run in ephemeral containers.
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<p>
|
||||||
|
With Converge it is possible to get remote shell access to such jobs. This works
|
||||||
|
by configuring the build job to connect to a Converge server using an agent program.
|
||||||
|
The agent program can be downloaded from within the CI job using curl or wget.
|
||||||
|
Next, an end-user can connect to the Converge server, a rendez-vous server, that connects
|
||||||
|
the client and server together.
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<p>
|
||||||
|
The setup is such that the connection from client (end-user) to server (agent on CI job)
|
||||||
|
is end-to-end encrypted. The Converge server itself is no more than a bitpipe which pumps
|
||||||
|
data between client and agent.
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<p>
|
||||||
|
Both ssh and sftp are supported. Multiple shells are also allowed.
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<p>
|
||||||
|
There is a timeout mechanism in the agent such that jobs do not hang indefinitely
|
||||||
|
waiting for a connection. This mechanism is useful to make sure build agents do not keep
|
||||||
|
build agents occupied for a long time. By default, the agent exits with status 0 when
|
||||||
|
the first client exits after logging in. This behavior as well as general expiry can be
|
||||||
|
controlled from within a shell session by touching a .hold file. After logging in, the
|
||||||
|
user can control expiry of the session as instructed by messages in the ssh session.
|
||||||
|
When the timeout of a session is near the user is informed about this with messages
|
||||||
|
in the shell.
|
||||||
|
</p>
|
||||||
|
</div>
|
||||||
|
}
|
||||||
|
|
||||||
39
pkg/templates/downloads.templ
Normal file
39
pkg/templates/downloads.templ
Normal file
@ -0,0 +1,39 @@
|
|||||||
|
package templates
|
||||||
|
|
||||||
|
|
||||||
|
templ Downloads() {
|
||||||
|
<div>
|
||||||
|
|
||||||
|
<h1 id="downloads">Downloads</h1>
|
||||||
|
|
||||||
|
<table class="table">
|
||||||
|
<thead>
|
||||||
|
<tr>
|
||||||
|
<th>Component</th>
|
||||||
|
<th>Purpose</th>
|
||||||
|
<th>Linux</th>
|
||||||
|
<th>Windows</th>
|
||||||
|
</tr>
|
||||||
|
</thead>
|
||||||
|
<tr>
|
||||||
|
<td>agent</td>
|
||||||
|
<td>The agent to run inside aa CI job</td>
|
||||||
|
<td><a href="docs/agent">agent</a></td>
|
||||||
|
<td><a href="docs/agent.exe">agent.exe</a></td>
|
||||||
|
</tr>
|
||||||
|
<tr>
|
||||||
|
<td>wsproxy</td>
|
||||||
|
<td>SSH proxy command that can be directly used by ssh</td>
|
||||||
|
<td><a href="docs/wsproxy">wsproxy</a></td>
|
||||||
|
<td><a href="docs/wsproxy.exe">wsproxy.exe</a></td>
|
||||||
|
</tr>
|
||||||
|
<tr>
|
||||||
|
<td>tcptows</td>
|
||||||
|
<td>TCP to WS tunnel for allowing regular
|
||||||
|
SSH and SFTP clients to connect to converge</td>
|
||||||
|
<td><a href="docs/tcptows">tcptows</a></td>
|
||||||
|
<td><a href="docs/tcptows.exe">tcptows.exe</a></td>
|
||||||
|
</tr>
|
||||||
|
</table>
|
||||||
|
</div>
|
||||||
|
}
|
||||||
@ -18,194 +18,10 @@ templ Index(secure string, host string, username string) {
|
|||||||
<div class="container-fluid">
|
<div class="container-fluid">
|
||||||
<div class="row">
|
<div class="row">
|
||||||
<div class="col">
|
<div class="col">
|
||||||
|
|
||||||
<div class="container">
|
<div class="container">
|
||||||
|
@About()
|
||||||
<h1>About</h1>
|
@Usage(secure, host, username)
|
||||||
|
@Downloads()
|
||||||
<p>
|
|
||||||
Converge is a utility for troubleshooting builds on continuous integration servers.
|
|
||||||
It solves a common problem where the cause of job failure is difficult to determine.
|
|
||||||
This is complicated further by the fact that build jobs are usually run on a build
|
|
||||||
farm where there is no access to the build agents or in more modern envrionments when
|
|
||||||
jobs are run in ephemeral containers.
|
|
||||||
</p>
|
|
||||||
|
|
||||||
<p>
|
|
||||||
With Converge it is possible to get remote shell access to such jobs. This works
|
|
||||||
by configuring the build job to connect to a Converge server using an agent program.
|
|
||||||
The agent program can be downloaded from within the CI job using curl or wget.
|
|
||||||
Next, an end-user can connect to the Converge server, a rendez-vous server, that connects
|
|
||||||
the client and server together.
|
|
||||||
</p>
|
|
||||||
|
|
||||||
<p>
|
|
||||||
The setup is such that the connection from client (end-user) to server (agent on CI job)
|
|
||||||
is end-to-end encrypted. The Converge server itself is no more than a bitpipe which pumps
|
|
||||||
data between client and agent.
|
|
||||||
</p>
|
|
||||||
|
|
||||||
<p>
|
|
||||||
Both ssh and sftp are supported. Multiple shells are also allowed.
|
|
||||||
</p>
|
|
||||||
|
|
||||||
<p>
|
|
||||||
There is a timeout mechanism in the agent such that jobs do not hang indefinitely
|
|
||||||
waiting for a connection. This mechanism is useful to make sure build agents do not keep
|
|
||||||
build agents occupied for a long time. By default, the agent exits with status 0 when
|
|
||||||
the first client exits after logging in. This behavior as well as general expiry can be
|
|
||||||
controlled from within a shell session by touching a .hold file. After logging in, the
|
|
||||||
user can control expiry of the session as instructed by messages in the ssh session.
|
|
||||||
When the timeout of a session is near the user is informed about this with messages
|
|
||||||
in the shell.
|
|
||||||
</p>
|
|
||||||
|
|
||||||
<h1>Usage</h1>
|
|
||||||
|
|
||||||
<h2>Continuous integration jobs</h2>
|
|
||||||
|
|
||||||
<p>
|
|
||||||
In a
|
|
||||||
continuous integration job, download the agent, chmod it and run it.
|
|
||||||
</p>
|
|
||||||
<pre>{`
|
|
||||||
# linux
|
|
||||||
`}curl http{secure}://{host}/docs/agent > agent{`
|
|
||||||
chmod 755 agent
|
|
||||||
`}./agent --id ID ws{secure}://{host}{`
|
|
||||||
|
|
||||||
# windows
|
|
||||||
`}curl http{secure}://{host}/docs/agent.exe > agent.exe{`
|
|
||||||
`}agent --id ID ws{secure}://{host}{`
|
|
||||||
`}</pre>
|
|
||||||
<p>
|
|
||||||
Above, ID is a unique id for the job, the so-called rendez-cous ID. This should not conflict with IDs
|
|
||||||
used by other agents. The ID is used for a rendez-vous between the end-user on a local system and
|
|
||||||
the continuous integration job running on a build agent. If you don't specify an id, a random
|
|
||||||
id will be generated.
|
|
||||||
|
|
||||||
The agent to the converge server and tells it the ID. Clients can now connect to the Converge
|
|
||||||
server to establish a connection to the CI job through converge by also specifying the same
|
|
||||||
ID.
|
|
||||||
|
|
||||||
Communication between
|
|
||||||
end-user and agent is encrypted using SSH and the rendez-vous server is unable to
|
|
||||||
read the contents. The rendez-vous server is nothing more then a glorified bit pipe,
|
|
||||||
simply transferring data between end-user SSH client and the agent which runs an
|
|
||||||
embedded SSH server.
|
|
||||||
</p>
|
|
||||||
|
|
||||||
<p>
|
|
||||||
NOTE: When running the agent on windows, an exit of the remote session using
|
|
||||||
exit in powershell or command prompt does not terminate the shell completely.
|
|
||||||
To terminate the client ssh session must be killed by closing the terminal.
|
|
||||||
Cleanup of remote processes on the agent appears to work properly despite this
|
|
||||||
problem. It is just that exit of the windows shell (powershell or command prompt)
|
|
||||||
is not detected properly.
|
|
||||||
</p>
|
|
||||||
|
|
||||||
<p>
|
|
||||||
The agent has more options, download the agent and run it without arguments to
|
|
||||||
see all options.
|
|
||||||
</p>
|
|
||||||
|
|
||||||
<h2>Local clients: using ssh with a proxy command </h2>
|
|
||||||
|
|
||||||
<p><code>wsproxy</code> is a command that can be used as a proxy command for SSH which performs the connection to the
|
|
||||||
remote server. This command needs to be downloaded only once (see <a href="#downloads">downloads</a> below). It does not depend on
|
|
||||||
the converge implementation but only on the websocket standards. Other tools that
|
|
||||||
provide a mapping of stdio to a websocket can also be used instead of wsproxy.
|
|
||||||
</p>
|
|
||||||
<p>
|
|
||||||
Next step is to run a local SSH or SFTP client:
|
|
||||||
</p>
|
|
||||||
|
|
||||||
<pre>
|
|
||||||
{`
|
|
||||||
`}ssh -oServerAliveInterval=10 -oProxyCommand="wsproxy ws{secure}://{host}/client/ID" { username }{"@localhost"} {`
|
|
||||||
`}sftp -oServerAliveInterval=10 -oProxyCommand="wsproxy ws{secure}://{host}/client/ID" { username }{"@localhost"} {`
|
|
||||||
`}</pre>
|
|
||||||
|
|
||||||
<h2>Local clients: using SSH with a local TCP forwarding proxy</h2>
|
|
||||||
|
|
||||||
<p>
|
|
||||||
This option is less convenient than the proxy command because it requires two separate
|
|
||||||
commands to execute.
|
|
||||||
</p>
|
|
||||||
|
|
||||||
<p>
|
|
||||||
Local clients can connect using regular ssh and sftp commands through a tunnel that
|
|
||||||
translates a local TCP port to a websocket connection in converge. See
|
|
||||||
the <a href="#downloads">downloads</a> section.
|
|
||||||
This runs a local client that allows SSH to port 10000 and connects to converge using
|
|
||||||
a websocket connection.
|
|
||||||
</p>
|
|
||||||
|
|
||||||
|
|
||||||
<p>
|
|
||||||
Next step is to run a local SSH of SFTP client:
|
|
||||||
</p>
|
|
||||||
|
|
||||||
<pre> {`
|
|
||||||
`}ssh -oServerAliveInterval=10 -p 10000 { username }{"@localhost"} {`
|
|
||||||
`}sftp -oServerAliveInterval=10 -oPort=10000 { username }{"@localhost"} {`
|
|
||||||
`}</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.
|
|
||||||
Another way to authenticate is through an .authorized_keys file in the
|
|
||||||
same directory as where the agent is started.
|
|
||||||
|
|
||||||
This can be setup as follows before starting the agent:
|
|
||||||
</p>
|
|
||||||
<pre> {`
|
|
||||||
`}# linux {`
|
|
||||||
`}echo "ssh-rsa dkddkdkkk a@b.c" > .authorized_keys {`
|
|
||||||
`}echo "ssh-rsa adfadjfdf d@e.f" >> .authorized_keys {`
|
|
||||||
`} {`
|
|
||||||
`}# windows {`
|
|
||||||
`}echo ssh-rsa dkddkdkkk a@b.c > .authorized_keys {`
|
|
||||||
`}echo ssh-rsa adfadjfdf d@e.f >> .authorized_keys
|
|
||||||
</pre>
|
|
||||||
<p>
|
|
||||||
Note that on windows you should not used quotes.
|
|
||||||
</p>
|
|
||||||
|
|
||||||
<h1 id="downloads">Downloads</h1>
|
|
||||||
|
|
||||||
<table class="table">
|
|
||||||
<thead>
|
|
||||||
<tr>
|
|
||||||
<th>Component</th>
|
|
||||||
<th>Purpose</th>
|
|
||||||
<th>Linux</th>
|
|
||||||
<th>Windows</th>
|
|
||||||
</tr>
|
|
||||||
</thead>
|
|
||||||
<tr>
|
|
||||||
<td>agent</td>
|
|
||||||
<td>The agent to run inside aa CI job</td>
|
|
||||||
<td><a href="/docs/agent">agent</a></td>
|
|
||||||
<td><a href="/docs/agent.exe">agent.exe</a></td>
|
|
||||||
</tr>
|
|
||||||
<tr>
|
|
||||||
<td>wsproxy</td>
|
|
||||||
<td>SSH proxy command that can be directly used by ssh</td>
|
|
||||||
<td><a href="/docs/wsproxy">wsproxy</a></td>
|
|
||||||
<td><a href="/docs/wsproxy.exe">wsproxy.exe</a></td>
|
|
||||||
</tr>
|
|
||||||
<tr>
|
|
||||||
<td>tcptows</td>
|
|
||||||
<td>TCP to WS tunnel for allowing regular
|
|
||||||
SSH and SFTP clients to connect to converge</td>
|
|
||||||
<td><a href="/docs/tcptows">tcptows</a></td>
|
|
||||||
<td><a href="/docs/tcptows.exe">tcptows.exe</a></td>
|
|
||||||
</tr>
|
|
||||||
</table>
|
|
||||||
</div>
|
</div>
|
||||||
</div>
|
</div>
|
||||||
</div>
|
</div>
|
||||||
|
|||||||
122
pkg/templates/usage.templ
Normal file
122
pkg/templates/usage.templ
Normal file
@ -0,0 +1,122 @@
|
|||||||
|
package templates
|
||||||
|
|
||||||
|
templ Usage(secure string, host string, username string) {
|
||||||
|
<div>
|
||||||
|
<h1>Usage</h1>
|
||||||
|
|
||||||
|
<h2>Continuous integration jobs</h2>
|
||||||
|
|
||||||
|
<p>
|
||||||
|
In a
|
||||||
|
continuous integration job, download the agent, chmod it and run it.
|
||||||
|
</p>
|
||||||
|
<pre>{`
|
||||||
|
# linux
|
||||||
|
`}curl http{secure}://{host}/docs/agent > agent{`
|
||||||
|
chmod 755 agent
|
||||||
|
`}./agent --id ID ws{secure}://{host}{`
|
||||||
|
|
||||||
|
# windows
|
||||||
|
`}curl http{secure}://{host}/docs/agent.exe > agent.exe{`
|
||||||
|
`}agent --id ID ws{secure}://{host}{`
|
||||||
|
`}</pre>
|
||||||
|
<p>
|
||||||
|
Above, ID is a unique id for the job, the so-called rendez-cous ID. This should not conflict with IDs
|
||||||
|
used by other agents. The ID is used for a rendez-vous between the end-user on a local system and
|
||||||
|
the continuous integration job running on a build agent. If you don't specify an id, a random
|
||||||
|
id will be generated.
|
||||||
|
|
||||||
|
The agent to the converge server and tells it the ID. Clients can now connect to the Converge
|
||||||
|
server to establish a connection to the CI job through converge by also specifying the same
|
||||||
|
ID.
|
||||||
|
|
||||||
|
Communication between
|
||||||
|
end-user and agent is encrypted using SSH and the rendez-vous server is unable to
|
||||||
|
read the contents. The rendez-vous server is nothing more then a glorified bit pipe,
|
||||||
|
simply transferring data between end-user SSH client and the agent which runs an
|
||||||
|
embedded SSH server.
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<p>
|
||||||
|
NOTE: When running the agent on windows, an exit of the remote session using
|
||||||
|
exit in powershell or command prompt does not terminate the shell completely.
|
||||||
|
To terminate the client ssh session must be killed by closing the terminal.
|
||||||
|
Cleanup of remote processes on the agent appears to work properly despite this
|
||||||
|
problem. It is just that exit of the windows shell (powershell or command prompt)
|
||||||
|
is not detected properly.
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<p>
|
||||||
|
The agent has more options, download the agent and run it without arguments to
|
||||||
|
see all options.
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<h2>Local clients: using ssh with a proxy command </h2>
|
||||||
|
|
||||||
|
<p><code>wsproxy</code> is a command that can be used as a proxy command for SSH which performs the connection to the
|
||||||
|
remote server. This command needs to be downloaded only once (see <a href="#downloads">downloads</a> below). It does not depend on
|
||||||
|
the converge implementation but only on the websocket standards. Other tools that
|
||||||
|
provide a mapping of stdio to a websocket can also be used instead of wsproxy.
|
||||||
|
</p>
|
||||||
|
<p>
|
||||||
|
Next step is to run a local SSH or SFTP client:
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<pre>
|
||||||
|
{`
|
||||||
|
`}ssh -oServerAliveInterval=10 -oProxyCommand="wsproxy ws{secure}://{host}/client/ID" { username }{"@localhost"} {`
|
||||||
|
`}sftp -oServerAliveInterval=10 -oProxyCommand="wsproxy ws{secure}://{host}/client/ID" { username }{"@localhost"} {`
|
||||||
|
`}</pre>
|
||||||
|
|
||||||
|
<h2>Local clients: using SSH with a local TCP forwarding proxy</h2>
|
||||||
|
|
||||||
|
<p>
|
||||||
|
This option is less convenient than the proxy command because it requires two separate
|
||||||
|
commands to execute.
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<p>
|
||||||
|
Local clients can connect using regular ssh and sftp commands through a tunnel that
|
||||||
|
translates a local TCP port to a websocket connection in converge. See
|
||||||
|
the <a href="#downloads">downloads</a> section.
|
||||||
|
This runs a local client that allows SSH to port 10000 and connects to converge using
|
||||||
|
a websocket connection.
|
||||||
|
</p>
|
||||||
|
|
||||||
|
|
||||||
|
<p>
|
||||||
|
Next step is to run a local SSH of SFTP client:
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<pre> {`
|
||||||
|
`}ssh -oServerAliveInterval=10 -p 10000 { username }{"@localhost"} {`
|
||||||
|
`}sftp -oServerAliveInterval=10 -oPort=10000 { username }{"@localhost"} {`
|
||||||
|
`}</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.
|
||||||
|
Another way to authenticate is through an .authorized_keys file in the
|
||||||
|
same directory as where the agent is started.
|
||||||
|
|
||||||
|
This can be setup as follows before starting the agent:
|
||||||
|
</p>
|
||||||
|
<pre> {`
|
||||||
|
`}# linux {`
|
||||||
|
`}echo "ssh-rsa dkddkdkkk a@b.c" > .authorized_keys {`
|
||||||
|
`}echo "ssh-rsa adfadjfdf d@e.f" >> .authorized_keys {`
|
||||||
|
`} {`
|
||||||
|
`}# windows {`
|
||||||
|
`}echo ssh-rsa dkddkdkkk a@b.c > .authorized_keys {`
|
||||||
|
`}echo ssh-rsa adfadjfdf d@e.f >> .authorized_keys
|
||||||
|
</pre>
|
||||||
|
<p>
|
||||||
|
Note that on windows you should not used quotes.
|
||||||
|
</p>
|
||||||
|
|
||||||
|
</div>
|
||||||
|
}
|
||||||
|
|
||||||
Loading…
Reference in New Issue
Block a user