Network Device Connectivity and Backup Process

After reading this page, you can describe how rConfig selects a connection protocol, follows the authentication priority chain, executes commands, and stores the resulting configuration file. This reference is useful when diagnosing connection failures, planning firewall rules, or understanding how credentials are resolved.

---

Supported Connection Protocols

SSH (Secure Shell)

rConfig uses its own built-in SSH engine rather than relying on the operating system’s SSH client. This provides greater control over connection handling, authentication methods, and error management, ensuring consistent behavior across different deployment environments.

• Default port: 22 (configurable per device)
• Authentication methods: Password, SSH keys, keyboard-interactive
• Key exchange and encryption: Industry-standard algorithms with configurable cipher suites
• When SSH is preferred: Always recommended for security and reliability on modern network devices
• Mixed fleets: A template can declare Telnet as a fallback so devices without SSH still back up. See Protocol fallback for SSH and Telnet

Telnet

Telnet support is available for legacy devices that do not support SSH. However, Telnet is not supported in rConfig Vector and will not be added in future Vector releases due to its inherent security limitations.

• Default port: 23 (configurable per device)
• Security considerations: Transmits credentials and data in cleartext; use only on isolated management networks
• Legacy device support: Essential for older equipment lacking SSH capabilities
• When to use Telnet: Only when SSH is not available and the device is on a secure, isolated network

API Connections

rConfig supports REST API connections for devices that expose configuration management through modern API interfaces. API support is currently read-only (RO) and REST-based.

• Supported protocols: REST APIs
• Authentication methods: Token-based, Basic Auth, custom headers
• Use cases: Cloud-native devices, SDN controllers, modern network appliances
• Limitations: Currently read-only; write operations planned for future releases

SNMP

SNMP support enables configuration retrieval from devices via SNMP protocol, as well as receiving SNMP traps for event-driven configuration backups.

• Supported versions: SNMPv2c, SNMPv3 (recommended for security)
• Operations: Read operations for configuration data, trap receiving for event notifications
• Community strings / credentials: Encrypted storage with RBAC-controlled access
• Use cases: Devices where CLI access is restricted, trap-triggered backups, bulk data collection

xFTP Services (Docker-based)

rConfig includes an optional xFTP Docker container that provides FTP, TFTP, and SFTP services for devices that push configurations to an FTP server. You can also use your own FTP services if Docker is not allowed or feasible.

• Protocols: FTP, TFTP, SFTP (SCP)
• Use cases: Devices configured to push configurations automatically, legacy backup workflows
• Security: SFTP recommended; FTP/TFTP should only be used on isolated networks

xFTP documentation

Detailed xFTP configuration is covered in the xFTP Services documentation.

BYOC/SIE (Bring Your Own Code / Script Integration Engine)

The Script Integration Engine allows you to use custom scripts written in any programming language to retrieve configurations or run advanced custom workflows from devices.

• Supported languages: Any language available on your system (Python, Perl, Ruby, Go, etc.)
• Use cases: Proprietary devices, custom protocols, complex authentication flows, specialized parsing
• Integration: Scripts are executed by rConfig with device parameters passed as arguments

SIE documentation

BYOC/SIE implementation details and examples are covered in the Script Integration Engine documentation.

---

Authentication Flow

When rConfig initiates a device connection, it follows a precise sequence of operations to ensure successful authentication and command execution.

For the same sequence expressed at template level, showing which template key acts at each step and in what order, see order of operations in the templates repository.

Order of Operations

graph TD
    A[Job Initiated] --> B[Device Selection]
    B --> C[Retrieve Device Settings]
    C --> D[Retrieve Credentials]
    D --> E[Determine Protocol]
    E --> F{Template declares<br/>a fallback protocol?}
    F -->|No| G[Use template protocol]
    F -->|Yes| H[Resolve protocol<br/>probe, connect, cache]
    G --> I{Protocol Type}
    H --> I
    I -->|SSH| J[SSH Connection]
    I -->|Telnet| K[Telnet Connection]
    I -->|API| L[API Connection]
    I -->|SNMP| M[SNMP Connection]
    I -->|BYOC| N[Custom Script]
    J --> O[Authenticate]
    K --> O
    L --> O
    M --> O
    N --> O
    O --> P{Auth Success?}
    P -->|Yes| Q[Execute Commands]
    P -->|No| R[Log Failure]
    Q --> S[Capture Output]
    S --> T[Process & Store Config]
    T --> U[Clean Disconnect]
    U --> V[Generate Logs]
    R --> V

Step 1: Job Initiation A backup job is triggered via scheduled task, manual CLI command, UI action, or external event (SNMP trap, API call).

Step 2: Device Selection rConfig identifies the target device(s) from the job parameters. For scheduled tasks, this includes all devices assigned to the command group associated with the task.

Step 3: Retrieve Device Settings Device-specific settings are loaded from the database, including IP address, port, connection timeout, protocol preferences, and vendor template associations.

Step 4: Credential Retrieval Credentials are retrieved based on device assignment. rConfig supports both device-specific credentials and shared credential sets. Credentials are decrypted from secure storage just-in-time for the connection attempt.

Step 5: Protocol Determination The connection protocol comes from the device’s connection template, with a device-level port override applied if one is set. Where the template declares a fallback protocol, rConfig resolves which of the two protocols the device actually answers on before opening a session, then reuses that result on later downloads. See Protocol fallback for SSH and Telnet below.

Step 6: Connection Establishment On a fallback-capable template, a TCP port probe runs first to confirm something is listening before any credentials are used. rConfig then initiates the connection using the selected protocol:

• SSH: TCP connection to port (default 22), SSH handshake, cipher negotiation
• Telnet: TCP connection to port (default 23), terminal negotiation
• API: HTTPS connection, SSL/TLS handshake, token/header preparation
• SNMP: UDP or TCP connection to port (default 161), community string or v3 auth prep
• BYOC: Script execution with device parameters passed as environment variables or arguments

Step 7: Authentication Authentication is attempted using the retrieved credentials. The specific method depends on the protocol:

• SSH: Password, public key, keyboard-interactive, or combination
• Telnet: Username/password prompts with pattern matching
• API: Bearer tokens, Basic Auth, or custom header authentication
• SNMP: Community strings (v2c) or user credentials (v3)
• BYOC: Script-defined authentication logic

Step 8: Command Execution Once authenticated, rConfig executes the command set associated with the device’s command group. Commands are sent sequentially with prompt detection between each command to ensure proper timing.

Step 9: Output Capture Command output is captured in real-time, with intelligent buffering to handle large configurations. Pagination is automatically handled by detecting “More” prompts and sending appropriate responses (space, return, etc.).

Step 10: Configuration Processing Raw output is processed to remove prompts, ANSI escape sequences, terminal artifacts, and unnecessary whitespace. The cleaned configuration is then validated and prepared for storage.

Step 11: Storage The processed configuration is stored in the file system following rConfig’s hierarchical structure and a corresponding database record is created with metadata including timestamp, file path, hash, and relationship to previous versions.

Step 12: Clean Disconnection The session is gracefully terminated with proper logout commands (if applicable) and the connection is closed. This ensures device resources are released and logs on the device reflect a clean disconnect.

Step 13: Logging and Notification Connection attempt details, execution times, success/failure status, and any errors are logged to the activity log. If configured, email or webhook notifications are sent for failures or specific events.

Queued Connections vs Debug/CLI Connections

• Queued Connections: Follow the full authentication and command execution flow as described above, with retries and error handling. Used for scheduled tasks and bulk operations.
• Debug/CLI Connections: Bypass certain steps for immediate execution. Used for manual testing and troubleshooting. Limited error handling, no retries, and critically do not timeout.

Protocol Fallback for SSH and Telnet (V8.3.1+)

A connection template can declare a second protocol to try when the first one is not answering. This covers fleets where the same platform runs SSH on some units and Telnet on others, without splitting them across two templates or setting a protocol by hand on every device.

Fallback applies to SSH and Telnet only. Templates that do not declare connect.fallbackProtocol dispatch exactly as they did before and are unaffected by any of this.

Enabling fallback on a template

connect:
  protocol: ssh
  port: 22
  fallbackProtocol: telnet
  fallbackPort: 23
  probeTimeout: 5

Key	Purpose	Notes
fallbackProtocol	Protocol tried when nothing answers on the primary port	Must be ssh or telnet, and different from protocol
fallbackPort	TCP port for the fallback protocol	Defaults to 22 for SSH, 23 for Telnet when omitted
probeTimeout	Seconds to wait when testing whether a port is open	Clamped to 1-10; falls back to connect.timeout, then 5 seconds

A device-level port override still wins over both port and fallbackPort, exactly as it does for single-protocol templates, so an overridden device is probed on the port the connection will actually dial.

How resolution works

graph TD
    A[Download starts] --> B{Device has a<br/>resolved protocol?}
    B -->|Yes| C[Try the cached protocol first]
    B -->|No| D[Try the primary protocol first]
    C --> E[TCP port probe]
    D --> E
    E --> F{Port open?}
    F -->|No| G{Other protocol<br/>still untried?}
    G -->|Yes| H[Switch to the other protocol]
    H --> E
    G -->|No| I[Run the primary attempt for real<br/>normal unreachable handling fires]
    F -->|Yes| J[Connect and authenticate]
    J --> K{Session succeeded?}
    K -->|No| L[Report the session error as-is<br/>no protocol switch]
    K -->|Yes| M[Cache the protocol on the device]
    M --> N{Landed on the<br/>fallback protocol?}
    N -->|Yes| O[Queue a 24-hour recheck<br/>of the primary protocol]
    N -->|No| P[Done]
    O --> P

1. Probe - a cheap TCP connection to the port for the protocol being tried. Nothing is sent and no credentials are used. A closed port here is an expected outcome, not a device failure.
2. Connect - the first protocol whose port answers is used for the real session.
3. Cache - on success the protocol is stored on the device record and reused for every later download, so there is no repeated guessing.
4. Recheck - a device that landed on the fallback protocol queues a background job to retest the primary protocol, at most once every 24 hours.

Only connection failures trigger fallback

Fallback exists for one situation: nothing is listening on that port. If the port answers but the session then fails (wrong credentials, an unexpected prompt, a template mismatch), that failure is reported as-is. rConfig does not retry over the other protocol, because the protocol choice was already sound and switching would mask a real credential or template problem.

If neither port answers, the primary protocol attempt runs for real so the normal unreachable handling (device status, notifications, activity log) fires once, the same as for a single-protocol template.

Promotion back to the primary protocol

A device that fell back to Telnet does not stay there indefinitely. After a successful fallback download, rConfig queues a primary-protocol recheck for that device on the rConfigDefault queue:

• Throttled to once every 24 hours per device, with up to 15 minutes of random delay so the daily rechecks do not all fire in one burst behind the nightly backup task.
• The recheck opens a full login on the primary protocol, not just a port probe, then closes the session without running any commands. A listening-but-unusable daemon (a console server, for example) therefore will not promote the device.
• It never demotes a device and never marks one failed. A negative result leaves the cached protocol alone and the device stays on the fallback.
• On success the device is promoted back to the primary protocol and the change is written to the activity log.

Rechecks are tagged in Horizon as RecheckPrimaryProtocol:DeviceId:<id>.

When the cached protocol is discarded

A cached protocol only describes the device at its current address under its current template, so it is cleared automatically when:

• The device IP address or hostname changes
• The device is assigned a different template
• The template is edited so its protocol pair no longer includes the cached value

The next download then re-probes from scratch.

Seeing which protocol a device resolved to

The device details panel shows a Protocol row with the protocol that device last connected on. The row appears only once a fallback-capable template has resolved a protocol, so devices on single-protocol templates do not show it. Protocol resolution and promotion events are also written to the activity log.

Debug runs analyse against the device’s resolved protocol rather than the template default, so a debug session on a device sitting on the fallback reflects what a real download will do.

Fallback gotchas

• A device that resolves to Telnet is sending credentials in cleartext. Treat a fallback as a signal to fix SSH on that device, not as a permanent configuration.
• A device-level port override applies to both attempts, so an overridden device is probed on the same port for each protocol. Leave the override empty on devices that need the template’s SSH and Telnet ports.
• A firewall that drops SSH silently looks identical to a device with SSH disabled. Both close the port probe, and both push the device onto the fallback protocol.

Authentication Methods Priority

rConfig follows a hierarchical credential priority system to ensure flexible and secure authentication. The order of credential attempts varies by protocol, with SSH and Telnet following the most comprehensive hierarchy.

SSH and Telnet Authentication Priority

When connecting via SSH or Telnet, rConfig attempts authentication in the following order:

1. Device-Specific Credentials (Highest Priority)

   • Credentials configured directly on the device record
   • Used when a device requires unique authentication (jump hosts, special access accounts, etc.)
   • Overrides all other credential sources
   • Best for devices with unique security requirements or non-standard authentication

2. Device Credential Set

   • Shared credential sets assigned to the device
   • Allows grouping devices that share common credentials (e.g., all branch routers)
   • Supports credential rotation across multiple devices simultaneously
   • Ideal for devices organized by region, role, or security zone

3. Key Vault Credentials (Fallback)

   • Credentials stored in external key vault integrations (HashiCorp Vault, AWS Secrets Manager, etc.)
   • Used when set is configured
   • Provides centralized credential management across multiple rConfig instances
   • Requires key vault integration to be configured in system settings

4. SSH Keys from Credential Sets

   • If SSH keys are configured in the credential set, they are attempted after passwords
   • Supports both password and key-based authentication methods
   • Allows for more secure, key-based access where supported by the device

5. Authentication Failure

   • If all credential sources fail, the connection attempt is logged as failed
   • Retry logic may attempt the sequence again depending on configuration
   • Detailed error messages indicate which credential methods were attempted

API Authentication

API connections use protocol-specific authentication methods:

• No Auth: Some APIs may not require authentication (public endpoints)
• Token-Based: Bearer tokens, API keys from device configuration or credential sets
• Basic Auth: Username/password combinations
• Custom Headers: Vendor-specific authentication headers configured per device

SNMP Authentication

SNMP authentication follows a simpler hierarchy:

1. Device-specific community strings or SNMPv3 credentials
2. Credential set SNMP credentials
3. Global SNMP defaults (if configured)

BYOC/SIE Authentication

Custom scripts handle their own authentication logic. rConfig passes credentials as environment variables or command-line arguments based on script configuration:

• $RCONFIG_USERNAME, $RCONFIG_PASSWORD, $RCONFIG_ENABLE_PASSWORD
• Scripts can implement their own fallback logic

Best Practice

For production environments, use credential sets or key vaults to centralize credential management and simplify rotation. Reserve device-specific credentials for exceptions only.

Configuration Backup Process

How Backups Are Initiated

Scheduled Backups Configuration backups can be scheduled via the rConfig UI or CLI. Scheduled tasks run at defined intervals (daily, weekly, monthly) and can target specific command groups or individual devices.

Manual Backups Manual backups can be initiated through the rConfig UI or CLI. Users can select specific devices or command groups to back up immediately.

Event-Triggered Backups Event-triggered backups can be initiated by external events such as SNMP traps or API calls. This allows for real-time configuration backups in response to network changes or alerts.

Backup Execution Flow

The backup execution flow follows the authentication flow detailed above, with additional steps for processing and storing the configuration data. The key steps include:

1. Job Queue - Job is queued and scheduled for execution
2. Device Connection - Connection is established per the above authentication flow
3. Command Execution - Commands are run to retrieve the device configuration
4. Output Capture - Output is captured and validated for completeness
5. File Processing - Output is parsed, cleaned, and formatted as needed
6. Storage - Files are stored in the appropriate location
7. Versioning - Versions are tracked using a consistent naming convention and metadata
8. Notification - Success/failure notifications are sent to relevant stakeholders

---

Configuration Storage

File System Structure

Configuration files are stored in a hierarchical directory structure based on device categories, device names, and timestamps. This structure allows for easy navigation and retrieval of configuration files and efficient identification of the most recent version. Custom scripting can be used to interact with the file system directly if needed.

/storage/app/rconfig/
  ├── data/
  │   ├── [Category]/
  │   │   ├── [Device]/
  │   │   │   ├── [YYYY]/
  │   │   │   │   ├── [MMM]/
  │   │   │   │   │   ├── [DD]/
  │   │   │   │   │   │   ├── config_timestamp.txt

The file naming convention includes the device name and timestamp to ensure uniqueness and facilitate version tracking.

Database Records

Each configuration file stored in the file system has a corresponding record in the rConfig database. This record includes metadata such as:

• Device ID
• File path
• Timestamp of backup
• File hash (for integrity verification)
• Version number
• User who initiated the backup (if applicable)

Encryption

Configuration files can be encrypted at rest using filesystem-level encryption or application-level encryption. This ensures that sensitive configuration data is protected from unauthorized access. See the configuration encryption documentation for more details.

---

Command Execution

Connection Templates

Connection templates define the command sequences used to interact with different device types. These templates are associated with vendor profiles and can be customized per device or command group. Templates include:

• Login sequences
• Enable/privilege escalation commands
• Configuration retrieval commands
• Logout sequences

There is a library of pre-defined templates for common vendors, and custom templates can be created as needed. They are stored on GitHub for easy access and version control, and can be imported into your rConfig instance via the UI or CLI for use in your environment. Every key a template can carry is documented in the connection template legend.

Terminal Handling

Some templates may require specific terminal settings (e.g., terminal length, width) to ensure proper output formatting. rConfig can send terminal configuration commands as part of the connection sequence to optimize output for parsing.

Review the vendor-specific templates for recommended terminal settings, or contact rConfig support for assistance.

Output Processing

Output from command execution is processed to remove extraneous data such as prompts, ANSI escape sequences, and pagination artifacts. This ensures that the stored configuration is clean and usable. rConfig includes built-in parsers for common output formats, and custom parsers can be developed for unique device outputs.

rConfig code and templates can handle a variety of output formats, including:

• Plain text
• XML
• JSON
• Proprietary formats

Custom scripts can also be used to further process output if needed, or contact rConfig support for assistance.

---

Error Handling and Retries

Connection Failure Scenarios

• Authentication failures - incorrect credentials and unsupported authentication methods are all logged in the activity log
• Timeout handling - connection timeouts and command execution timeouts are managed by the Horizon Queue Engine
• Protocol negotiation failures - unsupported protocols and version mismatches are all logged in the activity log
• Network connectivity issues - unreachable devices and DNS resolution failures are all logged in the activity log

Retry Strategy

• Retry attempts and intervals: rConfig only attempts a single connection attempt per job execution. If the connection fails, it is logged and the job is marked as failed. Users can manually re-run the job or schedule a new job as needed.
• Backoff logic: Not applicable as rConfig does not implement automatic retries. The exception is for inbound SNMP trap jobs, which have a configuration retry and backoff mechanism to handle transient failures.
• Protocol fallback is not a retry. It selects a protocol before the session opens, and once a session has started and failed, no second attempt is made.

Logging and Auditing

All connection attempts and errors are logged with detailed messages to facilitate troubleshooting.

---

Security Considerations

Credential Management

• Encryption at rest: All sensitive credential data is encrypted when stored to protect against unauthorized access.
• Access control: Fine-grained access controls restrict who can view or modify credentials.
• Credential rotation: Regular rotation of credentials is recommended to minimize the risk of compromise.

---

What’s next

• CLI Commands - Manual device download commands and automation
• Device Management Fundamentals - Core device concepts and workflows
• Universal Device Support - Multi-vendor device support