Controller Configuration Reference
OpenZiti uses configuration files for controllers that are in the YAML format. All configuration files are also subject to a set of conventions such as environment variable substitution, identity sections, and addressing formats.
The controller configuration file has several top level configuration sections that group together related configuration settings.
ctrl- define control channel listener
db- specifies database file location
edge- configures edge specific functionality
events- allows configuration of event output
healthChecks- enables controller database health checks for transactions
identity- configures the certificates used for outbound client connections, server listening, and CA bundles
network- set network level cost values
profile- enables profiling of controller memory and CPU statistics
trace- adds a peek handler to all controller messaging for debug purposes
web- configures API presentation exposure
v- A special section to note the version of the configuration file, only
v: 3is currently supported
The standard OpenZiti experience minimally requires the following sections:
Of those values, to start the controller only the
identity sections are required. However, not
edge section will start the controller in "fabric only" mode and will not support any edge functionality
or concepts (identities, JWT enrollment, 3rd Party CAs, policies, etc.). Not including the
web section will result in
none of the REST APIs (Fabric Management API, Edge Client API, Edge Management API, Health Check API) being started.
Without the Edge and Fabric Management APIs running administration of the network will be impossible. Without the Edge
Client API running it will be impossible for Edge clients to connect to services.
Example Minimum Controller Configuration:
- name: all-apis-localhost
- interface: 127.0.0.1:1280
- binding: fabric
- binding: edge-management
- binding: edge-client
ctrl section configures how the controller will listen for incoming connections from routers. This includes the
protocol(s) used for router connections and how those connections are managed.
listener- (required) is in the format of
<protocol>:<interface>:<port>format. The value set here must be resolvable by routers and correspond the routers
ctrl.endpointconfiguration value. See addressing.
options- a set of option which includes the below options and those defined in channel options
newListener- (optional) an
<protocol>:<interface>:<port>address that is sent to routers to indicate a controller address migration. Should only be specified when the new listener address is reachable as clients will begin to use the new value on restart
Example w/o options:
Example w/ options:
db section is a single scalar value that defines the path to the database file that the controller should use.
OpenZiti uses a file backed in memory database. This path may be on the same or different drive. This section is
edge section instructs the controller to start the edge components. If the section is not defined, all edge
functionality will be disabled. This includes all features associated with identities (e.g. identity enrollment), 3rd
Party CAs, policies, edge router connections, posture checks, and more. It is highly unlikely that this section should
edge section also has the following subsections:
api- (required) defines API specific configuration
enrollment- (required) defines enrollment specific configuration
Example Minimum Edge:
Example Fully Defined:
api section within the
edge section defines API specific functionality.
activityUpdateInterval- (optional) the interval used to buffer API Session usage notices
sessionTimeout- (optional) The amount of time an Edge API Session remains alive after the last REST API Request was processed or the last Edge Router connection for an API Session was closed
address- (required) the
<host>:<port>combination that should be used to externally resolve to the Edge Client API
activityUpdateInterval, Edge Routers report connected API Sessions periodically and the controller tracks REST API
activityUpdateInterval defines the interval those updates are collated and buffered over. This is done to
reduce the number of database writes required to persist API Session activity data. During the interval period the
controller will buffer updates and flush at the end. Increasing this interval may increase the chance of unsaved updates
on controller crash or kill. Decreasing it will increase the frequency of database writes. The default should be
address setting is unique as it must match the
address in a
bindPoint for the
edge-client API. This is to
ensure that responses and data persisted outside the system can reach the controller. An example of this is
enrollment JWTs that contain the URL that is used to complete enrollment via the Edge Client API.
enrollment section under
edge defines values that pertain specifically to identity and router enrollment. This
includes the certificate and private key used to sign certificates as well as enrolment JWT lifetimes.
The enrolment section has these subsection:
signingCert- (required) defines the certificate and key used to sign identity and router certificates
edgeIdentity- (optional) controls identity enrollment options
edgeRouter- (optional) controls router enrollment options
An object defining the
key used to issue certificates to identities and routers.
cert- (required) the x509 PEM formatted certificate of the CA that the controller will use to issue edge identity certificates
key- (required) the x509 PEM formatted private key for the certificate defined in
OpenZiti clients rely on the controller to provide a bundle of trusted certificates during enrollment. The bundle is specified by the
identity.ca field and points to a file on the server containing the bundle of trusted certificates. The signing certificate must be included in this file.
edgeIdentity section controls the lifetime of identity enrollment JWTs. It has only one value:
duration- (optional) the lifetime of identity enrollment JWTs
edgeRouter section controls the lifetime of router enrollment JWTs. It has only one value:
duration- (optional) the lifetime of router enrollment JWTs
events section allows for the definition of multiple event loggers with their own handler and event subscriptions.
Handlers define the type, format, and destination for events. Subscriptions handle which events are routed to the
handler. This allows different events to be output in different manners or to different locations.
events section is an array of named objects. The name (
jsonLogger in the example below) is used for
configuration error output only. Each logger has a
handler section. The
subscriptions section is
an array of objects with fields associated with the event type. Specifying an event type will cause it to be output via
the defined handler. If an event type is omitted, it will not be output. The list of valid event types and their options
is as follows:
edge.apiSessions- (optional) Edge API Session events
include- (optional) a string or array of strings that specify which API session events to include ("created" and/or " deleted")
edge.entityCounts- (optional) Edge entity counts (API Sessions, sessions, routers, etc.)
interval- (optional) the time interval to generate entity count events on (e.g. "5s", "5000ms", "1h")
edge.sessions- (optional) Edge Session events
include- (optional) a string or array of strings that specify which session events to include ("created" and/or "deleted")
fabric.circuits- (optional) Fabric circuit events
include- (optional) a string or array of strings that specify which circuit events to include ("created", " pathUpdated", " deleted", "failed")
fabric.links- - (optional) Fabric link events
fabric.routers- (optional) Fabric router events
fabric.usage- (optional) Fabric usage events
version- (optional) a string representing the value of the usage event to use ("2' or "3")
metrics- (optional) - System-wide metrics
sourceFilter- (optional) a regular expression to match the source name value on
metricFilter- (optional) a regular expression to match the metric name value on
services- (optional) Service events
The properties in the
handler section depend on handler
type (one of
- common properties for all handler types
format- (required) the format of events for the
path- (conditional) used the "file"
type, the path of the output file
amqp: note that queue and consumer options must match
url(required) the URL of the AMQP broker to connect to
queue(required) the name of the queue to publish events to
durable(optional) whether the queue should be durable between broker runs (default: true)
autoDelete(optional) whether the queue should be deleted when there are no consumers (default: false)
exclusive(optional) whether the queue should be exclusive to a single consumer (default: false)
noWait(optional) whether the controller should wait for the queue to confirm receipt of messages (default: false)
Example JSON File Logger:
- type: fabric.circuits
- type: fabric.links
- type: fabric.routers
- type: fabric.terminators
- type: metrics
- type: edge.sessions
- type: edge.apiSessions
- type: fabric.usage
- type: services
- type: edge.entityCounts
Example amqp Logger:
- type: fabric.usage
healthChecks section configures how often health checking is performed. As of now, health checks are limited
to ensuring the internal database has not deadlocked by attempting to acquire a locking transaction on some interval.
Health check status is reported externally on the
boltCheck- (optional) bbolt specific configuration
interval- (optional, 30s) how often to try entering a bolt read transaction
timeout- (optional, 15s) how long to wait for a transaction before timing out
initialDelay- (optional, 15s) how long to wait on startup before performing the first check
The identity section includes the default server certificate and private key used for services hosted by the controller,
alternate server certificates and keys to support SNI on hosted services, client certificate and private key when making
connections, and the
ca bundle that the controller will use when making connections and when bootstrapping identities
and routers. See the conventions that apply to all identity sections for field level detail.
network section sets network wide options.
minRouterCost- (optional, 10) the minimum router cost
routerConnectionChurnLimit- (optional, 1m) how often a new connection from a router can take over for an existing connection
intervalAgeThreshold- (optional, 80s) how old a batch of metrics must be before it's eligible to be emitted
metricsReportInterval- (optional, 1m) the frequency at which controller metrics events are emitted
The profile section allows for CPU (pprof) and memory (memprof) dumps to be created. CPU profiling is buffered by the application's runtime and output to the designated file. Memory profiling allows the interval memory profiling occurs at and is output. These settings are useful for debugging purposes only and should not be enabled in production environments without careful consideration.
path- (required) the path to output the pprof data
path- (required) the path to output the memprof data
intervalMs(optional, 15s) the frequency to output memprof data
trace section instructs the controller to output incoming and outgoing messaging it receives. This setting is
useful for debugging purposes only and should not be enabled in production environments without careful consideration.
path- (required) the file to output decoded messages to
web section follows the conventions of XWeb. The controller has the following APIs
health-checks- provides a health check API that allows remote parties to verify the health of the controller
fabric- the Fabric Management API which allows remote administration of a network
edge-management- the Edge Management API which allows remote administration of a network's edge components ( identities, policies, authentication, etc.)
edge-client- the Edge Client API which allows clients to authenticate and request connections to services
Each API may have their own options, but currently do not.
v section is used to detect if the version file is supported by the OpenZiti binary read it. The current and only
supported value is "3".