130 lines
6.4 KiB
Plaintext
130 lines
6.4 KiB
Plaintext
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}/static/agent > agent{`
|
|
chmod 755 agent
|
|
`}./agent --id ID ws{secure}://{host}{`
|
|
|
|
# windows
|
|
`}curl http{secure}://{host}/static/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>
|
|
}
|
|
|
|
|
|
|
|
templ UsageTab(secure string, host string, username string) {
|
|
@BasePage(2) {
|
|
@Usage(secure, host, username)
|
|
}
|
|
}
|