Connection Templates guides
A CLI backup in rConfig is the product of several separate objects: a connection template, the device’s prompts, a command group, the commands in it, and the device record that ties them together. These guides explain what each one controls, how they interact during a session, and which design choices make backups reliable or fragile. The step-by-step procedures stay in the main docs, starting at Connection Templates; these pages explain the model behind them.
The moving parts
Each object answers one question about the session. Knowing which object owns which behaviour is most of the work when a backup fails.
| Object | Answers | Relationship | Main docs |
|---|---|---|---|
| Connection template | How do I talk to this device? Protocol, port, login prompt patterns, enable mode, paging, timeouts, line breaks. | One template per device; one template serves any number of devices. | Connection Templates |
| Device prompts | When has the device finished sending output? A main prompt and an enable prompt. | Set on the device record, not in the template. | Device Prompts |
| Command group | Which commands run against this device, and which scheduled tasks pick it up? | Exactly one per device. Scheduled tasks target command groups. | Command Groups |
| Command | What does each command capture, and how is its output treated afterwards? | Many-to-many with command groups. Edit once, every group sees it. | Commands |
| Vendor | Who made it? Used for organising, filtering and reporting. | Independent of the command group. | Vendors |
| Device profile | Which defaults should a synced device get? Credential, template, vendor, command group, model, prompts and tags in one bundle. | Referenced from integration sync (V8.2.0+). | Device Profiles |
Two points catch people out. The prompts that tell rConfig a command has finished live on the device, while the username and password prompt patterns used at login live in the template. And “Categories” from rConfig versions before 7.2.0 are the same thing as command groups; the rename was terminology only, and API endpoints keep the old name.
What happens in a session
The connectivity and backup process describes the full sequence. In outline, and showing which object drives each step:
- Protocol and port come from the template, with a device-level port override if one is set.
- Login uses the device’s credentials and the template’s username and password prompt patterns.
- Privilege escalation runs if the template enables it, and rConfig waits for the device’s enable prompt.
- Paging is turned off with the template’s paging command, so long output arrives without pausing at a “More” prompt.
- Commands from the device’s command group are sent one at a time, in order. After each one, rConfig waits for the main prompt before sending the next.
- Output is cleaned of prompts and terminal artefacts, stored, and compared with the previous version using each command’s settings.
For the same sequence at template key level, the templates repository publishes an order of operations with a table that maps each symptom to the stage and keys responsible.
Design decisions
Generic templates or one per platform
A broadly compatible template with neutral prompt patterns and conservative timeouts covers many vendors with one file. A library of vendor and platform templates gives precise prompt recognition, tuned timeouts and the right paging and escalation commands for each device type. Templates are labelled by vendor, but they often work for other manufacturers with similar CLIs, so test before you assume either way. The baseline templates that ship with rConfig and the community template repository are the usual starting points.
Editing in place or cloning
A template change applies to every device assigned to it, immediately. The editor has no real-time YAML validation, so a bad indent often shows up only as a connection failure. Cloning a working template into a variant, testing it on one device, then reassigning is the safer pattern. Repository import refreshes the library of imported templates only; templates you already created keep their code until you change them.
SSH, Telnet, or both
From V8.3.1 a single template can declare Telnet as a fallback for SSH. rConfig probes the primary port, uses the fallback only when nothing answers, caches the result on the device, and promotes it back to SSH once SSH works. Fallback chooses a protocol before the session opens; it is not a retry after a failed login. Telnet is not supported in rConfig Vector. See protocol fallback.
Specific or broad prompt patterns
Specific patterns match quickly and rarely misfire, but need more upkeep. Broad patterns are easier to maintain but risk matching text inside the output. A bare # will stop capture at the first comment line in a FortiGate config. Anchor patterns, cover configuration sub-modes where needed, and enter them without regex delimiters. The prompt troubleshooting page shows the common failures.
Command group granularity
Every command in a group runs against every device in it, so a vendor-specific command in a mixed-vendor group fails on the devices that don’t understand it. More groups give finer control at the cost of administration. Start broad and split only where command needs really differ. It also pays to separate a frequent configuration backup from a less frequent, heavier operational snapshot with its own schedule.
Command sets or individual commands
A command set (several commands separated by line breaks) stores its output as one file. Individual commands get independent change tracking, comparison rules, integrity checks and notifications. Each command also carries the CIC, Keep Unchanged Config and Change Notifications toggles plus its own compare exclusions, which decide how much noise each backup creates. See Commands.
Why backups fail
Most failures trace back to one of these objects not matching how the device actually behaves.
| Symptom | Usual cause | Where it’s set |
|---|---|---|
| Connection refused or unreachable | Network path, firewall, or the service not listening on the configured port | Network; template port or device override |
| Authentication fails | Wrong credentials, or login prompt patterns that don’t match the device | Device credentials; template auth section |
| Backup completes but the file is blank | Prompt detection failed | Device prompts |
| Backup is slow or times out | A prompt that never matches, or a timeout too short for the device or link | Device prompts; template timeout |
| Config is truncated | Paging not disabled, or a prompt pattern matched text inside the output | Template paging command; device prompts |
| Login works, then every command times out or returns nothing | The device ignores commands ending in a bare carriage return | Template commandLinebreak (V8.4.0, SSH only) |
| Session stalls with no error | Interactive banner, first-login wizard, or a missing enable password | The device, or device credentials |
| Errors on some devices in a group only | A command not valid for every vendor in the group | Command group |
A timeout that is too short and a prompt that never matches look the same from outside, so raising the timeout first usually turns a fast failure into a slow one. The troubleshooting docs work through the layers in order: network, service, authentication, protocol interaction, then rConfig configuration.
Two behaviours shape how you investigate. rConfig makes one connection attempt per job and does not retry automatically (trap-triggered jobs are the exception), so a failure stays failed until the next run. And debug and CLI connections bypass the queue and do not time out, so they can succeed where a queued job did not. The Live Debug Console (V8.2.0+) and the CLI diagnostic tools both show the session as it happens.
Templates beyond the CLI
The template’s connect.protocol also selects collection methods that don’t use an interactive CLI: script hands collection to the Script Integration Engine, tl1 routes the device to the TL1 collector, and xftp marks a device as inbound-only so rConfig never connects out to it. The Collection Methods guides compare these and explain when to use each.