Skip to content
Guides & References

Building a template for a new device

A method for a device with no template: record a manual session, start from the starter or a similar CLI, map what you saw to keys, and test on one device.

Connection TemplatesUpdated
On this page

Building a template for a new device

The repository’s folders are the templates people have contributed so far, not the limit of what rConfig can drive. Anything that presents a CLI over SSH or telnet can be backed up with a template, and most new devices need only three things changed from the starter: the prompts, the paging command and the enable setting. This page is a method for getting there quickly, and for knowing when a template is the wrong tool.


1. Log in by hand first

Before you write any YAML, connect to the device the way rConfig will, with the account rConfig will use, and keep the transcript. It answers every question the template asks:

  • What does the device print before asking for a username? Before the password? Is there a banner that needs a keypress, or a menu?
  • Does the SSH client do the login, or does the device ask for the password again inside the session?
  • Where does the account land? What does the prompt look like, and does it change after enable?
  • How do you turn paging off for the session, and does the device confirm it?
  • What command prints the configuration, and does its output contain your prompt character anywhere?
  • What does the device print when it rejects a command?

2. Pick a starting point

Look for a device with a similar CLI before you start from nothing. Anything Cisco-like is usually a short edit from an IOS template, and many switch families share a paging command. Otherwise start from the starter template.

rConfig-templates / _base /base.ymlView on GitHub
What
Starter template
Protocol
telnet, port 23
Change first
Protocol, prompts, paging

The starter is a telnet template with enable and paging off. For most devices, change the protocol to ssh and the port to 22 before anything else.

3. Map what you saw to keys

In the transcript Key to set
Username and password prompts auth.username, auth.password (prompt text, not credentials)
The account lands in a restricted mode auth.enable: on, enableCmd, enablePassPrmpt
enable asks for a username too auth.enableUsername: on, enableUsernamePrmpt (SSH only)
The password is asked for inside the session auth.sshInteractive: on, and an empty username if there is no username prompt (Pro V8.4.2)
A banner or menu before the prompt A vt100 section: the text to read up to and the keystroke to send
“Press any key to continue” auth.hpAnyKeyStatus: on
Output pauses at --More-- config.paging: on and the command in pagingCmd
Escape codes or cursor junk in the output options.AnsiHost: "yes"
Commands are ignored after a good login config.commandLinebreak: "n" (Pro V8.4.0, Core 8.2.19)
SSH hangs during key exchange connect.kexOverride: on and kexAlgorithms (Pro V8.3.3, Core 8.2.19)
Each output appears under the previous command config.syncToPromptOnLogin: on (Pro)
The device rejects a command with a fixed message snippet_errors.error_patterns, so snippet sends catch it (Pro V8.4.1)

Keep config.linebreak: "n", write on and off for switches, and quote free text. Anatomy of a template explains why.

4. Set the device record

The template can’t hold everything. On the device record, set the main prompt (the privileged prompt) and the enable prompt (the one before enable), the credentials, and the command group with the retrieval command. Some platforms need more here than in the template: MikroTik needs +cte on the username, and an FTD needs a main prompt of '>'. See prompts, privilege and paging.

5. Test on one device, by stage

Run a backup of one device with the Live Debug Console (Run Debug on the device page), or from the server:

Terminal window
php artisan rconfig:download-device <device_id> -d

Debug and CLI runs bypass the queue and don’t time out, so they can succeed where a queued job fails. Once the debug run works, confirm with a normal queued backup.

Read the session as a sequence. The repository’s order of operations lists every stage of the login and the keys that drive it, with a table that maps a symptom to the stage that failed. Find the last stage that worked and look only at the keys of the next one.

rConfig-templates / docs /ORDER-OF-OPERATIONS.mdView on GitHub
Use for
Finding the failing stage
Section
Debugging by stage

6. Roll it out carefully

A template change applies to every device on that template from the next connection. Create the new template as its own entry, assign it to one device, then a handful, then the rest. When you change a template that’s already in use, clone it, test the clone, and reassign.

When a template is the wrong tool

Some devices can’t be driven by a prompt-matching session at all: restricted CLIs that never present a shell rConfig can read to a prompt (the Zyxel GS1900 is one), configurations that only come out as a file, or retrieval that needs logic between commands. For those, use the Script Integration Engine or xFTP. If the device needs behaviour no key expresses, that is a change to rConfig itself: open a new key request with a sanitised session transcript and the point in the login where the new behaviour has to happen.

Contributing it back

Templates that work are worth sharing, including ones you had to adapt. The contributing guide covers the file naming pattern, the header, and the validator that has to pass.

rConfig-templates / docs /CONTRIBUTING.mdView on GitHub
Covers
Naming, header, rules
New template status
untested-starter

A template you ran against real hardware can go in as community-tested, with the device, OS version and rConfig version in the pull request. Remove hostnames, addresses, usernames and serials from anything you attach.


Type to search.