Network Automation Script Integration Engine - rConfig V8

Script Integration Engine: Extending rConfig Beyond Standard Protocols

The Script Integration Engine (SIE) extends rConfig’s device management capabilities beyond traditional SSH and Telnet protocols, enabling custom script execution for specialized network devices, proprietary platforms, and complex automation workflows. SIE empowers organizations to integrate any device or system into rConfig’s centralized configuration management framework using custom scripts in any scripting language.

Danger

Custom scripts executed by SIE may introduce security risks if not properly validated and tested. Organizations should implement strict access controls, code reviews, and testing procedures to mitigate potential vulnerabilities.

Developers must read the Developer Notice before implementing SIE in production environments.

---

Understanding Script Integration Engine

What is SIE?

Script Integration Engine is rConfig’s extensibility framework for device communication and data retrieval. While rConfig natively supports SSH and Telnet for configuration backup from standard network devices, SIE recognizes that modern network environments include:

Proprietary Devices: Equipment with custom management interfaces, non-standard protocols, or vendor-specific APIs that don’t support SSH/Telnet configuration retrieval.

Legacy Systems: Older devices or platforms requiring specific connection sequences, authentication methods, or data extraction procedures not supported by standard protocols.

Operational Technology (OT): Industrial control systems, SCADA devices, building management systems, and other OT infrastructure requiring specialized communication protocols.

IoT Devices: Internet of Things devices with REST APIs, MQTT interfaces, or custom management protocols rather than traditional CLI access.

Complex Workflows: Devices requiring multi-step procedures, intermediary systems, or orchestrated sequences to extract configuration data.

How SIE Works

SIE bridges the gap between rConfig’s standard device management workflows and custom device requirements through a script-based approach:

Script as Protocol: Instead of SSH or Telnet, devices are configured to use “script” as their connection protocol. This instructs rConfig to execute a custom script rather than initiating a standard network connection.

Parameter Injection: rConfig passes device-specific information (IP address, credentials, custom fields) to the script as command-line parameters or environment variables.

Script Execution: The custom script—written in Expect, Python, Bash, Perl, or any language with a server-installed interpreter—executes its logic: connecting to the device, authenticating, retrieving data, processing output, and formatting results.

Output Capture: Script output (stdout) is captured by rConfig and treated as device configuration content, subject to the same processing as SSH/Telnet-retrieved configs.

Standard Integration: Captured output integrates seamlessly with rConfig’s core features: versioning and diff analysis, compliance checking, search and reporting, scheduled backups, and change notifications.

---

SIE Architecture and Components

System Components

Script Storage: Custom scripts reside in a dedicated directory on the rConfig server:

/var/www/html/rconfig8/current/storage/app/rconfig/scripts/

All scripts must be placed in this location with appropriate execute permissions for the web server user (typically www-data or apache).

Script Interpreters: SIE supports any scripting language with an interpreter installed on the rConfig server:

• Expect: For interactive command-line automation (terminal expect/send sequences)
• Python: For API calls, data processing, complex logic
• Bash: For shell-based automation, piping commands, file operations
• Perl: For text processing, regex-heavy operations, legacy scripts
• Others: Ruby, PowerShell (on Windows), custom binaries—any executable the server can run

Connection Templates: Device templates specify “script” as the protocol, distinguishing SIE-enabled devices from standard SSH/Telnet devices. Templates define timeout values, idle timeout settings, and protocol designation.

Command Categories: Commands in rConfig’s command categories invoke scripts with the full interpreter path, script filename, and parameter variables. Commands execute during scheduled backups or manual debug runs, just like standard device commands.

Parameter Substitution: rConfig provides variables that are replaced with actual values when scripts execute:

• {script_path}: Full path to scripts directory
• {device_ip}: Device IP address from rConfig database
• {device_username}: Primary device credential username
• {device_password}: Primary device credential password
• {device_enable_password}: Enable/privilege password (if configured)

Execution Workflow

Stage 1: Backup Initiation

When a scheduled backup runs or manual debug is triggered for an SIE-enabled device:

1. rConfig identifies device uses “script” protocol (from connection template)
2. Retrieves command from assigned category
3. Substitutes parameter variables with actual device data
4. Constructs full command line with interpreter path, script name, parameters

Stage 2: Script Execution

rConfig executes the constructed command on the server:

1. Script interpreter launches with specified script file
2. Parameters passed as command-line arguments or environment variables
3. Script logic executes: device connection, authentication, data retrieval, processing
4. Script outputs results to stdout
5. Script exits with status code (0 = success, non-zero = failure)

Stage 3: Output Processing

rConfig captures script execution results:

1. Stdout captured as “configuration” content
2. Stderr captured for error logging and troubleshooting
3. Exit code determines backup success/failure status
4. Output stored in device’s configuration history with timestamp
5. Diff generated against previous version (if exists)
6. Compliance checks executed against captured output (if configured)

Stage 4: Integration

Captured script output integrates with rConfig features:

• Configuration History: Script output appears in device config history timeline
• Diff Analysis: Changes between script runs highlighted in visual diff
• Search: Script output indexed and searchable via rConfig’s search features
• Compliance: Output validated against compliance policies and rules
• Reporting: Script execution results included in backup reports and statistics

---

Use Cases and Applications

Use Case 1: Proprietary Device Management

Scenario: Organization uses proprietary load balancers with custom CLI interfaces that don’t support standard SSH config dumps.

SIE Solution:

• Expect script automates interactive login sequence
• Script navigates proprietary menu system
• Executes vendor-specific config export commands
• Captures and formats output for rConfig
• Result: Load balancer configs backed up like standard network devices

Benefits: Centralized management of proprietary and standard devices, consistent versioning and change tracking across all infrastructure, compliance checking for specialized equipment.

Use Case 2: API-Based Device Integration

Scenario: Modern firewall provides REST API for configuration retrieval but no CLI access.

SIE Solution:

• Python script calls firewall REST API with authentication
• Retrieves configuration in JSON/XML format
• Converts API response to readable text format
• Outputs formatted config to stdout for rConfig capture
• Result: API-only devices integrated into standard backup workflows

Benefits: Leverage vendor APIs without custom integration development, convert API data to human-readable configs, maintain version history of API-retrieved configurations.

Use Case 3: Multi-Step Device Procedures

Scenario: Industrial control system requires connecting through jump host, authenticating with two-factor, then executing proprietary data extraction tool.

SIE Solution:

• Bash script orchestrates multi-step connection sequence
• SSH to jump host with first credential
• Authenticate to target device with second credential plus OTP
• Execute vendor-specific data export utility
• Parse and format output for rConfig
• Result: Complex connection workflows automated and integrated

Benefits: Handle complex authentication and connection requirements, orchestrate multi-system procedures, capture data from difficult-to-access systems.

Use Case 4: IoT and OT Device Management

Scenario: Building management system with MQTT interface for configuration export, no traditional CLI.

SIE Solution:

• Python script with MQTT client library
• Subscribes to device configuration topic
• Requests config export via MQTT publish
• Receives configuration data via MQTT message
• Formats and outputs for rConfig capture
• Result: IoT/OT devices managed alongside network infrastructure

Benefits: Integrate non-traditional devices into centralized management, apply same governance to IoT/OT as network devices, unified view of all infrastructure configurations.

---

Enabling SIE

Caution

Security Consideration: Script Integration Engine allows execution of arbitrary scripts on the rConfig server. Enable SIE only in trusted environments with strict script review processes. All scripts should be audited for security vulnerabilities, malicious code, or unintended consequences before deployment.

Activation Process

SIE is disabled by default and must be explicitly enabled in rConfig’s environment configuration.

Step 1: Access Server CLI

Connect to the rConfig server with root or sudo privileges:

ssh admin@rconfig-server
sudo -i

Step 2: Edit Environment File

Open the rConfig environment configuration:

nano /var/www/html/rconfig8/current/.env

Step 3: Enable SIE Feature

Locate the SIE configuration setting (or add if not present) and set to true:

SCRIPT_INTEGRATION_ENGINE_ENABLED=true

Step 4: Save and Exit

Save changes to .env file (Ctrl+O, Enter, Ctrl+X in nano).

Step 5: Clear Application Cache

Clear rConfig’s application cache to apply configuration changes:

cd /var/www/html/rconfig8/current
php artisan rconfig:clear-all

Verification: Confirm SIE is enabled by checking that script-based device commands now execute. Disabled SIE results in script commands being ignored or failing with “script protocol not supported” errors.

---

Script Development Guidelines

Script Requirements

Output to Stdout: Scripts must write configuration data to standard output (stdout). rConfig captures stdout as the device “configuration” for storage and processing.

Exit Codes: Use standard Unix exit codes to signal success or failure:

• Exit 0: Successful execution, output captured
• Exit non-zero: Execution failed, output may be discarded or logged as error

Error Handling: Implement robust error handling within scripts:

• Validate input parameters
• Handle connection failures gracefully
• Provide meaningful error messages to stderr
• Exit with appropriate status codes

Parameter Usage: Access rConfig-provided parameters via command-line arguments or environment variables based on script language conventions.

Idempotency: Scripts should produce consistent output when run multiple times against unchanged device state, enabling accurate diff analysis.

Supported Languages and Interpreters

Expect:

• Ideal for: Interactive CLI automation, terminal-based devices
• Binary location: /usr/bin/expect (verify with which expect)
• Use when: Device requires interactive command/response sequences

Python:

• Ideal for: API calls, JSON/XML processing, complex logic
• Binary location: /usr/bin/python3 (verify with which python3)
• Use when: REST APIs, data transformation, library-rich operations

Bash:

• Ideal for: Shell command orchestration, file operations, piping
• Binary location: /bin/bash (verify with which bash)
• Use when: Simple CLI automation, command chaining, text processing

Perl:

• Ideal for: Regular expressions, text parsing, legacy automation
• Binary location: /usr/bin/perl (verify with which perl)
• Use when: Complex text processing, maintaining existing Perl scripts

Locating Interpreters: Use which command to find binary paths:

which expect   # /usr/bin/expect
which python3  # /usr/bin/python3
which bash     # /bin/bash
which perl     # /usr/bin/perl

These paths are required when constructing commands in rConfig command categories.

Script Parameters

Available Variables:

rConfig provides five variables for use in script commands:

{script_path}: Full path to scripts directory (/var/www/html/rconfig8/current/storage/app/rconfig/scripts/)

• Use: Prefix script filename to construct full path
• Example: {script_path}device_backup.py expands to full script path

{device_ip}: Device IP address from rConfig device record

• Use: Connect to device, API endpoint construction
• Example: 192.168.1.100

{device_username}: Primary device credential username

• Use: Authentication to device
• Example: admin

{device_password}: Primary device credential password

• Use: Authentication to device
• Example: secretpassword
• Security note: Handle securely in scripts, avoid logging

{device_enable_password}: Enable or privilege escalation password

• Use: Cisco-style enable mode or privilege escalation
• Example: enablesecret
• May be empty if device doesn’t use enable passwords

Parameter Order: Variables can be specified in any order in commands. Use only the parameters your script requires—not all five are mandatory.

Example Command Using Parameters:

/usr/bin/python3 {script_path}api_backup.py {device_ip} {device_username} {device_password}

Expands to:

/usr/bin/python3 /var/www/html/rconfig8/current/storage/app/rconfig/scripts/api_backup.py 192.168.1.100 admin secretpassword

---

Testing and Debugging

Pre-Deployment Testing

Test Scripts Independently: Before integrating with rConfig, test scripts directly on the server:

# Manual execution with test parameters
/usr/bin/expect /var/www/html/rconfig8/current/storage/app/rconfig/scripts/test_script.exp 192.168.1.100 admin password

# Verify output and exit code
echo $?  # Should be 0 for success

Validate Output Format: Ensure script output is suitable for rConfig configuration storage:

• Text format (not binary)
• Reasonable size (very large outputs may cause performance issues)
• Consistent format across executions (for accurate diff)

Error Scenario Testing: Test script behavior under failure conditions:

• Unreachable device (network down, IP incorrect)
• Authentication failure (wrong credentials)
• Unexpected device responses
• Timeout scenarios

rConfig Debug Mode

Debug Command Execution: Use rConfig’s debug feature to test script integration:

1. Navigate to device page in rConfig UI
2. Click “Debug” or “Test Connection”
3. Select command category containing script command
4. Review execution output and any errors

Output Review: Debug mode displays:

• Complete command executed (with parameters substituted)
• Script stdout (configuration output)
• Script stderr (error messages)
• Exit code and execution status
• Execution time

Iterative Refinement: Use debug mode to refine scripts:

1. Run debug, review output
2. Identify issues in script logic or output format
3. Update script on server
4. Re-run debug to validate fixes
5. Repeat until successful

---

Best Practices

Script Management

Version Control: Maintain scripts in version control system (Git) outside rConfig server, enabling change tracking, rollback capability, and collaborative development.

Naming Conventions: Use descriptive script names indicating device type and function:

• cisco_asa_backup.exp - Expect script for Cisco ASA
• paloalto_api_config.py - Python for Palo Alto API
• radware_alteon_dump.exp - Expect for Radware Alteon

Documentation: Include comments in scripts documenting:

• Purpose and use case
• Required parameters and order
• Expected device responses
• Error handling logic
• Author and modification history

Permissions: Set appropriate execute permissions on scripts:

chmod 755 /var/www/html/rconfig8/current/storage/app/rconfig/scripts/your_script.sh
chown www-data:www-data /var/www/html/rconfig8/current/storage/app/rconfig/scripts/your_script.sh

Security Considerations

Credential Handling: Never log or expose device credentials:

• Avoid echoing passwords to stdout/stderr
• Don’t write credentials to temporary files
• Clear sensitive variables after use

Input Validation: Validate all parameters received from rConfig:

• Check IP address format
• Sanitize inputs to prevent injection attacks
• Validate expected parameter count

Least Privilege: Run scripts with minimum necessary permissions. Avoid requiring root privileges for script execution if possible.

Audit Trail: Log script execution to separate audit log (not rConfig output):

• Timestamp and device identifier
• Execution status (success/failure)
• Any security-relevant events

Operational Excellence

Timeout Configuration: Set appropriate timeouts in connection templates:

• Consider script execution time (API calls, data processing)
• Balance responsiveness with reliability
• Test with worst-case scenarios (slow networks, busy devices)

Error Handling: Implement comprehensive error handling:

• Catch and handle all exceptions
• Provide actionable error messages
• Log errors for troubleshooting without exposing to stdout

Performance: Optimize scripts for execution speed:

• Minimize unnecessary operations
• Cache reusable data where applicable
• Avoid excessive logging or debug output in production

Monitoring: Track script execution metrics:

• Success/failure rates per device
• Execution time trends
• Common error patterns

---

Limitations and Considerations

Current Limitations

Beta Status: SIE is currently in beta phase. Features, interfaces, and behavior may change in future releases based on user feedback and operational experience.

Server Resources: Script execution consumes server resources (CPU, memory, network). High concurrency (many devices backing up simultaneously via scripts) may impact server performance.

Execution Timeout: Scripts must complete within timeout configured in connection template. Long-running scripts (minutes) may time out, causing backup failure.

No Interactive Input: Scripts cannot prompt for user input during execution. All parameters must be provided via command or script must use hardcoded defaults.

Error Visibility: Script errors may not be immediately visible in UI. Check debug output, server logs, and stderr capture for troubleshooting.

When to Use SIE

Use SIE When:

• Device doesn’t support SSH/Telnet for config retrieval
• Vendor provides only API access to configuration data
• Complex multi-step procedures required for data extraction
• Device uses proprietary or non-standard protocols
• Existing automation scripts can be repurposed for rConfig integration

Don’t Use SIE When:

• Device supports standard SSH/Telnet config backup (use native rConfig)
• Simple REST API can be handled by future rConfig API connector features
• Security policy prohibits server-side script execution
• Script complexity would be difficult to maintain long-term

---

Support and Resources

Getting Help

Tip

Enterprise Support for SIE: Script Integration Engine implementation can be complex depending on device types and requirements. Organizations deploying SIE for critical infrastructure should contact rConfig support for implementation assistance, script development guidance, and best practices consultation. Our support team can help with script architecture, troubleshooting, and optimization for production environments.

Support Channels:

• Email: [email protected]
• Documentation: Check SIE-specific guides and examples
• Community: rConfig user forums and discussion groups
• GitHub: Example scripts and templates repository

Example Repository

rConfig maintains a public repository of community-contributed SIE scripts and connection templates:

GitHub Repository: https://github.com/rconfig/rConfig-templates

Repository Contents:

• Example scripts for common device types
• Connection templates for SIE-enabled devices
• Documentation and usage guides
• Community contributions and improvements

Contribution: Users are encouraged to contribute working scripts and templates to benefit the broader rConfig community.

---

Related Documentation

• SIE Expect Script Example - Detailed Expect script walkthrough
• Device Templates - Creating and managing device templates
• Commands Configuration - Setting up device commands
• Configuration Backup Implementation - Understanding backup workflows

---

Quick Reference

Enabling SIE

# Edit .env file
nano /var/www/html/rconfig8/current/.env

# Add or set:
SCRIPT_INTEGRATION_ENGINE_ENABLED=true

# Clear cache
cd /var/www/html/rconfig8/current
php artisan rconfig:clear-all

Script Storage Location

/var/www/html/rconfig8/current/storage/app/rconfig/scripts/

Available Parameters

• {script_path} - Scripts directory path
• {device_ip} - Device IP address
• {device_username} - Device username
• {device_password} - Device password
• {device_enable_password} - Enable password

Command Format

/path/to/interpreter {script_path}scriptname.ext {device_ip} {device_username} {device_password}

Connection Template Protocol

connect:
  protocol: script

Finding Interpreters

which expect   # /usr/bin/expect
which python3  # /usr/bin/python3
which bash     # /bin/bash
which perl     # /usr/bin/perl