Skip to content

Bulk commands

← Documentation index

Run RouterOS console commands across many devices, in waves, stopping at the first failure. Several commands on separate lines run in order.

Commands run over SSH, because console syntax — :put, :foreach, /interface print — is not reachable through the binary API, which has its own command tree.

Running and scheduling commands is for admins (fleet admins, or site admins on devices in their sites), since a command can do anything the router's admin account can. Operators can see runs and schedules and cancel a run in progress. Schedules an operator saved earlier keep running; an admin can edit, pause or delete them.

Templates

Commands you run more than once can be saved as templates: firewall rules, LTE settings, DNS and NTP defaults, anything you would otherwise keep in a notes file. Creating, editing and deleting templates is for fleet admins, since a template can run after a firmware upgrade. Site admins can load and run them.

  • The Templates page (under Operations) lists them all, with search, and lets you create, edit, duplicate and delete them. Run opens a template in Bulk Commands.
  • On Bulk Commands, Save as template saves what's in the command box, and Load a saved template puts one back. Edit it there if needed; Update saves the edited version.

Loading or running a template only fills the command box. It runs like any typed command, with the same waves, halt-on-failure and Change Guard. A template can also run on each device after a firmware upgrade: pick it under Then run when creating a rollout (see Firmware rollouts). Like running commands, that needs admin access to every device in the rollout.

A template from a device

To copy settings from a device you've already set up, press From a device… on the Templates page. Choose the device and what to take: DNS servers, the NTP client, IP services (on or off, port and allowed addresses), SNMP (on or off, contact and location), the remote syslog target and the time zone. The device is read there and then, and its settings are written as the commands that set them, for example /ip dns set servers=1.1.1.1,9.9.9.9 allow-remote-requests=yes, in a new template to check and edit before you save it. Anything it couldn't take is listed under the commands.

Nothing secret is taken: no SNMP communities, passwords or keys. Neither is anything that belongs to the device itself, such as its identity, addresses and interfaces. NTP is written for the RouterOS version the device runs (a server list on 7, primary and secondary on 6), so capture from a device on the same major version as the ones you'll run it on.

To point many devices at a package source, use the local package mirror instead.

Secrets in commands

A command that sets a password, such as creating a dedicated user for the manager on every device, would otherwise show that password in the template, the run, its history and its output. Store it as a secret instead (#259):

  1. On the Templates page, under Secrets, give it a name and either type the value or choose Generate for a random 24-character one. The value is stored encrypted and never shown again, not even to whoever saved it.
  2. Use it in a command or template as {{secret:name}}, for example:
/user add name=mtm group=full password="{{secret:mtm_password}}" address=10.0.0.5/32

When the command runs, the manager fills the value in just before sending it to the device. Everything stored or shown keeps the placeholder: the template, the run's command, its history, the manager's logs. If a device prints the value back (in an error, say), it's shown as ••••.

Only fleet admins can run a command that uses secrets, or put one in a firmware rollout's Then run: a command can print a value a piece at a time, which masking can't catch, so whoever writes it has to be someone trusted with the secret anyway. A command naming a secret that doesn't exist is refused before it runs. Values can't contain quotes, backslashes, $ or line breaks, since they're placed inside a RouterOS command.

To have the manager use a user created this way, see Changing the login for many devices.

Config Templates

Config Templates, which could only set DNS servers, NTP servers and a syslog host, have been merged into templates. Existing ones are converted automatically on upgrade, marked "from Config Templates", into the equivalent commands:

/ip dns set servers="1.1.1.1,8.8.8.8"
/system ntp client set enabled=yes servers="pool.ntp.org"
:local a [/system logging action find target=remote]; :if ([:len $a] > 0) do={ /system logging action set ($a->0) remote="10.0.0.5" }

The syslog line does what Config Templates did: it updates the first remote logging action and does nothing if there isn't one. The NTP line uses RouterOS v7 syntax; the old version also tried the v6 form. The old /api/config-templates endpoints now answer 410 Gone.

Choosing devices

Pick them individually, or use All / None. Devices are grouped by site, with a checkbox per site that selects all of it, and a search box once the list is long. The same picker is used for maintenance windows.

Where devices carry tags, each tag in use appears as a chip beside those buttons and selects every device carrying it. Tags are assigned on the device page, or to many devices at once from the device list.

This is what tags are for. Sites group devices by where they are and device types group them by what they are, and both are single-valued; a tag is many-per-device and crosses both, which makes it the right way to express "the three switches I upgrade first" or "never touch these during business hours".

Why waves exist

A shell loop already runs a command on many hosts, costs nothing, and prints errors as they happen. What it cannot do is stop.

Devices run together within a wave; waves run strictly in sequence. With halt-on-failure enabled, a mistake reaches one wave rather than the whole fleet. That is the entire reason to do this here rather than in a terminal — without it, this would be a worse shell loop.

Start with a wave of one. Widen it once the command has proved itself.

Detecting failure

RouterOS reports most errors in the output text rather than through an exit code, so a rejected command and a successful one are indistinguishable unless the output is read.

Output is scanned for unambiguous markers — syntax error, bad command name, no such item, failure: and similar. The matching is deliberately conservative: mistaking ordinary output for failure would halt a run that was working, which is worse than the error it guards against.

Change Guard

Each device is wrapped by Change Guard by default, so one that stops answering after the command restores itself.

With Change Guard on, a device that can't arm it (for example, its API user isn't allowed to save a backup) is marked failed rather than run without protection, and that counts toward halt-on-failure. A device where the revert couldn't be confirmed removed is marked successful, with a note giving the time it may still revert.

Change Guard arms its auto-revert over the RouterOS API, so it can't protect a device added over SSH only. With the guard on, such a device fails with a note saying so, and the form warns before you start. Run the command that turns the API on (/ip service enable api-ssl) with Change Guard off.

It is one click to turn off. You may know exactly why you are running something that will drop a device, and a tool that refuses to cut is not a sharp tool.

The one combination that asks for explicit acknowledgement is a command that can sever management with the guard disabled — the only case where nothing catches a mistake.

Preview

Before running, the preview shows:

  • which devices are selected and which wave each falls into
  • whether the command matches patterns that can cut management access, and why
  • devices with no SSH credential, which would otherwise produce a wave of identical authentication failures

It warns; it never blocks.

Output

Captured per device and kept with the run. Some commands exist purely for their output — :put [:resolve google.com] across a fleet is a legitimate use — and "it failed" without the device's own words is not actionable.

Stopping a run

Cancelling prevents the next wave. Devices already executing finish, because that is the only point at which stopping is safe.

Schedules

Schedule…, next to Run, saves the command to run later or again, from Ron's request in

359. A schedule runs on the devices chosen, plus every device with the tags or in the sites you

pick, worked out each time it runs, so a device added to a site later is included.

When it runs:

  • Once: a date and time.
  • Simple: daily, weekly on a day, or monthly on a day from 1 to 28, at a time of day.
  • Advanced: a cron expression with five fields (minute, hour, day of month, month, day of week), for example 0 3 * * 1-5 for 03:00 on weekdays, or */15 * * * * for every 15 minutes.

Times are in the manager's time zone (Settings → General), except a one-off's date, which you enter in your browser's time.

Each scheduled run is an ordinary run in Recent Runs, marked with a calendar, with waves, Change Guard and output as usual. Its options:

  • Only inside a maintenance window: a device that isn't in an active maintenance window when it runs is skipped.
  • Alert when it fails or doesn't run, through your alert channels; on by default.
  • Change Guard, on by default. A command that can cut management access can only be scheduled with Change Guard on, since nobody is watching when it runs.

Some things stop a scheduled run, and it then shows as missed in the run history, with the reason:

  • The manager wasn't running at that time. It never runs late: a command runs when it was set to run, or not at all. A run can still start up to five minutes late, for example while the manager restarts.
  • Another bulk run was still going after 15 minutes. Only one bulk run goes at a time.
  • The account that last saved it was removed or made read-only. A schedule runs as that account: an account limited to some sites reaches only devices in those sites, and a command with secrets needs a fleet admin.
  • None of its devices was in a maintenance window, when it's set to run only inside one.

The Schedules list shows each one's next run, how the last went (click it to open the run), and Run now, Pause, Edit and Delete. Resuming a paused schedule starts from then: times passed while it was paused aren't counted as missed. Deleting a schedule keeps its past runs.

Requirements

Every targeted device needs an SSH credential: either a password, or a verified SSH key. On a fleet of any size, keys are the practical answer.