# Manual install: WebFig and Winbox

Install the agent from the router's WebFig or Winbox menus, form by form, with no CLI; then start it, check it and remove it.

Source: https://jmrplens.github.io/mikroscope/install/manual-gui/

Install the agent from the router's own menus, with no computer that runs the CLI. Each step is a
form: its menu, the fields to fill in, and the form as it looks filled in. The values are the ones
`mikroscope install` writes, so `mikroscope status`, `upgrade` and `uninstall` treat the result as
their own. Winbox has the same menus and fields as WebFig, though no install has run in Winbox
([not tested](https://jmrplens.github.io/mikroscope/about/status/#not-tested)); the pictures, and the run behind them, are
WebFig's ([Tested on](https://jmrplens.github.io/mikroscope/about/status/#install-routes-tested)).

## Before you start

- The router runs RouterOS 7.24 or later, has the `container` package and has device mode with
  containers enabled: [Requirements](https://jmrplens.github.io/mikroscope/install/prerequisites/). Device mode has no page
  in WebFig; it is a terminal command ([Device mode](https://jmrplens.github.io/mikroscope/install/prerequisites/#device-mode-containeryes)).
- For the list memberships: the interface list and the address list your firewall drops by (`LAN`
  and `LANs` in MikroTik's default configuration): [Firewall lists](https://jmrplens.github.io/mikroscope/install/firewall/).
- For the image tar: the tar for the router's architecture, renamed `mikroscope.tar`
  ([Offline install](https://jmrplens.github.io/mikroscope/install/offline/#choose-the-image-tar) names each one).

The steps use the defaults below. To change one, change it in every step it appears in, the
manifest included. [Manual install: terminal](https://jmrplens.github.io/mikroscope/install/manual-cli/#before-you-start)
lists every value and how the others follow from it.

| Value                            | Default                                                                  |
| -------------------------------- | ------------------------------------------------------------------------ |
| Tag, the Comment of every object | `mikroscope:mikroscope (managed by mikroscope)`                          |
| veth                             | `veth-mikroscope`                                                        |
| Router's address                 | `172.30.10.1/30`                                                         |
| Agent's address and port         | `172.30.10.2/30`, `9123`                                                 |
| Envlist                          | `mikroscope-env`                                                         |
| Root dir                         | `mikroscope/mikroscope`                                                  |
| Manifest                         | `mikroscope/mikroscope.manifest.txt`                                     |
| Image, registry pull             | `registry-1.docker.io/jmrplens/mikroscope-agent:1.6.1` |
| Image, tar                       | `mikroscope.tar`                                                         |

Keep the tag as it is, character for character: it is how the CLI recognises every object as the
install's.

**Log in.** Open `http://<router address>/` and log in as an admin user. Then pick **Advanced** at
the top: the steps use the full menu tree, which Quick Set hides.

*The WebFig login page: Login admin, the Password field empty, and the Login button.*

**Filling in a form.** A field shown only as a **+** button is unset: press **+** to open it. When
RouterOS refuses an object, the form stays open with the reason under its buttons.

> **The terminal, for two settings**
>
> Two settings have no field in WebFig: device mode and `ignore-remote-image-change`
> ([verified](https://jmrplens.github.io/mikroscope/about/status/#verified-webfig-no-ignore-remote-image-change)). Set them in **Terminal** at the top of WebFig, or
> **New Terminal** in Winbox. If the terminal asks whether to show the software licence, answer
> it first: what you type before the `] >` prompt goes to that question.

## Write the install manifest

The manifest lists every object the next steps create, so that `mikroscope uninstall` can find
them all.

**Files** › **New** › **Text File**:

| Field    | Value                                           |
| -------- | ----------------------------------------------- |
| Name     | `mikroscope/mikroscope.manifest.txt`            |
| Contents | the lines below, for the image source you use |

- **Registry pull**

  ```text
  mikroscope-manifest=1
  name=mikroscope
  tag=mikroscope:mikroscope (managed by mikroscope)
  disk=
  veth=veth-mikroscope
  subnet=172.30.10.0/30
  port=9123
  iface-list=LAN
  addr-list=LANs
  expose=
  container-name=
  remote-image=registry-1.docker.io/jmrplens/mikroscope-agent:1.6.1
  token=no
  dir=mikroscope
  file=mikroscope/mikroscope.manifest.txt
  object=/interface/veth name=veth-mikroscope
  object=/ip/address interface=veth-mikroscope
  object=/interface/list/member interface=veth-mikroscope list=LAN
  object=/ip/firewall/address-list list=LANs address=172.30.10.0/30
  object=/container/envs list=mikroscope-env
  object=/container interface=veth-mikroscope
  dir=mikroscope/mikroscope
  ```

- **Image tar**

  ```text
  mikroscope-manifest=1
  name=mikroscope
  tag=mikroscope:mikroscope (managed by mikroscope)
  disk=
  veth=veth-mikroscope
  subnet=172.30.10.0/30
  port=9123
  iface-list=LAN
  addr-list=LANs
  expose=
  container-name=
  remote-image=
  token=no
  dir=mikroscope
  file=mikroscope/mikroscope.manifest.txt
  object=/interface/veth name=veth-mikroscope
  object=/ip/address interface=veth-mikroscope
  object=/interface/list/member interface=veth-mikroscope list=LAN
  object=/ip/firewall/address-list list=LANs address=172.30.10.0/30
  file=mikroscope.tar
  object=/container/envs list=mikroscope-env
  object=/container interface=veth-mikroscope
  dir=mikroscope/mikroscope
  ```

If you skip a list membership, write `none` after its `iface-list=` or `addr-list=` and leave out
its `object=` line. OK creates the `mikroscope` directory with the file.
[RouterOS script](https://jmrplens.github.io/mikroscope/install/script/#install-manifest) explains each line.

*Files › New File: Name mikroscope/mikroscope.manifest.txt, and in Contents the manifest, from mikroscope-manifest=1 to dir=mikroscope/mikroscope.*

*Files after OK: the new mikroscope directory and mikroscope/mikroscope.manifest.txt in it.*

## Create the veth

**Interfaces** › **VETH** › **New**:

| Field   | Value                                           |
| ------- | ----------------------------------------------- |
| Comment | `mikroscope:mikroscope (managed by mikroscope)` |
| Name    | `veth-mikroscope`                               |
| Address | `172.30.10.2/30`                                |
| Gateway | `172.30.10.1`                                   |

Leave the rest as it is.

*Interfaces › New Interface of type VETH: Comment is the mikroscope tag, Name veth-mikroscope, Address 172.30.10.2/30 and Gateway 172.30.10.1.*

*The VETH tab after OK: veth-mikroscope, with the mikroscope tag as its comment.*

## Add the address

**IP** › **Addresses** › **New**:

| Field     | Value                                           |
| --------- | ----------------------------------------------- |
| Comment   | `mikroscope:mikroscope (managed by mikroscope)` |
| Address   | `172.30.10.1/30`                                |
| Interface | `veth-mikroscope`                               |

*IP › Addresses › New Address: the mikroscope tag as Comment, Address 172.30.10.1/30 and Interface veth-mikroscope.*

*IP › Addresses after OK: 172.30.10.1/30 on veth-mikroscope beside the router's own addresses.*

## Add list memberships

Optional. They let the agent's replies past raw firewall rules that drop by interface list or by
address list. A membership is not scoped to mikroscope: any other rule that matches the list
matches the veth or the /30 too ([Firewall lists](https://jmrplens.github.io/mikroscope/install/firewall/)).

**Interfaces** › **Interface List** › **New**:

| Field     | Value                                           |
| --------- | ----------------------------------------------- |
| Comment   | `mikroscope:mikroscope (managed by mikroscope)` |
| List      | `LAN`                                           |
| Interface | `veth-mikroscope`                               |

*Interfaces › Interface List › New Interface List Member: List LAN, Interface veth-mikroscope, and the mikroscope tag as Comment.*

*The Interface List tab after OK: veth-mikroscope is a member of LAN.*

**IP** › **Firewall** › **Address Lists** › **New**:

| Field   | Value                                           |
| ------- | ----------------------------------------------- |
| Comment | `mikroscope:mikroscope (managed by mikroscope)` |
| List    | `LANs`                                          |
| Address | `172.30.10.0/30`                                |

*IP › Firewall › Address Lists › New: List LANs, Address 172.30.10.0/30, and the mikroscope tag as Comment.*

*The Address Lists tab after OK: 172.30.10.0/30 in LANs beside the router's LAN range.*

## Create the envlist

**Container** › **Envs** › **New**, once per entry, each with List `mikroscope-env`:

| Key              | Value                                           |
| ---------------- | ----------------------------------------------- |
| `MIKROSCOPE_TAG` | `mikroscope:mikroscope (managed by mikroscope)` |
| `RATE_HZ`        | `10`                                            |
| `BUFFER_S`       | `60`                                            |
| `PORT`           | `9123`                                          |
| `ADDR`           | `172.30.10.2`                                   |
| `MEM_LIMIT_MB`   | `16`                                            |
| `CAPTURE_MB`     | `4`                                             |

`MIKROSCOPE_TAG` is how the CLI tells the envlist is the install's. The other keys are the agent's
settings: [Environment variables](https://jmrplens.github.io/mikroscope/reference/environment/#the-agents-envlist).
`MEM_LIMIT_MB` follows from the rate and the ring; the
[Script generator](https://jmrplens.github.io/mikroscope/install/generator/) computes it for other values.

*Container › Envs › New: List mikroscope-env, Key MIKROSCOPE_TAG, and the mikroscope tag as Value.*

*The Envs tab with the seven entries of mikroscope-env: MIKROSCOPE_TAG, RATE_HZ 10, BUFFER_S 60, PORT 9123, ADDR 172.30.10.2, MEM_LIMIT_MB 16 and CAPTURE_MB 4.*

A `TOKEN` entry holds its value in clear, and WebFig shows it in clear in this list and in its
form ([verified](https://jmrplens.github.io/mikroscope/about/status/#verified-webfig-shows-env-values)). Add one only for
[Expose on the LAN](https://jmrplens.github.io/mikroscope/security/expose/), and treat any screen that shows it as a secret.

## Create the container

- **Registry pull**

  **Container** › **New**:

  | Field             | Value                                                                    |
  | ----------------- | ------------------------------------------------------------------------ |
  | Comment           | `mikroscope:mikroscope (managed by mikroscope)`                          |
  | Remote Image      | `registry-1.docker.io/jmrplens/mikroscope-agent:1.6.1` |
  | Root Dir          | `mikroscope/mikroscope`                                                  |
  | Privileged        | ticked                                                                   |
  | Interface         | `veth-mikroscope`                                                        |
  | Envlists          | `mikroscope-env`                                                         |
  | Memory Max        | `64M`                                                                    |
  | Logging           | ticked                                                                   |
  | Start On Boot     | ticked                                                                   |
  | Restart Policy    | `on failure (non 0 exit code)`                                           |
  | Restart Interval  | `00:00:10`                                                               |
  | Restart Max Count | `5`                                                                      |

  Leave Name empty: RouterOS names the container after the image. OK starts the pull: the router
  pulls the image for its own architecture, so it needs to reach the registry and have room for the
  layers.

  *Container › New Container, top of the form: the mikroscope tag as Comment, Remote Image registry-1.docker.io/jmrplens/mikroscope-agent with the release tag, and Root Dir mikroscope/mikroscope.*

  *The same form further down: Privileged ticked, Interface veth-mikroscope and Envlists mikroscope-env.*

  *The bottom of the form: Memory Max 64M, Logging and Start On Boot ticked, Restart Policy on failure, Restart Interval 10 s and Restart Max Count 5.*

  Wait for `download/extract done` in **Log**. The row is then ready to start, and does not carry
  the `R` flag yet.

  *The Container tab once the pull is over: one row, with the tag as Comment, its root dir, veth-mikroscope and mikroscope-env, and no R flag.*

- **Image tar**

  1. **Files** › **Upload…**, and pick `mikroscope.tar`. It lands at the top of the router's
     storage.

        *Files after Upload…: mikroscope.tar at the top of the router's storage, beside the mikroscope directory that holds the manifest.*

  2. **Container** › **New**, with the fields of the registry pull but **File** `mikroscope.tar` in
     place of Remote Image:

        *Container › New Container for the image tar: File mikroscope.tar in place of Remote Image, and Root Dir mikroscope/mikroscope.*

  3. Wait for `download/extract done` in **Log**.

        *The Container tab once the tar is extracted: one row, with the tag as Comment, its root dir, veth-mikroscope and mikroscope-env, and no R flag.*

  Keep the tar until the next step is done.

### Set ignore-remote-image-change

In the terminal, set `ignore-remote-image-change`, and name `restart-policy` in the same command: a
`/container/set` that leaves `restart-policy` out puts it back to `always`
([verified](https://jmrplens.github.io/mikroscope/about/status/#verified-container-set-resets-restart-policy)).

```routeros
/container/set [find comment="mikroscope:mikroscope (managed by mikroscope)"] ignore-remote-image-change=yes restart-policy=on-failure
:put [/container/get [find comment="mikroscope:mikroscope (managed by mikroscope)"] ignore-remote-image-change]
:put [/container/get [find comment="mikroscope:mikroscope (managed by mikroscope)"] restart-policy]
```

The two reads print `true` and `on-failure`. `install` sets it for both image sources: without
it, RouterOS stops and removes the container on its own once the tar is deleted, and re-creates it
minutes later.

*WebFig's Terminal: /container/set with ignore-remote-image-change=yes and restart-policy=on-failure, then two reads that print true and on-failure.*

For the image tar, delete it now: **Files**, select `mikroscope.tar`, **Remove**.

*Files with mikroscope.tar selected, before Remove: the image is extracted and the tar is no longer needed.*

## Start and verify

1. **Container**, select the row, then **Start** in the Actions panel.

      *The Container tab with the mikroscope row selected and Start in the Actions panel.*

   The row gets the `R` (running) flag.

      *The Container tab after Start: the mikroscope container running.*

2. **Log**, with **Filter** on and Topics contains `container`: the log ends with
   `*** started /mikroscope-agent` and the agent's own line.

      *Log, filtered on container: the pull finishing and the container starting.*

3. In the terminal, ask the agent from the router:

   ```routeros
   :put ([/tool/fetch url="http://172.30.10.2:9123/healthz" output=user as-value]->"data")
   ```

   It prints `{"ok":true,…}`.

      *WebFig's Terminal: /tool/fetch of `http://172.30.10.2:9123/healthz`, and the first row of the agent's answer, which opens with "ok":true.*

From a computer on the router's LAN, `curl http://172.30.10.2:9123/healthz` answers the same, and
`mikroscope status --router …` lists every object of the install
([Network access](https://jmrplens.github.io/mikroscope/install/reaching-the-agent/) if it does not answer).

## Remove

From a computer with the CLI, `mikroscope uninstall --router … --yes` reads the manifest, removes
everything the steps above created, and checks that nothing is left
([Upgrade and uninstall](https://jmrplens.github.io/mikroscope/install/upgrade/#uninstall)). Through the menus, remove in this order:

1. **Container**: select the row, **Stop** in the Actions panel, wait until the `R` flag is gone,
   then **Remove**. RouterOS removes the root dir, `mikroscope/mikroscope`, with the container; if
   Files still lists it, remove it there too.

      *The Container tab with the stopped mikroscope row selected, before Remove.*

2. **Container** › **Envs**: select the seven `mikroscope-env` entries, **Remove**.

      *The Envs tab with the seven mikroscope-env entries selected, before Remove.*

3. **IP** › **Firewall** › **Address Lists**: the `172.30.10.0/30` entry, **Remove**.
4. **Interfaces** › **Interface List**: the `veth-mikroscope` member, **Remove**.
5. **IP** › **Addresses**: `172.30.10.1/30`, **Remove**.
6. **Interfaces** › **VETH**: `veth-mikroscope`, **Remove**.
7. **Files**: `mikroscope/mikroscope.manifest.txt`, **Remove**; then the `mikroscope` directory, if
   nothing else is in it.

      *Files with mikroscope/mikroscope.manifest.txt selected, before Remove: the container's root dir went with the container, and the mikroscope directory goes once it is empty.*

A tar left behind by an extraction that did not finish goes too: **Files**, `mikroscope.tar`,
**Remove**.

## See also

- [Manual install: terminal](https://jmrplens.github.io/mikroscope/install/manual-cli/): the same objects as commands.
- [Script generator](https://jmrplens.github.io/mikroscope/install/generator/): the commands with your values filled in, as
  one script.
- [Install methods](https://jmrplens.github.io/mikroscope/install/routes/): the other ways to install, a script included.
- [Storage and container settings](https://jmrplens.github.io/mikroscope/install/layout/): what each container setting does.
- [Firewall lists](https://jmrplens.github.io/mikroscope/install/firewall/): when the list memberships are needed.
- [Expose on the LAN](https://jmrplens.github.io/mikroscope/security/expose/): reaching the agent on the router's own
  address.