Skip to main content

System API

System API is the single interface between services running inside TDX and the operator. The code can be found in github.com/flashbots/system-api.

Design goals​

  1. Provide basic visibility into TDX system to the operator (assuming no access to logs or other data).
  2. Allow operator to restart services and to trigger a graceful reboot.
  3. Allow operator to apply configuration.

Key functions​

System API provides the following functionality:

  • Event log: Services inside a TDX instance can record events they want exposed to the operator. Useful to record service startup/shutdown, status, errors, progress updates, etc.
  • Actions: Ability to execute pre-defined shell commands via API, such as rebooting the instance or restarting the rbuilder service.
  • Configuration: Ability to upload files to pre-defined destinations.

The API supports HTTP Basic Auth to restrict access.

Information sent to the operator currently only includes service startup information. This might be expanded over time to include non-sensitive event information, certain metrics, and/or system status details.

Example usage​

The following shell snippet shows the general use of the System API:

Example configuration​

[general]
listen_addr = "0.0.0.0:3535"
pipe_file = "pipe.fifo"
pprof = true
log_json = false
log_debug = true

# HTTP Basic Auth
basic_auth_secret_path = "basic-auth-secret.txt" # basic auth is supported if a path is provided
basic_auth_secret_salt = "D;%yL9TS:5PalS/d"      # use a random string for the salt

# HTTP server timeouts
# http_read_timeout_ms = 2500
# http_write_timeout_ms = 2500

[actions]
echo_test = "echo test"
# reboot = "reboot"
# rbuilder_restart = "/etc/init.d/rbuilder restart"
# rbuilder_stop = "/etc/init.d/rbuilder stop"

[file_uploads]
testfile = "/tmp/testfile.txt"

Example usage​

# Start the API server
$ make run

# Add events
$ echo "hello world" > pipe.fifo
$ curl localhost:3535/api/v1/new_event?message=this+is+a+test

# Execute actions
$ curl -v localhost:3535/api/v1/actions/echo_test

# Upload files
$ curl -v -X POST -d "@README.md" localhost:3535/api/v1/file-upload/testfile

# Get event log
$ curl localhost:3535/logs
2024-11-05T22:03:23Z     hello world
2024-11-05T22:03:26Z     this is a test
2024-11-05T22:03:29Z     [system-api] executing action: echo_test = echo test
2024-11-05T22:03:29Z     [system-api] executing action success: echo_test = echo test
2024-11-05T22:03:31Z     [system-api] file upload: testfile = /tmp/testfile.txt
2024-11-05T22:03:31Z     [system-api] file upload success: testfile = /tmp/testfile.txt - content: 1991 bytes

Contribute to System-API on Github: https://github.com/flashbots/system-api