Skip to content
Guides & References

Anatomy of a connection template

What each section of an rConfig connection template controls, which keys each protocol reads, and the rules that stop a template failing silently.

Connection TemplatesUpdated
On this page

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
rConfig-templates / docs /ORDER-OF-OPERATIONS.mdView on GitHub
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.

  1. Write on and off for switches. rConfig compares switch keys against the strings on and yes. YAML’s true and false are booleans, and not every key treats them the same way, so paging: true can leave paging on with nothing logged. The repository’s validator rejects booleans in enable, paging and hpAnyKeyStatus for this reason.
  2. Quote free text. Every prompt, command and description goes in double quotes.
  3. Write the protocol in lower case. Before Pro V8.3.2, connect.protocol: SSH doesn’t match ssh, and the device never connects.
  4. 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, use commandLinebreak instead.

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.


Type to search.