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)
    }
}