Skip to main content

Operator API

The Operator API provides an interface for operators to interact with the BuilderNet node. It allows operators to observe the node's status, restart services, trigger a graceful reboot, and apply configuration changes.

The service listening on port 3535. It uses the system-api codebase (Golang).

Functionality for operators​

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

Access & Security​

The Operator API...

  • listens on port 3535.
  • is designed to be used by the operator only, and the port should be firewalled to restrict public access.
  • supports HTTP Basic Auth to restrict access, and TLS for secure communication.
  • uses the system-api codebase (Golang).

Basic auth​

The Operator API supports HTTP Basic Auth for authentication. The secret is configured by the operator using the /api/v1/set-basic-auth endpoint.

warning

Once an operator configures basic auth, the secret not recoverable! If an operator looses the secret, the whole instance will need to be terminated and recreated.

Live configuration​

The Operator API is configured with a system-api.toml config file. The configuration used in BuilderNet v1.2.1 is available at the following link: github.com/flashbots/meta-confidential-compute@f1b1770 /recipes-core/system-api/files/systemapi-config.toml.mustache

[general]
listen_addr = "0.0.0.0:3535"
pipe_file = "/var/volatile/system-api.fifo"
pprof = false
log_json = true
log_debug = false

# HTTP Basic Auth
basic_auth_secret_path = "/persistent/system-api/basic-auth-secret"
basic_auth_secret_salt = "1_drink_coffee:|"

# TLS configuration
tls_enabled = true
tls_create_if_missing = true
tls_cert_hosts = ["127.0.0.1","localhost","{{public_ip}}","{{dns_name}}"]
tls_cert_path = "/persistent/system-api/cert.pem"
tls_key_path = "/persistent/system-api/key.pem"

[actions]
reboot = "reboot"
rbuilder_restart = "/etc/init.d/rbuilder restart"
rbuilder_stop = "/etc/init.d/rbuilder stop"
fetch_config = "/etc/init.d/fetch-config start"
rbuilder_bidding_restart = "/etc/init.d/rbuilder-bidding restart"
ssh_stop = "/etc/init.d/dropbear stop"
ssh_start = "/etc/init.d/dropbear start"

[file_uploads]
rbuilder_blocklist = "/persistent/rbuilder/rbuilder.blocklist.json"

Example usage​

# Set the initial basic auth secret (from here on out, authentication is required for all API requests)
$ curl --insecure -v --data "basic_auth_secret" https://instance_ip:3535/api/v1/set-basic-auth

# Update the basic auth secret
$ curl --insecure -v --user admin:old_basic_auth_secret --data "new_basic_auth_secret" https://instance_ip:3535/api/v1/set-basic-auth

# Get logs via API
$ curl --insecure --user admin:basic_auth_secret https://instance_ip:3535/logs

# Liveness API
$ curl --insecure --user admin:basic_auth_secret https://instance_ip:3535/livez

# Execute 'rbuilder_restart' action
$ curl --insecure --user admin:basic_auth_secret https://instance_ip:3535/api/v1/actions/rbuilder_restart

# Upload file
$ curl --insecure --user admin:basic_auth_secret --data-binary "@file.json" https://instance_ip:3535/api/v1/file-upload/rbuilder_blocklist

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