Flexible File Matching - rConfig V8 xFTP Services

File Matching Rules: Custom Device Association

The xFTP File Matching feature allows administrators to define custom patterns for automatically associating uploaded files with specific devices. Instead of relying solely on the default device ID extraction method described here, you can configure flexible matching rules using multiple pattern types.

---

Overview

What is File Matching?

File Matching determines which device an uploaded file belongs to by analyzing the filename against configured patterns. When a file arrives in the xFTP directory (/srv/xftp/), the sweep task attempts to match the filename to a device using:

1. Custom Pattern Rules (if configured) - Checked first
2. Default Device ID Extraction - Fallback method if no patterns match

This flexibility enables support for diverse filename conventions across different network environments and device manufacturers.

Pattern Types

rConfig supports five pattern matching types:

Regex (Regular Expression):

• Pattern: ^router\d+-config-.*\.cfg$
• Matches: router1-config-20240101.cfg, router42-config-backup.cfg
• Use Case: Complex filename structures requiring pattern matching

Prefix:

• Pattern: switch-backup-
• Matches: switch-backup-daily.cfg, switch-backup-2024.txt
• Use Case: Files starting with specific text

Suffix:

• Pattern: -vlan.dat
• Matches: core-switch-vlan.dat, access01-vlan.dat
• Use Case: Files ending with specific text

Contains:

• Pattern: firewall
• Matches: firewall-config.txt, main-firewall-01.cfg
• Use Case: Files containing specific keywords anywhere in filename

Exact:

• Pattern: main-core-switch.conf
• Matches: Only main-core-switch.conf (exact match)
• Use Case: Specific, known filenames for particular devices

---

Configuring File Matching Rules

Accessing File Matching Settings

Navigate to Settings → xFTP Services → File Matching Rules section in the rConfig UI.

Adding a Pattern

1. Click “Add Pattern” to display the pattern creation form

2. Enter Pattern Details:

   • Name: Descriptive identifier (e.g., “Core Switch VLAN Files”)
   • Type: Select pattern type (regex, prefix, suffix, contains, exact)
   • Pattern: Enter the matching pattern
   • Device: Select the target device for matched files
   • Description: Optional explanation of pattern purpose
   • Notes: Optional internal notes
   • Enabled: Check to activate pattern immediately

3. Save Pattern: Click “Save/Update” to create the pattern

Tip

Pattern Priority: Patterns are evaluated in order by ID (lowest first). The first matching pattern determines device association. Order your patterns from most specific to most general for accurate matching.

Example Patterns

Click “Add example patterns” to populate pre-configured examples demonstrating each pattern type:

• Cisco Router Configs: Regex pattern for router configuration files
• Switch Backups: Prefix pattern for switch backup files
• VLAN Database Files: Suffix pattern for VLAN database files
• Firewall Configs: Contains pattern for firewall-related files
• Specific Config: Exact pattern for a particular configuration file
• IP-based Pattern: Regex pattern matching subnet-based filenames
• Date-stamped Configs: Regex pattern for timestamp-formatted files

Note

Example Devices: Example patterns reference device IDs (10001-10007) that may not exist in your installation. Update the device association to valid device IDs in your inventory before enabling these patterns.

---

Pattern Matching Process

How Matching Works

When the sweep task (php artisan rconfig:sweep-xftp-dir) runs:

1. Load Active Patterns: Retrieve all enabled patterns from database, ordered by ID
2. Process Each File: For each file in /srv/xftp/:
   • Test filename against each pattern in order
   • On first match, associate file with pattern’s configured device ID
   • Move file to device storage directory with timestamp
3. Fallback to Default: If no patterns match, attempt default device ID extraction
4. Orphan Files: Files matching no patterns and containing no extractable device ID remain in /srv/xftp/

Pattern Evaluation Order

Patterns are evaluated sequentially by ID (lowest to highest). The first matching pattern wins:

Example Scenario:

Pattern 1 (ID: 5): Type=Contains, Pattern="config", Device=10
Pattern 2 (ID: 10): Type=Prefix, Pattern="router-config", Device=20

File: router-config-daily.cfg

• Matches Pattern 1 (contains “config”) → Associates with Device 10
• Pattern 2 never evaluated (first match wins)

Caution

Pattern Order Matters: If a general pattern (e.g., “contains: config”) has a lower ID than a specific pattern (e.g., “prefix: router-config”), the general pattern will match first. Consider pattern order when creating rules or adjust by deleting and recreating patterns to control ID sequence.

Match Counter

Each pattern tracks successful matches in the Match Count field:

• Increments each time the pattern matches a file
• Helps identify actively used patterns vs unused rules
• Useful for auditing and optimizing pattern configurations

---

Managing Patterns

Editing Patterns

1. Click Edit icon in the Actions column for the target pattern
2. Modify fields inline in the table
3. Click “Save/Update” to apply changes or “Cancel” to discard

Enabling/Disabling Patterns

• Toggle Status: Use the Actions menu to enable or disable patterns without deletion
• Disabled Patterns: Remain in configuration but are skipped during matching
• Enabled Only Filter: Check “Enabled only” to view only active patterns

Deleting Patterns

1. Click Delete icon in the Actions column
2. Confirm deletion in the prompt
3. Pattern removed permanently from configuration

Note

Match Count Preservation: Deleting a pattern removes all configuration data including historical match counts. Consider disabling patterns instead of deleting to preserve match statistics.

---

Default Device ID Extraction

Fallback Behavior

If no custom patterns match a filename, rConfig attempts to extract the device ID using built-in rules:

Pattern 1: ID at Start

• Format: {deviceid}-{filename}
• Example: 12345-config.cfg → Device ID: 12345

Pattern 2: ID with Marker

• Format: device-{deviceid}-{filename} or id-{deviceid}-{filename}
• Examples:
  • device-12345-backup.cfg → Device ID: 12345
  • id-12345-vlan.dat → Device ID: 12345

Validation: Extracted device IDs are verified against the devices table. Invalid IDs result in orphaned files.

When to Use Custom Patterns

Custom patterns are beneficial when:

• Device filenames don’t follow default extraction patterns
• Multiple devices upload files with similar naming conventions
• Manufacturer-specific filename formats require specialized matching
• Files lack embedded device IDs entirely
• Centralizing pattern management improves maintainability

---

Troubleshooting

Files Not Matching Patterns

Symptom: Files remain in /srv/xftp/ despite configured patterns.

Diagnostic Steps:

1. Verify Pattern Enabled: Check pattern status in File Matching Rules table
2. Test Pattern Matching: Manually test pattern against filename:
   • Regex: Use online regex tester with pattern and filename
   • Prefix/Suffix/Contains/Exact: Verify string matching logic
3. Check Pattern Order: Ensure more specific patterns have lower IDs than general patterns
4. Review Sweep Logs: Check Laravel logs for pattern matching errors:

   tail -50 /var/www/html/rconfig8/current/storage/logs/laravel.log | grep sweep

Common Issues:

• Invalid Regex: Malformed regex patterns fail silently. Validate regex syntax.
• Case Sensitivity: Pattern matching is case-sensitive by default.
• Special Characters: Ensure special characters are properly escaped in regex patterns.

Pattern Never Matches

Symptom: Match count remains zero despite receiving matching files.

Resolution:

1. Upload Test File: Manually upload a file matching the pattern
2. Run Manual Sweep:

   php artisan rconfig:sweep-xftp-dir

3. Check Logs: Review output for pattern matching decisions
4. Verify Device Exists: Confirm pattern’s device_id exists in devices table:

   mysql -u rconfig -p rconfig -e "SELECT id, device_name FROM devices WHERE id = {device_id};"

Multiple Patterns Match Same File

Symptom: Uncertain which device receives files matching multiple patterns.

Expected Behavior: First matching pattern (lowest ID) wins. Subsequent patterns are not evaluated.

Resolution:

• Review Pattern Order: List patterns by ID to understand evaluation sequence
• Adjust Specificity: Make higher-priority patterns more specific
• Reorder Patterns: Delete and recreate patterns in desired evaluation order

---

Best Practices

Pattern Design

Be Specific: Create specific patterns for known filename formats rather than overly broad matches:

• ✓ Good: ^core-switch-\d+-vlan\.dat$ (matches specific format)
• ✗ Poor: vlan (matches any file containing “vlan”)

Use Regex for Complexity: Leverage regex patterns for complex filename structures:

• Timestamps: .*-\d{8}-\d{6}\.cfg$ (YYYYMMDD-HHMMSS)
• IP Addresses: 192\.168\.1\.\d+.*\.cfg
• Device Types: ^(router|switch|firewall)\d+-.*

Document Patterns: Use Description and Notes fields to explain pattern purpose and expected filenames.

Performance Optimization

Minimize Pattern Count: Consolidate similar patterns using regex where possible:

• Instead of 10 prefix patterns, use one regex pattern with alternation: ^(prefix1|prefix2|prefix3)

Disable Unused Patterns: Disable patterns that no longer apply to reduce evaluation overhead.

Monitor Match Counts: Regularly review match counts to identify unused patterns for cleanup.

Security Considerations

Validate Device Associations: Ensure patterns associate files with correct devices to prevent misclassification.

Audit Pattern Changes: Track pattern modifications through activity logs for security and compliance.

Restrict Pattern Access: Limit file matching configuration to authorized administrators through role-based access control.

---

Command Reference

Manual Sweep Execution

Trigger file matching and processing immediately:

cd /var/www/html/rconfig8/current
php artisan rconfig:sweep-xftp-dir

View Directory Contents

List files awaiting processing:

ls -la /srv/xftp/

---

Related Documentation

• xFTP Server Overview - Complete xFTP service documentation
• Configuration Backup Implementation - Understanding backup workflows
• Device Management - Managing device inventory

---

Summary

File Matching Rules provide flexible, configurable device association for xFTP uploaded files. By defining custom patterns, administrators can support diverse filename conventions across heterogeneous network environments without modifying device configurations or relying solely on embedded device IDs.

Key Capabilities:

• Five Pattern Types: Regex, prefix, suffix, contains, and exact matching
• Priority-Based Matching: First matching pattern determines device association
• Fallback Support: Default device ID extraction when no patterns match
• Match Tracking: Automatic counting of successful pattern matches
• Flexible Management: Enable, disable, edit, or delete patterns without affecting other configurations

Configuration Best Practices:

• Order patterns from most specific to most general
• Document pattern purpose in description fields
• Monitor match counts to identify unused rules
• Test patterns with manual sweep execution before production deployment
• Consolidate similar patterns using regex for performance

For complex pattern requirements or assistance with regex development, contact rConfig support for consultation and implementation guidance.