System Proposal: xrpld YAML Configuration File Support

[mvadari]

  title: `xrpld` YAML Configuration File Support
  description: Add YAML as an alternative configuration file format for `xrpld`.
  implementation: https://github.com/XRPLF/rippled/pull/6210
  author: Mayukha Vadari (@mvadari), Bart Thomee (@bthomee)
  category: System
  status: Proposal
  created: 2026-01-26

System Proposal: xrpld YAML Configuration File Support

1. Abstract

This specification defines YAML as an alternative configuration file format for xrpld, alongside the existing INI-esque format (rippled.cfg and validators.txt). YAML provides a more structured, readable, and maintainable format for complex configuration hierarchies.

2. Motivation

The current INI-esque (henceforth referred to as INI, though it technically does not quite match the INI standard) configuration format for xrpld has several limitations:

1. Flat structure: INI files lack native support for nested configuration, requiring workarounds like the [server] section referencing separate [port_*] sections.

2. Limited data types: All values are strings, with no distinction between numbers, booleans, or lists.

3. Verbose list syntax: Lists require either multiple lines or comma-separated values within a single line, which can be difficult to read and maintain.

4. No standard: INI format lacks a formal specification, leading to parser inconsistencies.

YAML addresses these issues by providing:

• Native support for nested structures
• Clear data type representation
• Clean list/array syntax
• A well-defined specification (yaml.org)
• Wide tooling support for validation and editing

3. Specification

3.1 File Detection

xrpld SHALL detect the configuration format based on file extension:

• Files ending in .yaml or .yml (case-insensitive) SHALL be parsed as YAML
• All other files SHALL be parsed as INI format

This applies to both the main configuration file and the validators file. YAML files will take precedence over INI files if both are present.

3.2 YAML Schema

The YAML configuration MUST be a mapping (dictionary) at the root level. Each top-level key corresponds to an INI section name.

3.2.1 Scalar Sections

Single-value sections are represented as scalar values:

database_path: /var/lib/xrpld/db
node_size: medium
ledger_history: 256

Equivalent INI:

[database_path]
/var/lib/xrpld/db

[node_size]
medium

[ledger_history]
256

3.2.2 Mapping Sections

Sections with key-value pairs are represented as nested mappings:

node_db:
  type: NuDB
  path: /var/lib/xrpld/db/nudb
  online_delete: 512

Equivalent INI:

[node_db]
type=NuDB
path=/var/lib/xrpld/db/nudb
online_delete=512

3.2.3 Sequence Sections

Sections with multiple values are represented as sequences:

validator_list_sites:
  - https://vl.ripple.com
  - https://unl.xrplf.org

Equivalent INI:

[validator_list_sites]
https://vl.ripple.com
https://unl.xrplf.org

3.2.4 Server Ports (Nested Structure)

The server section supports a nested ports structure for improved readability:

server:
  ports:
    port_rpc_admin_local:
      ip: 127.0.0.1
      port: 5005
      protocol: http
      admin: 127.0.0.1
    port_peer:
      ip: 0.0.0.0
      port: 51235
      protocol: peer

This is flattened to the equivalent INI structure:

[server]
port_rpc_admin_local
port_peer

[port_rpc_admin_local]
ip=127.0.0.1
port=5005
protocol=http
admin=127.0.0.1

[port_peer]
ip=0.0.0.0
port=51235
protocol=peer

3.2.5 IPs Section

The ips section accepts a structured format:

ips:
  - host: r.ripple.com
    port: 51235

3.2.6 Null Values

Null values (null, ~, or empty) result in empty sections:

empty_section: null
another_empty: ~
also_empty:

3.3 Conversion Rules

YAML Type	INI Equivalent
Scalar	Single line in section
Mapping	key=value pairs
Sequence of scalars	Multiple lines
Sequence of {host, port} maps	"host port" format
Null	Empty section
Nested mapping in value	Warning logged, skipped
Nested sequence	Warning logged, skipped

3.4 Error Handling

• YAML parse errors SHALL be logged with line and column information
• If parsing fails, xrpld SHALL NOT start and SHALL report the error
• Warnings for unsupported nested structures and other incorrect configurations SHALL be logged and SHALL prevent startup

4. Rationale

4.1 Extension-Based Detection

Using file extension for format detection (rather than content sniffing) provides:

• Predictable behavior
• No ambiguity between formats
• Simple user control over format choice

4.2 Nested Port Structure

The nested server.ports structure was chosen to demonstrate YAML's advantages while maintaining full compatibility with the existing flat port section approach.

5. Backwards Compatibility

This proposal is fully backward compatible:

• Existing INI configuration files continue to work unchanged
• No changes to configuration semantics or validation
• Users may migrate to YAML at their own pace, and may do so easily with a script
• Both formats produce identical internal configuration state

Further down the line (in a few months), the original INI format may be deprecated.

6. Test Plan

The implementation includes comprehensive unit tests covering:

• YAML parsing (valid and invalid inputs)
• Conversion to INI format for all section types
• Edge cases (null values, special characters, Unicode)
• File extension detection
• Integration tests with full configuration structures

7. Reference Implementation

A reference implementation is available here.

The reference implementation adds:

• A full implementation
• Unit tests
• Example configs (for both xrpld.cfg and validators.txt)
• A migration helper script that could be shipped with future versions of xrpld to make migration easier

8. Security Considerations

8.1 YAML Parsing Safety

The yaml-cpp library is used for parsing. This library:

• Does not execute code during parsing
• Does not support YAML tags that could cause code execution
• Has been widely used and security-audited

8.2 No New Attack Surface

Since YAML is converted to the same internal format as INI:

• All existing validation applies
• No new configuration options are introduced
• Attack surface is unchanged

8.3 File Permission Recommendations

Configuration files (YAML or INI) SHOULD have restricted permissions (e.g., 600 or 640) as they may contain sensitive information such as admin credentials.

Appendix

Appendix A: FAQ

A.1: Can I mix YAML and INI files?

Yes. The main configuration file and validators file are detected independently. You could use xrpld.yaml with validators.txt or vice versa.

A.2: How do I migrate from INI to YAML?

Use the provided cfg/ini2yaml.sh script:

./cfg/ini2yaml.sh xrpld.cfg xrpld.yaml

Note: The script produces flat YAML. Manual editing may be desired to use nested structures like server.ports.

A.3: Which format should I use?

Either format is fully supported. YAML may be preferable for:

• New deployments
• Complex configurations
• Users familiar with YAML from other tools (Kubernetes, Ansible, etc.)

INI may be preferable for:

• Existing deployments (no migration needed)
• Simple configurations
• Users who prefer the established format

It is recommended to switch to YAML within a few months, once the format has proved to be safe and free of bugs.

[lathanbritz]

is this to get away from executing code on start up or to get to a std syntax?

honestly the part I would appreciate more as a node operator would be a validation screen with a tree of the config with a confirm -y

as currently if one defines a section multiple times you simply over write it (if my memory serves correct, done at least once).

if not mistaken a duplicate YAML definition (section) throws an error?

[Bronek]

This is an excellent idea !

[WietseWind]

Maybe a dinosaur take but YAML is horrific imo.

It's so much easier to get it wrong with YAML. Screw it up with a tab or uneven amount of spaces or triple brackets 😵
And not even that much better in terms of readability imo.

Only node operator/geeks use it (so config file aesthetics don't matter that much?) and more prone to mistakes. Reliability > aesthetics = keep current format?

[Bronek]

how about TOML ?

[mvadari]

You get a lot of advantages that come from using a standardized format - e.g. easier for new people, improved tooling, simplified xrpld code. I've had to write custom parsers for the config when writing tooling a couple of times, and it'd be much easier if I could use an existing library to parse the config, for example.

[mvadari]

I like TOML too, not married to any specific standard - I mainly want to use an actual standard instead of using something custom.

[albertrsimmons]

Given that the proposal intentionally avoids most advanced YAML features and prioritizes deterministic parsing, TOML may be a better fit than YAML as a structured, typed successor to the existing INI-style configuration, especially for operational safety and long-term maintainability.

[Tokeiito]

That is excellent idea. My two cents, plan not to run it alongside current configuration, but to replace it. Like one year run it along side, one year, deprecate ini, on the third remove ini. But to be honest, this roll out phase could be even quicker.

[mvadari]

See Appendix A.3