This document is a configuration reference for SPIRE Server. It includes information about plugin types, built-in plugins, the server configuration file, plugin configuration, and command line options for spire-server commands.

Plugin types

Built-in plugins

Server configuration file

The following table outlines the configuration options for SPIRE server. These may be set in a top-level server { ... } section of the configuration file. Most options have a corresponding CLI flag which, if set, takes precedence over values defined in the file.

SPIRE configuration files may be represented in either HCL or JSON. Please see the sample configuration file section for a complete example.

If the -expandEnv flag is passed to SPIRE, $VARIABLE or ${VARIABLE} style environment variables are expanded before parsing. This may be useful for templating configuration files, for example across different trust domains, or for inserting secrets like database connection passwords.

Plugin configuration

The server configuration file also contains a configuration section for the various SPIRE server plugins. Plugin configurations live inside the top-level plugins { ... } section, which has the following format:

plugins {
    pluginType "pluginName" {
        ...
        plugin configuration options here
        ...
    }
}

The following configuration options are available to configure a plugin:

Please see the built-in plugins section below for information on plugins that are available out-of-the-box.

Federation configuration

SPIRE Server can be configured to federate with others SPIRE Servers living in different trust domains. This allows a trust domain to authenticate identities issued by other SPIFFE authorities, allowing workloads in one trust domain to securely autenticate workloads in a foreign trust domain. A key element to achieve federation is the use of SPIFFE bundle endpoints, these are resources (represented by URLs) that serve a copy of a trust bundle for a trust domain. Using the federation section you will be able to configure the bundle endpoints as follows:

server {
    .
    .
    .
    federation {
        bundle_endpoint {
            address = "0.0.0.0"
            port = 8443
            acme {
                domain_name = "example.org"
                email = "mail@example.org"
            }
        }
        federates_with "domain1.test" {
            bundle_endpoint {
                address = "1.2.3.4"
                port = 8443
                use_web_pki = true
            }
        }
        federates_with "domain2.test" {
            bundle_endpoint {
                address = "5.6.7.8"
                port = 8443
                spiffe_id = "spiffe://domain2.test/beserver"
            }
        }
    }
}

Worth noting that the federation.bundle_endpoint and federation.federates_with sections are both optional.

Configuration options for federation.bundle_endpoint

This optional section contains the configurables used by SPIRE Server to expose a bundle endpoint.

Configuration options for federation.bundle_endpoint.acme

Configuration options for federation.federates_with["<trust domain>"].bundle_endpoint

The optional federates_with section is a map of bundle_endpoint configurations keyed by the name of the "<trust domain>" this server wants to federate with. This bundle_endpoint configurations have the following configurables:

To clarify, address and port are used to form the bundle endpoint URL to federate with "<trust domain>" as follows:

https://<address>:<port>/

Telemetry configuration

Please see the Telemetry Configuration guide for more information about configuring SPIRE Server to emit telemetry.

Health check configuration

The server can expose an additional endpoint that can be used for health checking. It is enabled by setting listener_enabled = true. Currently it exposes 2 paths: one for liveness (is server up?) and one for readiness (is server ready to serve requests?). By default, health checking endpoint will listen on localhost:80, unless configured otherwise.

health_checks {
        listener_enabled = true
        bind_address = "localhost"
        bind_port = "8080"
        live_path = "/live"
        ready_path = "/ready"
}

Command line options

spire-server run

Most of the configuration file above options have identical command-line counterparts. In addition, the following flags are available.

spire-server token generate

Generates one node join token and creates a registration entry for it. This token can be used to bootstrap one spire-agent installation. The optional -spiffeID can be used to give the token a human-readable registration entry name in addition to the token-based ID.

spire-server entry create

Creates registration entries.

spire-server entry update

Updates registration entries.

spire-server entry delete

Deletes a specified registration entry.

spire-server entry show

Displays configured registration entries.

spire-server bundle show

Displays the bundle for the trust domain of the server.

spire-server bundle list

Displays federated bundles.

spire-server bundle set

Creates or updates bundle data for a trust domain. This command cannot be used to alter the server trust domain bundle, only bundles for other trust domains.

spire-server bundle delete

Deletes bundle data for a trust domain. This command cannot be used to delete the server trust domain bundle, only bundles for other trust domains.

spire-server agent evict

De-attesting an already attested node given its spiffeID.

spire-server agent list

Displays attested nodes.

spire-server agent show

Displays the details (including node selectors) of an attested node given its spiffeID.

spire-server healthcheck

Checks SPIRE server’s health.

spire-server validate

Validates a SPIRE server configuration file. Arguments are the same as spire-server run. Typically, you may want at least:

spire-server x509 mint

Mints an X509-SVID.

spire-server jwt mint

Mints a JWT-SVID.

spire-server experimental bundle show

(Experimental) This command has been deprecated and will be removed in a future release. Its functionality was subsumed into the bundle show command.

Displays the bundle for the trust domain of the server as a JWKS document.

spire-server experimental bundle list

(Experimental) This command has been deprecated and will be removed in a future release. Its functionality was subsumed into the bundle list command.

Displays bundles from other trust domains as JWKS documents.

spire-server experimental bundle set

(Experimental) This command has been deprecated and will be removed in a future release. Its functionality was subsumed into the bundle set command.

Creates or updates bundle data for a trust domain. This command cannot be used to alter the server trust domain bundle, only bundles for other trust domains.

Bundle data read from stdin or the path is expected to be a JWKS document.

JSON object for -data

A JSON object passed to -data for entry create/update expects the following form:

{
    "entries":[]
}

The entry object is described by RegistrationEntry in the common protobuf file.

Note: to create node entries, set parent_id to the special value spiffe://<your-trust-domain>/spire/server. That’s what the code does when the -node flag is passed on the cli.

Sample configuration file

This section includes a sample configuration file for formatting and syntax reference

server {
    trust_domain = "example.org"

    bind_address = "0.0.0.0"
    bind_port = "8081"
    log_level = "INFO"
    data_dir = "/opt/spire/.data/"
    registration_uds_path = "/opt/spire/registration.sock"
    default_svid_ttl = "6h"
    ca_ttl = "72h"
    ca_subject {
        country = ["US"]
        organization = ["SPIRE"]
        common_name = ""
    }
}

telemetry {
    Prometheus {
        port = 1234
    }
}

plugins {
    DataStore "sql" {
        plugin_data {
            database_type = "sqlite3"
            connection_string = "/opt/spire/.data/datastore.sqlite3"
        }
    }
    NodeAttestor "join_token" {
        plugin_data {}
    }
    NodeResolver "noop" {
        plugin_data {}
    }
    KeyManager "disk" {
        plugin_data {
            keys_path = "/opt/spire/.data/keys.json"
        }
    }
}

Further reading

• SPIFFE Reference Implementation Architecture
• Design Document: SPIFFE Reference Implementation (SRI)