Tenzir provides a REST API to interact with a server node. The
plugin implements the API as a dedicated
component that can run in multiple ways.
There exist two ways to run the
web plugin: either as a separate process or
embedded inside a Tenzir node:
Running the REST API as dedicated process gives you more flexibility with respect to deployment, fault isolation, and scaling. An embedded setup offers higher throughput and lower latency between the REST API and the other Tenzir components.
To run the REST API as dedicated process, use the
web server command:
tenzir-ctl web server --certfile=/path/to/server.certificate --keyfile=/path/to/private.key
To run the server within the main Tenzir process, use the
tenzir-node --commands="web server [...]"
The server will only accept TLS requests by default. To allow clients to connect
successfully, you need to pass a valid certificate and corresponding private key
Clients must authenticate all requests with a valid token. The token is a short
string that clients put in the
X-Tenzir-Token request header. You can generate
a valid token on the command line:
tenzir-ctl web generate-token
For local testing and development, generating suitable certificates and tokens can be a hassle. For this scenario, you can start the server in developer mode where it accepts plain HTTP connections are does not perform token authentication.
There exist four modes to start the REST API, each of which suits a slightly different use case.
The developer mode bypasses encryption and authentication token verification.
--mode=dev to start the REST API in developer mode:
tenzir-ctl web server --mode=dev
The server mode reflects the "traditional" mode of operation where Tenzir binds to a network interface. This mode only accepts HTTPS connections and requires a valid authentication token for every request. This is the default mode of operation.
--mode=server to start the REST API in server mode:
tenzir-ctl web server --mode=server
Upstream TLS Mode
The upstream TLS mode is suitable when Tenzir sits upstream of a separate TLS terminator that is running on the same machine. This kind of setup is commonly encountered when running nginx as a reverse proxy.
Tenzir only listens on localhost addresses, accepts plain HTTP but still checks authentication tokens.
--mode=upstream to start the REST API in server mode:
tenzir-ctl web server --mode=upstream
Mutual TLS Mode
The mutual TLS mode is suitable when Tenzir sits upstream of a separate TLS terminator that may be running on a different machine. This setup is commonly encountered when running nginx as a load balancer. Tenzir would typically be configured to use a self-signed certificate in this setup.
Tenzir only accepts HTTPS requests, requires TLS client certificates for incoming connections, and requires valid authentication tokens for any authenticated endpoints.
--mode=mtls to start the REST API in server mode:
tenzir-ctl web server --mode=mtls
There are two ways to scale the REST API, shall it be the bottleneck. You can either spawn more REST API actors within Tenzir and expose them at different ports, or you can spawn more dedicated web server processes:
We do not anticipate that the web frontend will be on the critical path, since the web server itself performs very little work. But we get this form of scaling "for free" as a byproduct of Tenzir's actor model architecture, which is why we mentioned it here.