Connector

This section details the API in the Packetriot client for automating commands and operations. Access the client API at the base URL: http://127.0.0.1:4100. To customize the listening port, use the --api-port flag with the pktriot start command.

The admin API only accepts requests in JSON format and responds with JSON. All API requests must include the following headers:

Content-Type: application/json
Accept: application/json

The admin API only accepts requests and returns responses in JSON format.

The schema for HTTP and port objects returned in the configuration is the same for HTTP API endpoints in Gateway that create and update traffic rules.

Info

This endpoint provides the status of the client and tunnel. It returns the installed client version, which may differ from the runtimeVersion. The runtimeVersion reflects the version of the client software currently running, which can be newer if an update has been saved in the client configuration directory.

The isUpdated parameter is true when the version and runtimeVersion differ.

HTTP Method

GET

URL

/api/client/v1.0/info

Response Parameters

Example Response Body

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

Configuration

This endpoint returns the attributes of the client and the OS hosting the tunnel, along with the details of the traffic rules.

Object types like HTTPS and ports are used when creating or updating traffic rules.

HTTP Method

GET

URL

/api/client/v1.0/config

Response Parameters

Example Response Body

{
    "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 endpoints below are used to manage the tunnel session, including starting, stopping, and restarting it. By default, a tunnel session is established when the client is run using the pktriot start command.

Start

HTTP Method

GET

URL

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

This endpoint checks if a valid tunnel session is currently established. If a session exists, this operation maintains the existing session and returns a status value of true.

If no session exists, a new one will be created. This operation is asynchronous, so it’s advisable to combine it with calls to the info endpoint to determine when the tunnel is connected.

The operation initiates the tunnel session maintenance routine, which attempts to establish a new session. If it fails, it will keep trying until it reaches the limits set by the reconnection parameters.

Response Parameters

Example Response Body

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

Shutdown

HTTP Method

GET

URL

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

This endpoint will shut down an existing tunnel session.

Response Parameters

Example Response Body

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

Restart

HTTP Method

GET

URL

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

This endpoint combines the functionality of the shutdown and start endpoints. It terminates any existing session and initiates the asynchronous routines to establish and maintain a new tunnel session.

This operation is asynchronous, so it’s recommended to pair it with calls to the info endpoint to determine when the tunnel is connected.

Response Parameters

Example Response Body

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

Health

HTTP Method

GET

URL

/api/client/v1.0/health

This endpoint checks the health and availability of the upstream resources defined in the traffic rules on the client.

For example, when an HTTP site serves static content, the endpoint verifies that the path on the file system exists and that it has appropriate read permissions. For upstream application servers identified by a destination and port, or via upstreamURL, it checks connectivity by attempting to establish a TCP connection.

Port forwarding rules are validated by checking if the destination TCP application is reachable through a TCP connection.

Note: Port mappings are not verified.

Response Parameters

Example Response Body

{
    "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
    }]
}

Note: This endpoint’s implementation is not yet complete. Each traffic flow corresponds to an HTTP or port forwarding rule, identified by a generated flowID. Currently, it is difficult to relate the availability information to specific rules, which will be improved in future iterations. The corresponding objects will be included as children under the http or port properties to provide service details.

Traffic Management

The endpoints in this section allow you to create new traffic rules for HTTP sites, TCP applications, and local port mappings to remote services on the host where the client tunnel is running. You can also update and delete existing traffic rules.

These endpoints work with data types that include HTTP websites, TCP applications, and port mappings. They follow the same JSON object schema used in the Spokes Admin API. For detailed descriptions of these object types, refer to the Data Types section.

Create

HTTP Method

POST

URL

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

This endpoint creates new traffic rules for HTTP sites, traffic forwarding for TCP applications, and local port mappings. You can provide a list of each object type in an array using the following structure.

Request Parameters

Example Request Body

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

For detailed descriptions of object types, refer to the Data Types section of the Spokes Admin API docs.

Below is an example of creating a single HTTP site traffic rule. The request uses destination and port to specify the upstream application to which this HTTP traffic will be sent.

Similar to the CLI client, you can also use the --upstream-url option to specify the destination. The upstreamURL property can be used instead of the other two properties with the value 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": ""
    }]
}

The following example demonstrates creating a new TCP forwarding rule. Before creating a new port traffic rule, a port allocation must be completed and then used as the port property in the object.

To clear a port traffic rule so that no forwarding occurs while the allocated port remains attached to the tunnel, simply exclude the destination and dstPort fields, or set them to 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 mapping creates a local listener port and maps it to a remote service. This remote service could be another service hosted behind a different tunnel or an application running elsewhere on the public Internet.

For example, a cloud-hosted database, like MySQL or Redis, can be exposed publicly and mapped to a local port.

In this case, the dstPort is a TCP port allocated to another tunnel, which is inferred by the empty destination value. This remote service, hosted by another tunnel, will be mapped to the local port on this host, identified by the port property in the port mapping object.

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

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

Response Parameters

Example Response Body

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

Update

HTTP Method

POST

URL

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

This endpoint updates existing HTTP, port forwarding, and port mapping traffic rules using the same structure as creating new traffic rules.

Request Parameters

Example Request Body

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

For detailed descriptions of these objects, refer to the Data Types section of the Spokes Admin API docs.

This endpoint uses key values to look up existing rules and replace their details with updated values. For HTTP sites, the domain value identifies an existing site for updating.

In port forwarding rules, the port property value is used to identify an existing rule for updates.

For port mapping rules, the port property (the local listening port number) is used to find the existing rule and update its details.

Response Parameters

Example Response Body

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

Delete

HTTP Method

GET

URL

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

This endpoint deletes existing HTTP, port forwarding, and port mapping traffic rules. It uses the same basic structure employed for creating new traffic rules.

Request Parameters

Example Request Body

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

For detailed descriptions of these objects, refer to the Data Types section of the Spokes Admin API docs.

This endpoint uses the domain to identify and delete HTTP site rules from the existing configuration. It also sends requests to the server to drop the relays for that website that were previously set up.

Port forwarding rules are identified by the port property in the included objects. Note that TCP ports are not released back to the server; instead, the traffic rules are reset, meaning that destination and dstPort are set to empty values. A request is sent to the server to drop the previously established port forwarding relays.

Port mapping rules are identified through the portmaps property, where each object in the list uses the port value to find and remove an existing port mapping rule. These rules are deleted from the configuration, and the local listeners are closed.

Response Parameters

Example Response Body

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

Ports

The following endpoints manage port allocations with the Spokes server. Clients can request TCP port allocations that remain persistently associated with the tunnel until they are released.

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

Allocate

HTTP Method

GET

URL

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

This endpoint requests a new TCP port from the server for the tunnel.

Response Parameters

Example Response Body

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

While a status of the operation is returned, this endpoint is not yet complete and does not provide the actual port number. You will need to call the List Ports endpoint to obtain the value of the newly allocated port.

Release

HTTP Method

POST

URL

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

This endpoint instructs the tunnel to release a previously allocated TCP port back to the server and will also drop any associated port forwarding rules. The specific port to release is indicated using the port field in the request body.

Request Parameters

Example Request Body

{
    "port": 22872
}

Response Parameters

Example Response Body

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

List

HTTP Method

GET

URL

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

This endpoint returns a list of all port information in JSON array format. This includes allocated ports that do not have any associated forwarding rules (these will have an empty destination and dstPort value of zero).

Details of the forwarding rules are included, as well as any firewall rules (IP filtering) associated with a port forwarding rule.

For detailed descriptions of port objects, refer to the Data Types section of the Spokes Admin API docs.

Response Parameters

Example Response Body

[{
    "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"
    }]
}]