From aabf54b6d1cd4f73f78e996fdd2194b8c3caf8eb Mon Sep 17 00:00:00 2001 From: YueGuobin Date: Sun, 14 Jun 2026 13:11:15 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20Add=20best=20practices=20section=20for?= =?UTF-8?q?=20device=20config=20=E2=80=94=20template=20usage,=20error=20ch?= =?UTF-8?q?ecking,=20config=20backup?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/features/mcp-service.md | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+) diff --git a/docs/features/mcp-service.md b/docs/features/mcp-service.md index 1d072c1ba..c15ebc653 100644 --- a/docs/features/mcp-service.md +++ b/docs/features/mcp-service.md @@ -242,6 +242,30 @@ device_command_run(project_id, ]) ``` +### Best Practices + +**Prefer template over direct commands for batch.** When ≥2 nodes share the same config structure with different values, use `template`+`vars` instead of writing `config_commands` per node. This reduces token usage and transcription errors. + +**Batch merging.** Multiple entries with the same `device_name` are merged into a single Nornir session. The output contains all commands' results in one block. Match results by `device_name`, not list index. + +**Don't rely on `status: success` alone.** It only means commands entered config mode. IOS errors (`% Invalid input`, `% overlaps`, `% Incomplete command`) appear inside `output` text — always scan for `%` lines. + +**Pilot before full rollout.** Test template + vars on 1–2 devices first to verify rendering and syntax, then expand to all nodes. + +**Config backup via file operations.** IOU and Dynamips nodes save startup config as a plain text file (`startup-config.cfg`) in the node directory after `write memory`. These can be backed up and restored via `node_file_get`/`node_file_write`. + +```python +# Save config on device +device_command_run(project_id, device_configs=[ + {"device_name": "R1", "commands": ["write memory"]}, +]) +# Backup +config = node_file_get(project_id, node_id, "startup-config.cfg") +# Restore if config breaks +node_file_write(project_id, node_id, "startup-config.cfg", config) +node_reload(project_id, node_id) +``` + ## Configuration ### Claude Code (CLI)