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:
php artisan rconfig:download-device <device_id> -dDebug 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.