eCapture Remote Configuration Update API

April 23, 2026 · View on GitHub

This document describes how to update eCapture’s runtime configuration via HTTP, from the client side.
It focuses on how to construct HTTP requests and JSON payloads to communicate with eCapture.

Notes:

Default: disabled (no HTTP server). Pass --listen to enable, for example: --listen 127.0.0.1:28256

Set --listen "" to explicitly disable the HTTP server (runtime config update will be unavailable)

All endpoints are HTTP POST + JSON

Endpoint paths have no prefix. They are just the module names (e.g. /tls, /gotls, /gnutls).

1. Overview

1.1 Use cases

Adjust capture behavior without restarting the eCapture process
Build an external management tool / control panel / script that can “update and apply configuration” on demand
Dynamically change target processes, ports, filters, and other runtime parameters

1.2 Basic rules

Protocol: HTTP
HTTP method: POST
Content-Type: application/json
Request body: JSON configuration object for the target module
(same structure as the corresponding config.*Config type inside eCapture)
Response body: a unified JSON structure with status code and module name

2. Supported HTTP paths and platform differences

The set of supported configuration update paths is slightly different between Linux and Android GKI.

2.1 Linux paths

On Linux, you can update configurations via the following HTTP paths:

Path	Description
`/tls`	OpenSSL / TLS module
`/openssl`	Alias of `/tls`
`/boringssl`	Alias of `/tls`
`/gotls`	Go TLS module
`/gnutls`	GnuTLS module
`/nss`	NSS / NSPR module
`/nspr`	Alias of `/nss`
`/bash`	Bash command capture (Linux only)
`/mysqld`	MySQLd protocol capture (Linux only)
`/postgress`	PostgreSQL protocol capture (Linux only, note the spelling)

Reminder:

/openssl and /boringssl are aliases of /tls; they share the same configuration structure.

/nss and /nspr share the same configuration structure.

/bash, /mysqld, and /postgress do not exist on Android GKI.

2.2 Android GKI paths

On Android GKI, the available paths are:

Path	Description
`/tls`	OpenSSL / TLS module
`/openssl`	Alias of `/tls`
`/boringssl`	Alias of `/tls`
`/gotls`	Go TLS module
`/gnutls`	GnuTLS module
`/nss`	NSS / NSPR module
`/nspr`	Alias of `/nss`

Reminder:

Android GKI does not expose /bash, /mysqld, /postgress configuration endpoints.

If your management client needs to support both Linux and Android, detect the platform and only call supported paths.

3. Common request and response format

3.1 Request format

All configuration update endpoints use the same HTTP request pattern:

Method: POST
URL: http://<listen-address>/<path>
Example: http://127.0.0.1:28256/tls
Headers:
- Content-Type: application/json
Body:
- JSON object. Its fields depend on the specific module.
- Typically includes:
  - Common fields: pid, uid, debug, hex, btf, per_cpu_map_size, truncate_size, etc.
  - Module-specific fields: target process names, ports, protocol-related options, and so on.

Exact field names and types are defined in user/config/*.go.
Examples below are illustrative only, to show how to call the API from the client side.

3.2 Response format

All endpoints return a unified JSON structure:

{
  "code": 0,
  "module_type": "openssl",
  "msg": "RespOK",
  "data": null
}

Field description:

code (number): status code
- 0 – success (RespOK)
- 4 – configuration JSON decode failed (RespConfigDecodeFailed)
- 5 – configuration check failed (RespConfigCheckFailed)
- 6 – failed to send configuration into internal channel (RespSendToChanFailed)
- other values – reserved (e.g. invalid request, internal server error)
module_type (string): module identifier for this update (e.g. openssl, gotls, gnutls)
msg (string): human-readable string corresponding to code, useful for logging and debugging
data: currently unused and usually null

Relationship between HTTP status and code (for clients):

HTTP 200 + code == 0:
Configuration accepted. eCapture has begun applying the new config (by restarting the module internally).
HTTP 400:
Request format or config content is invalid (code usually 4 or 5).
HTTP 503:
eCapture is currently busy and cannot accept new config updates (code is 6). You can retry later.

4. Typical module calls

All examples assume eCapture is running on the local machine with the default address 127.0.0.1:28256.

Again, JSON fields below are examples only.
Align them with the actual fields from your current user/config/*.go.

4.1 OpenSSL / TLS module (`/tls` / `/openssl` / `/boringssl`)

Used for applications based on OpenSSL / BoringSSL / generic TLS.
The three paths are equivalent; you can pick any of them.

4.1.1 Using curl

curl -v \
  -H "Content-Type: application/json" \
  -X POST \
  --data '{
    "pid": 0,
    "uid": 0,
    "debug": false,
    "hex": false,
    "btf": 0,
    "per_cpu_map_size": 1024,
    "truncate_size": 0,
    "filters": {
      "target_process": ["nginx", "curl"],
      "ignore_process": ["ecapture"]
    }
  }' \
  http://127.0.0.1:28256/tls

A typical success response:

{
  "code": 0,
  "module_type": "openssl",
  "msg": "RespOK",
  "data": null
}

4.1.2 Using Go

package main

import (
    "bytes"
    "encoding/json"
    "log"
    "net/http"
)

type TlsConfig struct {
    Pid           uint64 `json:"pid"`
    Uid           uint64 `json:"uid"`
    Debug         bool   `json:"debug"`
    Hex           bool   `json:"hex"`
    Btf           uint8  `json:"btf"`
    PerCpuMapSize int    `json:"per_cpu_map_size"`
    TruncateSize  uint64 `json:"truncate_size"`
    // Add real TLS config fields here to match user/config/OpensslConfig
}

type Resp struct {
    Code       uint8       `json:"code"`
    ModuleType string      `json:"module_type"`
    Msg        string      `json:"msg"`
    Data       interface{} `json:"data"`
}

func main() {
    cfg := TlsConfig{
        Pid:           0,
        Uid:           0,
        Debug:         false,
        Hex:           false,
        Btf:           0,
        PerCpuMapSize: 1024,
        TruncateSize:  0,
    }

    body, _ := json.Marshal(cfg)
    resp, err := http.Post(
        "http://127.0.0.1:28256/tls",
        "application/json",
        bytes.NewReader(body),
    )
    if err != nil {
        log.Fatalf("request failed: %v", err)
    }
    defer resp.Body.Close()

    var r Resp
    if err := json.NewDecoder(resp.Body).Decode(&r); err != nil {
        log.Fatalf("decode resp failed: %v", err)
    }

    log.Printf("status=%d code=%d module=%s msg=%s",
        resp.StatusCode, r.Code, r.ModuleType, r.Msg)
}

4.2 GoTLS module (`/gotls`)

Used for Go applications that use the Go TLS stack.

curl -v \
  -H "Content-Type: application/json" \
  -X POST \
  --data '{
    "pid": 0,
    "uid": 0,
    "debug": true,
    "per_cpu_map_size": 2048
  }' \
  http://127.0.0.1:28256/gotls

4.3 GnuTLS module (`/gnutls`)

Used for applications that rely on GnuTLS.

curl -v \
  -H "Content-Type: application/json" \
  -X POST \
  --data '{
    "pid": 0,
    "uid": 0,
    "debug": false
  }' \
  http://127.0.0.1:28256/gnutls

4.4 NSS / NSPR module (`/nss` / `/nspr`)

Used for modules based on NSS / NSPR (e.g. some browsers or system components).

curl -v \
  -H "Content-Type: application/json" \
  -X POST \
  --data '{
    "pid": 0,
    "uid": 0,
    "debug": false
  }' \
  http://127.0.0.1:28256/nss

/nspr is identical, only the path changes:

curl -v \
  -H "Content-Type: application/json" \
  -X POST \
  --data '{ ... }' \
  http://127.0.0.1:28256/nspr

4.5 Bash command capture module (Linux only: `/bash`)

Not available on Android GKI.
If your management tool targets multiple platforms, detect the platform before calling this endpoint.

curl -v \
  -H "Content-Type: application/json" \
  -X POST \
  --data '{
    "pid": 0,
    "uid": 0,
    "debug": true
  }' \
  http://127.0.0.1:28256/bash

4.6 MySQLd module (Linux only: `/mysqld`)

curl -v \
  -H "Content-Type: application/json" \
  -X POST \
  --data '{
    "pid": 0,
    "uid": 0,
    "debug": false
  }' \
  http://127.0.0.1:28256/mysqld

4.7 PostgreSQL module (Linux only: `/postgress`)

The path is spelled /postgress with a double “s”.

curl -v \
  -H "Content-Type: application/json" \
  -X POST \
  --data '{
    "pid": 0,
    "uid": 0,
    "debug": false
  }' \
  http://127.0.0.1:28256/postgress

5. Error handling and retry strategy

5.1 Common status codes

You can combine HTTP status and the code field from the JSON response:

HTTP status	`code`	Meaning	Client suggestion
200	0	Success, configuration accepted and applied	Normal flow
200	4	JSON decode failed (syntax error / type mismatch)	Fix request body and retry
200	5	Config check failed (missing field, invalid value)	Fix config content based on logs and retry
200	6	Internal update channel is full / busy	Wait and retry later
200	1 / 2	Invalid request / internal server error	Log and alert as needed

5.2 Recommended calling pattern

Configuration updates are management operations; they should not be called at high frequency.
When you see HTTP 503 with code == 6:
- Use a backoff strategy (e.g. exponential backoff) and retry later.
On the caller side, keep a copy of the last known-good config:
- If a new config causes unexpected behavior, you can quickly rollback by posting the previous config again.

6. Platform compatibility (Linux vs Android)

If your tool only targets Linux, you can use all paths listed for Linux.
If your tool must work on both Linux and Android GKI:
1. Determine the platform using CLI flags, environment variables, or your own detection mechanism.
2. Only call /bash, /mysqld, /postgress on Linux, because they do not exist on Android.
3. TLS / GoTLS / GnuTLS / NSS paths are shared and can be used on both platforms.

7. Versioning and field alignment

Different eCapture versions may slightly change config structures in user/config/*.go.
Recommended approach:
- In your client code, define config structs that mirror the current eCapture version (field names and types match).
- Or use dynamic JSON (e.g. map[string]any) and only fill fields that you really need.
- If you need to support multiple eCapture versions, build your own compatibility layer (e.g. version negotiation or feature flags).

8. Changelog

Version	Date	Description
0.1.0	2025-12-07	Initial version of the remote config API doc