Skip to main content
Configures the operating system so that it can run Firedancer. This command manages system-level settings required for optimal validator performance. See the initialization guide for more information.

​
Usage

fdctl configure <subcommand> [stages...] --config <path>

​
Arguments

​
--config
string
required
Path to a configuration TOML file to configure the validator with. This must be the same configuration file the validator will be started with.

​
Configuration Stages

There are several stages to each configure command:
Reserves huge and gigantic pages for use by Firedancer and mounts huge page filesystems under a path specified in the configuration TOML file.
Set required kernel parameters for optimal validator performance.
Disables hyperthreaded pair for critical CPU cores to ensure consistent performance.
Prepares bonded network devices for XDP networking.
Configures the number of channels on the network device.
Modify offload feature flags on the network device.
Disables UDP segmentation on the loopback device.

​
Subcommands

​
configure init

Prepare the operating system environment to run Firedancer. This will reserve and mount the huge page filesystems, set the kernel parameters, and configure the number of combined channels on the network device. 
fdctl configure init <stage>... --config <path>
Example: Initialize all stages 
sudo fdctl configure init hugetlbfs sysctl ethtool-channels ethtool-offloads ethtool-loopback --config config.toml
Example: Initialize specific stages 
sudo fdctl configure init hugetlbfs sysctl --config config.toml

​
Required Capabilities

​
root
capability
Required for:
  • Increasing /proc/sys/vm/nr_hugepages and mounting hugetlbfs filesystems (hugetlbfs stage)
  • Increasing network device channels with ethtool --set-channels (ethtool-channels stage)
  • Disabling network device offloads with ethtool --offload (ethtool-offloads stage)
  • Disabling network device tx-udp-segmentation (ethtool-loopback stage)
​
CAP_SYS_ADMIN
capability
Required for setting kernel parameters in /proc/sys (only applies for the sysctl stage)

​
configure check

Check if the operating system environment is properly configured. Exits with a non-zero exit code if it is not, after printing relevant diagnostics to stderr. 
fdctl configure check <stage>... --config <path>
Example: Check all configuration 
fdctl configure check hugetlbfs sysctl ethtool-channels ethtool-offloads ethtool-loopback --config config.toml
Use configure check before starting the validator to ensure all system prerequisites are met.

​
configure fini

Remove any Firedancer specific operating system configuration still lingering. This only unmounts the hugetlbfs stages and returns the reserved huge and gigantic pages to the kernel pool. 
fdctl configure fini <stage>... --config <path>
Example: 
sudo fdctl configure fini hugetlbfs --config config.toml
The fini command will not reduce sysctls that were earlier increased, or change the network channel count back, as the original values are not stored.

​
Required Capabilities

​
root
capability
Required for removing directories from /mnt and unmounting hugetlbfs (only applies for the hugetlbfs stage)

​
Configuration File Example

[hugetlbfs]
    mount_path = "/mnt/.fd"
[layout]
    net_tile_count = 2
[tiles]
    [net]
        interface = "ens3f0"

​
Workflow

Typical workflow for configuring a system:
  1. Create configuration file with your system-specific settings
  2. Initialize configuration: sudo fdctl configure init hugetlbfs sysctl ethtool-channels ethtool-offloads ethtool-loopback --config config.toml
  3. Verify configuration: fdctl configure check hugetlbfs sysctl ethtool-channels ethtool-offloads ethtool-loopback --config config.toml
  4. Run validator: sudo fdctl run --config config.toml
When finished:
  1. Clean up (optional): sudo fdctl configure fini hugetlbfs --config config.toml

Build docs developers (and LLMs) love

Get started for freeTalk to us