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.

Profiling Names

These are the available profiles that can be set in the profiling_freq configuration value:

• goroutine
• threadcreate
• heap
• block
• mutex
• trace
• cpu

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. SPIRE supports configuring federation relationships in the SPIRE Server configuration file (static relationships) and through the Trust Domain API (dynamic relationships). This section describes how to configure statically defined relationships in the configuration file.

Note: static relationships override dynamic relationships. If you need to configure dynamic relationships, see the federation command. Static relationships are not reflected in the federation command.

Configuring a federated trust domain allows a trust domain to authenticate identities issued by other SPIFFE authorities, allowing workloads in one trust domain to securely authenticate 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 set up SPIRE as a SPIFFE bundle endpoint server and also configure the federated trust domains that this SPIRE Server will fetch bundles from.

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_url = "https://1.2.3.4:8443"
            bundle_endpoint_profile "https_web" {}
        }
        federates_with "domain2.test" {
            bundle_endpoint_url = "https://5.6.7.8:8443"
            bundle_endpoint_profile "https_spiffe" {
                endpoint_spiffe_id = "spiffe://domain2.test/beserver"
            }
        }
    }
}

The federation.bundle_endpoint section is optional and is used to set up a SPIFFE bundle endpoint server in SPIRE Server. The federation.federates_with section is also optional and is used to configure the federation relationships with foreign trust domains. This section is used for each federated trust domain that SPIRE Server will periodically fetch the bundle.

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 profile configurations keyed by the name of the "<trust domain>" this server wants to federate with. This section has the following configurables:

SPIRE supports the https_web and https_spiffe bundle endpoint profiles.

The https_web profile does not require additional settings.

Trust domains configured with the https_spiffe bundle endpoint profile must specify the expected SPIFFE ID of the remote SPIFFE bundle endpoint server using the endpoint_spiffe_id setting as part of the configuration.

For more information about the different profiles defined in SPIFFE, along with the security considerations for setting up SPIFFE Federation, please refer to the SPIFFE Federation standard.

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.

Running SPIRE Server as a Windows service

On Windows platform, SPIRE Server can optionally be run as a Windows service. When running as a Windows service, the only command supported is the run command.

Note: SPIRE does not automatically create the service in the system, it must be created by the user. When starting the service, all the arguments to execute SPIRE Server with the run command must be passed as service arguments.

Example to create the SPIRE Server Windows service

> sc.exe create spire-server binpath=c:\spire\bin\spire-server.exe

Example to run the SPIRE Server Windows service

> sc.exe start spire-server run -config c:\spire\conf\server\server.conf

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 count

Displays the total number of registration entries.

spire-server entry delete

Deletes a specified registration entry.

spire-server entry show

Displays configured registration entries.

spire-server bundle count

Displays the total number of bundles.

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 federation create

Creates a dynamic federation relationship with a foreign trust domain.

spire-server federation delete

Deletes a dynamic federation relationship.

spire-server federation list

Lists all the dynamic federation relationships.

spire-server federation refresh

Refreshes the bundle from the specified federated trust domain.

spire-server federation show

Shows a dynamic federation relationship.

spire-server federation update

Updates a dynamic federation relationship with a foreign trust domain.

spire-server agent ban

Ban attested node given its spiffeID. A banned attested node is not able to re-attest.

spire-server agent count

Displays the total number of attested nodes.

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.

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/"
    default_x509_svid_ttl = "6h"
    default_jwt_svid_ttl = "5m"
    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 {}
    }
    KeyManager "disk" {
        plugin_data {
            keys_path = "/opt/spire/.data/keys.json"
        }
    }
}

Further reading

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