Configuration Archive Guide

Automated Versioning and Historical Tracking for AirScale Configurations

Overview

The Configuration Archive system automatically tracks and versions all AirScale base station configuration files. Instead of storing configuration snapshots in InfluxDB, configurations are saved as timestamped XML files on the server, providing a complete audit trail of configuration changes.

Key Features

Automatic Versioning - New versions created only when configuration changes
Hourly Polling - Checks for config changes every hour (configurable)
Change Detection - Smart comparison detects actual changes, ignoring whitespace
Size-Based Limits - Maximum 100 MB storage per device (keeps ~690 versions)
Web Interface - Browse, download, and manage config versions
Fast Access - File-based storage for instant retrieval
Zero InfluxDB Load - Configs no longer stored in time-series database
Automatic Cleanup - Old versions deleted when size limit reached

How It Works

Polling Schedule

Configuration is polled from each registered AirScale base station:

Interval: Every 1 hour (default)
First Poll: Immediately on application startup
Change Detection: Compares content with previous version
Storage: Only saves if changed or first time

Storage Location

Configurations are stored on the RAN Monitor server filesystem:

priv/airscale_configs/
└── <airscale-name>/
    ├── current.xml                                    # Latest configuration
    ├── ONS-Lab-Airscale_config_20251230_143522.xml   # Version from Dec 30, 2:35pm
    ├── ONS-Lab-Airscale_config_20251229_120000.xml   # Previous version
    ├── ONS-Lab-Airscale_config_20251228_093045.xml   # Older version
    └── ...                                            # Versions kept until 100 MB limit

Filename Format: <AirScaleName>_config_YYYYMMDD_HHMMSS.xml

Directory Naming: AirScale names are sanitized (special characters replaced with underscores, lowercase)

Version Management

Latest Version: Always available as current.xml
Historical Versions: Timestamped files showing when config changed
Auto-Cleanup: Deletes oldest versions when 100 MB size limit reached
Manual Cleanup: Delete specific versions via Web UI (except current.xml)
Storage Protection: Size-based limit prevents unlimited disk usage
Flexible Retention: More versions if files are small, fewer if files are large

Storage Protection

Size-Based Storage Limit

To prevent unlimited disk usage, the system uses a size-based limit instead of a version count:

Maximum Size: 100 MB per device (configurable)
Automatic Cleanup: Oldest versions deleted when size limit exceeded
Cleanup Timing: Every time a new config version is saved
Protected Files: current.xml and at least one version always kept
Flexible: Keeps ~690 versions at 145KB each, more if files are smaller

How It Works

When a new config version is saved:

Save new version - Config written as <AirScale>_config_YYYYMMDD_HHMMSS.xml
Update current - current.xml updated with latest config
Calculate size - System sums total size of all versioned files
Cleanup old - If total > 100 MB, delete oldest versions until under limit
Log activity - Deletions logged with freed space

Example Scenario

Initial state: 95 MB used (655 versions at 145KB each)
├── ONS-Lab-Airscale_config_20240101_100000.xml  <- Oldest (145KB)
├── ONS-Lab-Airscale_config_20240102_100000.xml  (145KB)
├── ... (653 more versions)
└── ONS-Lab-Airscale_config_20251230_100000.xml  <- Newest (145KB)

New config detected at 2025-12-31 10:00:00 (145KB)

Actions:
1. Save: ONS-Lab-Airscale_config_20251231_100000.xml (145KB)
2. Total size now: 95 MB + 145KB = 95.14 MB (still under 100 MB limit)
3. No deletion needed
4. Final: 656 versions, 95.14 MB used

---

Later: Large config change (new features added, file is now 500KB)

Actions:
1. Save: ONS-Lab-Airscale_config_20251231_150000.xml (500KB)
2. Total size now: 95.14 MB + 500KB = 95.64 MB (still under limit)
3. No deletion needed
4. Final: 657 versions, 95.64 MB used

---

After many more changes: Approaching limit

Current state: 99.8 MB (685 versions)

New config: 200KB
1. Save new version
2. Total would be: 100 MB (exceeds limit)
3. Delete oldest versions until total < 100 MB
4. Deletions logged: "Deleted 3 versions, freed 435 KB"
5. Final: 682 versions, 99.6 MB used

Storage Guarantees

The automatic cleanup ensures:

Bounded Storage: Each device limited to 100 MB maximum
No Surprises: Storage won't grow indefinitely
Production Safe: No manual intervention required
Flexible History: More versions for small configs, fewer for large configs
Always Available: At least one version always kept

Monitoring Storage

Check storage usage for all devices:

# Total storage used
du -sh priv/airscale_configs/
# Example: 215M (for 3 devices averaging 70 MB each)

# Storage per device
du -sh priv/airscale_configs/*/
# Example:
# 95M     priv/airscale_configs/ons-lab-airscale/
# 68M     priv/airscale_configs/sector-1/
# 52M     priv/airscale_configs/sector-2/

# Check if any device is near the limit
find priv/airscale_configs -maxdepth 1 -type d -exec du -sm {} \; | awk '$1 > 90 {print $2 " is at " $1 "MB (approaching 100MB limit)"}'

Using the Config Archive Page

Accessing Config Archive

Web UI: Navigate to Nokia → Config Archive

URL: https://<ran-monitor-ip>:9443/nokia/config-archive

Config Archive Interface

The Config Archive interface showing base station selector, version history table with timestamps and file sizes, and storage information.

Interface Overview

The Config Archive page has three main sections:

1. Base Station Selector

Grid View - Shows all registered AirScale devices
Version Count - Number of config versions stored for each
Selection - Click a device to view its config history
Visual Indicator - Selected device highlighted in blue

2. Version History Table

Displays all configuration versions for the selected base station:

Column	Description
Timestamp	When the configuration was saved (UTC)
Filename	Version filename (e.g., `config_20251230_143522.xml`)
Size	File size in KB or MB
Age	How long ago the version was created (e.g., "2h ago", "3d ago")
Actions	Download or Delete buttons

Sorting: Newest versions appear first (descending by timestamp)

Current Config: The current.xml file cannot be deleted (safety measure)

3. Storage Information

Summary panel showing:

Total Versions - Number of config versions stored
Total Size - Combined size of all versions
Storage Path - Filesystem location on server

Common Operations

Downloading a Configuration

Purpose: Retrieve a specific config version for review, backup, or comparison

Steps:

Navigate to Config Archive page
Select the desired base station
Find the version you want in the table
Click Download button
File downloads with format: <AirScaleName>_config_YYYYMMDD_HHMMSS.xml (matches stored filename)

Use Cases:

Creating offline backups
Comparing configurations between timestamps
Rolling back to previous known-good config
Analyzing configuration drift over time

Deleting Old Versions

Purpose: Remove outdated config versions to free storage space

Steps:

Navigate to Config Archive page
Select the base station
Find the version to delete
Click Delete button
Confirm deletion in popup dialog
Version is permanently removed

Important Notes:

Cannot delete current.xml (latest version protected)
Deletion is immediate and cannot be undone
Manual deletion doesn't affect auto-cleanup settings

Comparing Configurations

Purpose: Identify what changed between two config versions

Manual Comparison:

Download both versions you want to compare
Use an XML diff tool (e.g., xmldiff, Beyond Compare, WinMerge)
Review differences to understand changes

Example using command line:

# Download both versions
wget https://<server>:9443/download/config/ONS-Lab-Airscale/ONS-Lab-Airscale_config_20251230_143522.xml
wget https://<server>:9443/download/config/ONS-Lab-Airscale/ONS-Lab-Airscale_config_20251229_120000.xml

# Compare with diff
diff ONS-Lab-Airscale_config_20251229_120000.xml ONS-Lab-Airscale_config_20251230_143522.xml

# Or use xmldiff for cleaner output
xmldiff ONS-Lab-Airscale_config_20251229_120000.xml ONS-Lab-Airscale_config_20251230_143522.xml

Configuration Management Workflows

Audit Trail Investigation

Scenario: Need to determine when a configuration changed

Steps:

Open Config Archive
Select affected base station
Review version timestamps
Download relevant versions
Compare to identify exact changes
Correlate with performance issues or alarms

Example:

Version Timeline:
- ONS-Lab-Airscale_config_20251230_143522.xml (143KB) - Most recent
- ONS-Lab-Airscale_config_20251228_091045.xml (142KB) - 2 days ago
- ONS-Lab-Airscale_config_20251225_180000.xml (142KB) - 5 days ago

Analysis:
- Size increased from 142KB to 143KB on Dec 30
- Compare Dec 28 vs Dec 30 to find what was added
- Check if timing correlates with alarm spike

Configuration Rollback

Scenario: Recent config change caused issues, need to restore previous version

Steps:

Identify known-good configuration version
Download that version from Config Archive
Navigate to Configuration Management page (Web UI)
Upload the downloaded config → receive Plan ID
Validate the plan → check for errors
If validation succeeds, activate the plan
Monitor device for stability
Verify new config appears in archive after next poll

Safety Checklist:

✓ Downloaded correct previous version
✓ Validated plan before activation
✓ Coordinated with operations team
✓ Scheduled during maintenance window
✓ Monitoring tools ready for verification

Baseline Configuration Management

Scenario: Maintain a "golden config" for standardization

Best Practice:

Create and validate baseline configuration
Apply to reference device
Download from Config Archive after next poll
Store externally as template
Use for deploying new devices
Periodically review and update baseline

Technical Details

Change Detection Algorithm

The system uses smart content comparison to avoid false positives:

Normalization Process:

Remove leading/trailing whitespace
Collapse whitespace between XML tags
Normalize internal whitespace
Compare resulting normalized content

Benefits:

Formatting changes don't trigger new versions
Only actual configuration changes create versions
Reduces storage requirements
Provides meaningful change history

Example:

<!-- These are considered identical -->

<!-- Version 1 (with extra whitespace) -->
<parameter>
    <name>cellId</name>
    <value>1</value>
</parameter>

<!-- Version 2 (compact) -->
<parameter><name>cellId</name><value>1</value></parameter>

Storage Requirements

Typical Config Size: ~145 KB per version (based on actual AirScale configs)

Capacity Planning:

Devices	Max Size per Device	Versions Kept (at 145KB)	Max Total Storage
10	100 MB	~690	1 GB
50	100 MB	~690	5 GB
100	100 MB	~690	10 GB
500	100 MB	~690	50 GB
1000	100 MB	~690	100 GB

Growth Characteristics:

Maximum storage per device: 100 MB (configurable)
Typical versions retained: ~690 (145KB each)
If config never changes: Minimal growth (only current.xml at 145KB)
If config changes frequently: Growth stops at 100 MB limit
Adaptive: Keeps more versions for small configs, fewer for large configs

Automatic Protection:

Old versions deleted when size limit reached
No manual intervention needed
Storage usage strictly capped per device
At least one version always retained

Retention Policy

Default Settings:

Maximum 100 MB storage per device
Automatically delete oldest versions when limit exceeded
current.xml always retained (exempt from cleanup)
Cleanup occurs every time a new version is saved
At least one versioned file always kept

Customizing Retention:

The storage limit is configured in the ConfigStorage module:

# In lib/ran_monitor/nokia/airscale/config_storage.ex
# Module attribute at the top of the file
@max_storage_bytes 100 * 1024 * 1024  # 100 MB default

# Change to different limit:
@max_storage_bytes 50 * 1024 * 1024   # 50 MB (keeps ~345 versions)
@max_storage_bytes 200 * 1024 * 1024  # 200 MB (keeps ~1380 versions)

# The cleanup function uses this default
def cleanup_old_versions(airscale_name, max_size_bytes \ @max_storage_bytes)

After modifying, recompile:

mix compile
# Restart RAN Monitor to apply changes

Polling Configuration

Default Interval: 1 hour (3,600,000 milliseconds)

To Change Polling Interval:

Edit lib/ran_monitor/nokia/airscale/manager.ex:

defp schedule_get_airscale_config do
  # Pull config every 1 hour (3,600,000 ms)
  Process.send_after(self(), :get_airscale_config, 3_600_000)
end

Common Intervals:

30 minutes: 1_800_000
1 hour: 3_600_000 (default)
2 hours: 7_200_000
4 hours: 14_400_000
24 hours: 86_400_000

After changing, recompile and restart RAN Monitor.

Troubleshooting

No Config Versions Showing

Symptoms:

Config Archive page shows "0 versions"
Selected device shows empty table

Possible Causes:

Device Not Registered
- Check Base Stations page
- Verify device shows "REGISTERED" status
- Review Application Logs for registration errors
Session Not Active
- Check device detail view
- Ensure session status is "ACTIVE"
- Review session timestamps
Config Not Yet Polled
- Wait for first hourly poll cycle
- Or manually trigger: Kernel.send(Process.whereis(RanMonitor.Nokia.Airscale.Manager), :get_airscale_config)
Storage Path Issues
- Check priv/airscale_configs/ directory exists
- Verify RAN Monitor has write permissions
- Review Application Logs for filesystem errors

Download Returns 404 Error

Symptoms:

Clicking Download shows "Configuration file not found"
Browser shows 404 error

Possible Causes:

File Path Mismatch
- Directory names are sanitized (lowercase, special chars replaced)
- Verify actual directory name in priv/airscale_configs/
File Deleted
- Check if file was manually deleted from filesystem
- Refresh Config Archive page to update list
Permission Issues
- Verify web server process can read config files
- Check file permissions on config directory

Resolution:

# Check directory exists
ls -la priv/airscale_configs/

# Verify file exists
ls -la priv/airscale_configs/<device-name>/

# Fix permissions if needed
chmod 755 priv/airscale_configs/
chmod 644 priv/airscale_configs/*/*.xml

Config Not Updating

Symptoms:

Only current.xml exists, no new versions
Version count stays at 1 even after changes

Possible Causes:

Config Hasn't Changed
- System only creates versions when content changes
- Review logs: Configuration unchanged, no new version created
Polling Not Running
- Check Application Logs for polling messages
- Verify Manager process is running
- Check for errors during config retrieval
Change Detection Too Strict
- Whitespace-only changes are ignored (by design)
- Verify actual parameter values changed

Verification:

# Check logs for config polling
grep "process_configuration" <log-file>

# Manually trigger config pull
# In IEx console:
Kernel.send(Process.whereis(RanMonitor.Nokia.Airscale.Manager), :get_airscale_config)

Best Practices

Regular Backups

Recommendation: Create external backups of critical configs

Automated Backup Script Example:

#!/bin/bash
# backup-configs.sh - Daily config backup to external storage

BACKUP_DIR="/backup/ran-monitor/configs"
CONFIG_DIR="priv/airscale_configs"
DATE=$(date +%Y%m%d)

# Create dated backup directory
mkdir -p "$BACKUP_DIR/$DATE"

# Copy all configs
rsync -av "$CONFIG_DIR/" "$BACKUP_DIR/$DATE/"

# Keep last 30 days
find "$BACKUP_DIR" -type d -mtime +30 -exec rm -rf {} +

echo "Backup completed: $BACKUP_DIR/$DATE"

Schedule with cron:

0 2 * * * /path/to/backup-configs.sh

Change Documentation

Best Practice: Document why configs changed

Suggested Process:

Before making config changes, document the reason
Create a change log file alongside configs
Include: Date, Device, Changes, Justification, Approver

Example Change Log:

# config_changes.log

2025-12-30 14:35:22 - ONS-Lab-Airscale
Changed By: John Smith
Reason: Increase cell power to improve coverage in Sector 1
Parameters: txPower changed from 40dBm to 43dBm
Validated: Yes
Activated: 2025-12-30 14:40:00
Result: Coverage improved, no degradation observed

2025-12-28 09:10:45 - ONS-Lab-Airscale
Changed By: Jane Doe
Reason: Update neighbor cell list after new site deployment
Parameters: Added neighbor cells 10, 11, 12
Validated: Yes
Activated: 2025-12-28 09:15:00
Result: Handovers working correctly

Storage Monitoring

Recommendation: Monitor disk usage periodically

Check Storage Usage:

# Total size of config archive
du -sh priv/airscale_configs/

# Size per device
du -sh priv/airscale_configs/*/

# Number of versions per device
find priv/airscale_configs/ -name "*.xml" | \
  sed 's|/[^/]*\.xml||' | uniq -c

Set Up Alerts:

Alert if total size exceeds threshold (e.g., 500MB)
Alert if any device has unusually high version count
Alert if disk space below 10% free

Integration with Configuration Management

The Config Archive system works alongside the Configuration Management page:

Workflow Integration

Download Current Config:

Use Config Archive to get current.xml
Or use Configuration Management "Download" button (triggers immediate pull)

Upload Modified Config:

Use Configuration Management page
Upload → Validate → Activate workflow
New version appears in Archive after next poll

Rollback Process:

Download previous version from Archive
Upload via Configuration Management
Follow Validate → Activate workflow

Data Flow

API Access

While the Config Archive is primarily accessed via the Web UI, configurations can also be downloaded via direct HTTP requests.

Download Endpoints

Current Config:

curl -k "https://<server>:9443/download/config/<airscale-name>/current.xml" \
  -o current_config.xml

Specific Version:

curl -k "https://<server>:9443/download/config/<airscale-name>/ONS-Lab-Airscale_config_20251230_143522.xml" \
  -o ONS-Lab-Airscale_config_20251230_143522.xml

Note: AirScale name in URL must match the sanitized directory name (lowercase, underscores for special chars)

Programmatic Access

List Versions (from IEx console):

# Get all versions for a device
RanMonitor.Nokia.Airscale.ConfigStorage.list_config_versions("ONS-Lab-Airscale")

# Get current config content
{:ok, xml} = RanMonitor.Nokia.Airscale.ConfigStorage.get_current_config("ONS-Lab-Airscale")

# Check version count
RanMonitor.Nokia.Airscale.ConfigStorage.count_versions("ONS-Lab-Airscale")
# Returns: 655

# Get max storage size setting
RanMonitor.Nokia.Airscale.ConfigStorage.max_storage_bytes()
# Returns: 104857600 (100 MB in bytes)

# Get current storage usage
RanMonitor.Nokia.Airscale.ConfigStorage.get_storage_usage("ONS-Lab-Airscale")
# Returns: 99614055 (bytes)

# Get detailed storage statistics
RanMonitor.Nokia.Airscale.ConfigStorage.get_storage_stats("ONS-Lab-Airscale")
# Returns: %{version_count: 655, total_size_bytes: 99614055, ...}

# Manually cleanup (keep under 50 MB)
RanMonitor.Nokia.Airscale.ConfigStorage.cleanup_old_versions("ONS-Lab-Airscale", 50 * 1024 * 1024)
# Returns: {:ok, 345, 50000000} - deleted 345 versions, freed 50MB

# Cleanup using default (100 MB)
RanMonitor.Nokia.Airscale.ConfigStorage.cleanup_old_versions("ONS-Lab-Airscale")
# Returns: {:ok, 0, 0} - no cleanup needed if under limit

Overview​

Key Features​

How It Works​

Polling Schedule​

Storage Location​

Version Management​

Storage Protection​

Size-Based Storage Limit​

How It Works​

Example Scenario​

Storage Guarantees​

Monitoring Storage​

Using the Config Archive Page​

Accessing Config Archive​

Interface Overview​

1. Base Station Selector​

2. Version History Table​

3. Storage Information​

Common Operations​

Downloading a Configuration​

Deleting Old Versions​

Comparing Configurations​

Configuration Management Workflows​

Audit Trail Investigation​

Configuration Rollback​

Baseline Configuration Management​

Technical Details​

Change Detection Algorithm​

Storage Requirements​

Retention Policy​

Polling Configuration​

Troubleshooting​

No Config Versions Showing​

Download Returns 404 Error​

Config Not Updating​

Best Practices​

Regular Backups​

Change Documentation​

Storage Monitoring​

Integration with Configuration Management​

Workflow Integration​

Data Flow​

API Access​

Download Endpoints​

Programmatic Access​

See Also​

Overview

Key Features

How It Works

Polling Schedule

Storage Location

Version Management

Storage Protection

Size-Based Storage Limit

How It Works

Example Scenario

Storage Guarantees

Monitoring Storage

Using the Config Archive Page

Accessing Config Archive

Interface Overview

1. Base Station Selector

2. Version History Table

3. Storage Information

Common Operations

Downloading a Configuration

Deleting Old Versions

Comparing Configurations

Configuration Management Workflows

Audit Trail Investigation

Configuration Rollback

Baseline Configuration Management

Technical Details

Change Detection Algorithm

Storage Requirements

Retention Policy

Polling Configuration

Troubleshooting

No Config Versions Showing

Download Returns 404 Error

Config Not Updating

Best Practices

Regular Backups

Change Documentation

Storage Monitoring

Integration with Configuration Management

Workflow Integration

Data Flow

API Access

Download Endpoints

Programmatic Access

See Also