Skip to content

issue#206: back up MikroTik RouterOS over SSH - #207

Merged
TheWitness merged 4 commits into
developfrom
feature/mikrotik-ssh-206
Nov 16, 2026
Merged

TheWitness merged 4 commits into
developfrom
feature/mikrotik-ssh-206

Conversation

@TheWitness

@TheWitness TheWitness commented Nov 16, 2026 •

Copy link
Copy Markdown
Member

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, PHPSsh runs 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.

  • No interactive shell is opened, so there are no prompts, echo, or terminal control codes to scrape. No TFTP server is involved for these devices.
  • Device types without a capture command behave exactly as before.
  • Line endings are normalised to \n, because the backup flow adds its own CRLFs and RouterOS output would otherwise end up as \r\r\n.
  • A TFTP server is required only by devices that copy to one. The check moved from the shared preflight in plugin_routerconfigs_download() (which stopped the whole run when the global TFTP Server was empty) to plugin_routerconfigs_download_config(), so a device that needs a TFTP server and has none fails on its own with an error. Most of that functions.php diff is a block losing one level of nesting; use git diff -w.
  • A capture command always runs over SSH, never falling back to Telnet.
  • A capture that times out (120s, enforced on every read) or returns nothing fails the backup instead of saving a partial or empty configuration as a good backup. The file is written to a temporary name and renamed into place only when complete.
  • PHPConnection::sshExec() is a thin ssh2_exec() wrapper, like the other ssh* helpers, so it can be stubbed in tests.

Database.

  • New column plugin_routerconfigs_devicetypes.capturecmd varchar(255) NULL.
  • Fresh installs get it through the existing table map (routerconfigs_devicetypes_table_data()).
  • Existing installs get it through a guarded ALTER TABLE ... ADD COLUMN in routerconfigs_check_upgrade(). It has to run before AddDeviceTypes(), because the seed now writes that column and routerconfigs_upgrade_tables() only runs afterwards.
  • New built-in device type MikroTik RouterOS: connection type ssh, capture command /export, assume-elevated on, Check End in Config off (an export has no end). 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.php saves it. Any other device type can use it with a command that prints its configuration to the terminal.

Housekeeping. INFO 2.0 -> 2.1 (needed so existing installs run the upgrade), CHANGELOG, README section, cacti.pot.

Not in this PR

  • Restore. The plugin has no upload path at all today (every transport implements only Download()), so restore is a separate feature and Support MikroTik Switch/Router Backup and Restore #206 should stay open for it.
  • RouterOS REST/API transport.
  • Hostname/last-change detection from the export. The device keeps its configured name.

Testing

Run locally on PHP 8.3 against a Cacti tree, using the same commands as CI:

  • Pest: 324 passed (new 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 .pot msgids against a fresh xgettext run), and tests/bin/patch-coverage.php ... 100 all pass. Note classes/PHPSsh.php and PHPConnection.php are 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.php and includes/database.php already fail it on develop.
  • Real MariaDB 10.5: from a 2.0-shaped devicetypes table, ran the upgrade ALTER and then the real AddDeviceTypes(). The MikroTik row is inserted with ssh and /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 ssh2 extension on my dev box, so ssh2_exec() itself is stubbed in the tests. Worth confirming on a router, ideally RouterOS 6 and 7:

  1. The exec channel returns the full /export and the loop reaches EOF (it reads non-blocking and relies on feof()).
  2. The minimum policies for the backup account. I believe ssh and read (plus sensitive for /export show-sensitive), but have not verified it on a router.

Known behaviour worth knowing

  • RouterOS 7 /export hides 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-sensitive can be set as the capture command, with the backup directory protected accordingly.
  • The first line of an export is a header comment with the export date and time, so two otherwise identical backups differ on that line. The README suggests the existing Diff Exclude Patterns setting for emailed diffs. Stripping it at capture time would be a reasonable follow-up.
  • Capture is SSH-only: a device type with a capture command always connects over SSH, whatever its Connection Type.

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>
@TheWitness
TheWitness requested a balanced review from Copilot November 16, 2026 18:31
@TheWitness
TheWitness marked this pull request as ready for review November 16, 2026 18:31
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 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

Comment thread classes/PHPSsh.php Resolved
Comment thread classes/PHPSsh.php Resolved
Comment thread classes/PHPSsh.php Resolved
TheWitness and others added 2 commits November 16, 2026 13:42
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>
@sonarqubecloud

Copy link
Copy Markdown

@TheWitness
TheWitness merged commit 721ec59 into develop Nov 16, 2026
7 checks passed
@TheWitness
TheWitness deleted the feature/mikrotik-ssh-206 branch November 16, 2026 19:01
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants