Repository navigation
issue#206: back up MikroTik RouterOS over SSH - #207
Merged
Merged
Conversation
RouterOS cannot copy its configuration to a TFTP server, so the SSH shell copy-to-TFTP flow does not apply. Add a per-device-type Capture Command that PHPSsh runs on an exec channel, saving its output as the incoming configuration the backup flow already reads. No interactive shell or TFTP server is involved when it is set; device types without one are unchanged. Add the capturecmd column to plugin_routerconfigs_devicetypes (new installs through the table map, existing installs through a guarded ALTER that runs before the built-ins are seeded), and seed a built-in 'MikroTik RouterOS' device type (SSH, /export). A capture that times out fails rather than saving a partial configuration, and the device's CRLF line endings are converted so the backup flow does not double them. Restoring a configuration to a device is not part of this change. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Contributor
There was a problem hiding this comment.
🟡 Changes recommended
Critical issues block SSH-only backups without a TFTP address, let continuously streaming commands bypass the capture timeout, and allow partial writes to be archived as successful backups.
3 open issues
What changed in this PR
Adds MikroTik RouterOS backup support to Cacti’s routerconfigs plugin by capturing /export over SSH and feeding it into the existing backup pipeline. This addresses the backup portion of #206; restore remains out of scope.
Changes:
- Adds a per-device-type Capture Command using SSH exec channels.
- Extends the schema and Device Type form, and seeds a MikroTik RouterOS profile.
- Adds capture and upgrade tests, updates documentation and translations, and bumps the version to 2.1.
| File | Description |
|---|---|
| tests/Unit/RouterconfigsSshCaptureTest.php | Tests SSH capture, line endings, failures, and shell selection. |
| tests/Unit/RouterconfigsSetupTableTest.php | Checks MikroTik seed values and updated defaults. |
| tests/Unit/RouterconfigsCheckUpgradeTest.php | Tests capture-column creation before seeding. |
| tests/Integration/RouterconfigsInstallHooksTest.php | Updates the expected built-in device-type count. |
| setup.php | Adds the upgrade column and MikroTik profile. |
| router-devtypes.php | Saves the Capture Command field. |
| README.md | Documents MikroTik setup and backup limitations. |
| locales/po/cacti.pot | Adds Capture Command translation strings. |
| INFO | Bumps the plugin version to 2.1. |
| includes/database.php | Adds capturecmd to the device-type schema. |
| includes/arrays.php | Defines the Capture Command form field. |
| classes/PHPSsh.php | Implements exec-channel capture into an incoming backup file. |
| classes/PHPConnection.php | Adds a testable ssh2_exec() wrapper. |
| CHANGELOG.md | Records MikroTik SSH backup support. |
Review effort: Balanced
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
- Require a TFTP server only for devices that copy to one. The shared preflight in plugin_routerconfigs_download() stopped the whole run when the global TFTP Server was empty, so SSH-only devices could not be backed up without an unrelated address. The check now runs per device in plugin_routerconfigs_download_config(), and a device type with a capture command is exempt. A capture command also always runs over SSH, never falling back to Telnet. - Enforce the capture limit on every read, so a command that keeps producing output fails at the limit instead of running on. - Write the capture to a temporary file in the same directory and rename it into place only when complete, so a failed write cannot leave a partial file for the backup flow to archive as a good backup. - Share the capture command lookup and trim the lines added to the SSH connect path, which is boilerplate shared with PHPScp and PHPSftp. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
|
xmacan
approved these changes
Nov 16, 2026
This was referenced Nov 17, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.




Part of #206 (MikroTik backup over SSH; restore is not included, see below).
Why
RouterOS cannot
copy ... tftp, so the plugin's SSH flow, which types a copy-to-TFTP command into an interactive shell and waits for the device to push the file, cannot back up a MikroTik. RouterOS can print its whole configuration to the terminal (/export), so this change captures that output instead.What changed
Capture Command (new, per device type). When a device type has one,
PHPSshruns it on its own SSH exec channel and writes the output to the incoming file the backup flow already reads. Everything downstream (validation, archiving, backup list, diff, email, retention) is untouched.\n, because the backup flow adds its own CRLFs and RouterOS output would otherwise end up as\r\r\n.plugin_routerconfigs_download()(which stopped the whole run when the global TFTP Server was empty) toplugin_routerconfigs_download_config(), so a device that needs a TFTP server and has none fails on its own with an error. Most of thatfunctions.phpdiff is a block losing one level of nesting; usegit diff -w.PHPConnection::sshExec()is a thinssh2_exec()wrapper, like the otherssh*helpers, so it can be stubbed in tests.Database.
plugin_routerconfigs_devicetypes.capturecmd varchar(255) NULL.routerconfigs_devicetypes_table_data()).ALTER TABLE ... ADD COLUMNinrouterconfigs_check_upgrade(). It has to run beforeAddDeviceTypes(), because the seed now writes that column androuterconfigs_upgrade_tables()only runs afterwards.ssh, capture command/export, assume-elevated on, Check End in Config off (an export has noend). Seeded on install and on upgrade; the existing "insert if the name does not exist" guard means a customised row is never overwritten.AddDeviceType()gains two trailing optional parameters ($connecttype,$capturecmd), so existing callers are unaffected.UI. The Device Type form has a new Capture Command field.
router-devtypes.phpsaves it. Any other device type can use it with a command that prints its configuration to the terminal.Housekeeping.
INFO2.0 -> 2.1 (needed so existing installs run the upgrade), CHANGELOG, README section,cacti.pot.Not in this PR
Download()), so restore is a separate feature and Support MikroTik Switch/Router Backup and Restore #206 should stay open for it.Testing
Run locally on PHP 8.3 against a Cacti tree, using the same commands as CI:
RouterconfigsSshCaptureTest; seed counts updated 5 -> 6; two new upgrade-ordering tests).tests/bin/validate-manifest.php,tests/bin/check-i18n-pot.php(also checked the.potmsgids against a freshxgettextrun), andtests/bin/patch-coverage.php ... 100all pass. Noteclasses/PHPSsh.phpandPHPConnection.phpare on the gate's unmeasured allowlist, but the new code in them is covered by the tests.php-cs-fixer(Cacti config): no new findings.setup.phpandincludes/database.phpalready fail it ondevelop.devicetypestable, ran the upgradeALTERand then the realAddDeviceTypes(). The MikroTik row is inserted withsshand/export, and a second run adds nothing (6 rows before and after).Please check on real hardware
I have not run this against a real RouterOS device: there is no
ssh2extension on my dev box, sossh2_exec()itself is stubbed in the tests. Worth confirming on a router, ideally RouterOS 6 and 7:/exportand the loop reaches EOF (it reads non-blocking and relies onfeof()).sshandread(plussensitivefor/export show-sensitive), but have not verified it on a router.Known behaviour worth knowing
/exporthides sensitive values by default and never exports user passwords, so this is a readable record of the configuration, not a full restore image./export show-sensitivecan be set as the capture command, with the backup directory protected accordingly.