Connection Templates in rConfig V8 Core

Connection templates define how rConfig V8 Core authenticates, connects, and interacts with your network devices. After reading this page, you can understand how templates work, import community templates, create and edit your own in the YAML editor, and troubleshoot connection problems they cause.

When to use this

Use connection templates whenever you need rConfig to talk to a new device type, standardise connection behaviour across a fleet, or fix connection failures caused by mismatched prompts, timeouts, or paging. Templates let you define connection parameters once and reuse them across many devices, rather than configuring each device by hand.

Understanding connection templates

A connection template is a reusable blueprint that specifies connection parameters, authentication prompt patterns, CLI prompt recognition, command syntax, and behaviour for a group of devices. Define these parameters once in a template, then apply that template to every device of the same type or vendor family.

Templates solve several common problems in configuration management:

• Consistency across the fleet: All devices of a type use identical connection parameters, reducing drift and troubleshooting effort.
• Multi-vendor support: Each template encapsulates a vendor’s CLI behaviour, prompt patterns, and command syntax, so rConfig can talk to diverse equipment.
• Simplified onboarding: Assign a pre-built template to a new device instead of configuring connection parameters from scratch.
• Centralised maintenance: Update a template once (for example a changed timeout) and the change applies to every device using it.

Template architecture

Each template is written in YAML, a human-readable data format. A template defines:

• Connection protocol: Whether to use SSH, Telnet, or another protocol.
• Authentication parameters: The username and password prompt patterns (not actual credentials).
• CLI prompt recognition: Patterns that identify when the device is ready for commands.
• Command execution behaviour: Timeout values, paging settings, and command delimiters.
• Privilege escalation: Enable mode access and privilege level commands.
• Vendor-specific handling: Special handling for unique device behaviours.

How templates map to devices

• One template per device: Each device is assigned exactly one connection template, giving predictable connection behaviour.
• Many devices per template: A single template can be assigned to unlimited devices. This is the main mechanism for scaling configuration management.
• Cross-vendor flexibility: A template labelled for one vendor (such as Cisco IOS) often works with other vendors using similar CLI patterns. Test before relying on it across vendor boundaries.
• No limit on template count: Create as many templates as your equipment requires.
• Portability: Templates use a standard format compatible across rConfig versions, so they can be shared and reused.

Default and community templates

rConfig V8 Core ships with four default connection templates covering common device types:

• Cisco IOS/IOS-XE: Standard Cisco router and switch platforms.
• Cisco NXOS: Nexus data center switching platforms.
• Cisco ASA: Adaptive Security Appliance firewalls.
• Generic SSH: Basic SSH connectivity for Linux/Unix systems.

Although labelled for Cisco, these templates frequently work with Arista, HP/Aruba, Juniper (with modifications), and other vendors using similar CLI patterns. Verify compatibility through testing before production deployment.

The rConfig project maintains an open-source template repository on GitHub with templates for dozens of vendor platforms, YAML key/value documentation, and contribution guidelines.

Tip

If you build a working template for equipment not yet in the repository, consider contributing it by emailing info@rconfig.com so other users benefit.

Templates main view

The Templates interface provides centralised management for your template library. The main view lists all templates in a searchable, sortable table.

From this view you can:

• View all configured templates with their key metadata.
• Filter templates by name or protocol.
• Add a new custom template.
• Import the community template repository to local storage.
• Edit or delete existing templates.
• Assign templates to test devices for validation.

How to import community templates

Importing community templates is a deliberate two-step process. First you download the repository to local storage on the server, then you import the individual templates you want into your library.

Prerequisites

• The git command available on the server or in your container. See Docker setup if you run rConfig in containers.
• The storage directory writable by the web server user.
• Access to the Templates interface under Inventory → Templates.

Step 1: Download the community repository

1. Navigate to Inventory → Templates.
2. Click Import Templates (the button with the GitHub icon).
3. rConfig clones the repository into local storage under storage/app/rconfig/templates/rConfig-templates.
4. Read the success message confirming how many template files were downloaded.

At this point the templates are staged on disk but the Templates list is unchanged. Nothing has been added to your library yet.

Step 2: Import individual templates into your library

1. Click Add Template, or edit an existing template, to open the YAML editor.
2. Click Choose Template to Import (this appears once the repository has been downloaded).
3. Select a vendor folder, then select a template file from that vendor.
4. Click Apply to load the selected template’s YAML into the editor.
5. Review or adjust the template name and contents.
6. Click Save to add the template to your library.

Each save creates one template record. Repeat for every community template you want. Because you save them individually, you keep full control over naming and content, and existing custom templates are never overwritten.

Tip

Re-run Import Templates periodically to refresh the local copy with updated templates and new vendor support, then use Choose Template to Import to pull in what you need.

Common gotchas when importing

• Downloading the repository does not add templates to your list. The Import Templates button only clones the repository to local storage. Your template count will not change until you import templates individually in Step 2.
• If the download reports success but no files appear under storage/app/rconfig/templates/rConfig-templates, confirm git is installed and the storage directory is writable. In Docker, check the container includes git and the storage volume is writable.
• Choose Template to Import only appears after a successful download. If you do not see it, run Step 1 first.

How to create and edit templates

Template creation and editing happen in rConfig’s integrated YAML editor, which provides syntax highlighting and structured formatting.

Prerequisites

• Access to the Templates interface under Inventory → Templates.
• A non-production device available for testing the template before deployment.
• Console or out-of-band access to that test device in case a connection test locks you out.

Create a new template

1. Navigate to Inventory → Templates.
2. Click Add Template to open the YAML editor with a blank template.
3. Enter a descriptive template name indicating the vendor or platform.
4. Specify the connection protocol (SSH, Telnet, and so on).
5. Set the authentication prompt patterns.
6. Configure the command prompt recognition patterns.
7. Set timeout values appropriate for the device’s response time.
8. Define paging control commands if the device requires them.
9. Click Save, then assign the template to a test device and run a debug connection test (see How to test and debug a template).
10. Refine the parameters based on the test, then assign to production devices.

Edit an existing template

1. Select the template from the templates list.
2. Click the Edit action to open the YAML editor with the current configuration.
3. Modify the required parameters, preserving YAML formatting and indentation.
4. Click Save.

Template edits affect every device currently using that template. Test changes on non-production devices first, schedule them during maintenance windows, and document the rationale.

Clone a template

The fastest way to build a similar template:

1. Open an existing template close to your target device.
2. Change the template name.
3. Adjust the vendor-specific parameters.
4. Click Save to store it as a new template.

This preserves a working configuration while letting you customise for device variations.

YAML editor guidelines

The editor is a direct interface to the YAML configuration file. Follow these syntax rules to avoid errors:

• Comments begin with #, on their own line or at the end of a configuration line. Default templates include extensive comments explaining each parameter. Keep them or add your own.
• Indentation uses spaces, not tabs, typically 2 or 4 spaces per level.
• Quotation marks may be needed on string values containing special characters.
• Key-value pairs use key: value with a space after the colon.
• List items begin with a dash and a space, - item.
• Case matters: keys and values are case-sensitive.

Username and password prompts

The username and password keys define the CLI prompt patterns rConfig watches for during authentication. They specify prompt text patterns, not actual credentials:

username: "Username:"  # The prompt the device displays
password: "Password:"  # The password prompt pattern

Device credentials are stored separately in the device configuration and provided at connection time. Never put real usernames or passwords in a template.

Timeout configuration

The timeout parameter controls how long rConfig waits for a device response before declaring a connection failure:

timeout: 15  # Timeout in seconds

Timeout best practices

rConfig recommends timeout values between 5 and 30 seconds for most devices. Devices that need extended processing time (large outputs, config generation) may need higher values. Legacy 60-second defaults cause long waits during failures. If you hit timeout issues, start at 15 to 20 seconds and adjust from there.

The YAML editor does not perform real-time syntax validation. Syntax errors may not surface until template execution, where they cause connection failures. Watch for the common YAML mistakes: extra or missing indentation spaces, missing colons after keys, unmatched quotes, incorrect list formatting, mixed tabs and spaces, and trailing spaces.

How to test and debug a template

Effective template development is iterative. Test, read the debug output, refine, and repeat.

1. Identify a non-production device for testing, with console or out-of-band access available.
2. Navigate to Inventory → Devices and edit the test device.
3. Assign the new template and save.
4. Run a debug connection test from the CLI:

cd /var/www/html/rconfig
php artisan rconfig:download-device {device-id} --debug

The --debug flag prints verbose output covering connection attempts, the authentication sequence, prompt recognition, command execution, and any errors or timeout events.

5. Review the output for successful authentication, correct prompt recognition, complete command execution, and a clean disconnect.
6. Adjust the prompt patterns, timeout values, command syntax, or privilege escalation as needed, then retest.
7. Before production, test against multiple devices of the same type and over several connection cycles.

For full YAML key documentation, value formats, and worked examples, see the rConfig templates repository on GitHub.

Why isn’t my template connecting?

Template problems usually show up as connection failures, authentication errors, or incomplete output. The tabs below cover the most common causes and fixes.

Connection timeouts

Symptoms: connections fail with timeout errors, downloads are incomplete, or success is intermittent.

Common causes: the timeout value is too low, network latency on WAN or VPN paths, an overloaded device responding slowly, or a prompt pattern mismatch that leaves rConfig waiting for a prompt that never matches.

Resolution:

1. Increase the timeout incrementally (start with 5-second steps).
2. Run with --debug to observe actual response times.
3. Verify prompt patterns match the real device output.
4. Extend timeouts for remote devices on high-latency paths.
5. Check device CPU and memory during connection attempts.

# Original - too aggressive
timeout: 5

# Adjusted for WAN devices
timeout: 20

Authentication failures

Symptoms: login fails despite correct credentials, connection succeeds but authentication is rejected, or prompt recognition fails after login.

Common causes: username/password prompt patterns do not match the device, case mismatches, unexpected special characters in prompts, or insufficient privilege after authentication.

Resolution:

1. Connect to the device manually and record the exact prompt text.
2. Update the template prompt patterns to match precisely.
3. Account for case sensitivity.
4. Verify credential storage in the device configuration.
5. Check privilege escalation commands if enable mode is required.

# Standard format
username: "Username:"
password: "Password:"

# Case variations
username: "username:"
password: "password:"

# Device-specific format
username: "login:"
password: "Enter password:"

Incomplete output

Symptoms: configuration retrieval stops mid-file, sections are missing, or responses are truncated.

Common causes: paging is not disabled, command output exceeds the timeout, buffer size limits, or mid-output text that matches the prompt pattern.

Resolution:

1. Verify the paging disable command in the template.
2. Increase the timeout for lengthy outputs.
3. Check for prompt pattern false positives.
4. Test with simplified commands to isolate the issue.
5. Review the device’s paging control requirements.

# Cisco IOS
paging_command: "terminal length 0"

# Juniper JunOS
paging_command: "set cli screen-length 0"

# HP/Aruba
paging_command: "no page"

YAML syntax errors

Symptoms: the template fails to save, connections fail immediately, or behaviour is unexpected.

Common causes: inconsistent indentation, unmatched or incorrect quotes, missing colons, trailing spaces, or tab characters instead of spaces.

Resolution:

1. Run the template through a YAML validator.
2. Check indentation is consistent (2 or 4 spaces).
3. Confirm all quotes are paired.
4. Replace any tab characters with spaces.
5. Compare against a working template from the repository, modifying incrementally and testing after each change.

Common template parameters

Parameter	Purpose	Typical values
timeout	Connection timeout in seconds	5-30 seconds
username	Username prompt pattern	”Username:”, “login:“
password	Password prompt pattern	”Password:”, “password:“
prompt	CLI ready prompt pattern	Device-specific regex
protocol	Connection protocol	SSH, Telnet
paging_command	Disable output paging	Vendor-specific
enable_password	Enable mode prompt	”Password:“
enable_command	Privilege escalation	”enable”, “en”

Recommended timeout values by scenario

Scenario	Recommended timeout	Rationale
LAN devices, modern hardware	10-15 seconds	Fast network, responsive devices
WAN devices, remote locations	20-30 seconds	Network latency considerations
Legacy equipment	25-35 seconds	Slower device processing
Devices with large configs	30-45 seconds	Extended output generation time
Test/development environment	15 seconds	Balance speed and reliability

Security considerations

• Never embed credentials in template files. Use rConfig’s encrypted credential storage instead.
• Prefer SSH over Telnet wherever the device supports it.
• Use the minimum required privilege level, and enable mode only when a command needs it.
• Document vendor-specific quirks and security requirements in YAML comments.

Assign a template to a device

1. Navigate to Inventory → Devices.
2. Select the device to configure, or create a new device.
3. Select the template from the Connection Template dropdown.
4. Save the device configuration.

The assigned template controls all connection behaviour for that device, including configuration downloads and SNMP operations. Multiple devices can share one template for consistent behaviour across a fleet.

What’s next

• Add and manage devices to assign templates and run bulk operations.
• CLI commands for testing and debugging templates from the command line.
• Scheduled tasks to automate configuration downloads using your templates.