Config Reference

This is a list of all known Configuration settings. This list is based on declared settings within the Choria Go code base and so will not cover 100% of settings - plugins can contribute their own settings which are note known at compile time.

Version Hint

Built on 29 Jul 24 19:20 UTC using version 0.29.3

Run-time configuration

The run-time configuration can be inspected using choria tool config --config /etc/choria/server.cfg, this will show the active configuration.

Search and list directives

In addition to the full list below you can get configuration information for your version using the CLI:

% choria tool config security.provider
....
Configuration item: plugin.security.provider

║        Value: puppet
║    Data Type: string
║   Validation: enum=puppet,file,pkcs11,certmanager,choria
║      Default: puppet
║
║ The Security Provider to use
╙─

Data Types

A few special types are defined, the rest map to standard Go types

TypeDescription
comma_splitA comma separated list of strings, possibly with spaces between
durationA duration such as 1h, 300ms, -1.5h or 2h45m. Valid time units are ns, ms, s, m, h
path_splitA list of paths split by a OS specific PATH separator
path_stringA path that can include ~ for the users home directory
stringsA space separated list of strings
title_stringA string that will be stored as a Title String

Index

classesfilecollectives
colordefault_discovery_method
default_discovery_optionsdiscovery_timeout
identitylibdir
logfileloglevel
main_collectiveplugin.choria.adapters
plugin.choria.agent_provider.mcorpc.agent_shimplugin.choria.agent_provider.mcorpc.config
plugin.choria.agent_provider.mcorpc.libdirplugin.choria.broker_federation
plugin.choria.broker_networkplugin.choria.discovery.broadcast.windowed_timeout
plugin.choria.discovery.external.commandplugin.choria.discovery.inventory.source
plugin.choria.federation.clusterplugin.choria.federation.collectives
plugin.choria.federation_middleware_hostsplugin.choria.legacy_lifecycle_format
plugin.choria.machine.signing_keyplugin.choria.machine.store
plugin.choria.middleware_hostsplugin.choria.network.client_hosts
plugin.choria.network.client_portplugin.choria.network.client_signer_cert
plugin.choria.network.client_tls_force_requiredplugin.choria.network.deny_server_connections
plugin.choria.network.gateway_nameplugin.choria.network.gateway_port
plugin.choria.network.gateway_remotesplugin.choria.network.leafnode_port
plugin.choria.network.leafnode_remotesplugin.choria.network.listen_address
plugin.choria.network.mapping.namesplugin.choria.network.peer_password
plugin.choria.network.peer_portplugin.choria.network.peer_user
plugin.choria.network.peersplugin.choria.network.pprof_port
plugin.choria.network.provisioning.client_passwordplugin.choria.network.provisioning.provisioner_without_token
plugin.choria.network.provisioning.signer_certplugin.choria.network.public_url
plugin.choria.network.server_signer_certplugin.choria.network.soft_shutdown_timeout
plugin.choria.network.stream.advisory_replicasplugin.choria.network.stream.advisory_retention
plugin.choria.network.stream.event_replicasplugin.choria.network.stream.event_retention
plugin.choria.network.stream.leader_election_replicasplugin.choria.network.stream.leader_election_ttl
plugin.choria.network.stream.machine_replicasplugin.choria.network.stream.machine_retention
plugin.choria.network.stream.manage_streamsplugin.choria.network.stream.store
plugin.choria.network.system.passwordplugin.choria.network.system.user
plugin.choria.network.tls_timeoutplugin.choria.network.websocket_advertise
plugin.choria.network.websocket_portplugin.choria.network.write_deadline
plugin.choria.prometheus_textfile_directoryplugin.choria.puppetca_host
plugin.choria.puppetca_portplugin.choria.puppetdb_host
plugin.choria.puppetdb_portplugin.choria.puppetserver_host
plugin.choria.puppetserver_portplugin.choria.registration.file_content.compression
plugin.choria.registration.file_content.dataplugin.choria.registration.file_content.target
plugin.choria.registration.inventory_content.compressionplugin.choria.registration.inventory_content.target
plugin.choria.require_client_filterplugin.choria.security.certname_whitelist
plugin.choria.security.privileged_usersplugin.choria.security.request_signer.seed_file
plugin.choria.security.request_signer.serviceplugin.choria.security.request_signer.token_file
plugin.choria.security.request_signer.urlplugin.choria.security.server.seed_file
plugin.choria.security.server.token_fileplugin.choria.server.provision
plugin.choria.server.provision.allow_updateplugin.choria.services.registry.cache
plugin.choria.services.registry.storeplugin.choria.srv_domain
plugin.choria.ssldirplugin.choria.stats_address
plugin.choria.stats_portplugin.choria.status_file_path
plugin.choria.status_update_intervalplugin.choria.submission.max_spool_size
plugin.choria.submission.spoolplugin.choria.use_srv
plugin.login.aaasvc.login.urlplugin.machines.bucket
plugin.machines.check_intervalplugin.machines.download
plugin.machines.keyplugin.machines.poll_interval
plugin.machines.purgeplugin.machines.signing_key
plugin.nats.credentialsplugin.nats.pass
plugin.nats.userplugin.rpcaudit.logfile
plugin.rpcaudit.logfile.groupplugin.rpcaudit.logfile.mode
plugin.scout.agent_disabledplugin.scout.goss.denied_local_resources
plugin.scout.goss.denied_remote_resourcesplugin.scout.overrides
plugin.scout.tagsplugin.security.certmanager.alt_names
plugin.security.certmanager.api_versionplugin.security.certmanager.issuer
plugin.security.certmanager.namespaceplugin.security.certmanager.replace
plugin.security.choria.caplugin.security.choria.certificate
plugin.security.choria.keyplugin.security.choria.seed_file
plugin.security.choria.sign_repliesplugin.security.choria.token_file
plugin.security.choria.trusted_signersplugin.security.cipher_suites
plugin.security.client_anon_tlsplugin.security.ecc_curves
plugin.security.file.caplugin.security.file.certificate
plugin.security.file.keyplugin.security.issuer.names
plugin.security.pkcs11.driver_fileplugin.security.pkcs11.slot
plugin.security.providerplugin.security.server_anon_tls
plugin.security.support_legacy_certificatesplugin.yaml
registerintervalregistration
registration_collectiveregistration_splay
rpcauditrpcauthorization
rpcauthproviderrpclimitmethod
soft_shutdown_timeoutttl

classesfile

  • Type: path_string
  • Default Value: /opt/puppetlabs/puppet/cache/state/classes.txt

Path to a file listing configuration classes applied to a node, used in matches using Class filters

collectives

  • Type: comma_split

The list of known Sub Collectives this node will join or communicate with, Servers will subscribe the node and each agent to each sub collective and Clients will publish to a chosen sub collective. Defaults to the build settin build.DefaultCollectives

color

  • Type: boolean
  • Default Value: true

Disables or enable CLI color

default_discovery_method

  • Type: string
  • Validation: enum=mc,broadcast,puppetdb,choria,external,inventory
  • Default Value: mc

The default discovery plugin to use. The default “mc” uses a network broadcast, “choria” uses PuppetDB, external calls external commands

default_discovery_options

  • Type: strings

Default options to pass to the discovery plugin

discovery_timeout

  • Type: integer
  • Default Value: 2

How long to wait for responses while doing broadcast discovery

identity

  • Type: string

The identity this machine is known as, when empty it’s derived based on the operating system hostname or by calling facter fqdn

libdir

  • Type: path_split

The directory where Agents, DDLs and other plugins are found

logfile

  • Type: path_string
  • Default Value: stdout

The file to write logs to, when set to ‘discard’ logging will be disabled. Also supports ‘stdout’ and ‘stderr’ as special log destinations.

loglevel

  • Type: string
  • Validation: enum=debug,info,warn,error,fatal
  • Default Value: info

The lowest level log to add to the logfile

main_collective

  • Type: string

The Sub Collective where a Client will publish to when no specific Sub Collective is configured

plugin.choria.adapters

The list of Data Adapters to activate

plugin.choria.agent_provider.mcorpc.agent_shim

  • Type: string

Path to the helper used to call MCollective Ruby agents

plugin.choria.agent_provider.mcorpc.config

  • Type: string

Path to the MCollective configuration file used when running MCollective Ruby agents

plugin.choria.agent_provider.mcorpc.libdir

  • Type: path_split

Path to the libdir MCollective Ruby agents should have

plugin.choria.broker_federation

Enables the Federation Broker

plugin.choria.broker_network

Enables the Network Broker

plugin.choria.discovery.broadcast.windowed_timeout

  • Type: boolean

Enables the experimental dynamic timeout for choria/mc discovery

plugin.choria.discovery.external.command

  • Type: path_string

The command to use for external discovery

plugin.choria.discovery.inventory.source

  • Type: path_string

The file to read for inventory discovery

plugin.choria.federation.cluster

The cluster name a Federation Broker serves

plugin.choria.federation.collectives

List of known remote collectives accessible via Federation Brokers

plugin.choria.federation_middleware_hosts

Middleware brokers used by the Federation Broker, if unset uses SRV

plugin.choria.legacy_lifecycle_format

  • Type: boolean
  • Default Value: 0

When enabled will publish lifecycle events in the legacy format, else Cloud Events format is used

plugin.choria.machine.signing_key

  • Type: string

Public key used to sign data for watchers like machines watcher. Will override the value compiled in or in the watcher definitions if set here. This is primarily to allow development environments to use different private keys.

plugin.choria.machine.store

Directory where Autonomous Agents are stored

plugin.choria.middleware_hosts

  • Type: comma_split

Set specific middleware hosts in the format host:port, if unset uses SRV

plugin.choria.network.client_hosts

  • Type: comma_split

CIDRs to limit client connections from, appropriate ACLs are added based on this

plugin.choria.network.client_port

Port the Network Broker will accept client connections on

plugin.choria.network.client_signer_cert

  • Type: comma_split

Fully qualified paths to the public certificates used by the AAA Service to sign client JWT tokens. This enables users with signed JWTs to use unverified TLS to connect. Can also be a list of ed25519 public keys.

plugin.choria.network.client_tls_force_required

  • Type: boolean

Force requiring/not requiring TLS for all clients

plugin.choria.network.deny_server_connections

  • Type: boolean

Set ACLs denying server connections to this broker

plugin.choria.network.gateway_name

  • Type: string
  • Default Value: CHORIA

Name for the Super Cluster

plugin.choria.network.gateway_port

  • Type: integer
  • Default Value: 0

Port to listen on for Super Cluster connections

plugin.choria.network.gateway_remotes

  • Type: comma_split

List of remote Super Clusters to connect to

plugin.choria.network.leafnode_port

  • Type: integer
  • Default Value: 0

Port to listen on for Leafnode connections, disabled with 0

plugin.choria.network.leafnode_remotes

  • Type: comma_split

Remote networks to connect to as a Leafnode

plugin.choria.network.listen_address

Address the Network Broker will listen on

plugin.choria.network.mapping.names

  • Type: comma_split

List of subject remappings to apply

plugin.choria.network.peer_password

  • Type: string

Password to use when connecting to cluster peers

plugin.choria.network.peer_port

Port used to communicate with other local cluster peers

plugin.choria.network.peer_user

  • Type: string

Username to use when connecting to cluster peers

plugin.choria.network.peers

List of cluster peers in host:port format

plugin.choria.network.pprof_port

  • Type: integer
  • Default Value: 0

The port the network broker will listen on for pprof requests

plugin.choria.network.provisioning.client_password

  • Type: string

Password the provisioned clients should use to connect

plugin.choria.network.provisioning.provisioner_without_token

  • Type: boolean

Allows a provisioner without a token to connect over TLS using username and password. This facilitates v1 provisioning on an Issuer based network

plugin.choria.network.provisioning.signer_cert

  • Type: path_string

Path to the public cert that signs provisioning tokens, enables accepting provisioning connections into the provisioning account

plugin.choria.network.public_url

  • Type: string

Name:Port to advertise to clients, useful when fronted by a proxy

plugin.choria.network.server_signer_cert

  • Type: comma_split

Fully qualified Paths to the public certificates used by the Provisioner Service to sign server JWT tokens. This enables servers with signed JWTs to use unverified TLS to connect. Can also be a list of ed25519 public keys.

plugin.choria.network.soft_shutdown_timeout

  • Type: integer
  • Default Value: 60

The amount of time to allow the broker to exit, after this memory and thread dumps will be performed and a force exit will be done

plugin.choria.network.stream.advisory_replicas

  • Type: integer
  • Default Value: -1

When configuring Stream advisories storage ensure data is replicated in the cluster over this many servers, -1 means count of peers

plugin.choria.network.stream.advisory_retention

  • Type: duration
  • Default Value: 168h

When not zero enables retaining Stream advisories in the Stream Store

plugin.choria.network.stream.event_replicas

  • Type: integer
  • Default Value: -1

When configuring LifeCycle events ensure data is replicated in the cluster over this many servers, -1 means count of peers

plugin.choria.network.stream.event_retention

  • Type: duration
  • Default Value: 24h

When not zero enables retaining Lifecycle events in the Stream Store

plugin.choria.network.stream.leader_election_replicas

  • Type: integer
  • Default Value: -1

When configuring Stream based Leader Election storage ensure data is replicated in the cluster over this many servers, -1 means count of peers

plugin.choria.network.stream.leader_election_ttl

  • Type: duration
  • Default Value: 1m

The TTL for leader election, leaders must vote at least this frequently to remain leader

plugin.choria.network.stream.machine_replicas

  • Type: integer
  • Default Value: -1

When configuring Autonomous Agent event storage ensure data is replicated in the cluster over this many servers, -1 means count of peers

plugin.choria.network.stream.machine_retention

  • Type: duration
  • Default Value: 24h

When not zero enables retaining Autonomous Agent events in the Stream Store

plugin.choria.network.stream.manage_streams

  • Type: boolean
  • Default Value: 1

When set to zero will disable managing the standard streams on this node

plugin.choria.network.stream.store

  • Type: path_string

Enables Streaming data persistence stored in this path

plugin.choria.network.system.password

  • Type: string

Password used to access the Choria system account

plugin.choria.network.system.user

  • Type: string

Username used to access the Choria system account

plugin.choria.network.tls_timeout

  • Type: integer
  • Default Value: 2

Time to allow for TLS connections to establish, increase on slow or very large networks

plugin.choria.network.websocket_advertise

The URL to advertise for websocket connections

plugin.choria.network.websocket_port

Port to listen on for websocket connections

plugin.choria.network.write_deadline

  • Type: duration
  • Default Value: 10s

How long to allow clients to process traffic before treating them as slow, increase this on large networks or slow networks

plugin.choria.prometheus_textfile_directory

  • Type: path_string

Directory where Prometheus Node Exporter textfile collector reads data

plugin.choria.puppetca_host

  • Type: string
  • Default Value: puppet

The hostname where your Puppet Certificate Authority can be found

plugin.choria.puppetca_port

  • Type: integer
  • Default Value: 8140

The port your Puppet Certificate Authority listens on

plugin.choria.puppetdb_host

  • Type: string

The host hosting your PuppetDB, used by the “choria” discovery plugin

plugin.choria.puppetdb_port

  • Type: integer
  • Default Value: 8081

The port your PuppetDB listens on

plugin.choria.puppetserver_host

  • Type: string
  • Default Value: puppet

The hostname where your Puppet Server can be found

plugin.choria.puppetserver_port

  • Type: integer
  • Default Value: 8140

The port your Puppet Server listens on

plugin.choria.registration.file_content.compression

  • Type: boolean
  • Default Value: true

Enables gzip compression of registration data

plugin.choria.registration.file_content.data

  • Type: string

YAML or JSON file to use as data source for registration

plugin.choria.registration.file_content.target

  • Type: string

NATS Subject to publish registration data to

plugin.choria.registration.inventory_content.compression

  • Type: boolean
  • Default Value: true

Enables gzip compression of registration data

plugin.choria.registration.inventory_content.target

  • Type: string

NATS Subject to publish registration data to

plugin.choria.require_client_filter

  • Type: boolean
  • Default Value: false

If a client filter should always be required, only used in Go clients

plugin.choria.security.certname_whitelist

  • Type: comma_split
  • Default Value: .mcollective$,.choria$

Patterns of certificate names that are allowed to be clients

plugin.choria.security.privileged_users

Patterns of certificate names that would be considered privileged and able to set custom callers

plugin.choria.security.request_signer.seed_file

Path to the seed file used to access a Central Authenticator

plugin.choria.security.request_signer.service

Enables signing requests via Choria RPC requests

plugin.choria.security.request_signer.token_file

Path to the token used to access a Central Authenticator

plugin.choria.security.request_signer.url

URL to the Signing Service

plugin.choria.security.server.seed_file

  • Type: path_string

The server token seed to use for authentication, defaults to server.seed in the same location as server.conf

plugin.choria.security.server.token_file

  • Type: path_string

The server token file to use for authentication, defaults to serer.jwt in the same location as server.conf

plugin.choria.server.provision

Specifically enable or disable provisioning

plugin.choria.server.provision.allow_update

Allows the provisioner to perform in-place version updates

plugin.choria.services.registry.cache

  • Type: path_string
  • Environment Variable: CHORIA_REGISTRY

Directory where the Registry client stores DDLs found in the registry

plugin.choria.services.registry.store

  • Type: path_string

Directory where the Registry service finds DDLs to read

plugin.choria.srv_domain

The domain to use for SRV records, defaults to the domain the server FQDN is in

plugin.choria.ssldir

  • Type: path_string

The SSL directory, auto detected via Puppet, when specifically set Puppet will not be consulted

plugin.choria.stats_address

  • Type: string
  • Default Value: 127.0.0.1

The address to listen on for statistics

plugin.choria.stats_port

  • Type: integer
  • Default Value: 0

The port to listen on for HTTP requests for statistics, setting to 0 disables it

plugin.choria.status_file_path

  • Type: path_string

Path to a JSON file to write server health information to regularly

plugin.choria.status_update_interval

  • Type: integer
  • Default Value: 30

How frequently to write to the status_file_path

plugin.choria.submission.max_spool_size

  • Type: integer
  • Default Value: 500

Maximum amount of messages allowed into each priority

plugin.choria.submission.spool

  • Type: path_string

Path to a directory holding messages to submit to the middleware

plugin.choria.use_srv

If SRV record lookups should be attempted to find Puppet, PuppetDB, Brokers etc

plugin.login.aaasvc.login.url

List of URLs to attempt to login against when the remote signer is enabled

plugin.machines.bucket

  • Type: string
  • Default Value: CHORIA_PLUGINS

The KV bucket to query for plugins to install

plugin.machines.check_interval

  • Type: string
  • Default Value: 30s

How frequently to integrity check deployed autonomous agents

plugin.machines.download

  • Type: boolean

Activate run-time installation of Autonomous Agents

plugin.machines.key

  • Type: string
  • Default Value: machines

The Key to query in KV bucket for plugins to install

plugin.machines.poll_interval

  • Type: string
  • Default Value: 1m

How frequently to poll the KV bucket for updates

plugin.machines.purge

  • Type: boolean
  • Default Value: true

Purge autonomous agents installed using other methods

plugin.machines.signing_key

  • Type: string

The public key to validate the plugins manifest with

plugin.nats.credentials

  • Type: string
  • Environment Variable: MCOLLECTIVE_NATS_CREDENTIALS

The NATS 2.0 credentials to use, required for accessing NGS

plugin.nats.pass

  • Type: string
  • Environment Variable: MCOLLECTIVE_NATS_PASSWORD

The password to use when connecting to the NATS server

plugin.nats.user

  • Type: string
  • Environment Variable: MCOLLECTIVE_NATS_USERNAME

The user to connect to the NATS server as. When unset no username is used.

plugin.rpcaudit.logfile

  • Type: path_string

Path to the RPC audit log

plugin.rpcaudit.logfile.group

  • Type: string

User group to set file ownership to

plugin.rpcaudit.logfile.mode

  • Type: string
  • Default Value: 0600

File mode to apply to the file

plugin.scout.agent_disabled

  • Type: boolean

Disables the scout agent

plugin.scout.goss.denied_local_resources

  • Type: comma_split

List of resource types to deny for Goss manifests loaded from local disk

plugin.scout.goss.denied_remote_resources

  • Type: comma_split
  • Default Value: command

List of resource types to deny when Goss manifests or variables were received over rpc

plugin.scout.overrides

  • Type: path_string

Path to a file holding overrides for Scout checks

plugin.scout.tags

  • Type: path_string

Path to a file holding tags for a Scout entity

plugin.security.certmanager.alt_names

  • Type: comma_split

when using Cert Manager security provider, add these additional names to the CSR

plugin.security.certmanager.api_version

  • Type: string
  • Default Value: v1

the API version to call in cert manager

plugin.security.certmanager.issuer

  • Type: string

When using Cert Manager security provider, the name of the issuer

plugin.security.certmanager.namespace

  • Type: string
  • Default Value: choria

When using Cert Manager security provider, the namespace the issuer is in

plugin.security.certmanager.replace

  • Type: boolean
  • Default Value: true

when using Cert Manager security provider, replace existing CSRs with new ones

plugin.security.choria.ca

  • Type: path_string

When using choria security provider, the path to the optional Certificate Authority public certificate

plugin.security.choria.certificate

  • Type: path_string

When using choria security provider, the path to the optional public certificate

plugin.security.choria.key

  • Type: path_string

When using choria security provider, the path to the optional private key

plugin.security.choria.seed_file

  • Type: path_string

The path to the seed file

plugin.security.choria.sign_replies

  • Type: boolean
  • Default Value: true

Disables signing replies which would significantly trim down the size of replies but would remove the ability to verify signatures or verify message origin

plugin.security.choria.token_file

  • Type: path_string

The path to the JWT token file

plugin.security.choria.trusted_signers

  • Type: comma_split

Ed25119 public keys of entities allowed to sign client and server JWT tokens in hex encoded format

plugin.security.cipher_suites

  • Type: comma_split

List of allowed cipher suites

plugin.security.client_anon_tls

  • Type: boolean
  • Default Value: false

Use anonymous TLS to the Choria brokers from a client, also disables security provider verification - only when a remote signer is set

plugin.security.ecc_curves

  • Type: comma_split

List of allowed ECC curves

plugin.security.file.ca

  • Type: path_string

When using file security provider, the path to the Certificate Authority public certificate

plugin.security.file.certificate

  • Type: path_string

When using file security provider, the path to the public certificate

plugin.security.file.key

  • Type: path_string

When using file security provider, the path to the private key

plugin.security.issuer.names

  • Type: comma_split

List of names of valid issuers this server will accept, set indvidiaul issuer data using plugin.security.issuer..public

plugin.security.pkcs11.driver_file

When using the pkcs11 security provider, the path to the PCS11 driver file

plugin.security.pkcs11.slot

When using the pkcs11 security provider, the slot to use in the device

plugin.security.provider

  • Type: string
  • Validation: enum=puppet,file,pkcs11,certmanager,choria
  • Default Value: puppet

The Security Provider to use

plugin.security.server_anon_tls

  • Type: boolean
  • Default Value: false

Use anonymous TLS to the Choria brokers from a server

plugin.security.support_legacy_certificates

  • Type: boolean
  • Default Value: false

Allow certificates without SANs to be used

plugin.yaml

  • Type: path_string

Where to look for YAML or JSON based facts

registerinterval

  • Type: integer
  • Default Value: 300

How often to publish registration data

registration

  • Type: comma_split

The plugins used when publishing Registration data, when this is unset or empty sending registration data is disabled

registration_collective

  • Type: string

The Sub Collective to publish registration data to

registration_splay

  • Type: boolean
  • Default Value: true

When true delays initial registration publish by a random period up to registerinterval following registration publishes will be at registerinterval without further splay

rpcaudit

When enabled uses rpcauditprovider to audit RPC requests processed by the server

rpcauthorization

When enables authorization is performed on every RPC request based on rpcauthprovider

rpcauthprovider

The Authorization system to use

rpclimitmethod

  • Type: string
  • Validation: enum=first,random
  • Default Value: first

When limiting nodes to a subset of discovered nodes this is the method to use, random is influenced by

soft_shutdown_timeout

  • Type: integer
  • Default Value: 2

The amount of time to allow the server to exit, after this memory and thread dumps will be performed and a force exit will be done

ttl

  • Type: integer
  • Default Value: 60

How long published messages are allowed to linger on the network, lower numbers have a higher reliance on clocks being in sync