Configuration reference

Census reads one TOML file, given with --config <path>, or config.toml in the current directory. Before it reads the file, Census replaces ${NAME} with the value of the environment variable NAME, or an empty string, and ${NAME:-default} with the value or, when it is unset or empty, default.

Census refuses a setting it does not know, so a misspelled key stops startup instead of being ignored.

[server]

Required.

Setting	Required	Default	Meaning
bind	Yes		Address and port of the API, the webhook receiver, the API reference and the web UI, for example 0.0.0.0:8080.

[memgraph]

Required.

Setting	Required	Default	Meaning
bolt_url	Yes		Memgraph's Bolt address, for example bolt://localhost:7687.
user	No	empty	Memgraph user.
password	No	empty	Memgraph password.

[branching]

Optional. Bounds the branch views Census holds.

Setting	Required	Default	Meaning
max_views	No	3	Branch views held at once. A query for one more branch retires the view read least recently.
idle_ttl	No	1h	Census retires a branch view that no query has read for this long.

[[connections]]

One table per source system. Connect source systems describes them.

Setting	Required	Default	Meaning
id	Yes		Unique among connections. Names the webhook route /webhooks/{id}.
type	Yes		infrahub or netbox.
endpoint	Yes		The source system's address.
api_key	No	empty	Infrahub API key, or NetBox API token.
branch	No	main	Infrahub only: the branch the default view reads.
webhook_secret	No	none	Infrahub only: the secret that signs webhooks.
external_base_url	No	none	The address browsers use to reach the source, for links to source objects. An absolute http or https address with a host.
external_base_url_fallback	No	endpoint	Without external_base_url: endpoint builds links from endpoint; error builds no links and reports an error in their place.

[inventories.<id>]

One table per inventory. Define an inventory describes it.

Setting	Required	Default	Meaning
description	No	empty	Shown to consumers.
entity_kind	No	empty	The kind of entity, for example device. Shown to consumers only.
priority	Yes		Every contribution id, once each, highest priority first.

[inventories.<id>.fields.<name>]

Setting	Required	Default	Meaning
type	Yes		string, number or boolean.
vocabulary	No	none	Canonical values, of the field's type.
default	No	none	A vocabulary value used for a supplied value with no mapping.
priority	No	the inventory's	Every contribution id, once each, for this field.

[inventories.<id>.freshness]

Key	Default	Meaning
default	1h	Budget of every field without its own, and of the location.
any field name	the default key	Budget of that field.

[inventories.<id>.location]

Required. Declare the location hierarchy describes it.

Setting	Required	Default	Meaning
levels	Yes		Level names, top first.
locations	No	empty	Every location as a /-joined path.
priority	No	the inventory's	Every contribution id, once each, for the location.

[[inventories.<id>.contributions]]

One table per contribution. Add a contribution describes it.

Setting	Required	Default	Meaning
id	Yes		Unique within the inventory.
connection	Yes		A connection id.
object_types	Yes		Infrahub node kinds or NetBox API paths.
hfid	Yes		Path of the source field that supplies the HFID.
refresh_interval	No	5m	Interval between full refreshes.
attributes	No	empty	Table of field name to source field path.
values	No	empty	Table of field name to a table of source value to canonical value.
defaults	No	empty	Table of field name to canonical value. Overrides the field's default for this contribution.
location	No	empty	Table of level name to source field path.
location_values	No	empty	Table of level name to a table of source name to declared name.

Durations are a number followed by s, m, h or d, or a number of seconds, and must be greater than zero.

Rules Census checks at startup

Census checks every rule before it connects to Memgraph or to any source. The first rule that fails stops startup, with a message that names the inventory, the contribution or field, and the rule number.

Rule	What it requires
C1	Connection ids are unique. type is infrahub or netbox.
C2	Inventory ids match ^[a-z0-9][a-z0-9_-]*$.
C3	Each inventory has at least one field and one contribution. Field and level names match ^[a-z][a-z0-9_]*$.
C4	A field's type is string, number or boolean.
C5	Every vocabulary value has the field's type. default is in vocabulary, and requires vocabulary.
C6	Contribution ids are unique within the inventory. connection names a declared connection. object_types is not empty. hfid is not empty.
C7	Every attributes, values and defaults key is a declared field. values and defaults are allowed only for fields with a vocabulary. Every values target and every defaults value is in the vocabulary.
C8	The priority of the inventory, of each field and of the location lists every contribution of the inventory exactly once.
C9	levels is not empty. Every location path has 1 to len(levels) names. Every path's parent is declared. No path is declared twice. Names do not contain /.
C10	Every location and location_values key is a declared level. Every location_values target is a name declared at that level.
C11	Durations parse. Freshness keys are default or declared fields.

Sections that are no longer supported

A file with one of these sections is refused, with a message naming its replacement.

Section	Replacement
[schema]	[inventories.<id>.fields.<name>]
[budgets]	[inventories.<id>.freshness]
[normalization.<field>]	vocabulary on each field and values on each contribution
[matching]	None: identity is the HFID, and priority orders contributions.
[[sources]]	[[connections]] for the connection, and [[inventories.<id>.contributions]] for object types, attributes and refresh interval