Anatomy of a connection template
A connection template is a YAML file that tells rConfig how to hold a conversation with a device: which protocol and port to use, which prompts to expect at login, how to reach privileged mode, how to stop the output paging, and what to send when the session ends. It never says which commands to run. Those come from the device’s command group.
The most useful way to read a template is as a script rather than a list of settings. rConfig runs a fixed sequence for each protocol (open the socket, log in, deal with any banner, enter enable mode, turn paging off, send each command, close the session), and every key acts at exactly one point in that sequence. A key that would be right at one step does nothing if the device’s behaviour happens at another, which is why adding a key that “looks right” often changes nothing.
The full reference lives in the templates repository. This page explains the shape; the repository has every key.
rConfig-templates / docs /TEMPLATES.mdView on GitHub- What
- The key legend
- Covers
- 54 keys, 8 sections
- Per key
- Values, default, protocols
- What
- When each key fires
- Covers
- SSH, telnet, TL1, script
- Includes
- Debugging by stage
The sections
A template has up to eight top-level sections. Most CLI templates use four or five of them.
| Section | Controls | Read by |
|---|---|---|
main |
The template’s name and description. name must be unique across your templates. Neither affects the session. |
SSH, telnet, TL1 |
connect |
Protocol, port and timeout, plus the extras for TL1, scripts and protocol fallback. | Every protocol |
auth |
Login prompt patterns, whether to enter enable mode and how, and the HP “press any key” handling. | SSH, telnet |
vt100 |
Splash screens and banners that must be dismissed before a prompt appears. | SSH, telnet |
config |
Paging on and off, the save and exit commands, and workarounds for MikroTik and prompt sync. | SSH, telnet (in part) |
options |
Terminal emulation: ANSI decoding and terminal size, for devices whose output carries escape codes. | SSH |
failure_criteria |
How a script run is judged a failure. | Script (Pro) |
snippet_errors |
Device replies that mean a snippet line was rejected. | SSH snippet sends (Pro V8.4.1+) |
connect.protocol decides everything else, because it selects which part of rConfig runs the session and so which of the other sections are read at all. A TL1 template reads only main and connect; a script template reads only connect and failure_criteria; an inbound-only (xFTP) template reads nothing but the protocol. Copy a working SSH template as the start of a TL1 one and everything below connect is dead weight.
Prompt patterns, not credentials
Every value in auth is a prompt pattern or a switch. username: "Username:" is the text rConfig waits for before sending the username, not the username. Real usernames, passwords and keys come from the device record or a credential set, so one template serves any number of devices with different credentials. The same goes for sshPrivKey: it is a flag that tells rConfig to authenticate with the private key on the device’s credential set, and it never holds key material.
The prompts that tell rConfig a command has finished (the main and enable prompts) aren’t in the template either. They are set per device. See prompts, privilege and paging.
SSH and telnet don’t read a template the same way
The same template behaves differently depending on its protocol. These differences account for a lot of confusion.
| Key | On SSH | On telnet |
|---|---|---|
pagingCmd |
Sent only when paging is on |
Always sent after login, whatever paging says |
resetPagingCmd |
Sent at the end only when paging is on |
Sent at the end whenever it has a value |
saveConfig |
Never sent | Sent at the end of every session when it has a value |
exitCmd |
Never sent | Sent at the end of every session when it has a value |
enableUsername |
Supported | Not read: a telnet device that asks for a username at enable can’t be handled |
commandLinebreak |
Sets the line ending for commands | Not read: telnet always sends \r\n |
The saveConfig row matters more than it looks. Many telnet templates carry saveConfig: "wr mem" or similar, so a telnet backup writes the running configuration on the device each time it runs. An SSH backup with the same lines in its template never does. If a backup must not change anything on the device, clear saveConfig in a telnet template.
Rules that prevent silent failures
rConfig doesn’t validate a template against a schema. It reads the keys it needs, so a mistake usually shows up as a connection that behaves oddly rather than an error. Four rules avoid most of it.
- Write
onandofffor switches. rConfig compares switch keys against the stringsonandyes. YAML’strueandfalseare booleans, and not every key treats them the same way, sopaging: truecan leave paging on with nothing logged. The repository’s validator rejects booleans inenable,pagingandhpAnyKeyStatusfor this reason. - Quote free text. Every prompt, command and description goes in double quotes.
- Write the protocol in lower case. Before Pro V8.3.2,
connect.protocol: SSHdoesn’t matchssh, and the device never connects. - Keep
config.linebreak: "n". It has no effect on any version, but rConfig Pro before V8.3.2 and Core before 8.2.16 fail every job on a template that leaves it out. To change the line ending SSH sends after each command, usecommandLinebreakinstead.
Keys that do nothing
Some keys are read and then ignored, so changing them has no visible effect. Knowing which they are saves time when you tune a template.
| Key | Why it has no effect |
|---|---|
hpAnyKeyPrmpt |
Read on both protocols but never used. hpAnyKeyStatus is the key that acts. |
linebreak |
Kept only so older versions don’t fail (see above). |
pagerPrompt, pagerPromptCmd |
Deprecated. Leave them out of new templates. |
saveConfig, exitCmd on SSH |
Read, never sent. |
Core, Pro and version-gated keys
Templates in vendor folders run on Core and Pro. Of the 54 keys, 18 are read only by Pro: the TL1 keys, the protocol fallback keys, prompt sync on login, the script keys and snippet_errors. A few keys need a minimum version, and older versions ignore them without an error, so a template that depends on one fails quietly there.
| Key | Needs | Used for |
|---|---|---|
kexOverride, kexAlgorithms |
Pro V8.3.3, Core 8.2.19 | SSH servers that hang during key exchange (see the Juniper page) |
commandLinebreak |
Pro V8.4.0, Core 8.2.19 | Devices that ignore a command ending in a bare carriage return (see the Dell page) |
snippet_errors |
Pro V8.4.1, SSH | Failing a snippet send when the device rejects a line |
Empty auth.username on SSH |
Pro V8.4.2 | Devices that ask for the password inside the session (see the SonicWall page) |
The repository’s editions matrix lists every capability by edition.