Packetriot Client API

This section covers an API available in the Packetriot client for automating commands and operations to the client. The client can be run 24/7 using systemd in Linux, Windows services, or by deploying as a Docker container. The client API can used by other applications to setup traffic rules dynamically.

The client API is available using the following base URL http://127.0.0.1:4100. The listening port for the client API can be customize by adding the flag --api-port to the pktriot start command.

The admin API will only accept request encoded in JSON and will send all responses in JSON.

Note: the definition (schema) of the HTTP and port objects returned in the configuration are used identically for the API endpoints that create and update traffic rules.

Info

GET/api/client/v1.0/info

This endpoint will return a status to indicate the client and tunnel is running. It also returns version of the client installed on the host, which can be different than the runtimeVersion. The runtimeVersion differs when an updated version of the client software is saved in the client configuration directory. The runtimeVersion is the version of the updated client software running.

The isUpdated will always be true when when the version and runtimeVersion are different.

Response

Parameters

status	boolean	Indicates success of the operation.
error	string	Message with more information or details on any errors.
version	string	Version string for the client installed on the host.
runtimeVersion	string	Version of the binary running. This value is different from vesion when an update is running.
isUpdated	boolean	Indicates if the running client binary is an updated version, not the one installed in the host.
isTunConnected	boolean	Indicates if a valid and working tunnel session is established.

{
    "status": true,
    "error": "",
    "version": "v0.14.0",
    "runtimeVersion": "v0.15.0",
    "isUpdated": true,
    "isTunConnected": true
}

Configuration

GET/api/client/v1.0/config

This endpoint will return attributes of the client and OS hosting the tunnel along with the traffic rules and their details.

Each object type, such as the HTTPS and ports, are also used when creating or updating traffic rules.

Response

Parameters

status	boolean	Indicates success of the operation.
error	string	Message with more information or details on any errors.
https	Array	List of HTTP website objects.
ports	Array	List of port objects.
portmaps	Array	List of portmapping objects

{
    "version": "v0.15.0",
    "os": "linux",
    "arch": "amd64",
    "https": [{
        "domain": "api-test-1.spokes.domain.com",
        "secure": true,
        "destination": "127.0.0.1",
        "port": 8080,
        "webRoot": "/tmp",
        "useLetsEnc": true,
        "firewall": [{
            "sequence": 1,
            "action": "allow",
            "network": "71.1.2.3/32"
        }],
        "redirect": true,
        "rewriteHost": "api-test-100.spokes.domain.com",
        "upstreamURL": ""
    }],
    "ports": [{
        "port": 22872,
        "destination": "127.0.0.1",
        "dstPort": 2200
    }, {
        "port": 22470,
        "destination": "127.0.0.1",
        "dstPort": 2200,
        "firewall": [{
            "sequence": 1,
            "action": "allow",
            "network": "71.1.2.3/32"
        }]
    }],
    "portmaps": [{
        "port": 15001,
        "dstPort": 22132,
        "destination": "",
        "transport": "tcp",
        "label": "port-mapping-1"
    }]
}

Tunnel Session

The following endpoints are used to manage the tunnel session. This includes starting, shutting down and restarting a tunnel session. By default, when the client is run using the pktriot start command, a tunnel session will be establsihed.

Start

GET/api/client/v1.0/tun/start

This endpoint will check if a valid tunnel session is currently established. If so, this operation is indepodement and will keep the existing intact and return a status value of true.

If no tunnel session is exists, a new one will be established. This operation is asynchronous and should be combined with calls to the info endpoint to determine when the tunnel is connected.

This operation will start the tunnel session maintenance routine which will establish a new session. If this fails, it will continously make attempts until it reaches limits of the configured reconnection parameters.

Response

Parameters

status	boolean	Indicates success initiating a new tunnel session.
isTunConnected	boolean	Indicates an existing tunnel session was established previously.
error	string	Message with more information or details on any errors.

In the example below isTunConnected indicates that no previous tunnel session existed and that the operation to establish a new one successfully started.

{
    "status": true,
    "isTunConnected": false,
    "error": ""
}

Shutdown

GET/api/client/v1.0/tun/shutdown

This endpoint will shutdown an existing tunnel session.

Response

Parameters

status	boolean	Indicates success of the operation. A true implies the session has been shutdown or did not exist.
error	string	Message with more information or details on any errors.

{
    "status": true,
    "error": ""
}

Restart

GET/api/client/v1.0/tun/restart

This endpoint is a composition of the stop and start endpoints. It will terminate an existing session and then kick off the asynchronous routines to establish and maintain a tunnel session.

This operation is asynchronous and should be combined with calls to the info endpoint to determine when the tunnel is connected.

Response

Parameters

status	boolean	Indicates success of the operation and the tunnel session was shutdown and a new session was initiated.
error	string	Message with more information or details on any errors.

{
    "status": true,
    "error": ""
}

Health

GET/api/client/v1.0/health

This endpoint will check health or availability for the upstream resources identified in the traffic rules that exist on the client.

For example, an HTTP site can be serving a static only site, in this case the path on the file-system is checked that it exists and permission to read from that location is true. When an upstream application server is identified by a destination and port, or with upstreamURL, it is checked by attempting a TCP connection and verifying that one could be established.

A port forwarding rule is verified by checking that the destination TCP application can be reach. This is performed by attempting a TCP connection and verifying that one can be established.

Port mappings are not verified.

Response

Parameters

status	boolean	Indicates success of the operation.
error	string	Message with more information or details on any errors.
services	Object	Contains two fields that indicate the unique traffic flow ID for a website or TCP application and its availability status.

{
    "status": true,
    "error": "",
    "services": [{
        "flowID": 12948771731084390768,
        "available": false
    }, {
        "flowID": 963154770239164234,
        "available": false
    }, {
        "flowID": 8528664672129644456,
        "available": true
    }, {
        "flowID": 9540066623829954314,
        "available": true
    }, {
        "flowID": 7782121883366390420,
        "available": true
    }, {
        "flowID": 1749949573963933268,
        "available": true
    }]
}

Please note this endpoints implementation is not yet complete. A traffic flow is identified for each HTTP or port forwarding rule. However, a generated ID called the flowID is used to identify the server. The actual rule is not specified which makes it difficult to relate the availability information provided by this endpoint.

This will be improved in future iterations of the client API. The corresponding object will be included a child using the http or port properties and include the details of the service.

Traffic Management

The following endpoints in this section allow callers to create new traffic rules for HTTP sites, TCP applications and create new local port-mappings to remote services on the host a client tunnel is being hosted on.

These endpoints also enable updating existing traffic rules and deleting them.

The data types for these endpoints include HTTP websites, TCP applications and port-mapping. These types following the same JSON object schema and definition that is used for the Spokes Admin API. You can find detailed descriptions of these objects in the Data Types section.

Create

POST/api/client/v1.0/traffic/create

This endpoint will create new traffic rules for HTTP sites, traffic forwarding for TCP applications and local port-mappings. A list of each object type can be provided in an array and is used this basic structure.

Parameters

https	Array	List of HTTP website objects.
ports	Array	List of TCP forwarding definition objects.
portmaps	Array	List of portmap definition objects.

Request

{
    "https": [],
    "ports": [],
    "portmaps": []
}

You can find detailed descriptions of these objects in the Data Types section of the Spokes Admin API docs.

Below is an example of a single HTTP site traffic rule being created with this request. The request uses destination and port to specify the upstream application to send this HTTP traffic too.

Similar to the CLI client, you can implement the same by using the --upstream-url to specify the destination. The upstreamURL property could be used instead of the other two properties and use a value of http://127.0.0.1:8080.

{
    "https": [{
        "domain": "api-test-1.spokes.domain.com",
        "secure": true,
        "destination": "127.0.0.1",
        "port": 8080,
        "webRoot": "/tmp",
        "useLetsEnc": true,
        "firewall": [{
            "sequence": 1,
            "action": "allow",
            "network": "71.1.2.3/32"
        }],
        "redirect": true,
        "rewriteHost": "api-test-100.spokes.domain.com",
        "upstreamURL": ""
    }]
}

Below is an example of creating a new TCP forwarding rule. Prior to create a new port traffic rule a port allocation must be performed and then used as the port property in object representing the port.

Clearing a port traffic rule so that no forwarding takes place, but the allocated port remains attached to the tunnel, is done by just not including the destination and dstPort fields or setting them with empty or 0 values.

{
    "ports": [{
        "port": 22872,
        "destination": "127.0.0.1",
        "dstPort": 2200
    }]
}

Below is an example of creating a port-mapping rule. A port map creates a local listener port and maps a remote service to it. A remote service can another service hosted behind a different tunnel. A remote service can also be an application running elsewhere on the public Internet.

A cloud-hosted database, MySQL or Redis, is an example of an application service publicly available that can be mapped to a local port.

In this example the dstPort is a TCP port that is allocated to another tunnel. This is inferred because the destination value is empty. This remote service hosted by another tunnel will be mapped to the local port on this host. That local port is identified with the port property in the portmap object.

With this rule, a program running on this host can access a remote service using the 127.0.0.1:15001 local address.

{
    "portmaps": [{
        "port": 15001,
        "dstPort": 22132,
        "destination": "",
        "transport": "tcp",
        "label": "port-mapping-1"
    }]
}

Response

Parameters

status	boolean	Indicates success of the operation. A true value implies all new traffic rules were created successfully.
error	string	Message to provide more details or description of any errors that occurred during the operation.

{
    "status": true,
    "error": ""
}

Update

POST/api/client/v1.0/traffic/update

This endpoint will update existing HTTP, port forwarding and port mapping traffic rules. It utilizes the same basic structure used in creating new traffic rules:

Parameters

https	Array	List of HTTP website objects.
ports	Array	List of TCP forwarding definition objects.
portmaps	Array	List of portmap definition objects.

Request

{
    "https": [],
    "ports": [],
    "portmaps": []
}

You can find detailed descriptions of these objects in the Data Types section of the Spokes Admin API docs.

This endpoint utilizes key values to lookup existing rules and replace their details with updated values. For HTTP site the domain value is used to key on an existing site and make an update.

The port property value in port forwarding rules is used to key on an existing rule and make an update.

Port mapping rules key on port property which is the local listening port number. This value is used to lookup an existing port mapping rule and then update its details.

Response

Parameters

status	boolean	Indicates success of the operation and if all the rules specified were updated correctly.
error	string	Message to provide more details or description of any errors that occurred during the operation.

{
    "status": true,
    "error": ""
}

Delete

GET/api/client/v1.0/traffic/delete

This endpoint will delete existing HTTP, port forwarding and port mapping traffic rules. It utilizes the same basic structure used in creating new traffic rules:

Parameters

https	Array	List of HTTP website objects.
ports	Array	List of TCP forwarding definition objects.
portmaps	Array	List of portmap definition objects.

Request

{
    "https": [],
    "ports": [],
    "portmaps": []
}

You can find detailed descriptions of these objects in the Data Types section of the Spokes Admin API docs.

For HTTP site, this endpoint will use the domain to lookup the rule in the existing configuration and and remove it. It will also send requests to the server to drop the relays for that website it had requested earlier.

Port forwarding rules are identified by the port property in objects include in this request. It is important to note that the TCP ports are not released back to the server. The traffic rules are just reset, e.g. destination and dstPort are set to empty values. A request to the server is sent as well to drop the previously request port forwarding relays.

Port mapping rules are identified in the portmaps property and each object in a specified list used the port value to identify an existing port mapping rules. These rules are removed the configuration and the local listeners closed.

Response

Parameters

status	boolean	Indicates success of the operation and if the deletion of the rules were all successful.
error	string	Message to provide more details or description of any errors that occurred during the operation.

{
    "status": true,
    "error": ""
}

Ports

The following endpoints manage port allocations with the Spokes server. Clients request port allocations that remain persistently associated to the tunnel until the port is released.

Allocated ports can be used with creating, updating, or deleting TCP forwarding traffic rules.

Allocate

GET/api/client/v1.0/ports/allocate

This endpoint will instruct the tunnel to request a new TCP port from the server.

Response

Parameters

status	boolean	Indicates success of the operation.
port	integer	The port number allocated on the server and assigned to this tunnel.
message	string	Information messages returned from the zero.
error	string	Message to provide more details or description of any errors that occurred during the operation.

{
    "status": true,
    "port": 22123,
    "message": "new port allocated",
    "error": ""
}

A status of the operation is returned, however, this endpoint is not yet complete and does not return the port itself. A call to List Ports endpoint is necessary to get the value of the newly allocated port.

Release

POST/api/client/v1.0/ports/release

This endpoint will instruct the tunnel to release a previously allocated TCP port back to the server. It will also drop any port forwarding rules as well. The port to release is specified using the port field in the object posted to this endpoint.

Parameters

port

integer

Number indicating the port value previously allocated.

Request

{
    "port": 22872
}

Response

Parameters

status	boolean	Indicates success of the operation and if the port was returned the server.
error	string	Message to provide more details or description of any errors that occurred during the operation.

{
    "status": true,
    "error": ""
}

List

GET/api/client/v1.0/ports/list

This endpoint will return a list, JSON array, containing all of the port information. This include ports that are allocated but do not that any forwarding rules associated to them. These rules do not include a destination (empty string) and a zero value for dstPort.

Details on the forwarding rules are included as well as firewall rules (IP-filtering) associated to a port forwarding rule.

You can find detailed descriptions of port objects in the Data Types section of the Spokes Admin API docs.

Response

Parameters

--

Array

An array for port objects are returned to the caller.

[{
    "port": 22872,
    "destination": "127.0.0.1",
    "dstPort": 2200
}, {
    "port": 22132,
    "destination": "",
    "dstPort": 0
}, {
    "port": 22470,
    "destination": "127.0.0.1",
    "dstPort": 2200,
    "firewall": [{
        "sequence": 1,
        "action": "allow",
        "network": "71.1.2.3/32"
    }]
}]