Snippet Error Detection

From V8.4.1, rConfig can tell when a device rejects a line of a snippet. Send interfaz Gi0/1 to a Cisco router and the device answers % Invalid input detected. Before V8.4.1 that send still showed green, because rConfig only checked that the session completed. With error detection turned on, rConfig reads the device’s reply to every line, marks the send Failed, and names the line that was rejected.

Error detection is set up per connection template. A template with a snippet_errors block is checked. A template without one sends snippets exactly as before.

---

How it works

With snippet_errors in the device’s template, a snippet is sent one line at a time:

1. rConfig sends a line and waits for the device’s prompt to come back.
2. It removes the echoed line and the prompt, and keeps what the device said in between.
3. It checks each line of that reply against the template’s error and warning patterns.
4. On an error, it stops (the default) or carries on to the next line, depending on the snippet’s Stop at first error setting.

Each send ends with one of four results:

Result	Meaning
Success	Every line was sent and nothing matched a pattern.
Success with warnings	A line matched a warning pattern, or the prompt didn’t come back before the template timeout. Nothing was rejected.
Failed	The device rejected at least one line.
Success (not checked)	rConfig didn’t check the replies: the template has no snippet_errors block, or the device connects over Telnet.

No rollback

Error detection reports what happened. It doesn’t undo it. Lines the device accepted before the rejected one stay applied. With Stop at first error on, the lines after it are never sent.

---

Turn it on for a template

Open Inventory → Templates, edit the device’s template, and add a snippet_errors block at the top level, next to main, connect, auth and config:

snippet_errors:
  error_patterns:
    - "% Invalid input detected"
    - "% Incomplete command"
    - "% Ambiguous command"
    - "% Unknown command"
  warning_patterns:
    - "re:^% Warning"

The next snippet sent to any device using that template is checked. Nothing else needs restarting.

Writing patterns

• Plain text matches anywhere in a line of the reply, ignoring case. % Invalid input detected matches % Invalid input detected at '^' marker.
• re: prefix makes the pattern a regular expression, the same convention used by compliance code block methods. re:^error: only matches a line that starts with error:. Without delimiters the regex ignores case. Write it as re:/pattern/flags to set your own flags, for example re:/^ERROR/ to match upper case only.
• Patterns are checked one reply line at a time, so ^ and $ refer to the start and end of a line.
• Errors win. If a reply matches both an error and a warning pattern, the line is an error.
• A broken regex stops the send. rConfig checks every pattern before it sends the first line. If one isn’t a valid regex, nothing is sent and the send is reported as Failed with the pattern named.

Tip

Keep patterns specific. error: on its own also matches a line such as description uplink error: none. re:^error: doesn’t. The echoed command is removed before checking, so the text of your own snippet never triggers a match.

Starting patterns by vendor

The Cisco IOS templates in the rConfig-templates repository include the block above. For other platforms, these are starting points. Test them against your own devices before relying on them: a pattern that matches normal output fails good sends.

Cisco IOS / IOS XE

snippet_errors:
  error_patterns:
    - "% Invalid input detected"
    - "% Incomplete command"
    - "% Ambiguous command"
    - "% Unknown command"
  warning_patterns:
    - "re:^% Warning"

Juniper Junos

snippet_errors:
  error_patterns:
    - "syntax error"
    - "unknown command"
    - "missing argument"
    - "re:^error:"
  warning_patterns:
    - "re:^warning:"

Arista EOS

snippet_errors:
  error_patterns:
    - "% Invalid input"
    - "% Incomplete command"
    - "% Ambiguous command"
    - "% Unavailable command"

MikroTik RouterOS

snippet_errors:
  error_patterns:
    - "bad command name"
    - "expected end of command"
    - "syntax error"
    - "input does not match"
    - "re:^failure:"

---

Stop at first error

Each snippet has a Stop at first error switch in its add and edit dialog under Config Tools → Snippets. It’s on by default.

• On: when the device rejects a line, rConfig sends nothing more and closes the session. The remaining lines are listed as not sent.
• Off: rConfig sends every line and reports every rejected one. Use this when the lines don’t depend on each other and you want the full list of problems in one run.

The setting only matters for templates with snippet_errors. Snippets sent with dynamic values carry the setting over from the snippet they were made from.

---

Where you see the result

Configurations table. A purple send icon marks a snippet sent to a device. A grey arrow marks a config downloaded from one. Failed and warned sends get a red or amber badge next to the command name. Hover over the badge for the reason.

Config view. Open the send from Configs > View Configurations or the device page. The Snippet Check section shows the result, the reason, the pattern that matched, the device’s reply to the rejected line, and whether Stop at first error was on. The saved output is the CLI exchange followed by a report:

router1#conf t
Enter configuration commands, one per line.  End with CNTL/Z.
router1(config)#interfaz foo
                       ^
% Invalid input detected at '^' marker.

router1(config)#

--- rConfig snippet check: Failed ---
Device rejected "interfaz foo" (matched "% Invalid input detected"). 1 line was not sent.
OK        conf t
ERROR     interfaz foo   <- matched "% Invalid input detected"
NOT SENT  end

Latest configs. A failed send is left out of the device’s Latest Good Configs list.

Scheduled tasks. Snippet task reports have an Outcome column with each device’s result and reason. A failed send counts as a failure, so a task set to email only on failure sends its report. See Scheduled Tasks.

Notifications. The in-app and email notifications for a snippet sent from the device page give the result and reason, and say “failed” when the device rejected a line.

CLI. php artisan rconfig:send-snippet prints the reason for every failed device and exits with code 1. Scripts can check $? instead of parsing the output.

API. Add wait=true to GET /api/v1/send-snippet/{snippetid}/{deviceid}, or "wait": true to the body of POST /api/v1/snippets/{id}/deploy. rConfig sends straight away instead of queueing, and answers with one result per device:

{
  "success": true,
  "message": "Snippet sent to 1 device(s): 1 failed",
  "data": {
    "results": [
      {
        "device_id": 1003,
        "config_id": 204,
        "status": "failed",
        "reason": "Device rejected \"interfaz foo\" (matched \"% Invalid input detected\"). 1 line was not sent.",
        "failed_line": "interfaz foo",
        "matched_pattern": "% Invalid input detected",
        "response": "^\n% Invalid input detected at '^' marker."
      }
    ]
  }
}

status is success, success_with_warnings, failed or not_checked. connection_failed and no_output mean nothing came back from the device. Devices are sent to one after another, so a deploy to many devices with wait takes as long as all of them together. Without wait, both endpoints queue the send and answer straight away as before. The full reference is in the in-app API docs under Settings → REST API Docs.

---

Prompts and timeouts

Line-by-line sending needs to recognise the prompt after every line, including in config mode. rConfig takes the device’s main prompt from the device record, drops the prompt character at the end, and accepts any prompt that starts with what’s left and ends in #, >, $ or %. With a main prompt of router1#, it recognises router1(config)# and router1(config-if)# without any extra setup. The same works for user@host> on Junos and [admin@MikroTik] > on RouterOS.

If a line’s reply has no recognisable prompt before the template’s connect.timeout, the line is marked as a warning (“no prompt before the timeout”) and rConfig carries on. The most common cause is a line that changes the prompt itself, such as hostname newname. Add a #[config_prompt] instruction with the new prompt before that line. From V8.4.1, a #[config_prompt] prompt is accepted as well as the device prompt, not instead of it.

Note

Sending line by line is slower than sending a snippet in one go, because rConfig waits for the prompt after each line. For a long snippet, allow for this in the template timeout.

---

Upgrading to V8.4.1

Templates copied or imported before V8.4.1 have no snippet_errors block, so snippet sends keep working as before and are reported as Success (not checked). To turn error detection on, add the block to each template you use for snippets, or re-import the Cisco IOS templates from the template repository.

Error detection works over SSH only. Telnet sends are always reported as Success (not checked).