Troubleshoot Device Connectivity in rConfig V8 Core

Q: How do I debug a single device's connection?

Use the built-in debug command from the rConfig server: php artisan rconfig:download-device -d. The verbose output shows the connection, authentication, prompt detection, and each command, so you can see exactly where the download fails. Redirect it to a file to share with support.

After reading this page, you can diagnose why rConfig V8 Core fails to download a configuration from a network device and apply the right fix, working from network reachability through authentication, prompt detection, and protocol-specific behaviour. You will also know how to read the built-in debug command output to pinpoint exactly where a connection breaks.

When to use this

Use this page when a device returns a blank or partial configuration, times out, refuses the connection, or fails authentication during a manual test or a scheduled download. It assumes the device already exists in rConfig and you are trying to work out why polling does not succeed.

Prerequisites

A device already added to rConfig with an IP address and management protocol set. See Add and manage devices.
A credential set assigned to the device. Credentials are entered during device add, see the Device Add Workbook.
Shell access to the rConfig server to run network tests and the debug command.
The device prompt configured to match the live device. See Device Prompts.

What do connectivity failures look like?

Device connectivity failures show up in a handful of recognisable ways:

Blank configuration files: The download completes without errors but the saved file has no content. This usually means prompt detection failed and rConfig could not tell when device output ended.
Timeout errors: The download fails with a timeout after the configured period (60 seconds by default). rConfig did not receive the expected prompt in time, often due to a slow device or an incorrect prompt.
Authentication failures: The connection fails during login with “authentication failed” or “access denied”. Caused by wrong credentials, disabled accounts, or an authentication protocol mismatch.
Connection refused: The network connection fails immediately, indicating a firewall block, an unreachable device, or no service listening on the configured port.
Partial downloads: Some sections download while others fail or truncate. Often a timeout, a prompt mismatch, or a command-specific failure.

Diagnose in layers

Work through the layers in sequence so you never skip a fundamental prerequisite:

Network connectivity: Basic IP reachability, routing, and firewall rules between the rConfig server and the device.
Service availability: SSH, Telnet, or SNMP is running on the device and accepting connections on the configured port.
Authentication: Credentials are correct, the account is active, and the authentication method matches the device.
Protocol interaction: Prompt detection, command execution, and output capture work for the device’s protocol behaviour.
rConfig configuration: Device settings in rConfig (prompts, commands, timeouts) reflect the actual device behaviour.

Verify network connectivity

Run these checks from the rConfig server, since that is the host that connects to devices.

Ping the device to confirm basic reachability (if ICMP is permitted):
Terminal window
```
ping -c 4 192.168.1.1
```
A successful ping confirms the device is powered on and reachable, routing exists, and any firewall permits ICMP.

ICMP is not required for rConfig to download configurations. Many networks block ping for security. If ping fails but you know the device is reachable, move on to the port test.
Test the management port. SSH listens on TCP 22, Telnet on TCP 23:
Terminal window
```
nc -zv 192.168.1.1 22
nc -zv 192.168.1.1 23
```
For a custom SSH port, test that number directly:
Terminal window
```
nc -zv 192.168.1.1 2222
```
A successful test reports “Connection succeeded” or returns a banner. “Connection refused” means the service is not running, a firewall is blocking the port, the wrong port is configured, or the device is not listening on that interface.
Trace the path if the port test fails, to find where packets stop:
Terminal window
```
traceroute 192.168.1.1
mtr 192.168.1.1
```
Look for timeouts at a specific hop (routing issue), firewall ACLs dropping traffic, or asymmetric routing losing return traffic.

When network checks fail, verify the device management interface is up with an IP, check firewall rules and ACLs on every device in the path, confirm routing to the management network, and verify VLAN and VRF configuration for management traffic.

Confirm the service responds

After network reachability is confirmed, check that the management protocol itself answers.

Test SSH:

ssh admin@192.168.1.1

A working SSH service returns a version banner, host key fingerprint, and an authentication prompt. Failures point to SSH not being enabled, an SSH version mismatch, host key issues, or cipher or algorithm negotiation failures.

Test Telnet:

telnet 192.168.1.1

A working Telnet service returns a login prompt or banner. Failures point to Telnet being disabled, VTY lines not configured, or access class restrictions.

Test SNMP (for SNMP-enabled devices):

snmpwalk -v 2c -c public 192.168.1.1 system

A working SNMP service returns system information. Failures point to SNMP not enabled, a wrong community string, SNMP ACLs, or the wrong SNMP version.

Verify authentication

Incorrect credentials are the most common cause of connectivity failures. Confirm they work through an interactive login before checking anything in rConfig.

Log in over SSH and enter the password when prompted:
Terminal window
```
ssh admin@192.168.1.1
```
A successful login confirms the username and password are correct, the account is active, and the authentication method is compatible.
For Telnet devices, log in and enter the username and password when prompted:
Terminal window
```
telnet 192.168.1.1
```
For devices that require privilege escalation, attempt enable after logging in and enter the enable password:
```
enable
```
A successful escalation confirms the enable password is correct.

Common authentication issues

Case sensitivity: Usernames and passwords are typically case-sensitive. Match the exact case configured in rConfig.
Special characters: Passwords containing $, !, @, # and similar may need escaping or cause parsing issues. Test without special characters first to isolate the problem.
Account lockouts: Repeated failed logins can trigger lockout policies. Check device logs and wait for the timer or unlock the account.
Privilege levels: Some devices need a specific privilege level for configuration access. Ensure the account can run show commands and retrieve configurations.
Authentication methods: SSH supports password, public key, and keyboard-interactive. Ensure the device and rConfig agree on a compatible method.
Password expiration: Expired passwords block login. Update them on the device.

Check the credential set in rConfig

Once credentials work interactively, confirm they are stored correctly in rConfig:

Open the device for editing and locate the assigned credential set.
Verify the username and password match the tested values exactly, including case.
Verify the enable password is set if the device requires privilege escalation.
Re-run the device connection test.
Review the Application Log for authentication failure messages with specific error detail.

For where credentials are entered against a device, see the Device Add Workbook.

How do I fix device prompt problems?

Device prompts are the second most common cause after credentials. An incorrect prompt stops rConfig detecting when command output ends, producing timeouts or blank configurations.

How prompt matching works

rConfig connects and authenticates.
The device shows its prompt (for example Router#).
rConfig sends a command (for example show running-config).
The device returns output line by line.
The device shows the prompt again when output ends.
rConfig detects the prompt, treats the output as complete, and moves to the next command.

When this breaks, rConfig waits indefinitely for a prompt that never appears (timeout), matches a false prompt inside the output (truncation), or fails to match because of a regex error.

Common prompt configuration issues

Overly generic prompts. A prompt set to just # matches any # in the output. FortiGate output, for example, contains # at the start of config lines:

Fortigate-Device # show
#config-version=FG200E-6.2.3-FW-build1066-191218:opmode=1:vdom=0:user=someadmin
#conf_file_ver=22474973413141345234794

rConfig treats the first # after the command as the prompt and truncates the rest. Fix it by using the full, specific prompt: Fortigate-Device #.

Dynamic prompts that change with mode. Configuration modes change the prompt:

Router(config)#
Router(config-if)#
Router(config-router)#

A prompt set for one mode fails in others. Use a regex that matches the variations:

Router.*#

This matches Router#, Router(config)#, Router(config-if)#, and so on.

Unescaped regex characters. Square brackets are regex metacharacters:

Router[1]#

Without escaping, [1] is read as a character class. Escape the literals:

Router\[1\]#

Trailing whitespace. A prompt with a trailing space (Router# ) will not match Router#. Match optional whitespace with a regex:

Router#\s*

Capture and test the real prompt

Log in interactively and copy the exact prompt, including all characters and whitespace:
Terminal window
```
ssh admin@192.168.1.1
Router#
```
Paste it into a text editor to spot hidden characters or trailing spaces.
Open the device edit page, locate the Prompt field, and paste the exact prompt. For multi-mode devices, use a regex that matches all variations.
Run the debug command (below) to confirm rConfig detects the prompt and captures output correctly.
If detection still fails, try a more specific prompt (include the hostname), use a regex for flexible matching, check for vendor-specific prompt behaviour, and review the device documentation.

For full prompt guidance, see Device Prompts.

Using the rConfig debug command

The CLI debug tools show the exact protocol interaction, timing, and the point where a failure occurs.

Download device debug command

The primary tool is rconfig:download-device with the debug flag:

cd /var/www/html/rconfig
php artisan rconfig:download-device <device_id> -d

Debug a single device (ID 1001):

cd /var/www/html/rconfig
php artisan rconfig:download-device 1001 -d

Debug several devices:

php artisan rconfig:download-device 1001 1002 1003 -d

Run without verbose output by dropping the -d flag:

php artisan rconfig:download-device 1001

Find the device ID

Devices list: The device ID is in the leftmost column of the devices table.
Device detail page: The ID appears in the page header. Click the Copy Debug Command icon to copy the complete debug command to the clipboard.
Device URL: The ID is the number in the URL on the device detail page, for example https://rconfig.company.com/devices/1001.

Read the debug output

The debug output shows what rConfig sends and receives. A healthy SSH run looks like:

Connecting to device...
Authentication successful
Detecting prompt...
Prompt detected: Router#
Sending command: show running-config
[command output appears here line by line]
Prompt detected: Router#
Command complete
Sending command: show version
[command output appears here]
Prompt detected: Router#
Command complete
Configuration saved to: /path/to/config/file

A healthy Telnet run with privilege escalation looks like:

Connecting to device...
Username: admin
Password: ********
Login successful
Detecting prompt...
Prompt detected: Router>
Sending command: enable
Enable Password: ********
Prompt detected: Router#
Sending command: show running-config
[command output appears here]
Prompt detected: Router#

Focus on connection timing (long delays mean slow response or latency), prompt detection (what matched, or a 60-second timeout if nothing matched), command execution (each command and its output), the authentication flow, and any error messages.

Recognise common failure patterns

Timeout: the prompt was never detected, usually an incorrect prompt:

Connecting to device...
Authentication successful
Detecting prompt...
[60 second pause]
Error: Timeout waiting for prompt

False prompt match: rConfig matched a # inside the output and truncated:

Sending command: show running-config
#config-version=...
Prompt detected: #
Command complete

Authentication failure: wrong username, password, or a disabled account:

Connecting to device...
Username: admin
Password: ********
Error: Authentication failed
Permission denied

Hung connection: the device is not responding after login, often a banner or interactive prompt:

Connecting to device...
Authentication successful
Detecting prompt...
[indefinite hang with no output]

Debug command best practices

Run it from the rConfig server, not a remote workstation, so the network path and timing match real downloads.
Debug one device at a time for cleaner output, then move on to the next.

Save the output to a file for analysis and to share with support:

php artisan rconfig:download-device 1001 -d > /tmp/device-1001-debug.txt 2>&1

Compare working and failing devices to spot differences in prompt detection or timing.
Test at different times of day, since latency and device load vary.

Resolve timeout and protocol issues

Timeouts

Timeouts happen when rConfig does not receive the expected prompt within the timeout period (60 seconds by default). Run the debug command and note where the pause occurs:

During connection: a network or service availability issue.
During authentication: a slow authentication provider (TACACS+, RADIUS, LDAP).
During prompt detection: a prompt mismatch or no prompt displayed.
During command execution: a command that takes longer than the timeout.

Resolution depends on the cause:

Increase the timeout in the device connection settings from 60 to 120 or 180 seconds for devices with large configurations or slow processors.
Optimise commands that return excessive output. Replace show tech-support with show running-config, and drop diagnostic commands from the command set.
Fix the prompt if the timeout is waiting for a prompt that never appears.
Reduce authentication latency by using local device accounts for rConfig, configuring fallback to local authentication, or improving the authentication server’s performance.

Stalled connections

A stall is when the interaction stops without a timeout or error. Common causes and fixes:

Interactive setup prompts (for example “Would you like to enter basic configuration? [yes/no]”). Disable or suppress initial configuration prompts on the device.
Banners or MOTD that require a keypress. Remove interactive banners or use banners that do not require acknowledgement.
Privilege escalation prompts with no enable password configured. Set the enable password in the credential set, or use an account with adequate privilege.

Protocol-specific issues

SSH host key verification failures happen when a device’s SSH key changes (firmware upgrade or hardware swap). rConfig accepts unknown host keys automatically, but a stale cached key causes a failure. Remove the stale entry so rConfig can learn the new key:

ssh-keygen -R 192.168.1.1

SSH cipher or key exchange negotiation failures occur with older devices that support only legacy algorithms. Allow legacy algorithms on the client side or upgrade device firmware.

Telnet negotiation failures can hang or garble output with some implementations. Telnet is inherently less reliable than SSH, so migrate to SSH where possible for reliability and security.

Vendor-specific behaviours

Cisco IOS: Generally reliable SSH and Telnet. Watch for privilege levels needing an enable password, and VTY line limits on concurrent sessions.
Juniper Junos: Prompts change with hierarchy level in configuration mode. Use | display set for consistent configuration output.
Palo Alto Networks: SSH sessions can time out on large configurations, and commit operations affect download timing.
Fortinet FortiGate: Output format varies by FortiOS version and prompts include spaces, so use careful regex.
Arista EOS: Generally excellent SSH compatibility, with common prompt customisation that benefits from flexible regex.

Consult the vendor configuration reference and vendor documentation for deeper, device-specific troubleshooting.

Troubleshooting workflow

Work the failure end to end in five phases:

Basic verification: Confirm the device is reachable (ping, port test), interactive login works, the enable password works if required, and the expected prompt is shown.
rConfig configuration review: Confirm the correct IP and protocol, the right credential set, a matching prompt, and an appropriate command set.
Debug command analysis: Run the debug command, identify where it fails (connection, authentication, prompt, command), and note timing and errors. Compare against a working device.
Targeted resolution: Apply the fix indicated by phase 3, whether network, authentication, prompt, timeout, or protocol.
Validation: Re-run the debug command, run the real download, confirm the configuration is complete, and watch the next scheduled downloads.

When should I contact rConfig support?

Contact rConfig support at support@rconfig.com when issues persist after these steps, when the debug output points to rConfig software rather than configuration, when a vendor protocol behaviour needs a software adaptation, or when many devices show the same failure suggesting a systemic problem.

Include this information so support can act without a round trip:

Environment: rConfig version, operating system and version, PHP version, and where rConfig sits relative to managed devices.
Device: vendor, model, software version, management protocol and port, a sample prompt, and the relevant access configuration (SSH, VTY, user accounts).
Diagnostics: the complete debug output from php artisan rconfig:download-device <id> -d, related Application Log entries, and System Log entries with timestamps. Redact credentials in any screenshots.
Reproduction: steps to reproduce, frequency (every attempt, intermittent, time-of-day), and a comparison with a working device.
What you tried: steps already attempted, any partial workarounds, and changes that had no effect.

Frequently Asked Questions

How do I test if a device is reachable from rConfig?

Run the network checks from the rConfig server itself, since that is the host that connects to devices. Use ping -c 4 <host> for basic reachability, then nc -zv <host> 22 (or 23 for Telnet) to confirm the management port is open. If the port test succeeds, the device is reachable and you can move on to authentication and prompt checks.

Why does rConfig connect manually but fail on scheduled tasks?

Manual tests and scheduled downloads can use different credentials or run from different hosts. Confirm the device credentials are saved in rConfig (not just entered for a one-off manual test), that the correct credential set is assigned to the device, and that the rConfig server, not just your workstation, can reach the device on its management port.

What ports does rConfig need open to manage devices?

rConfig needs outbound access to each device’s management protocol: TCP 22 for SSH, TCP 23 for Telnet, and UDP 161 for SNMP polling. Firewalls and ACLs between the rConfig server and your devices must permit these ports, and return traffic for established sessions must be allowed.

How do I fix host key verification failures?

Host key verification fails when a device’s SSH key changes, for example after a firmware upgrade or hardware swap, and no longer matches the cached key. Remove the stale entry with ssh-keygen -R <host> so rConfig can learn the new key on the next connection. This is safe when you expect the change.

How do I debug a single device’s connection?

Use the built-in debug command from the rConfig server: php artisan rconfig:download-device <device_id> -d. The verbose output shows the connection, authentication, prompt detection, and each command, so you can see exactly where the download fails. Redirect it to a file to share with support.

What’s next

Configure device prompts to match live device output and avoid truncated downloads.
Add and manage devices to review IP, protocol, and credential assignment.
Review the Application Log for connection attempt detail and error messages.