Configuration Reference

SPORK CA can be configured through CLI flags, environment variables, and a TOML configuration file. This page documents every option.

Configuration Methods

Settings are resolved in the following order of precedence (highest first):

CLI flags — Override everything. Passed directly on the command line.
Environment variables — Override config file and defaults.
Config file — /etc/spork/config.toml (or path set by --config).
Built-in defaults — Sensible values that work for development and simple deployments.

Tip: For production deployments, use the config file for base settings and environment variables for secrets (such as SPORK_KEYSTORE_PASSPHRASE).

Environment Variables

Core

Variable	Description	Default
`SPORK_DATA_DIR`	Root directory for CA data, keys, and certificates	`/opt/spork-acme/data`
`SPORK_DB_PATH`	Path to the SQLite database file	`$SPORK_DATA_DIR/spork.db`
`DATABASE_URL`	PostgreSQL connection string (spork-web only)	—
`SPORK_LOG_LEVEL`	Log verbosity: `trace`, `debug`, `info`, `warn`, `error`	`info`
`SPORK_LOG_FORMAT`	Log format: `text` or `json`	`text`
`RUST_BACKTRACE`	Enable Rust backtraces: `1` or `full`	`0`

Server Ports

Variable	Description	Default
`SPORK_BIND_ADDR`	IP address to bind all listeners to	`0.0.0.0`
`SPORK_ACME_PORT`	ACME server HTTPS port	`6446`
`SPORK_EST_PORT`	EST server port	`8443`
`SPORK_OCSP_PORT`	OCSP responder port	`8888`
`SPORK_CRL_PORT`	CRL distribution point HTTP port	`8889`
`SPORK_API_PORT`	REST API port (mTLS-protected)	`9443`

TLS

Variable	Description	Default
`SPORK_TLS_CERT`	Path to the server TLS certificate (PEM)	Auto-generated self-signed
`SPORK_TLS_KEY`	Path to the server TLS private key (PEM)	Auto-generated
`SPORK_TLS_CA`	Path to the CA certificate for client verification	Uses the CA's own certificate
`SPORK_TLS_REQUIRE_CLIENT_CERT`	Require mTLS client certificates: `true` or `false`	`false`

HSM (PKCS#11)

Variable	Description	Default
`SPORK_HSM_MODULE`	Path to the PKCS#11 shared library	—
`SPORK_HSM_SLOT`	HSM slot number	`0`
`SPORK_HSM_PIN`	HSM PIN (use env var, never config file)	—

ACME-Specific

Variable	Description	Default
`SPORK_KEYSTORE_PASSPHRASE`	Passphrase for the encrypted keystore. Required for non-interactive (service) mode. In interactive mode, the passphrase is prompted.	—

Security: Never place SPORK_KEYSTORE_PASSPHRASE or SPORK_HSM_PIN in a config file. Use environment variables or a secrets manager. For systemd services, set them via EnvironmentFile= with restricted permissions.

Config File

The default config file location is /etc/spork/config.toml. Override with --config /path/to/config.toml.

Below is a complete example covering all sections:

# /etc/spork/config.toml

[general]
data_dir = "/opt/spork-acme/data"
log_level = "info"           # trace, debug, info, warn, error
log_format = "text"          # text, json

[database]
# SQLite (default)
path = "/opt/spork-acme/data/spork.db"

# PostgreSQL (spork-web only, uncomment to use)
# url = "postgresql://spork:password@localhost:5432/spork"

[acme]
bind = "0.0.0.0"
port = 6446
# External URLs used in issued certificates
cdp_url = "http://crl.example.com/spork.crl"
aia_base_url = "http://aia.example.com/"
# ACME directory metadata
terms_of_service = "https://example.com/tos"
website = "https://example.com"

[tls]
cert = "/etc/spork/tls/server.pem"
key = "/etc/spork/tls/server-key.pem"
ca = "/etc/spork/tls/ca.pem"
require_client_cert = false   # Set true to enforce mTLS on all endpoints

[logging]
# Syslog integration (optional)
syslog = false
syslog_facility = "local0"
# File logging (optional, in addition to stdout)
file = "/var/log/spork/spork.log"
max_size_mb = 100
max_backups = 5

CLI Flags

Common flags for spork-acme:

Flag	Description	Example
`-s, --state-dir`	Path to the state/data directory	`spork-acme -s /opt/spork-acme`
`--bind`	IP address to bind to	`spork-acme --bind 127.0.0.1`
`--port`	HTTPS port for the ACME server	`spork-acme --port 443`
`--cdp-url`	CRL Distribution Point URL embedded in issued certificates	`--cdp-url http://crl.example.com/spork.crl`
`--aia-base-url`	Authority Information Access base URL for CA certificate and OCSP	`--aia-base-url http://aia.example.com/`
`--config`	Path to config file (overrides default `/etc/spork/config.toml`)	`--config /opt/spork/my-config.toml`

mTLS Setup

SPORK CA uses mutual TLS (mTLS) with admin certificates to authenticate destructive operations. Certificates contain a Policy OID that determines the access level:

Admin Certificate Hierarchy

Level	Policy OID	Created Via	Capabilities
SuperAdmin	`.1.20.4`	Initial setup (inception)	Full control: factory reset, issue admin certs, all operations
Admin	`.1.20.3`	WebUI (by SuperAdmin)	Revoke certs, manage CRLs, issue end-entity certs
Operator	`.1.20.2`	WebUI	Issue certs, view logs
Viewer	`.1.20.1`	WebUI	View-only access (status, certificates, logs)

Importing PFX in Your Browser

To access the admin web UI, import the admin PFX certificate into your browser:

Chrome/Edge: Settings → Privacy and Security → Security → Manage certificates → Import. Select the .pfx file and enter the passphrase.
Firefox: Settings → Privacy & Security → View Certificates → Your Certificates → Import. Select the .pfx file and enter the passphrase.
Safari: Double-click the .pfx file to add it to Keychain Access. Enter the passphrase when prompted.

Once imported, navigate to the admin UI (e.g., https://your-server:6446/admin). The browser will prompt you to select the client certificate. Choose the SPORK admin certificate.

Note: The admin UI is view-only by design. All destructive operations (revocation, CRL signing, admin cert management) must be performed via the mTLS-authenticated REST API or the CLI with an admin PFX.

Production Checklist

Before deploying SPORK CA in production, verify the following:

Item	Action	Why
Bind address	Set `SPORK_BIND_ADDR` to a specific interface (not `0.0.0.0`)	Limit network exposure
mTLS enforcement	Set `SPORK_TLS_REQUIRE_CLIENT_CERT=true` for admin endpoints	Prevent unauthenticated access to destructive operations
systemd service	Install the `spork-acme.service` unit file and enable it	Automatic startup, restart on failure, resource limits
Log rotation	Configure `[logging]` section or use logrotate for `/var/log/spork/`	Prevent disk exhaustion
Keystore passphrase	Set `SPORK_KEYSTORE_PASSPHRASE` via `EnvironmentFile=` with mode `0600`	Non-interactive startup without exposing secrets in process list
CRL timer	Enable `spork-acme-crl.timer` for periodic CRL regeneration	Ensure clients can check revocation status offline
Backup schedule	Configure automated backups via `spork-acme` → Backup → Schedule	Disaster recovery
Firewall	Allow only required ports (6446 for ACME, 8888 for OCSP, 8889 for CRL)	Minimize attack surface
File permissions	Ensure `/opt/spork-acme/data/` is owned by the service user with mode `0700`	Protect private keys and database

Important: Run the security audit from the auto-detect menu (sudo spork-acme → Security → Audit) to verify your deployment meets hardening requirements.