Networking NVIDIA Accelerated IO (XLIO) Documentation
Networking NVIDIA Accelerated IO (XLIO) Documentation
Breadcrumbs

XLIO Configuration Migration Guide

Migration Guide: Legacy Environment Variables to New Configuration System

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 provides: - 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

  1. Phase 1: Enable new system alongside legacy (backward compatible)

  2. Phase 2: Convert critical parameters to new format

  3. Phase 3: Migrate remaining parameters and deprecate legacy

  4. Phase 4: Full migration to new system

Backward Compatibility

The new configuration system is fully backward compatible: - Existing environment variables continue to work - Migration can be done gradually

Quick Migration

Step 1: Enable New Configuration System

export XLIO_USE_NEW_CONFIG=1

Step 2: Convert Your Current Settings

Use this mapping table to convert your current environment variables:

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 using 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 using 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

Before (Legacy):

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


After (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 using 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 this script when your deprecated environment variables are set:

#!/usr/bin/env python3 import osfrom functools import reduce import jsonimport 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

# Enable debug logging to see configuration loading export XLIO_INLINE_CONFIG="monitor.log.level=debug, monitor.log.details=3" # Run application and check logs ./your_application 2>&1 | grep -E "(Config|Parameter|Loading)"

Compare Legacy vs New Behavior

# Test with legacy configuration unset XLIO_USE_NEW_CONFIG export XLIO_TCP_NODELAY=1 ./test_app # Test with new configuration (using /etc/libxlio_config.json by default)# /etc/libxlio_config.json:{    "network": {        "protocols": {            "tcp": {                "nodelay": {                    "enable": true                }            }        }    }} export XLIO_USE_NEW_CONFIG=1 export XLIO_INLINE_CONFIG="network.protocols.tcp.nodelay.enable=true" ./test_app# Test with new configuration (using specific path)# /tmp/nodelay_conf.json:{    "network": {        "protocols": {            "tcp": {                "nodelay": {                    "enable": true                }            }        }    }} export XLIO_USE_NEW_CONFIG=1 export XLIO_CONFIG_FILE=/tmp/nodelay_conf.json ./test_app # Test with new Inline configuration export XLIO_USE_NEW_CONFIG=1 export XLIO_INLINE_CONFIG="network.protocols.tcp.nodelay.enable=true" ./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

# Maximum debug information export XLIO_INLINE_CONFIG="monitor.log.level=trace, monitor.log.details=3" # Check what parameters are actually loaded ./your_application 2>&1 | grep -E "(Parameter|Config|Loaded)" | head -20

Validation Tools

# Validate JSON syntax

python3 -m json.tool /etc/libxlio_config.json

Best Practices

  1. Test Migration: Always test in development environment first

  2. Gradual Migration: Migrate critical parameters first, then less critical ones

  3. Document Changes: Keep track of what parameters were migrated

  4. Validate Behavior: Ensure application behavior remains consistent

  5. 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 Configuration Reference.


Last updated: