converge/pkg/server/templates/about.templ

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>

      <h2>other tools</h2>

      <p>Using available existing tools such as
          <a href="https://github.com/namespacelabs/breakpoint">breakpoint</a> in combination
          with a websocket tunneling tool such as
          <a href="https://github.com/erebe/wstunnel">wstunnel</a> a similar solution can be
          obtained. There are however some problems with these solutions that converge is
          trying to address:
      </p>

      <p>
      <ul>
      <li>deployment: Breakpoint uses an embedded SSH server which is a really good idea but
      uses the QUIC protocol for connecting to a rendez-vous server. The rendez-vous server than
      exposes a random port for every client. This make deployment on kubernetes really hard
      where fixed ports must be used and QUIC is also not a widely supported protocol.</li>
      <li>The problem with the random ports can be solved by using wstunnel running together
      with breakpoint server in a kubernetes pod, where wstunnel can forward traffic over an
      extern websocket connection to the local random port that breakpoint server is listening on.</li>
      <li>breakpoint leaves it open on how users install the breakpoint executable (agent). </li>
      <li>Because of the hacky nature of this setup, it is very difficult for users to use
      and troubleshoot when things go wrong. </li>
      </ul>

      </p>
      Converve server addresses these issues in the following ways:
      <ul>
      <li>Use the websocket protocol both for agents and for clients, providing a fixed port and
          a supported protocol for kubernetes deploymment.</li>
      <li>Providing online documentation where the instructions take into account the
          hostname and protocol where converge is running allowing users to cut and paste
          instructions that can be used without modification. In the usage page the users
          can even generate the correct agent startup commands and client connection commands
          based on the type of shell they are connecting to. </li>
      <li>Converge server provides out of the box downloads of required software. This makes sure
          client and server are always up to date. In addition a protocol version check is done. </li>
      <li>User-friendly error messages can be given to users in most case when things do not work
          out because of <code>wsproxy</code>, an SSH proxy command that also talk to the server
          to tell the user if a connection is accepted and if not why not. </li>
      <li>A live screen showing the current sessions that are running. </li>
      <li>Interactivity in the user's session with notifications about timeouts and a very
      simple inactivity timmeout mechanism. </li>
      <li>Possibility for the user to define his own shell. </li>
      <li>Support for unix like bash shells and command prompt and powershell. </li>
      </ul>
      <p>
      </p>


      <h2>how it works</h2>

      <p>
          The steps involved are as follows:
          <ul>
          <li>The agent connects to converge server. If no id is specified than a new id will
              be generated. The ids specified by different agents must be unique. If the agent
              specifies an id that is already in use, then a new id will be generated.
              When started the agent will echo the commands to connect to it in its output.
          </li>
           <li>
              Since the emmbedded SSH server in the agent will allow multiple clients to connect
              to it, it wants to listen for copnnections. By default it cannot do this, it just
              setup a connection to the converge server, but the converge server can in general
              not connect back to it because of networking. Therefore, a multiplexing library is
              used to establish multiple virtual connections over a single TCP connection.
              The agent can now listen for connections from clients.
          </li>
          <li>The agent connects to the converge server using the commmand specified by the agent.
              The converge server can then match the agent with the client based on the id and
              the connectio at network level is established.
          </li>
          <li>The embedded SSH server now performs authentication, after successful login,
              a shell is spwaned and the network connection of the user is connected to it.
              The connection is practically identical to a regular terminal connection. To
              achieve this some magic is used to make the shell beiieve it is connected to a
              terminal.
          </li>
          </ul>
      </p>

      <h2>Security</h2>

      <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>Currently converge server still supports password based login but this will be disabled.
         Image two people configuring an agent with the same id where one of the agents actually
         gets it and other gets a new id. Now, with a password each user can access each other's
         agents. This is of course highly confusing and undesirable. Converge server already support
         authorized keys but this is not yet mandatory. I is made extremely easy through the
         <a href="usage.html">usage</a> page to configure this, so the additional complexity should
         not be an issue.
      </p>

      <h2>SSH and SFTP</h2>

      <p>
          Both ssh and sftp are supported. Multiple shells are also allowed.
      </p>

      <h2>Timeouts</h2>

      <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.
      </p>
      <p>When the user touches a .hold file, the agent keeps waiting for connections even
         after the last client logs out, taking into account the timeout.
      </p>
      <p>The sessions have an inactivity timeout. Any keypress on the keyboard by a user
      is interpreted as activity. </p>


     <h2>Remote shell usage</h2>

     <p>
       The agent supports a --shells command-line option by which a comma-separated
       list of shells can be prepended to the default search path for shells, e.g.
       <code>--shells zsh,csh,sh</code> (linux) or <code>cmd,powershell</code> for
       windows.
     </p>

     <p>
       The agent sets a <coder>agentdir</coder> environment variable that points to
       the directory where the agent is running.
     </p>
  </div>
}


templ AboutTab() {
    @BasePage(1) {
                    @About()
    }
}