Communication Between Tectia Server and the External Application

The communication between Tectia Server and an external application (from now on referred to as "application") proceeds as follows (also depicted in Figure E.1):

  1. Tectia Server waits for the parameter version from the application. The parameter indicates the highest protocol number the application understands. Currently, the only supported version is 1.

  2. Tectia Server sends version, indicating the highest protocol number Tectia Server understands. The application may ignore this.

  3. Tectia Server sends one or more requests. Each request is started by sending request:id, where id is the request identifier. It is unique for any ongoing requests the application has not yet completed. (The application later sends the request ID back to Tectia Server, see step 4).

    Next, Tectia Server sends zero or more data entries of the form <key>=<data>. For a list of the data entries sent by Tectia Server when matching local tunnel constraints with external data, see tunnel-local or Local Tunnels in Tectia Server Configuration tool.)

    The request is terminated by end-of-request:id where id is the same as in the start of the request.

  4. After sending the request(s), Tectia Server waits for the response(s) from the application. If Tectia Server has sent more than one request, the responses may come in any order. Each response starts with request:id and is followed by zero or more data entries of the form <key>=<data>, containing information the application needs to send to Tectia Server.

    The application ends each response with the parameter "success:" or "failure:". This parameter may contain additional information in the data field, for example "success: Access was allowed".

  5. Once Tectia Server has received all the responses from the application, it waits for the application to exit. Tectia Server collects the application's exit status and reports an error if the status is not 0.

    If the application hangs, Tectia Server will not kill it.

Tectia Mapper protocol from Tectia Server's perspective

Figure E.1. Tectia Mapper protocol from Tectia Server's perspective