Skip to content

remote-config-update-api.md

Latest commit

 

History

History
410 lines (318 loc) · 12.1 KB

remote-config-update-api.md

File metadata and controls

410 lines (318 loc) · 12.1 KB

eCapture Remote Configuration Update API

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 listen address: http://127.0.0.1:28256
  • You can change it via CLI flag --listen, for example: --listen 0.0.0.0:28256
  • 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