Skip to content
mikroscope

Upgrade and uninstall

upgrade replaces the container with a new image and keeps the rest of the install. uninstall removes everything the install created, and checks that nothing is left. Both read how the install was made from its manifest on the router, whichever method made it.

Upgrade

Section titled “Upgrade”
Terminal window
mikroscope upgrade --router admin@192.168.88.1 --remote-image jmrplens/mikroscope-agent:1.6.1

upgrade takes the image from its own flags only: pass --remote-image with the new version, --agent-tar with the new tar, or run it from an updated checkout. Everything else about the install’s shape comes from the router.

  1. Reads the install. From its manifest, or, for an install made without one, from the objects that carry its tag. nothing to upgrade: run install first when there is none. With --remote-image the same connect reads the registry settings and prints doctor’s registry-credential check; upgrade runs no other check, so run doctor first when you change registries.

  2. Prints its plan. The line keeps: veth interface veth-mikroscope, router address 172.30.10.1, interface-list membership LAN, address-list membership LANs: not touched, then the manifest, the container’s removal and the new container, and any step of the install the router no longer holds. --dry-run stops here and connects to nothing: it skips step 1, so its plan comes from the flags alone, the architecture included (arm64 unless --arch says otherwise).

  3. Asks, unless --yes.

  4. Writes the manifest, replaces the container and probes the agent:

      wrote install manifest mikroscope/mikroscope.manifest.txt
      gone  container mikroscope
      pull  the router pulls registry-1.docker.io/jmrplens/mikroscope-agent:1.6.1 itself
      new   container mikroscope
    probing http://172.30.10.2:9123/healthz from this host …
      direct transport ok: agent 1.6.1 (<commit>) built <time>, 10 Hz, seq 8, 0 slipped, 2ms round trip

What upgrade replaces

  • the install manifest, written first every time, so an install made before there was one gets it
  • a new image and the container
  • the envlist, rewritten from the flags upgrade is given; it refuses an install with a token when no --token is given
  • any other object of the install the router no longer holds, created again before the container
  • network objects stay

Every object carries the comment mikroscope:<name> (managed by mikroscope)

mikroscope plan prints every command before anything is written.

The envlist belongs to the container step, so upgrade writes it again from its own flags. Pass the agent settings you installed with, or they return to their defaults: --rate, --buffer, --mem-limit-mb, --capture-mb, --triggers, --floor-hz, --memory-max, --privileged, --restart-max-count and --restart-interval. That is also how to change them without touching the network objects. The shape (--veth, --subnet, the lists, --disk or --ephemeral, --port, --expose with --lan-address, --container-name, --start-on-boot) comes from the manifest; a flag that contradicts it is refused. An install with a token needs --token (or MIKROSCOPE_TOKEN) again: upgrade refuses to rewrite its envlist without one.

An install made by a RouterOS script, the generator or by hand upgrades the same way from a computer with the CLI. Without the CLI, remove it (Uninstall) and run the new release’s script.

CLI and dashboards

Section titled “CLI and dashboards”

upgrade replaces the agent only. The CLI upgrades by running its install script again, and the collector image by pulling it again. The dashboards are built into the CLI and the collector image, so publish them again after either changes: restart the collector run with --grafana, or run dashboards publish or dashboards import again (Update and remove).

Upgrade notes

Section titled “Upgrade notes”

When the install or your setup comes from an older release:

  • An install made by 1.3.1 or earlier has no manifest. status, upgrade and uninstall read its shape from its tagged objects: status and uninstall print no manifest at mikroscope/<name>.manifest.txt, and upgrade prints install on the router (its tagged objects, no manifest). The first upgrade writes one; uninstall removes such an install completely, the mikroscope/ directory those releases left behind included.
  • Shape variables in .env. A .env copied from an older .env.example may set MIKROSCOPE_ARCH, the lists or other shape variables. status, upgrade and uninstall refuse a value that contradicts the install; comment those lines out and let the router’s manifest decide.
  • An exposed agent upgraded without a token. An older upgrade without --token re-created an --expose agent with none while the LAN rules stayed. doctor warns the installed agent published on the LAN asks for a token; run upgrade with --token.
  • A registry mirror named in registry-url. mikroscope 1.2.2 and earlier sent the image reference without its registry host and left the registry to registry-url. Now the host travels in the reference, and a reference with none goes to registry-1.docker.io directly. To keep pulling through a mirror or a pull-through cache, name its host: --remote-image <mirror-host>/jmrplens/mikroscope-agent:1.6.1.
  • A Prometheus job that scrapes the agent. The agent serves no /metrics: an agent of 1.0.4 or earlier did. Point the job at the collector’s --prom address (Prometheus).
  • Dashboards imported from 1.3.0 or earlier. Publish or import them again (CLI and dashboards): the “Not available on this device” row shows table … not found badges on InfluxDB, the Elasticsearch dashboard opens with an empty Host and six red badges, and one imported with a probe into Grafana 12.3.0 shows No SQL statements were provided in the query string badges in that row.
  • A PostgreSQL alert file provisioned from 1.2.0 carries a mikroscope-bridge-port-dark rule that cannot run on the SQL schema: regenerate the rules and provision them again (Alert rules).
  • A whole InfluxDB write URL in MIKROSCOPE_INFLUX_URL from a 1.0.x deployment keeps working; nothing to do.

Uninstall

Section titled “Uninstall”
Terminal window
mikroscope uninstall --router admin@192.168.88.1          # lists what it would remove
mikroscope uninstall --router admin@192.168.88.1 --yes    # removes it, then verifies

It needs no other flag: the shape comes from the manifest, and a flag that contradicts it is refused. Pass --name for an install with a name other than mikroscope. Without --yes it only lists:

router objects (add --yes to remove them):
  5 router object(s) tagged "mikroscope:mikroscope (managed by mikroscope)":
    container mikroscope
    address-list membership LANs
    interface-list membership LAN
    router address 172.30.10.1
    veth interface veth-mikroscope
  then any other object tagged "mikroscope:mikroscope (managed by mikroscope)", in /ip/firewall/address-list, /interface/list/member, /ip/firewall/nat, /ip/firewall/filter, /ip/firewall/raw, /ip/firewall/mangle, /ip/route, /container/mounts, /ip/address, /interface/veth, /interface/list, /disk
  and last the install manifest mikroscope/mikroscope.manifest.txt with mikroscope/mikroscope, and mikroscope when nothing else is in it
  (the manifest on the router, when there is one, says which objects the plan holds)

With --yes it removes, newest first, every object the manifest lists; stops the container and waits while it runs or stops, up to 30 s, before removing it and its root; removes any other object that carries the install’s exact tag in those menus; and removes the manifest and the mikroscope/ directory last, when nothing else is in it. A removal that fails or prints anything shows as skip with what RouterOS said, and the rest go on. Then it counts what is left:

  0     install manifest mikroscope/mikroscope.manifest.txt
  0     veth interface veth-mikroscope
  0     router address 172.30.10.1
  0     interface-list membership LAN
  0     address-list membership LANs
  0     container mikroscope
verified: nothing mikroscope created remains on the router

When something remains it fails with uninstall left objects behind, naming the steps.

What uninstall removes

  • every object in the install's manifest, and any other object that carries its tag
  • the container root mikroscope/<name>, with the container, or on the manifest's word when a root is left
  • the manifest, last, and then the mikroscope directory when nothing else is in it
  • never device-mode, the container package, /container/config, or a list, disk or rule the router had before

Every object carries the comment mikroscope:<name> (managed by mikroscope)

mikroscope plan prints every command before anything is written.

uninstall removes by exact tag plus identity, never by pattern, and fails naming the step if anything remains.

Never removed

Section titled “Never removed”
  • device mode, the container package and /container/config (registry-url, the registry username);
  • a list, a disk, a firewall rule, or a file under mikroscope/, that was there before the install;
  • a path the manifest lists beyond what its install creates: uninstall leaves it and reports it as left behind (uninstall left objects behind: … which the manifest lists).

The one exception is an empty mikroscope/ directory: it goes even when it was there before, since nothing says whose it is.

Without the CLI, run the removal commands by hand: Manual install: terminal.

Remove dashboards and data

Section titled “Remove dashboards and data”

--targets widens uninstall past the router:

Target What goes
router everything the install created on the router, the default
dashboard per store the sink flags name: the dashboard mikroscope-<store>, however it was imported, and the datasource mikroscope-<store>. Not the folder, an adopted datasource or provisioned alert rules
data the tables and indices the sinks wrote, and the files the file sinks wrote
all the three above
Terminal window
export GRAFANA_TOKEN=…
mikroscope uninstall --targets all --influx "$MIKROSCOPE_INFLUX_URL" --influx-db mikroscope --grafana http://grafana:3000
mikroscope uninstall --targets all --influx "$MIKROSCOPE_INFLUX_URL" --influx-db mikroscope --grafana http://grafana:3000 --yes

Pass the same sink flags as forward. With --targets dashboard or data and no sink flag it finds no store and prints nothing of this is here to remove; all then acts on the router objects alone. Nothing goes without --yes. A datasource adopted with --grafana-datasource-uid is never removed, and --prom, --graphite and --sql store nothing this can remove, each saying why: uninstall --targets.

--targets dashboard also needs --grafana (or MIKROSCOPE_GRAFANA_URL, then GRAFANA_URL) and GRAFANA_TOKEN, from a service account that may delete datasources (Grafana token). The Grafana and the stores are asked before the router is touched: a Grafana it cannot read, unreachable or refusing the token, stops it with asking Grafana whether dashboard mikroscope-<store> is there: … before anything is removed, the router objects included.

Written and maintained by José Manuel Requena Plens (jmrplens)GitHub