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.

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.

Failure Detection: [8.1.1] SScripts are validated against defined failure criteria including exit codes, error patterns, and required success indicators. When multiple commands execute against a device, any matching success pattern validates the script execution, enabling flexible validation across different script outputs.

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, protocol designation, and failure criteria for script validation.

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_name}: Device name from rConfig database (V8.1.2+)
{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:

rConfig identifies device uses “script” protocol (from connection template)
Retrieves command from assigned category
Substitutes parameter variables with actual device data
Constructs full command line with interpreter path, script name, parameters
Loads failure criteria from connection template

Stage 2: Script Execution

rConfig executes the constructed command on the server:

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

Stage 3: Failure Validation

rConfig validates script execution against defined failure criteria:

Exit Code Check: Compares script exit code against configured failure exit codes
Error Pattern Matching: Searches stdout and stderr for defined error patterns (ANY match = failure)
Success Pattern Validation: Verifies at least one success pattern is present in output (ANY match = success)
Failure Determination: If any criteria indicate failure, backup is marked as failed

Stage 4: Output Processing

For successful script executions, rConfig captures results:

Stdout captured as “configuration” content
Stderr captured for error logging and troubleshooting
Exit code and failure criteria results stored with backup metadata
Output stored in device’s configuration history with timestamp
Diff generated against previous version (if exists)
Compliance checks executed against captured output (if configured)

Stage 5: 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
Notifications: Failed backups trigger configured notifications with failure reasons

Configuring Failure Criteria

Overview

Failure criteria enable precise control over script execution validation. Rather than relying solely on exit codes, you can define comprehensive failure detection rules that examine script output, validate expected results, and identify known error conditions.

Failure Criteria Types

Exit Code Validation

Exit codes are integer values returned by scripts upon completion. While zero typically indicates success, you can specify which non-zero codes should be treated as failures:

failure_criteria:
  exit_codes: [1, 2, 255]

This configuration treats exit codes 1, 2, and 255 as failures while allowing other non-zero codes (like informational warnings) to pass.

Error Pattern Detection

Error patterns are text strings or phrases that indicate failures when found in script output or error streams:

failure_criteria:
  error_patterns:
    - "Connection refused"
    - "Authentication failed"
    - "ERROR:"
    - "Timeout"
    - "No route to host"

rConfig searches both stdout and stderr for these patterns using case-insensitive matching. If any pattern is found, the backup is marked as failed with a detailed reason.

Success Pattern Validation

Success patterns are required text strings that must appear in script output for the backup to be considered successful:

failure_criteria:
  success_patterns:
    - "Configuration retrieved successfully"
    - "END OF CONFIG"

If any defined success pattern is missing from the output, the backup fails even if exit codes and error patterns would otherwise indicate success.

Template Configuration

Add failure criteria to your connection template YAML file:

# rConfig connection template
main:
  name: "custom_device_template"
  desc: "Template for custom device with failure validation"

connect:
  timeout: 30
  idleTimeout: 30
  protocol: script

failure_criteria:
  # Exit codes that indicate failure (optional)
  exit_codes: [1, 2, 255]

  # Patterns in output that indicate errors (optional)
  error_patterns:
    - "Connection refused"
    - "Authentication failed"
    - "ERROR:"
    - "FAILURE:"
    - "Could not connect"
    - "Timeout waiting for"

  # Patterns that must be present for success (optional)
  success_patterns:
    - "Configuration saved"
    - "Backup complete"

Configuration Examples

Example 1: Exit Code Only Validation

Simple validation based solely on exit codes:

failure_criteria:
  exit_codes: [1, 2]

Script fails if it exits with code 1 or 2. All other exit codes (including 0 and other non-zero values) are treated as success.

Example 2: Error Pattern Detection

Detect failures based on known error messages:

failure_criteria:
  error_patterns:
    - "connection timeout"
    - "authentication error"
    - "device not responding"
    - "invalid credentials"

Script fails if any of these patterns appear in stdout or stderr, regardless of exit code.

Example 3: Success Validation

Ensure specific success indicators are present:

failure_criteria:
  success_patterns:
    - "CONFIG-END"
    - "Total lines:"

Script fails if both patterns are not found in output, even with exit code 0.

Example 4: Multiple Scripts with Shared Template

Template supporting three different scripts on the same device:

failure_criteria:
  exit_codes: [1, 2, 255]

  error_patterns:
    - "Connection refused"
    - "Authentication failed"
    - "ERROR:"
    - "CRITICAL:"

  success_patterns: # ANY of these = success
    - "script end" # For config dump scripts
    - "Current AppWall signaling" # For system info scripts
    - "Configuration retrieved" # For backup scripts
    - ">> Main#" # Fallback prompt

Each script needs only ONE of these patterns in its output to succeed.

Example 5: Comprehensive Validation

Combine all three validation types:

failure_criteria:
  exit_codes: [1, 2, 255]

  error_patterns:
    - "Connection refused"
    - "Authentication failed"
    - "ERROR:"
    - "CRITICAL:"

  success_patterns:
    - "Configuration retrieved"
    - "Backup successful"

Script must:

Exit with code other than 1, 2, or 255
Not contain any error patterns in output
Contain all success patterns in output

Example 6: API-Based Device

Validation for REST API script:

failure_criteria:
  exit_codes: [1, 3, 5]

  error_patterns:
    - '"status": "error"'
    - '"code": 4'
    - '"code": 5'
    - "HTTP 401"
    - "HTTP 403"
    - "HTTP 500"

  success_patterns:
    - '"status": "success"'
    - '"config":'

Multiple Scripts Per Device

When a device template is assigned to multiple commands (scripts), all scripts share the same failure criteria from the template. The success pattern validation uses OR logic to accommodate different script outputs:

Example Scenario: Device has three commands:

alteon_cdump_test_script.exp - outputs “script end”
alteon_sys_cur_test_script.exp - outputs “Current AppWall signaling”
alteon_sys_mmgmt_cur_test_script.exp - outputs “Current AppWall signaling”

Template Configuration:

failure_criteria:
  success_patterns:
    - "script end" # Matches cdump script
    - "Current AppWall signaling" # Matches sys_cur and mmgmt_cur
    - ">> Main#" # Fallback for all scripts

How Validation Works:

Each script executes independently
Each script’s output is checked against ALL success patterns
If ANY pattern matches, that script succeeds
The cdump script passes because “script end” is found
The sys_cur and mmgmt_cur scripts pass because “Current AppWall signaling” is found
All three could also pass with just the ”>> Main#” pattern if present

Best Practice: Include success patterns for all scripts that share the template, plus a common fallback pattern that appears in all outputs.

Pattern Matching Behavior

Case Insensitivity: All pattern matching is case-insensitive. Pattern “ERROR” matches “error”, “Error”, “ERROR”, etc.

Substring Matching: Patterns match anywhere in the output. Pattern “failed” matches “Authentication failed” or “Connection attempt failed”.

Partial Matches: Patterns don’t require exact word boundaries. Pattern “timeout” matches “connection timeout”, “timeouts occurred”, etc.

OR Logic for Success Patterns: Success patterns use OR logic - any one pattern matching indicates success. This is critical when multiple scripts execute against a single device, as each script may produce different output with different success indicators.

AND Logic for Error Patterns: Error patterns use OR logic for detection - any one pattern matching indicates failure.

First Match Wins: Validation stops at first matching error pattern or first matching success pattern. The specific pattern that caused failure or success is reported.

Combined Output: Both stdout and stderr are searched when checking error and success patterns.

Best Practices

Be Specific: Use precise error patterns to avoid false positives:

# Too broad - might match legitimate output
error_patterns:
  - "error"

# Better - more specific error conditions
error_patterns:
  - "connection error"
  - "authentication error"
  - "ERROR:"

Test Thoroughly: Run scripts manually with various scenarios to identify all possible error messages:

# Test with unreachable device
/usr/bin/python3 script.py 192.168.1.999

# Test with wrong credentials
/usr/bin/python3 script.py 192.168.1.1 wronguser wrongpass

# Test with network timeout
# (disconnect network during execution)

Capture all error messages to build comprehensive error_patterns list.

Use Success Patterns Sparingly: Only require success patterns if your script consistently outputs them. Missing patterns cause failures even when scripts work correctly.

Document Exit Codes: Document what each exit code means in your script:

#!/usr/bin/env python3
# Exit codes:
# 0 - Success
# 1 - Connection failure
# 2 - Authentication failure
# 3 - Timeout
# 5 - Invalid response from device

import sys

try:
    # Script logic
    print("Configuration retrieved")
    sys.exit(0)
except ConnectionError:
    print("Connection failed", file=sys.stderr)
    sys.exit(1)
except AuthenticationError:
    print("Authentication failed", file=sys.stderr)
    sys.exit(2)

Monitor Failure Reasons: Review backup logs to see which failure criteria are triggering. Adjust patterns based on operational experience.

Design for Multiple Scripts: When one template serves multiple commands, list all possible success patterns from all scripts. Use OR logic - any pattern matching validates the script:

# Good - covers all scripts
success_patterns:
  - 'script end'          # Script 1
  - 'Config saved'        # Script 2
  - 'Backup complete'     # Script 3
  - '>> Main#'            # All scripts

# Bad - too restrictive if scripts vary
success_patterns:
  - 'script end'          # Only Script 1 will pass

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
Validates success with pattern matching
Result: Load balancer configs backed up like standard network devices

Failure Criteria:

failure_criteria:
  error_patterns:
    - "Invalid menu selection"
    - "Command not recognized"
    - "Session timeout"
  success_patterns:
    - "Configuration export complete"

Benefits: Centralized management of proprietary and standard devices, consistent versioning and change tracking across all infrastructure, compliance checking for specialized equipment, automated failure detection for unusual error conditions.

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
Validates API response codes and status fields
Result: API-only devices integrated into standard backup workflows

Failure Criteria:

failure_criteria:
  exit_codes: [1, 2, 3]
  error_patterns:
    - "HTTP 401"
    - "HTTP 403"
    - "HTTP 500"
    - '"status": "error"'
    - "API rate limit exceeded"
  success_patterns:
    - '"status": "success"'
    - '"configuration":'

Benefits: Leverage vendor APIs without custom integration development, convert API data to human-readable configs, maintain version history of API-retrieved configurations, detect API-specific failures (rate limits, authentication, server errors).

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
Validate each step completed successfully
Result: Complex connection workflows automated and integrated

Failure Criteria:

failure_criteria:
  exit_codes: [1, 2, 5, 10]
  error_patterns:
    - "Jump host unreachable"
    - "OTP verification failed"
    - "Export utility not found"
    - "Permission denied"
  success_patterns:
    - "Export completed"
    - "Data retrieved successfully"

Benefits: Handle complex authentication and connection requirements, orchestrate multi-system procedures, capture data from difficult-to-access systems, validate success at each step of complex workflows.

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
Validates MQTT connection and message receipt
Result: IoT/OT devices managed alongside network infrastructure

Failure Criteria:

failure_criteria:
  exit_codes: [1, 2, 3]
  error_patterns:
    - "MQTT connection failed"
    - "Subscription timeout"
    - "Message not received"
    - "Invalid message format"
  success_patterns:
    - "Configuration message received"
    - "MQTT client disconnected cleanly"

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

Enabling SIE

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 (if code is in failure_criteria.exit_codes)

Define meaningful exit codes for different failure scenarios:

# Exit code conventions
EXIT_SUCCESS = 0
EXIT_CONNECTION_FAILED = 1
EXIT_AUTH_FAILED = 2
EXIT_TIMEOUT = 3
EXIT_INVALID_RESPONSE = 5

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
Output error patterns that match template failure_criteria

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.

Success Indicators: If using success_patterns validation, ensure scripts consistently output the required patterns:

#!/bin/bash
# Always output success indicator at end
echo "Configuration retrieved successfully"
echo "END OF CONFIG"

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

{device_name}: Device name from rConfig device record

Use: Pass through to scripts for device-specific logic, labeling, or API calls
Example: switch-core-01

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

Example Command Using Parameters:

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

Expands to:

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

Script Example with Failure Handling

Python API Script with Exit Codes and Error Messages:

#!/usr/bin/env python3
"""
Device API backup script with comprehensive failure handling
"""
import sys
import requests
from requests.exceptions import ConnectionError, Timeout

# Exit codes matching template failure_criteria
EXIT_SUCCESS = 0
EXIT_CONNECTION_FAILED = 1
EXIT_AUTH_FAILED = 2
EXIT_TIMEOUT = 3

def main():
    if len(sys.argv) < 4:
        print("ERROR: Insufficient parameters", file=sys.stderr)
        sys.exit(1)

    device_ip = sys.argv[1]
    username = sys.argv[2]
    password = sys.argv[3]

    api_url = f"https://{device_ip}/api/v1/config"

    try:
        response = requests.get(
            api_url,
            auth=(username, password),
            timeout=30,
            verify=False
        )

        if response.status_code == 401:
            print("ERROR: Authentication failed", file=sys.stderr)
            sys.exit(EXIT_AUTH_FAILED)

        if response.status_code != 200:
            print(f"ERROR: HTTP {response.status_code}", file=sys.stderr)
            sys.exit(1)

        config_data = response.json()

        if config_data.get('status') != 'success':
            print("ERROR: API returned error status", file=sys.stderr)
            sys.exit(1)

        # Output configuration to stdout
        print(config_data.get('configuration', ''))

        # Output success indicator
        print("Configuration retrieved successfully")

        sys.exit(EXIT_SUCCESS)

    except ConnectionError:
        print("ERROR: Connection refused", file=sys.stderr)
        sys.exit(EXIT_CONNECTION_FAILED)

    except Timeout:
        print("ERROR: Connection timeout", file=sys.stderr)
        sys.exit(EXIT_TIMEOUT)

    except Exception as e:
        print(f"ERROR: {str(e)}", file=sys.stderr)
        sys.exit(1)

if __name__ == "__main__":
    main()

Corresponding Template:

main:
  name: "api_device_template"
  desc: "API-based device with failure validation"

connect:
  timeout: 60
  idleTimeout: 30
  protocol: script

failure_criteria:
  exit_codes: [1, 2, 3]
  error_patterns:
    - "ERROR: Connection refused"
    - "ERROR: Authentication failed"
    - "ERROR: Connection timeout"
    - "ERROR: HTTP 401"
    - "ERROR: HTTP 403"
    - "ERROR: HTTP 500"
  success_patterns:
    - "Configuration retrieved successfully"

Testing and Debugging

Pre-Deployment Testing

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

# Test successful execution
/usr/bin/python3 /var/www/html/rconfig8/current/storage/app/rconfig/scripts/test_script.py 192.168.1.100 admin password

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

# Test failure scenarios
/usr/bin/python3 test_script.py 192.168.1.999 admin password  # Unreachable
echo $?  # Should be non-zero

/usr/bin/python3 test_script.py 192.168.1.100 wrong wrong  # Bad credentials
echo $?  # Should be non-zero

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)
Contains required success patterns (if configured)

Validate Error Patterns: Confirm scripts output error patterns that match template configuration:

# Run script with error and check stderr
/usr/bin/python3 script.py 192.168.1.999 admin password 2>&1 | grep "Connection refused"

# Should find the error pattern defined in template

Error Scenario Testing: Test script behavior under failure conditions:

Unreachable device (network down, IP incorrect)
Authentication failure (wrong credentials)
Unexpected device responses
Timeout scenarios
API rate limiting or server errors
Missing or malformed data in responses

Failure Criteria Testing

Test Exit Code Detection:

# Create test script with specific exit code
cat > test_exit.sh << 'EOF'
#!/bin/bash
exit 1
EOF

chmod +x test_exit.sh

# Run and verify exit code
./test_exit.sh
echo $?  # Should output 1

# Verify rConfig detects this as failure

Test Error Pattern Detection:

# Create script that outputs error pattern
cat > test_error.sh << 'EOF'
#!/bin/bash
echo "Some output"
echo "ERROR: Connection refused" >&2
exit 0
EOF

chmod +x test_error.sh

# Run and verify error output
./test_error.sh 2>&1 | grep "ERROR: Connection refused"

# Verify rConfig detects this as failure despite exit 0

Test Success Pattern Validation:

# Create script missing success pattern
cat > test_success.sh << 'EOF'
#!/bin/bash
echo "Configuration data here"
# Missing required "Configuration retrieved successfully"
exit 0
EOF

chmod +x test_success.sh

# Verify rConfig detects missing success pattern as failure

rConfig Debug Mode

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

Navigate to device page in rConfig UI
Click “Debug” or “Test Connection”
Select command category containing script command
Review execution output and failure validation results

Output Review: Debug mode displays:

Complete command executed (with parameters substituted)
Script stdout (configuration output)
Script stderr (error messages)
Exit code and execution status
Failure criteria evaluation results:
- Which exit codes were checked
- Which error patterns were found (if any)
- Which success patterns were missing (if any)
- Overall pass/fail determination
Execution time

Iterative Refinement: Use debug mode to refine scripts and failure criteria:

Run debug, review output and failure detection
Identify issues in script logic, output format, or failure criteria
Update script or template on server
Re-run debug to validate fixes
Repeat until successful with appropriate failure detection

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
Exit codes and their meanings
Error handling logic
Required success patterns
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)
Failure reason (if applicable)
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 matching failure_criteria patterns
Log errors for troubleshooting without exposing to stdout
Use meaningful exit codes

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
Which failure criteria trigger most often
Execution time trends
Common error patterns

Failure Criteria Maintenance: Review and update failure criteria based on operational experience:

Add new error patterns as discovered
Remove patterns causing false positives
Adjust exit code handling based on script behavior
Update success patterns if script output format changes