Skip to content

feat(setup): discover the facts of the cardano node - #3716

Open
turmelclem wants to merge 17 commits into
mainfrom
ctl/3677-dicover-the-facts-of-the-Cardano-node
Open

turmelclem wants to merge 17 commits into
mainfrom
ctl/3677-dicover-the-facts-of-the-Cardano-node

Conversation

@turmelclem

@turmelclem turmelclem commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

Content

This PR adds Cardano node discovery to mithril-setup.

The discovery is runtime-agnostic: it finds running cardano-node processes and gathers facts through process, systemd, tool, and file probe traits. Linux host implementations inspect /proc, cgroups, node files, and the node executable.

The discovery:

  • Identifies the selected Cardano node and optionally the systemd unit running it.
  • Parses relevant cardano-node run command-line options, including socket, database, configuration, topology, credentials, listening address, and non-producing-node flags.
  • Selects exactly one block producer. It rejects nodes using an unsupported KES agent or bulk credentials file, unless a complete Shelley KES key and operational certificate pair is supplied.
  • Selects the only relay as a fallback when no block producer is running. This is intended for naive test-network deployments.
  • Reads the Shelley genesis file from the node configuration and identifies mainnet, preprod, preview, devnet, or a private network from networkMagic.
  • Reads pool peers from P2P localRoots[].accessPoints[] and legacy Producers[].
  • Discovers the node version and cardano-cli executable, resolving command-line paths against the node working directory.
  • Keeps missing or invalid facts best-effort, while distinguishing unsupported block-producer credentials as discovery errors.

Discovery attribute provenance

Attribute Provenance Fallback or rejection behavior
node.pid /proc process discovery for a running cardano-node Required to identify the detected node
node.systemd_unit Systemd cgroup/probe lookup by process PID None when no matching service is found
role Node command line and the number of detected block producers BlockProducer for an eligible block producer; Relay only for the sole non-block-producing node
socket_path --socket-path, resolved against the node working directory None if absent or not parseable
database_dir --database-path, resolved against the node working directory None if absent
config_file --config, resolved against the node working directory None if absent
topology_file --topology, resolved against the node working directory None if absent
shelley_genesis_file Node configuration key ShelleyGenesisFile, resolved relative to config_file None when the configuration or file cannot be interpreted
network Shelley genesis networkMagic, mapped to known Mithril signer names or a private network None when the genesis cannot be read or parsed
pool_peers P2P localRoots[].accessPoints[], or legacy Producers[] from the topology file Empty when the topology is absent, unreadable, or invalid
kes_key_path --shelley-kes-key, resolved against the node working directory None if absent
operational_certificate_path --shelley-operational-certificate, resolved against the node working directory None if absent
kes_agent_socket --shelley-kes-agent-socket, resolved against the node working directory None if absent
bulk_credentials_file --bulk-credentials-file, resolved against the node working directory None if absent
listening_address.ipv4 --host-addr from the node command line None if absent or invalid
listening_address.ipv6 --host-ipv6-addr from the node command line None if absent or invalid
listening_address.port --port from the node command line None if absent or invalid
service_user User recorded for the Cardano node process None if process ownership is unknown
node_version cardano-node --version, executed with the node process identity None if the executable or process identity is unknown or the version output cannot be parsed
cardano_cli_path Search beside the node executable first, then in the process search path None if no executable is found

Logging

mithril-setup now writes its logs with tracing instead of slog. The tracing subscriber is set up from the existing flags (verbosity, JSON format, output file), so the command line works the same. The logger is no longer passed through the command context: the code calls the tracing macros (info!, debug!, warn!) directly. The JSON output now uses the tracing format instead of Bunyan.

Pre-submit checklist

  • Branch
    • Tests are provided (if possible)
    • Crates versions are updated (if relevant)
    • CHANGELOG file is updated (if relevant)
    • Commit sequence broadly makes sense
    • Key commits have useful messages
  • PR
    • All check jobs of the CI have succeeded
    • Self-reviewed the diff
    • Useful pull request description
    • Reviewer requested
  • Documentation
    • Update README file (if relevant)
    • Update documentation website (if relevant)
    • Add dev blog post (if relevant)
    • Add ADR blog post or Dev ADR entry (if relevant)
    • No new TODOs introduced

Comments

The implementation includes a manual Linux host test in mithril-setup/tests/cardano_discovery_on_host.rs.

Issue(s)

Relates to #3677

@github-actions

github-actions Bot commented Nov 18, 2026 •

Copy link
Copy Markdown

Test Results

     5 files  ±  0     211 suites  ±0   58m 16s ⏱️ - 1h 4m 50s
 4 497 tests + 44   4 497 ✅ + 44  0 💤 ±0  0 ❌ ±0 
14 698 runs  +338  14 698 ✅ +338  0 💤 ±0  0 ❌ ±0 

Results for commit b4a45b9. ± Comparison against base commit e50bd4e.

This pull request removes 61 and adds 105 tests. Note that renamed tests count towards both.
mithril-stm ‑ circuits::halo2::tests::golden::cases::negative::slow::index_out_of_bounds
mithril-stm ‑ circuits::halo2::tests::golden::cases::negative::slow::index_too_large_for_circuit_range
mithril-stm ‑ circuits::halo2::tests::golden::cases::negative::slow::indices_not_increasing
mithril-stm ‑ circuits::halo2::tests::golden::cases::negative::slow::leaf_merkle_path_mismatch
mithril-stm ‑ circuits::halo2::tests::golden::cases::negative::slow::leaf_swap_keep_merkle_path
mithril-stm ‑ circuits::halo2::tests::golden::cases::negative::slow::leaf_wrong_verification_key
mithril-stm ‑ circuits::halo2::tests::golden::cases::negative::slow::merkle_path_corrupt_sibling
mithril-stm ‑ circuits::halo2::tests::golden::cases::negative::slow::merkle_path_flip_position
mithril-stm ‑ circuits::halo2::tests::golden::cases::negative::slow::merkle_path_length_long
mithril-stm ‑ circuits::halo2::tests::golden::cases::negative::slow::merkle_path_length_short
…
mithril-setup ‑ discovery::cardano::command_line::tests::a_node_not_using_a_kes_agent_is_detected_as_not_using_a_kes_agent
mithril-setup ‑ discovery::cardano::command_line::tests::a_node_started_as_non_producing_is_not_a_block_producer_even_with_credentials
mithril-setup ‑ discovery::cardano::command_line::tests::a_node_using_a_bulk_credentials_file_is_a_block_producer
mithril-setup ‑ discovery::cardano::command_line::tests::a_node_using_a_kes_agent_is_a_block_producer
mithril-setup ‑ discovery::cardano::command_line::tests::a_node_using_a_kes_agent_is_detected_as_using_a_kes_agent
mithril-setup ‑ discovery::cardano::command_line::tests::a_node_using_only_a_bulk_credentials_file_is_detected_as_using_bulk_credentials
mithril-setup ‑ discovery::cardano::command_line::tests::a_node_with_a_bulk_credentials_file_and_an_incomplete_kes_key_pair_is_using_bulk_credentials
mithril-setup ‑ discovery::cardano::command_line::tests::a_node_with_a_kes_key_and_an_operational_certificate_is_a_block_producer
mithril-setup ‑ discovery::cardano::command_line::tests::a_node_with_a_kes_key_and_an_operational_certificate_is_not_using_bulk_credentials
mithril-setup ‑ discovery::cardano::command_line::tests::a_node_without_kes_key_or_operational_certificate_is_not_a_block_producer
…

♻️ This comment has been updated with latest results.

@turmelclem turmelclem self-assigned this Nov 19, 2026
@jpraynaud jpraynaud added the feature 🚀 New implemented feature label Nov 19, 2026
@turmelclem
turmelclem deployed to testing-2-preview November 19, 2026 14:38 — with GitHub Actions Active
@turmelclem
turmelclem deployed to testing-preview November 19, 2026 14:38 — with GitHub Actions Active
@turmelclem
turmelclem deployed to testing-preview November 19, 2026 17:24 — with GitHub Actions Active
@turmelclem
turmelclem deployed to testing-2-preview November 19, 2026 17:24 — with GitHub Actions Active
@turmelclem
turmelclem marked this pull request as ready for review November 20, 2026 08:34
The discovery ran  with the privileges of the setup,
which may run as root, so any local user could get their own binary executed
as root by starting a process named  with block producer
credentials on its command line.

The command now runs with the real uid/gid of the node process, read
from status, so the binary gets no privilege the node does not already
have. It is not run at all when that identity is unknown.
…e Cardano node

- Read the shelley genesis file from configuration, and network from its magic
- Read the peers of the pool from the topology file
- Select a lone relay when no block producer is running
- Each fact is best-effort: a missing of invalid file leaves it undiscovered
- Install a tracing subscriber from the existing flags (verbosity, JSON format, output file)
- Remove the logger from the command context, logs use the tracing macros directly
- The JSON logs now use the tracing format instead of Bunyan
@turmelclem
turmelclem force-pushed the ctl/3677-dicover-the-facts-of-the-Cardano-node branch from 5852306 to b4a45b9 Compare November 20, 2026 08:35
@turmelclem
turmelclem deployed to testing-preview November 20, 2026 08:50 — with GitHub Actions Active

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

Two unresolved issues remain: credential-source precedence incorrectly rejects a valid KES pair with an agent socket, and the privilege drop leaves supplementary root groups on the spawned process.

2 open issues
What changed in this PR

Adds runtime-agnostic Cardano node discovery to mithril-setup, including Linux host probes, command-line and node-file parsing, node selection, and collection of signer-relevant facts. It also migrates setup logging from slog to tracing.

Changes:

  • Adds Cardano discovery models, probe traits, selection rules, and fact collection.
  • Adds Linux /proc, cgroup, filesystem, and executable inspection with unit and manual tests.
  • Replaces slog logging and logger propagation with a global tracing subscriber.
File Description
mithril-setup/​tests/​cardano_discovery_on_host.rs Adds an ignored manual host test for Cardano node discovery.
mithril-setup/​src/​test_tools/​mod.rs Registers shared test utilities.
mithril-setup/​src/​test_tools/​logs.rs Adds tracing log capture helpers and tests.
mithril-setup/​src/​main.rs Configures tracing output and removes logger injection.
mithril-setup/​src/​lib.rs Exposes discovery and test utility modules.
mithril-setup/​src/​discovery/​mod.rs Registers the environment discovery modules.
mithril-setup/​src/​discovery/​cardano/​probes.rs Defines runtime-agnostic Cardano observation traits and process models.
mithril-setup/​src/​discovery/​cardano/​node_files/​topology.rs Parses P2P and legacy topology peer definitions.
mithril-setup/​src/​discovery/​cardano/​node_files/​shelley_genesis.rs Parses Shelley genesis network magic values.
mithril-setup/​src/​discovery/​cardano/​node_files/​mod.rs Registers and re-exports node-file parsers.
mithril-setup/​src/​discovery/​cardano/​node_files/​configuration.rs Parses node configuration and resolves Shelley genesis paths.
mithril-setup/​src/​discovery/​cardano/​mod.rs Organizes and exports Cardano discovery components.
mithril-setup/​src/​discovery/​cardano/​host/​tools.rs Inspects node versions and locates cardano-cli.
mithril-setup/​src/​discovery/​cardano/​host/​procfs.rs Discovers Cardano processes and process identities from /proc.
mithril-setup/​src/​discovery/​cardano/​host/​mod.rs Registers Linux host probes and fixtures.
mithril-setup/​src/​discovery/​cardano/​host/​files.rs Reads Cardano node files from the host filesystem.
mithril-setup/​src/​discovery/​cardano/​host/​cgroup.rs Resolves systemd units from process cgroups.
mithril-setup/​src/​discovery/​cardano/​discovery.rs Defines public discovered-facts and node-role models.
mithril-setup/​src/​discovery/​cardano/​discoverer.rs Selects the node and aggregates command-line, process, tool, and file facts.
mithril-setup/​src/​discovery/​cardano/​command_line.rs Parses cardano-node run options and credential modes.
mithril-setup/​src/​commands/​signer.rs Migrates signer command logging to tracing.
mithril-setup/​src/​command_context.rs Removes the shared slog logger from command context.
mithril-setup/​Cargo.toml Adds discovery, serialization, error-handling, and tracing dependencies.
Cargo.lock Updates the dependency lockfile for tracing and discovery support.

Review effort: Lite

Comment on lines +44 to +47
// Dropping to the node identity also clears the supplementary groups when the setup
// runs as root, so that the node binary can't do more than the node itself
#[cfg(unix)]
command.uid(run_as.uid).gid(run_as.gid);
// One block producer
1 => {
let node = block_producers.remove(0);
if node.command_line.is_using_kes_agent() {

This branch was successfully deployed

2 active deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

feature 🚀 New implemented feature

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants