XLIO - Configuration Migration Guide | NVIDIA Accelerated IO (XLIO) Documentation DEV

This guide helps you migrate from the legacy XLIO environment variable configuration to the new structured configuration system.

Migration Overview

Why Migrate?

The new configuration system introduces key improvements:

Type Safety: Compile-time and runtime type checking
Validation: Schema-driven parameter validation
Structure: Hierarchical organization of related parameters
Flexibility: Multiple configuration sources with priority ordering
Documentation: Built-in parameter descriptions and constraints

Migration Strategy

Phase	Description
1	Enable the new system alongside the legacy configuration (backward compatible).
2	Convert critical parameters to the new format.
3	Migrate remaining parameters and mark legacy variables as deprecated.
4	Complete migration and remove legacy usage.

Quick Migration

Step 1: Enable the New Configuration System

export XLIO_USE_NEW_CONFIG=1

Step 2: Convert Existing Settings

Use the following mapping table to translate legacy environment variables to the new structured configuration paths.

Core Settings

Legacy Variable	New Configuration Path	Type	Example
`XLIO_MEM_ALLOC_TYPE`	`core.resources.memory_limit`	integer	4294967296
`XLIO_HANDLE_SIGINT`	`core.signals.handle_sigint`	boolean	true/false
`XLIO_HANDLE_SIGSEGV`	`core.signals.handle_sigsegv`	boolean	true/false

Network Protocol Settings

Legacy Variable	New Configuration Path	Type	Example
`XLIO_TCP_NODELAY`	`network.protocols.tcp.nodelay.enable`	boolean	true/false
`XLIO_TCP_QUICKACK`	`network.protocols.tcp.quickack`	boolean	true/false
`XLIO_TCP_TIMESTAMP`	`network.protocols.tcp.timestamp.enable`	boolean	true/false
`XLIO_MSS`	`network.protocols.tcp.mss`	integer	1460

Performance Settings

Legacy Variable	New Configuration Path	Type	Example
`XLIO_RING_ALLOCATION_LOGIC`	`performance.rings.allocation_logic`	string	"ring_per_interface"
`XLIO_TX_BUFS`	`performance.buffers.tx.global_array_size`	integer	200000
`XLIO_RX_CQ_DRAIN_RATE_NSEC`	`performance.completion_queue.rx_drain_rate`	integer	10

Hardware Features

Legacy Variable	New Configuration Path	Type	Example
`XLIO_LRO`	`hardware_features.tcp.lro`	string	"disable"
`XLIO_TSO`	`hardware_features.tcp.tso`	boolean	true/false
`XLIO_STRIDING_RQ`	`hardware_features.striding_rq.enable`	boolean	true/false

Monitoring and Logging

Legacy Variable	New Configuration Path	Type	Example
`XLIO_LOG_LEVEL`	`monitor.log.level`	string	"info"
`XLIO_LOG_FILE`	`monitor.log.file_path`	string	"/var/log/xlio.log"
`XLIO_LOG_DETAILS`	`monitor.log.details`	integer	1
`XLIO_LOG_COLORS`	`monitor.log.colors`	boolean	true/false
`XLIO_STATS_FILE`	`monitor.stats.file_path`	string	"/tmp/stats.log"
`XLIO_STATS_SHMEM_DIR`	`monitor.stats.shmem_dir`	string	"/tmp/xlio"

Application-Specific Settings

Legacy Variable	New Configuration Path	Type	Example
`XLIO_NGINX_WORKERS_NUM`	`applications.nginx.workers_num`	integer	Worker count
`XLIO_DISTRIBUTE_CQ`	`applications.nginx.distribute_cq`	boolean	true/false

Practical Migration Examples

Example 1: Basic TCP Configuration

(Before) Legacy

export XLIO_TCP_NODELAY=1
export XLIO_TCP_QUICKACK=1
export XLIO_LOG_LEVEL=3
export XLIO_LOG_FILE="/var/log/xlio.log"

(After) New System

export XLIO_USE_NEW_CONFIG=1

Using JSON file (/etc/libxlio_config.json):

{
  "network": {
    "protocols": {
      "tcp": {
        "nodelay": { "enable": true },
        "quickack": true
      }
    }
  },
  "monitor": {
    "log": {
      "level": "info",
      "file_path": "/var/log/xlio.log"
    }
  }
}

Or Inline Config:

 export XLIO_INLINE_CONFIG="network.protocols.tcp.nodelay.enable=true, network.protocols.tcp.quickack=true, monitor.log.level=info, monitor.log.file_path=/var/log/xlio.log"

Example 2: Performance Tuning

(Before) Legacy

export XLIO_RING_ALLOCATION_LOGIC=1
export XLIO_RING_TX_NUM=32
export XLIO_TX_BUFS=100000
export XLIO_CQ_DRAIN_INTERVAL=5

(After) New System

export XLIO_USE_NEW_CONFIG=1

Using JSON file (/etc/libxlio_config.json):

{
    "performance": {
        "rings": {
           
            "tx": {
                "allocation_logic": "per_ip_address",
                "max_count": 32
            }
        },
        "buffers": {
            "tx": {
                "global_array_size": 100000
            }
        },
        "completion_queue": {
            "rx_drain_rate_nsec": 500000000
        }
    }
}

Or Inline Config:

export XLIO_INLINE_CONFIG="performance.rings.allocation_logic=ring_per_ip, performance.rings.tx.max_count=32, performance.buffers.tx.global_array_size=100000, performance.cq.rx_drain_rate=5"

Example 3: Nginx Optimization

Legacy

export XLIO_NGINX_WORKERS_NUM=8
export XLIO_DISTRIBUTE_CQ=1
export XLIO_TCP_NODELAY=1

New System

export XLIO_USE_NEW_CONFIG=1

Using JSON file (/etc/libxlio_config.json):

{
    "applications": {
        "nginx": {
            "workers_num": 8,
            "distribute_cq": true
        }
    },
    "network": {
        "protocols": {
            "tcp": {
                "nodelay": {
                    "enable": true
                }
            }
        }
    }
}

Or Inline Config:

export XLIO_INLINE_CONFIG="applications.nginx.workers_num=8, applications.nginx.distribute_cq=true, network.protocols.tcp.nodelay.enable=true"

Migration Automation

JSON Generator Script

Run the following script while legacy environment variables are still set:

#!/usr/bin/env python3
import os
from functools import reduce
import json
import mappings # available in the repo at:src/core/config/mappings.py

def migrate_to_json():
    config = {}
    for key, env_var in mappings.config_mapping:
       if os.getenv(env_var):
           reduce(lambda d, k: d.setdefault(k, {}), keys[:-1], config)[keys[-1]] = os.getenv(env_var)
    return config

if __name__ == "__main__":
    config = migrate_to_json()
    if config:
        print(json.dumps(config, indent=2))
    else:
        print("No legacy configuration found to migrate")

Migration Validation

Verify Configuration Loading

 export XLIO_INLINE_CONFIG="monitor.log.level=debug, monitor.log.details=3"  
./your_application 2>&1 | grep -E "(Config|Parameter|Loading)"

Compare Legacy vs. New Behavior

# Legacy
unset XLIO_USE_NEW_CONFIG
export XLIO_TCP_NODELAY=1
./test_app

# New (default config)
export XLIO_USE_NEW_CONFIG=1
./test_app

To specify a custom config file:

export XLIO_USE_NEW_CONFIG=1
export XLIO_CONFIG_FILE=/tmp/nodelay_conf.json
./test_app

Troubleshooting Migration

Common Issues

Issue	Cause	Solution
Config not loading	`XLIO_USE_NEW_CONFIG` not set	Ensure `XLIO_USE_NEW_CONFIG=1`
Parameter ignored	Wrong parameter name	Check Configuration Reference
JSON syntax error	Invalid JSON format	Use `python3 -m json.tool` to validate

Debug Configuration Loading

export XLIO_INLINE_CONFIG="monitor.log.level=trace, monitor.log.details=3"
./your_application 2>&1 | grep -E "(Parameter|Config|Loaded)" | head -20

Validation Tools

pip install jsonschema
jsonschema -i /etc/libxlio_config.json /etc/xlio_config_schema.json

Best Practices

Test Migration: Always test in development environment first
Gradual Migration: Migrate critical parameters first, then less critical ones
Document Changes: Keep track of what parameters were migrated
Validate Behavior: Ensure application behavior remains consistent
Monitor Performance: Watch for any performance regressions during migration

Support

Configuration Reference - Complete parameter documentation
Quick Start Guide - Common configuration examples
Schema File: src/core/config/descriptor_providers/xlio_config_schema.json
Legacy Mappings: src/core/config/mappings.py

This migration guide covers the transition from legacy XLIO environment variables to the new configuration system. For specific parameter details, see the XLIO - Configuration Reference page.

Last updated: June 04, 2026