Erik Brakkee
aa46ed7b5c
installation dependent URLs. For now using ServerALiveInterval to avoid disconnects.
144 lines
4.3 KiB
HTML
144 lines
4.3 KiB
HTML
<!DOCTYPE html>
|
|
<html lang="en">
|
|
<head>
|
|
<meta charset="UTF-8">
|
|
<link rel="stylesheet" href="css/bootstrap.min.css"
|
|
crossorigin="anonymous">
|
|
<meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">
|
|
<title>Converge</title>
|
|
</head>
|
|
<body>
|
|
|
|
<script src="js/bootstrap.bundle.min.js"
|
|
crossorigin="anonymous"></script>
|
|
|
|
<div class="container">
|
|
|
|
<h1>About</h1>
|
|
|
|
<p>
|
|
Converge is a utility for troubleshooting builds on continuous integration serves.
|
|
It solves a common problem where the cause of job failure is difficult to determine.
|
|
This is complicated furhter 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-use 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 indefinetely waiting
|
|
for a connection.
|
|
</p>
|
|
|
|
<h1>Usage</h1>
|
|
|
|
<h2>Continous integration jobs</h2>
|
|
|
|
<p>
|
|
In a continous integration job, download the agent, chmod it and run it.
|
|
</p>
|
|
<pre>
|
|
curl http@secure@://@host@/docs/agent > agent
|
|
chmod 755 agent
|
|
./agent ws@secure@://@host@/agent/ID
|
|
</pre>
|
|
<p>
|
|
Above, ID is a unique id
|
|
for the job. This should not conflict with other ids.
|
|
|
|
This connects the agent to the converge server. Clients can now connect to converge
|
|
to establish a connection to the CI job through converge.
|
|
</p>
|
|
|
|
<h2>Local clients: using ssh proxy command </h2>
|
|
|
|
<pre>
|
|
curl http@secure@://@host@/docs/wsproxy > wsproxy
|
|
chmod 755 wsproxy
|
|
</pre>
|
|
|
|
<p>This is a command that can be used as a proxy command for SSH which performs the connection to the remote
|
|
server.</p>
|
|
|
|
<p>
|
|
Next step is to run a local SSH of SFTP client:
|
|
</p>
|
|
|
|
<pre>
|
|
ssh -oServerAliveInterval=10 -oProxyCommand="wsproxy ws@secure@://@host@/client/ID" abc@localhost
|
|
sftp -oServerAliveInterval=10 -oProxyCommand="wsproxy ws@secure@://@host@/client/ID" abc@localhost
|
|
</pre>
|
|
|
|
<p>
|
|
<code>abc</code> is a fixed user defined by converge. It has a very exciting password.
|
|
</p>
|
|
|
|
<h2>Local clients: with a local TCP forwarding proxy</h2>
|
|
|
|
This option is less convenient than the proxy command because it requires two separate
|
|
commands to execute.
|
|
|
|
<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.
|
|
|
|
First step is to download the tcptows program (see below):
|
|
</p>
|
|
|
|
<pre>
|
|
curl http@secure@://@host@/docs/tcptows > tcptows
|
|
chmod 755 tcptows
|
|
./tcptows 10000 ws@secure@://@host@/client/ID
|
|
</pre>
|
|
|
|
<p>
|
|
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 abc@localhost
|
|
sftp -oServerAliveInterval=10 -oPort 10000 abc@localhost
|
|
</pre>
|
|
|
|
<p>
|
|
<code>abc</code> is a fixed user defined by converge. It has a very exciting password.
|
|
</p>
|
|
|
|
<h1>Downloads</h1>
|
|
|
|
<ul>
|
|
<li><a href="/docs/agent">agent</a>: The agent to run inside aa CI job
|
|
</li>
|
|
<li><a href="/docs/tcptows">tcptows</a>: TCP to WS tunnel for allowing regular
|
|
SSH and SFTP clients to connect to converge.
|
|
</li>
|
|
<li><a href="/docs/wsproxy">wsproxy</a>: SSH proxy command that can be directly used by ssh
|
|
</li>
|
|
</ul>
|
|
|
|
</div>
|
|
|
|
</body>
|
|
</html>
|