Skip to content
Configuration keys

Configuration keys

Each deployment form reads its own YAML file: ~/.peers/config.yaml for a user Broker and /etc/peers/config.yaml for a system Broker. A Broker runs normally without a file, and every key is optional: an absent key takes its default. See The generated file below for how peers service install creates it. The Broker watches the file, so a valid change takes effect while it runs, whether the change is written by hand, by set_config or by peers config set. The two keepalive keys are the exception: they are read when a listener or a link is created, so a change applies only to listeners or links established afterwards.

The generated file

peers service install writes the template only when the file for its level does not exist; an existing file is left unchanged. The template lists every key, with one line of explanation above each. A key with a fixed default is written out with that value. The five keys whose default is empty or computed at runtime are written as comments with an example instead: broker.alias, whose default is computed at runtime, and broker.advertise, broker.advertise_extra, broker.local_socket_group and pairing.static_key, which default to empty. Uncomment a line and fill in a valid value, and the change takes effect while the Broker runs, like any other valid change. A Broker started without a configuration file does not get a template.

The two templates differ in three places. The first line names the level: # peers user Broker configuration. or # peers system Broker configuration. The opening comment differs: the user template says the file belongs to the account alone, while the system template explains that granting a group read access to the file lets that group’s accounts read the configuration, the full status and the audit log, and granting write access lets them change the configuration and manage pairing. The user template also notes after broker.local_socket_group and broker.local_socket_mode that those keys apply to the system Broker only.

The template begins with a comment block:

# peers user Broker configuration.
#
# Every key is optional; a key that is absent takes its default value.
# YAML anchors, aliases and merge keys are not supported.
# This file belongs to this account only: only this account runs the Broker
# and reads or writes the file.

The file groups its keys into sections. The broker section comes between this opening comment and pairing; the topics, directory, send, link and log sections follow pairing. The excerpt below omits them and shows the pairing section:

pairing:
  # Unmatched pairing requests allowed per source per minute; all sources together are limited to 10 times this, and static-key matches do not count.
  max_attempts_per_minute: 10
  # Failed verifications allowed before a one-time pairing key is invalidated.
  max_failures: 5
  # Static pairing key of 16 to 128 characters; a non-empty value takes effect.
  # static_key: ""
  # Fill in 16 to 128 random characters, for example the output of `openssl rand -hex 32`. An empty value leaves the static key unset.

Keys

KeyTypeDefaultMeaningset_config, peers config set
broker.aliasstringderivedThe alias this Broker reports. Derived from the hostname and, for a user Broker, the account when not set. 1 to 24 characters from letters, digits, ., - and _. The default is described below the table.Yes
broker.publicbooleanfalseWhether this Broker publishes a broker card and is visible to the whole connected network.Yes
broker.listenstring:17443The address and port to bind, written host:port, :port or [v6]:port. An empty host means every local address; an empty string means do not listen.Yes, except under --listen
broker.advertisestringemptyReplaces the automatically detected advertised address. Accepted forms are empty, host, host:port and :port. host takes the listen port; :port takes the addresses of the default-route interfaces and requires listening on every address. A non-empty value requires a listen address.Yes
broker.advertise_extrastring listemptyExtra advertised addresses to add. Each item is host or host:port; an item without a port uses the port in broker.advertise when it has one, otherwise the listen port. Requires a listen address.Yes
broker.address_check_intervalduration1mHow often the Broker re-reads the host’s local addresses.Yes
broker.local_socket_groupstringemptyThe group that owns the system Broker’s local socket. Empty keeps the runtime directory’s group. The group must exist in the account database; the value must not contain whitespace, : or /. Ignored by a user Broker.Yes
broker.local_socket_modestring0666The file mode of the system Broker’s local socket, written as 3 or 4 octal digits. A user Broker always uses 0600.Yes
broker.offlinebooleanfalseWhether this Broker refuses messages from other hosts. Links and the directory keep working, and a change applies while the Broker runs.Yes
pairing.static_keysecret stringemptyA pre-provisioned static pairing key, 16 to 128 characters. The key is active as soon as it is set. Generate one with openssl rand -hex 32, which produces 64 hexadecimal characters.No, file only
pairing.max_failuresinteger5Failed verifications allowed before a one-time pairing key is discarded.Yes
pairing.max_attempts_per_minuteinteger10Unmatched pairing requests allowed per source per minute, where a source is one IPv4 address or one IPv6 /64. All sources together are limited to 10 times this, a fixed factor. Requests matched by the static key do not count.Yes
topics.auto_joinbooleantrueWhether sessions join their default topics automatically.Yes
directory.reconcile_intervalduration10mHow often paired Brokers reconcile their directories.Yes
directory.max_recordsinteger1000Maximum number of records in the directory.Yes
directory.max_records_per_linkinteger250Maximum number of records accepted over one link.Yes
directory.max_topics_per_publisherinteger16Maximum number of public-topic declarations and records of unknown kind from one publisher. Broker cards and revocations do not count.Yes
send.link_retriesinteger5Retries when a link is not established.Yes
send.link_backoffduration500msWait before the first retry; it doubles each time, up to 8 seconds per wait.Yes
send.request_timeoutduration20sTotal time budget for one send, including retries and waits. A send_message call waits at most 30 seconds regardless; when the key is set above that, the tool’s own deadline ends the call first and also applies to the Broker, so the Broker stops the send when the tool gives up. The call returns Delivery unknown, and a message already sent may have been delivered, so a resend may deliver a second copy.Yes
send.inbox_retriesinteger2Retries when the inbox write definitely did not happen.Yes
send.inbox_backoffduration200msWait between inbox write retries.Yes
send.inbox_timeoutduration5sDeadline for one inbox write.Yes
send.dedupe_windowduration5mHow long entries stay in the duplicate-message table.Yes
link.dial_timeoutduration5sConnection deadline for each address while dialing. A connect_broker call waits at most 30 seconds regardless; when the key is set long enough to push a pairing past that, the tool’s own deadline ends the call first and also applies to the Broker, so the Broker stops the pairing when the tool gives up. The call returns Not connected, and a pairing already under way may have completed, so check with list_brokers.Yes
link.reconnect_minduration1sInitial backoff when re-establishing a link.Yes
link.reconnect_maxduration1mMaximum backoff when re-establishing a link.Yes
link.keepalive_intervalduration15sKeepalive probe interval. An interval below 10 seconds is raised to 10 seconds.Yes
link.keepalive_timeoutduration10sDeadline for a keepalive reply.Yes
log.levelstringinfoRun log level: debug, info, warn or error.Yes
update.checkbooleantrueWhether the Broker periodically checks GitHub for a newer formal release. When false, the Broker sends no check requests.Yes
update.check_intervalduration24hHow often the Broker checks for a newer release. The minimum is 1h.Yes

The update check contacts GitHub. Security model describes what it sends and what it receives. peers update also contacts GitHub, but only when you run it.

When broker.alias is not set, a system Broker uses the first segment of the system hostname, the part before the first .. A user Broker uses that segment, a . and the name of the account that runs it, for example workstation and workstation.alice. The alias does not depend on the listen address, the listen port or the advertised addresses. A character outside the alias character set is replaced with -. When the account name cannot be found or is empty, the decimal uid takes its place, for example workstation.1000. When the hostname cannot be read or is empty, the hostname part is broker. An alias longer than 24 characters is shortened first in its hostname part, which keeps at least 1 character, and, if it is still too long, then in its account part. After shortening, trailing . and - are removed; when the account part is the uid, it is the uid that is shortened. Set broker.alias to choose the alias yourself.

Types and constraints

  • A duration is a string in Go duration syntax, for example 10m, 500ms, 1s or 1h30m. Durations must be greater than zero.
  • Integers must be greater than zero, except send.link_retries and send.inbox_retries, which accept 0.
  • link.reconnect_max must be greater than or equal to link.reconnect_min, and link.keepalive_timeout must be less than link.keepalive_interval. Changing one key of either pair is checked against the other.
  • broker.listen is written host:port, :port or [v6]:port; the port is 1 to 65535. Setting a different value probes the address, and an address that cannot be bound is rejected. On a system Broker, a port below 1024 takes effect only while the configuration file can be written by root alone. When a group or others can write the file, a Broker started in the foreground fails to start, and one running as a service enters a local-only degraded run; chmod g-w <path> or a port of 1024 or higher fixes it. A request from root through set_config or peers config set that sets a port below 1024 is refused while the file is writable by an account other than root, and the error says what the file must be and gives the same two remedies. A request from an account other than root is refused outright, with changing broker.listen to a port below 1024 requires root. A refused start or hot reload names the current broker.listen value and asks root to check that it is the intended one before narrowing the permissions, because an account able to write the file may have set it. Manage a Broker by file permission describes the rule.
  • broker.advertise and broker.advertise_extra require a listen address, and a port-only broker.advertise also requires listening on every address. The host in each is an IP address or a domain name: an IP address is not a wildcard address, an IPv6 address is written in brackets and carries no zone, and a domain name is dot-separated labels of 1 to 63 bytes each, made of ASCII letters, digits, - and _, with no label starting or ending with -, at most 253 bytes overall and at most one trailing dot. A value that breaks this rule fails to load, and set_config and peers config set refuse it too, with an error such as invalid value: <key>: host "<host>" is not a valid host name; an IPv6 address without brackets gives invalid value: <key>: IPv6 addresses must be written in brackets, where <key> is the key that was set, broker.advertise or broker.advertise_extra.
  • The configured advertised addresses, including the implicit one for a specific listen address, may hold at most 8 entries. Addresses taken from the default-route interfaces are dropped from the end when the list would exceed 8; configured entries are all kept.
  • broker.local_socket_group must name a group that exists; startup fails when it does not, even with --allow-degraded.
  • broker.local_socket_mode accepts 3 or 4 octal digits, up to 0777.
  • pairing.static_key accepts 16 to 128 characters; an empty value means no static key.
  • update.check_interval must be at least 1h.

A value that fails a check is rejected, and the configuration remains as it was. At startup, a file that cannot be read or parsed, or a value that fails a check, stops the Broker, in the foreground and as a service alike. Only an unavailable data directory or audit log leads to the diagnostics-only degraded run.

File format and limits

The file is one YAML document. It does not accept YAML anchors, aliases (&name, *name) or merge keys (<<), and mappings and sequences may nest at most 32 levels deep. The file may be at most 1 MiB. A file that breaks one of these rules cannot be loaded:

  • config file parse error: anchors and aliases are not supported at line <line>, column <column>
  • config file parse error: merge keys are not supported at line <line>, column <column>
  • config file parse error: nesting is deeper than 32 levels at line <line>, column <column>
  • cannot read <path>: the file is larger than 1 MiB

At startup, any of these stops the Broker, with or without --allow-degraded. During a run, a reload that hits one of them keeps every current value and writes the error to the run log. set_config and peers config set fail when the file cannot be parsed, and the configuration stays as it was.

Changing the configuration

set_config takes the new value as text and returns the old and new values. peers config set does the same from the terminal and follows the same rules. When either changes a key that the template left commented out, it uncomments that line at the same position and writes the new value, leaving the rest of the file unchanged. When the file does not exist, the file it creates holds only that key. Neither can change pairing.static_key, and neither can change broker.listen while the Broker runs with --listen. A change to update.check_interval does not interrupt the current check cycle and applies from the next one. Setting update.check to false stops the checks and clears the reported version. When the file is edited by hand, the Broker applies the valid changes; a key whose value is invalid keeps its old value and the Broker writes an error to its log.

The file locations and their permissions are listed under Files and paths. Which topics sessions join by default is described under Project configuration file.