Skip to main content

System API

System API is the primary interface between node operators and the services running inside the TEE instance.

Goals​

  1. Basic observability (i.e. startup stages, errors, etc.)
  2. Restart services
  3. Trigger a graceful reboot
  4. Apply configuration

Code​

The service is written in Golang and the code is here: github.com/flashbots/system-api

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, and TLS for secure communication.

Information exposed as logs 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

# Maximum number of entries in the log
log_max_entries = 1000

# 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

# TLS configuration
tls_enabled = true
tls_create_if_missing = true
tls_cert_hosts = ["localhost", ""]
tls_cert_path = "cert.pem"
tls_key_path = "key.pem"

[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