Skip to content

SPIRE Server Configuration Reference

Command line options, server.conf settings, and built-in plugins for SPIRE Server

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.

TypeDescription
DataStoreProvides persistent storage and HA features. Note: Pluggability for the DataStore is no longer supported. Only the built-in SQL plugin can be used.
KeyManagerImplements both signing and key storage logic for the server’s signing operations. Useful for leveraging hardware-based key operations.
CredentialComposerAllows customization of SVID and CA attributes.
NodeAttestorImplements validation logic for nodes attempting to assert their identity. Generally paired with an agent plugin of the same type.
UpstreamAuthorityAllows SPIRE server to integrate with existing PKI systems.
NotifierDeprecated: use BundlePublisher instead. Notified by SPIRE server for certain events that are happening or have happened. For events that are happening, the notifier can advise SPIRE server on the outcome.
BundlePublisherPublishes the local trust bundle to a store.
TypeNameDescription
DataStoresqlAn SQL database storage for SQLite, PostgreSQL and MySQL databases for the SPIRE datastore
KeyManageraws_kmsA key manager which manages keys in AWS KMS
KeyManagerdiskA key manager which manages keys persisted on disk
KeyManagerhashicorp_vaultA key manager which manages keys in HashiCorp Vault’s Transit Secret Engine
KeyManagerkmipA key manager which manages keys in a KMIP-compliant server over binary TTLV/TCP
KeyManagermemoryA key manager which manages unpersisted keys in memory
CredentialComposeruniqueidAdds the x509UniqueIdentifier attribute to workload X509-SVIDs.
NodeAttestoraws_iidA node attestor which attests agent identity using an AWS Instance Identity Document
NodeAttestorazure_imdsA node attestor which attests agent identity using the Azure Instance Metadata Service
NodeAttestorazure_msiA node attestor which attests agent identity using an Azure MSI token
NodeAttestorgcp_iitA node attestor which attests agent identity using a GCP Instance Identity Token
NodeAttestorjoin_tokenA node attestor which validates agents attesting with server-generated join tokens
NodeAttestork8s_psatA node attestor which attests agent identity using a Kubernetes Projected Service Account token
NodeAttestorsshpopA node attestor which attests agent identity using an existing ssh certificate
NodeAttestortpm_devidA node attestor which attests agent identity using a TPM that has been provisioned with a DevID certificate
NodeAttestorx509popA node attestor which attests agent identity using an existing X.509 certificate
UpstreamAuthoritydiskUses a CA loaded from disk to sign SPIRE server intermediate certificates.
UpstreamAuthorityaws_pcaUses a Private Certificate Authority from AWS Certificate Manager to sign SPIRE server intermediate certificates.
UpstreamAuthorityawssecretUses a CA loaded from AWS SecretsManager to sign SPIRE server intermediate certificates.
UpstreamAuthoritygcp_casUses a Private Certificate Authority from GCP Certificate Authority Service to sign SPIRE Server intermediate certificates.
UpstreamAuthorityvaultUses a PKI Secret Engine from HashiCorp Vault to sign SPIRE server intermediate certificates.
UpstreamAuthorityspireUses an upstream SPIRE server in the same trust domain to obtain intermediate signing certificates for SPIRE server.
UpstreamAuthoritycert-managerUses a referenced cert-manager Issuer to request intermediate signing certificates.
Notifiergcs_bundleDeprecated: use the gcp_cloudstorage BundlePublisher instead. A notifier that pushes the latest trust bundle contents into an object in Google Cloud Storage.
Notifierk8sbundleDeprecated: use the k8s_configmap BundlePublisher instead. A notifier that pushes the latest trust bundle contents into a Kubernetes ConfigMap.
BundlePublisheraws_s3Publishes the trust bundle to an Amazon S3 bucket.
BundlePublishergcp_cloudstoragePublishes the trust bundle to a Google Cloud Storage bucket.
BundlePublisheraws_rolesanywhere_trustanchorPublishes the trust bundle to an AWS IAM Roles Anywhere trust anchor.
BundlePublisherazure_blobPublishes the trust bundle to an Azure Blob Storage account.
BundlePublisherk8s_configmapPublishes the trust bundle to a Kubernetes ConfigMap.

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.

ConfigurationDescriptionDefault
admin_idsSPIFFE IDs that, when present in a caller’s X509-SVID, grant that caller admin privileges. The admin IDs must reside on the server trust domain or a federated one, and need not have a corresponding admin registration entry with the server.
agent_ttlThe TTL to use for agent SVIDsThe value of default_x509_svid_ttl
audit_log_enabledIf true, enables audit loggingfalse
audit_log_exclude_agent_syncIf true, omits successful GetBundle, GetFederatedBundle, GetAuthorizedEntries, and SyncAuthorizedEntries audit records regardless of caller identity. Error audit records and other RPCs retain their existing behavior. Only applies when audit_log_enabled is true.false
bind_addressIP address or DNS name of the SPIRE server0.0.0.0
bind_portHTTP Port number of the SPIRE server8081
ca_key_typeThe key type used for the server CA (both X509 and JWT), <rsa-2048|rsa-4096|ec-p256|ec-p384>ec-p256 (the JWT key type can be overridden by jwt_key_type)
ca_subjectThe Subject that CA certificates should use (see below)
ca_ttlThe default CA/signing key TTL24h
data_dirA directory the server can use for its runtime
default_x509_svid_ttlThe default X509-SVID TTL1h
default_jwt_svid_ttlThe default JWT-SVID TTL5m
experimentalThe experimental options that are subject to change or removal (see below)
federationBundle endpoints configuration section used for federation
disable_jwt_svidsIf true, completely disables JWT-SVID functionality. The server will not generate JWT keys, sign JWT-SVIDs, or implement JWT-related API calls. This is useful for deployments that don’t need JWT-SVIDs support.false
jwt_key_typeThe key type used for the server CA (JWT), <rsa-2048|rsa-4096|ec-p256|ec-p384>The value of ca_key_type or ec-p256 if not defined
jwt_issuerThe issuer claim used when minting JWT-SVIDs
log_fileFile to write logs to. An external tool can move it aside on any platform, and SPIRE Server then starts a new one on receipt of SIGUSR2 on POSIX, or of the reopen control code on Windows (see below)
log_file_rotationRotates log_file in process rather than relying on an external tool (below). Works on all platforms. Disabled unless configured
log_levelSets the logging level <DEBUG|INFO|WARN|ERROR>INFO
log_formatFormat of logs, <text|json>text
log_source_locationIf true, logs include source file, line number, and method name fields (adds a bit of runtime cost)false
profiling_enabledIf true, enables a net/http/pprof endpointfalse
proxy_protocol_trusted_cidrsList of trusted CIDRs for PROXY protocol support. When non-empty, the TCP listener accepts PROXY protocol headers only from sources in these CIDRs; connections from other sources that send PROXY headers are rejected. Useful when the server is behind a load balancer so per-IP rate limiting sees real client IPs.
profiling_freqFrequency of dumping profiling data to disk. Only enabled when profiling_enabled is true and profiling_freq > 0.
profiling_namesList of profile names that will be dumped to disk on each profiling tick, see Profiling Names
profiling_portPort number of the net/http/pprof endpoint. Only used when profiling_enabled is true.
prune_attested_nodes_expired_forEnables periodic purging of attested node records with expired SVIDs where the expiry time further in the past than the specified duration. Non-reattestable nodes are not pruned unless prune_tofu_nodes is set to true. Banned nodes are not pruned. Join-token nodes also cascade-delete the CreateJoinToken alias entry on prune or agent evict/purge (forward-only).
prune_attested_nodes_batch_sizeMaximum number of expired attested nodes pruned per cycle. Only applies when prune_attested_nodes_expired_for is set.1000
prune_tofu_nodesIncludes expired TOFU nodes into consideration for pruning. This does not affect banned nodes, which are not pruned.false
ratelimitRate limiting configurations, usually used when the server is behind a load balancer (see below)
socket_pathPath to bind the SPIRE Server API socket to (Unix only)/tmp/spire-server/private/api.sock
trust_domainThe trust domain that this server belongs to (should be no more than 255 characters)
max_attested_node_info_stalenessHow long to cache and use attested node information before requiring fetching up to date data from the datastore.0s
tls_configDescriptionDefault
min_tls_versionMinimum TLS version for terminating server listeners (e.g. VersionTLS12, VersionTLS13). Values below VersionTLS12 are rejected at startup. When omitted, defaults to TLS 1.2.TLS 1.2 when block is present
cipher_suitesAllowed TLS 1.2 cipher suites for terminating listeners. Ignored when min_tls_version is VersionTLS13 or higher (Go negotiates TLS 1.3 ciphers). Insecure suite names are filtered with a warning.Go defaults if all filtered
curve_preferencesPreferred key exchange curves (e.g. X25519MLKEM768, X25519, secp256r1). When minimum TLS is 1.2, at least one classical curve is required.

tls_config is a top-level server { ... } block (not experimental). It is parsed once at startup; invalid values prevent the server from starting. Settings apply only to inbound TLS listeners — gRPC TCP API, federation bundle HTTPS endpoint, and Prometheus HTTPS (ApplyPolicy with WithServerTLSConfig()). They are not applied to outbound TLS clients.

When experimental.require_pq_kem is enabled, it overrides min_tls_version and curve_preferences on connections where the policy is applied.

ca_subjectDescriptionDefault
countryArray of Country values
organizationArray of Organization values
common_nameThe CommonName value
log_file_rotationDescriptionDefault
max_size_mbSize in MiB that log_file may reach before it is rotated. An explicit 0 disables size based rotation, leaving it to SIGUSR2 on POSIX or the reopen control code on Windows100
max_filesNumber of rotated files to retain, not counting the file currently being written. An explicit 0 retains every rotated file7

Requires log_file to be set. Rotation moves the accumulated content aside to a timestamped sibling of log_file (for example server-2026-08-18T22-43-01.123.log) and keeps writing to log_file itself. max_files is applied when a rotation happens, not on a timer. A key left unset takes its default, so a block with no keys still rotates and still prunes.

A reopen also forces an immediate rotation, whether it arrives as SIGUSR2 on POSIX or as the reopen control code on Windows. Rotating an already-empty file is a no-op, so a scheduled reopen on an idle service does not consume the max_files budget.

experimentalDescriptionDefault
agent_spiffe_id_as_selectorEnable adding the agent spiffe_id to the list of node selectors automatically.false
allow_nonconforming_agent_idsAllow node attestors to produce agent IDs outside of /spire/agent/<attestor>/. When false, such attestations fail.false
cache_reload_intervalThe amount of time between two reloads of the in-memory entry cache. Increasing this will mitigate high database load for extra large deployments, but will also slow propagation of new or updated entries to agents.5s
full_cache_reload_intervalHow often to a full reload of the cache from the database when using the events based cache.24h
events_based_cacheUse events to update the cache with what’s changed since the last update. Enabling this will reduce overhead on the database.false
prune_events_older_thanHow old an event can be before being deleted. Used with events based cache. Decreasing this will keep the events table smaller, but will increase risk of missing an event if connection to the database is down.12h
event_timeoutMaximum time to wait for an event to come in before giving up.15m
auth_opa_policy_engineThe auth opa_policy engine used for authorization decisionsdefault SPIRE authorization policy
named_pipe_namePipe name of the SPIRE Server API named pipe (Windows only)\spire-server\private\api
require_pq_kemRequire post-quantum-safe KEM on terminating server listeners.false
enable_wit_svidsEnable the WIT-SVID profile and its APIs. When disabled, WIT-SVID APIs return Unimplementedfalse
wit_issuerThe issuer claim used when minting WIT-SVIDs
default_wit_svid_ttlThe default WIT-SVID TTL1h
ratelimitDescriptionDefault
attestationwhether to rate limit node attestation. If true, node attestation is rate limited to one attempt per second per IP address.true
signingwhether to rate limit JWT and X509 signing. If true, JWT and X509 signing are rate limited to 500 requests per second per IP address (separately).true
auth_opa_policy_engineDescriptionDefault
localLocal OPA configuration for authorization policy.
auth_opa_policy_engine.localDescriptionDefault
rego_pathFile to retrieve OPA rego policy for authorization.
policy_data_pathFile to retrieve databindings for policy evaluation.

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

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

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:

ConfigurationDescription
plugin_cmdPath to the plugin implementation binary (optional, not needed for built-ins)
plugin_checksumAn optional sha256 of the plugin binary (optional, not needed for built-ins)
enabledEnable or disable the plugin (enabled by default)
plugin_dataPlugin-specific data (mutually exclusive with plugin_data_file)
plugin_data_filePath to a file containing plugin-specific data (mutually exclusive with plugin_data)

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

plugins {
    SomeType "some_plugin" {
        plugin_data = {
            option1 = "foo"
            option2 = 3
        }
    }
}

External Plugin with Dynamic Configuration

Section titled “External Plugin with Dynamic Configuration”

In the agent.conf, declare the plugin using the plugin_data_file option to source the plugin configuration from file.

plugins {
    SomeType "some_plugin" {
        plugin_cmd = "./path/to/plugin"
        plugin_checksum = "4e1243bd22c66e76c2ba9eddc1f91394e57f9f83"
        plugin_data_file = "some_plugin.conf"
    }
}

And then in some_plugin.conf you place the plugin configuration:

option1 = "foo"
option2 = 3

Plugins that use dynamic configuration sources (i.e. plugin_data_file) can be reconfigured at runtime by sending a SIGUSR1 signal to SPIRE Server. This is true for both built-in and external plugins.

SPIRE Server, upon receipt of the signal, does the following:

  1. Reloads the plugin data
  2. Compares the plugin data to the previous data
  3. If changed, the plugin is reconfigured with the new data

Note The DataStore is not reconfigurable even when configured with a dynamic data source (e.g. plugin_data_file).

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
            refresh_hint = "10m"
            profile "https_web" {
                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"
            }
            bootstrap_bundle_path = "/etc/spire/domain2.pem"
        }
    }
}

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

Section titled “Configuration options for federation.bundle_endpoint”

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

ConfigurationDescription
addressIP address where this server will listen for HTTP requests
portTCP port number where this server will listen for HTTP requests
refresh_hintAllow manually specifying a refresh hint. Defaults to 5 minutes. Small values allow retrieving trust bundle updates in a timely manner
profile “<https_web|https_spiffe>”Allows configuring bundle profile

Configuration options for federation.bundle_endpoint.profile

Section titled “Configuration options for federation.bundle_endpoint.profile”

When setting a bundle_endpoint, it is required to specify the bundle profile.

Allowed profiles:

Configuration options for federation.bundle_endpoint.profile "https_web".acme

Section titled “Configuration options for federation.bundle_endpoint.profile "https_web".acme”
ConfigurationDescriptionDefault
directory_urlDirectory endpoint URLhttps://acme-v02.api.letsencrypt.org/directory
domain_nameDomain for which the certificate manager tries to retrieve new certificates
emailContact email address. This is used by CAs, such as Let’s Encrypt, to notify about problems with issued certificates
tos_acceptedACME Terms of Service acceptance. If not true, and the provider requires acceptance, then certificate retrieval will failfalse

Configuration options for federation.bundle_endpoint.profile "https_web".serving_cert_file

Section titled “Configuration options for federation.bundle_endpoint.profile "https_web".serving_cert_file”
ConfigurationDescriptionDefault
cert_file_pathPath to the certificate file, in PEM format
key_file_pathPath to the key file, in PEM format
file_sync_intervalInterval on which to reload the files from disk1h

Configuration options for federation.bundle_endpoint.profile "https_spiffe"

Section titled “Configuration options for federation.bundle_endpoint.profile "https_spiffe"”

Default bundle profile configuration.

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

Section titled “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:

ConfigurationDescriptionDefault
bundle_endpoint_urlURL of the SPIFFE bundle endpoint that provides the trust bundle to federate with. Must use the HTTPS protocol.
bundle_endpoint_profile “<https_web|https_spiffe>”Configuration of the SPIFFE endpoint profile type.
bootstrap_bundle_pathPath to a bundle used to authenticate the first https_spiffe fetch if none is stored yet.
bootstrap_bundle_formatFormat of bootstrap_bundle_path. Either pem or spiffe.pem

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.

bootstrap_bundle_path replaces the need to run spire-server bundle set before the first https_spiffe poll. It authenticates that first connection only. The bundle returned by the endpoint is stored with a create, not an update. Subsequent refreshes use the stored bundle. The path is not watched.

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.

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

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"
}

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

CommandActionDefault
-bindAddressIP address or DNS name of the SPIRE server
-configPath to a SPIRE config fileconf/server/server.conf
-dataDirDirectory to store runtime data to
-expandEnvExpand environment $VARIABLES in the config file
-logFileFile to write logs to
-logFormatFormat of logs, <text|json>
-logLevelDEBUG, INFO, WARN or ERROR
-serverPortPort number of the SPIRE server
-socketPathPath to bind the SPIRE Server API socket to
-trustDomainThe trust domain that this server belongs to (should be no more than 255 characters)

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
Section titled “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
Section titled “Example to run the SPIRE Server Windows service”
> sc.exe start spire-server run -config c:\spire\conf\server\server.conf

A Windows service has no console, so deployments generally set log_file. An external tool can move that file aside, and the reopen is then requested with a user defined service control code, since Windows has no SIGUSR2.

> sc.exe control spire-server 128

Configure log_file_rotation instead to have SPIRE Server rotate the file itself, with no external tool involved. Either way the file is opened for append, so restarting the service does not reset it. Running from a console has no trigger, since control codes only reach a service.

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.

CommandActionDefault
-socketPathPath to the SPIRE Server API socket/tmp/spire-server/private/api.sock
-spiffeIDAdditional SPIFFE ID to assign the token owner (optional)
-ttlToken TTL in seconds600

Creates registration entries.

CommandActionDefault
-adminIf set, the SPIFFE ID in this entry will be granted access to the Server APIs
-dataPath to a file containing registration data in JSON format (optional, if specified, other flags related with entry information must be omitted). If set to ’-’, read the JSON from stdin.
-disableX509SVIDPrefetchA boolean value that, when set, disables prefetching X509 SVID for this entryfalse
-dnsA DNS name that will be included in SVIDs issued based on this entry, where appropriate. Can be used more than once
-downstreamA boolean value that, when set, indicates that the entry describes a downstream SPIRE server
-entryExpiryAn expiry, from epoch in seconds, for the resulting registration entry to be pruned from the datastore. Please note that this is a data management feature and not a security feature (optional).
-entryIDA user-specified ID for the newly created registration entry (optional). If no entry ID is provided, one will be generated during creation
-federatesWithA list of trust domain SPIFFE IDs representing the trust domains this registration entry federates with. A bundle for that trust domain must already exist
-nodeIf set, this entry will be applied to matching nodes rather than workloads
-parentIDThe SPIFFE ID of this record’s parent.
-selectorA colon-delimited type:value selector used for attestation. This parameter can be used more than once, to specify multiple selectors that must be satisfied.
-socketPathPath to the SPIRE Server API socket/tmp/spire-server/private/api.sock
-spiffeIDThe SPIFFE ID that this record represents and will be set to the SVID issued.
-x509SVIDTTLA TTL, in seconds, for any X509-SVID issued as a result of this record.The TTL configured with default_x509_svid_ttl
-jwtSVIDTTLA TTL, in seconds, for any JWT-SVID issued as a result of this record.The TTL configured with default_jwt_svid_ttl
-storeSVIDA boolean value that, when set, indicates that the resulting issued SVID from this entry must be stored through an SVIDStore plugin

Updates registration entries.

CommandActionDefault
-adminIf set, the SPIFFE ID in this entry will be granted access to the Server APIs
-dataPath to a file containing registration data in JSON format (optional, if specified, other flags related with entry information must be omitted). If set to ’-’, read the JSON from stdin.
-disableX509SVIDPrefetchA boolean value that, when set, disables prefetching X509 SVID for this entryfalse
-dnsA DNS name that will be included in SVIDs issued based on this entry, where appropriate. Can be used more than once
-downstreamA boolean value that, when set, indicates that the entry describes a downstream SPIRE server
-entryExpiryAn expiry, from epoch in seconds, for the resulting registration entry to be pruned from the datastore. Please note that this is a data management feature and not a security feature (optional).
-entryIDA user-specified ID for the newly created registration entry (optional). If no entry ID is provided, one will be generated during creation
-federatesWithA list of trust domain SPIFFE IDs representing the trust domains this registration entry federates with. A bundle for that trust domain must already exist
-parentIDThe SPIFFE ID of this record’s parent.
-selectorA colon-delimited type:value selector used for attestation. This parameter can be used more than once, to specify multiple selectors that must be satisfied.
-socketPathPath to the SPIRE Server API socket/tmp/spire-server/private/api.sock
-spiffeIDThe SPIFFE ID that this record represents and will be set to the SVID issued.
-x509SVIDTTLA TTL, in seconds, for any X509-SVID issued as a result of this record.The TTL configured with default_x509_svid_ttl
-jwtSVIDTTLA TTL, in seconds, for any JWT-SVID issued as a result of this record.The TTL configured with default_jwt_svid_ttl
-storeSVIDA boolean value that, when set, indicates that the resulting issued SVID from this entry must be stored through an SVIDStore plugin

Displays the total number of registration entries.

CommandActionDefault
-downstreamA boolean value that, when set, indicates that the entry describes a downstream SPIRE server
-federatesWithSPIFFE ID of a trust domain an entry is federate with. Can be used more than once
-parentIDThe Parent ID of the records to count.
-selectorA colon-delimited type:value selector. Can be used more than once to specify multiple selectors.
-socketPathPath to the SPIRE Server API socket/tmp/spire-server/private/api.sock
-spiffeIDThe SPIFFE ID of the records to count.

Deletes a specified registration entry.

CommandActionDefault
-entryIDThe Registration Entry ID of the record to delete
-socketPathPath to the SPIRE Server API socket/tmp/spire-server/private/api.sock

Displays configured registration entries.

CommandActionDefault
-downstreamA boolean value that, when set, indicates that the entry describes a downstream SPIRE server
-entryIDThe Entry ID of the record to show.
-federatesWithSPIFFE ID of a trust domain an entry is federate with. Can be used more than once
-parentIDThe Parent ID of the records to show.
-selectorA colon-delimited type:value selector. Can be used more than once to specify multiple selectors.
-socketPathPath to the SPIRE Server API socket/tmp/spire-server/private/api.sock
-spiffeIDThe SPIFFE ID of the records to show.

Displays the total number of bundles.

CommandActionDefault
-socketPathPath to the SPIRE Server API socket/tmp/spire-server/private/api.sock

Displays the bundle for the trust domain of the server.

CommandActionDefault
-formatThe format to show the bundle. Either pem or spiffepem
-socketPathPath to the SPIRE Server API socket/tmp/spire-server/private/api.sock

Displays federated bundles.

CommandActionDefault
-idThe trust domain SPIFFE ID of the bundle to show. If unset, all trust bundles are shown
-formatThe format to show the federated bundles. Either pem or spiffepem
-socketPathPath to the SPIRE Server API socket/tmp/spire-server/private/api.sock

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.

CommandActionDefault
-idThe trust domain SPIFFE ID of the bundle to set.
-pathPath on disk to the file containing the bundle data. If unset, data is read from stdin.
-socketPathPath to the SPIRE Server API socket/tmp/spire-server/private/api.sock
-formatThe format of the bundle to set. Either pem or spiffepem

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.

CommandActionDefault
-idThe trust domain SPIFFE ID of the bundle to delete.
-modeOne of: restrict, dissociate, delete. restrict prevents the bundle from being deleted if it is associated to registration entries (i.e. federated with). dissociate allows the bundle to be deleted and removes the association from registration entries. delete deletes the bundle as well as associated registration entries.restrict
-socketPathPath to the SPIRE Server API socket/tmp/spire-server/private/api.sock

Creates a dynamic federation relationship with a foreign trust domain.

CommandActionDefault
-bundleEndpointProfileEndpoint profile type. Either https_web or https_spiffe.
-bundleEndpointURLURL of the SPIFFE bundle endpoint that provides the trust bundle (must use the HTTPS protocol).
-dataPath to a file containing federation relationships in JSON format (optional, if specified, other flags related with federation relationship information must be omitted). If set to ’-’, read the JSON from stdin.
-endpointSpiffeIDSPIFFE ID of the SPIFFE bundle endpoint server. Only used for https_spiffe profile.
-socketPathPath to the SPIRE Server API socket./tmp/spire-server/private/api.sock
-trustDomainName of the trust domain to federate with (e.g., example.org)
-trustDomainBundleFormatThe format of the bundle data (optional). Either pem or spiffe.pem
-trustDomainBundlePathPath to the trust domain bundle data (optional).

Deletes a dynamic federation relationship.

CommandActionDefault
-idSPIFFE ID of the trust domain of the relationship.
-socketPathPath to the SPIRE Server API socket./tmp/spire-server/private/api.sock

Lists all the dynamic federation relationships.

CommandActionDefault
-idSPIFFE ID of the trust domain of the relationship
-socketPathPath to the SPIRE Server API socket./tmp/spire-server/private/api.sock

Refreshes the bundle from the specified federated trust domain.

CommandActionDefault
-idSPIFFE ID of the trust domain of the relationship
-socketPathPath to the SPIRE Server API socket./tmp/spire-server/private/api.sock

Shows a dynamic federation relationship.

CommandActionDefault
-socketPathPath to the SPIRE Server API socket./tmp/spire-server/private/api.sock
-trustDomainThe trust domain name of the federation relationship to show (e.g., example.org)

Updates a dynamic federation relationship with a foreign trust domain.

CommandActionDefault
-bundleEndpointProfileEndpoint profile type. Either https_web or https_spiffe.
-bundleEndpointURLURL of the SPIFFE bundle endpoint that provides the trust bundle (must use the HTTPS protocol).
-dataPath to a file containing federation relationships in JSON format (optional, if specified, other flags related with federation relationship information must be omitted). If set to ’-’, read the JSON from stdin.
-endpointSpiffeIDSPIFFE ID of the SPIFFE bundle endpoint server. Only used for https_spiffe profile.
-socketPathPath to the SPIRE Server API socket./tmp/spire-server/private/api.sock
-trustDomainName of the trust domain to federate with (e.g., example.org)
-trustDomainBundleFormatThe format of the bundle data (optional). Either pem or spiffe.pem
-trustDomainBundlePathPath to the trust domain bundle data (optional).

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

CommandActionDefault
-socketPathPath to the SPIRE Server API socket/tmp/spire-server/private/api.sock
-spiffeIDThe SPIFFE ID of the agent to ban (agent identity)

Displays the total number of attested nodes.

CommandActionDefault
-selectorA colon-delimited type:value selector. Can be used more than once to specify multiple selectors.
-canReattestFilter based on string received, ‘true’: agents that can reattest, ‘false’: agents that can’t reattest, other value will return all
-bannedFilter based on string received, ‘true’: banned agents, ‘false’: not banned agents, other value will return all
-expiresBeforeFilter by expiration time (format: “2006-01-02 15:04:05 -0700 -07”)
-spiffeIDThe SPIFFE ID of the records to count.

De-attesting an already attested node given its spiffeID.

CommandActionDefault
-socketPathPath to the SPIRE Server API socket/tmp/spire-server/private/api.sock
-spiffeIDThe SPIFFE ID of the agent to evict (agent identity)

Displays attested nodes.

CommandActionDefault
CommandActionDefault
:-----------------:----------------------------------------------------------------------------------------------------------------------------------:---------------------------------
-selectorA colon-delimited type:value selector. Can be used more than once to specify multiple selectors.
-canReattestFilter based on string received, ‘true’: agents that can reattest, ‘false’: agents that can’t reattest, other value will return all
-bannedFilter based on string received, ‘true’: banned agents, ‘false’: not banned agents, other value will return all
-expiresBeforeFilter by expiration time (format: “2006-01-02 15:04:05 -0700 -07”)
-attestationTypeFilters agents to those matching the attestation type, like join_token or x509pop.

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

CommandActionDefault
-socketPathPath to the SPIRE Server API socket/tmp/spire-server/private/api.sock
-spiffeIDThe SPIFFE ID of the agent to show (agent identity)

Prints debug information about the server, including uptime, registered agent/entry/federated bundle counts, and the server’s own SVID chain.

CommandActionDefault
-outputDesired output format (pretty, json)pretty
-socketPathPath to the SPIRE Server API socket/tmp/spire-server/private/api.sock

Checks SPIRE server’s health.

CommandActionDefault
-shallowPerform a less stringent health check
-socketPathPath to the SPIRE Server API socket/tmp/spire-server/private/api.sock
-verbosePrint verbose information

Gets the current logging level of the SPIRE Server.

CommandActionDefault
-socketPathPath to the SPIRE Server API socket/tmp/spire-server/private/api.sock

Sets the logging level of the SPIRE Server.

CommandActionDefault
-levelThe new log level, one of (panic, fatal, error, warn, info, debug, trace)
-socketPathPath to the SPIRE Server API socket/tmp/spire-server/private/api.sock

Resets the logging level of the SPIRE Server to the level it was set to at launch.

CommandActionDefault
-socketPathPath to the SPIRE Server API socket/tmp/spire-server/private/api.sock

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

CommandActionDefault
-configPath to a SPIRE server configuration fileserver.conf
-expandEnvExpand environment $VARIABLES in the config filefalse

Mints an X509-SVID.

CommandActionDefault
-dnsA DNS name that will be included in SVID. Can be used more than once
-socketPathPath to the SPIRE Server API socket/tmp/spire-server/private/api.sock
-spiffeIDThe SPIFFE ID of the X509-SVID
-ttlThe TTL of the X509-SVIDFirst non-zero value from Entry.x509_svid_ttl, Entry.ttl, default_x509_svid_ttl, 1h
-writeDirectory to write output to instead of stdout

Mints a JWT-SVID.

CommandActionDefault
-audienceAudience claim that will be included in the SVID. Can be used more than once
-socketPathPath to the SPIRE Server API socket/tmp/spire-server/private/api.sock
-spiffeIDThe SPIFFE ID of the JWT-SVID
-ttlThe TTL of the JWT-SVIDFirst non-zero value from Entry.jwt_svid_ttl, Entry.ttl, default_jwt_svid_ttl, 5m
-writeFile to write token to instead of stdout

Activates a prepared JWT authority for use, which will cause it to be used for all JWT signing operations serviced by this server going forward.

CommandActionDefault
-authorityIDThe authority ID of the JWT authority to activate
-outputDesired output format (pretty, json)pretty
-socketPathPath to the SPIRE Server API socket/tmp/spire-server/private/api.sock

Prepares a new JWT authority for use by generating a new key and injecting it into the bundle.

CommandActionDefault
-outputDesired output format (pretty, json)pretty
-socketPathPath to the SPIRE Server API socket/tmp/spire-server/private/api.sock

Revokes the previously active JWT authority by removing it from the bundle and propagating this update throughout the cluster.

CommandActionDefault
-authorityIDThe authority ID of the JWT authority to revoke
-outputDesired output format (pretty, json)pretty
-socketPathPath to the SPIRE Server API socket/tmp/spire-server/private/api.sock

Shows the local JWT authorities.

CommandActionDefault
-outputDesired output format (pretty, json)pretty
-socketPathPath to the SPIRE Server API socket/tmp/spire-server/private/api.sock

Marks the previously active JWT authority as being tainted.

CommandActionDefault
-authorityIDThe authority ID of the JWT authority to taint
-outputDesired output format (pretty, json)pretty
-socketPathPath to the SPIRE Server API socket/tmp/spire-server/private/api.sock

Activates a prepared X.509 authority for use, which will cause it to be used for all X.509 signing operations serviced by this server going forward.

CommandActionDefault
-authorityIDThe authority ID of the X.509 authority to activate
-outputDesired output format (pretty, json)pretty
-socketPathPath to the SPIRE Server API socket/tmp/spire-server/private/api.sock

Prepares a new X.509 authority for use by generating a new key and injecting the resulting CA certificate into the bundle.

CommandActionDefault
-outputDesired output format (pretty, json)pretty
-socketPathPath to the SPIRE Server API socket/tmp/spire-server/private/api.sock

Revokes the previously active X.509 authority by removing it from the bundle and propagating this update throughout the cluster.

CommandActionDefault
-authorityIDThe authority ID of the X.509 authority to revoke
-outputDesired output format (pretty, json)pretty
-socketPathPath to the SPIRE Server API socket/tmp/spire-server/private/api.sock

Shows the local X.509 authorities.

CommandActionDefault
-outputDesired output format (pretty, json)pretty
-socketPathPath to the SPIRE Server API socket/tmp/spire-server/private/api.sock

Marks the previously active X.509 authority as being tainted.

CommandActionDefault
-authorityIDThe authority ID of the X.509 authority to taint
-outputDesired output format (pretty, json)pretty
-socketPathPath to the SPIRE Server API socket/tmp/spire-server/private/api.sock

Revokes the previously active X.509 upstream authority by removing it from the bundle and propagating this update throughout the cluster.

CommandActionDefault
-outputDesired output format (pretty, json)pretty
-socketPathPath to the SPIRE Server API socket/tmp/spire-server/private/api.sock
-subjectKeyIDThe X.509 Subject Key Identifier (or SKID) of the authority’s CA certificate of the X.509 upstream authority to revoke

Marks the provided X.509 upstream authority as being tainted.

CommandActionDefault
-outputDesired output format (pretty, json)pretty
-socketPathPath to the SPIRE Server API socket/tmp/spire-server/private/api.sock
-subjectKeyIDThe X.509 Subject Key Identifier (or SKID) of the authority’s CA certificate of the upstream X.509 authority to taint

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.

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
        # optional TLS for prometheus
        tls {
            use_spire_svid = true
            authorized_spiffe_ids = [
                "spiffe://example.org/monitoring/prometheus",
            ]

            # Alternatively, configure a web certificate directly:
            # cert_file = "/path/to/cert.pem"
            # key_file = "/path/to/key.pem"
            # client_ca_file = "/path/to/ca.pem"
        }
    }
}

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"
        }
    }
}