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.
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.
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.
Both ssh and sftp are supported. Multiple shells are also allowed.
There is a timeout mechanism in the agent such that jobs do not hang indefinetely waiting for a connection.
In a continous integration job, download the agent, chmod it and run it.
curl http@secure@://@host@/docs/agent > agent
chmod 755 agent
./agent ws@secure@://@host@/agent/ID
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.
curl http@secure@://@host@/docs/wsproxy > wsproxy
chmod 755 wsproxy
This is a command that can be used as a proxy command for SSH which performs the connection to the remote server.
Next step is to run a local SSH of SFTP client:
ssh -oServerAliveInterval=10 -oProxyCommand="wsproxy ws@secure@://@host@/client/ID" abc@localhost
sftp -oServerAliveInterval=10 -oProxyCommand="wsproxy ws@secure@://@host@/client/ID" abc@localhost
abc is a fixed user defined by converge. It has a very exciting password.
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):
curl http@secure@://@host@/docs/tcptows > tcptows
chmod 755 tcptows
./tcptows 10000 ws@secure@://@host@/client/ID
This runs a local client that allows SSH to port 10000 and connects to converge using a websocket connection.
Next step is to run a local SSH of SFTP client:
ssh -oServerAliveInterval=10 -p 10000 abc@localhost
sftp -oServerAliveInterval=10 -oPort 10000 abc@localhost
abc is a fixed user defined by converge. It has a very exciting password.