Skip to content

Add MikroTik /app install documentation #107

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
dboze wants to merge 1 commit into
base: main
Choose a base branch
from
+161 −20
Open

Add MikroTik /app install documentation #107

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
168 changes: 148 additions & 20 deletions docs/setup-sensor/mikrotik.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,12 +28,12 @@ The following table shows MikroTik device compatibility:
| Device | Supported | Validated | Notes |
|--------|-----------|-----------|-------|
| RouterOS on AMD64 | ✓ | | |
| hEX refresh | ✓ | ✓ | Consider disabling bandwidth tests¹ |
| hEX refresh | ✓ | ✓ | ARMv5 (EN7562CT CPU) — Apps menu unavailable, see [Manual /container setup](#manual-container-setup-for-en7562ct-devices)¹ |
| hEX S (2025) | ✓ | ✓ | Consider disabling bandwidth tests¹ |
| L009UiGS-RM | ✓ | | Consider disabling bandwidth tests¹ |
| RB4011iGS+RM | ✓ | | |
| RB5009UG+S+IN | ✓ | | |
| RB5009UPr+S+IN | ✓ | | |
| RB5009UPr+S+IN | ✓ | ✓ | |
| RB5009UPr+S+OUT | ✓ | | |
| RB1100AHx4 | ✓ | | |
| RB1100AHx4 Dude Edition | ✓ | | |
Expand Down Expand Up @@ -73,10 +73,112 @@ The following table shows MikroTik device compatibility:
¹ ARMv5 devices have limited CPU performance. If using these devices for routing without hardware offload, disable bandwidth tests using `ORB_BANDWIDTH_DISABLED=1` to prevent CPU spikes.

:::note
After installation, ensure the device has at least 20MB of disk space remaining for the Orb database and logs.
If you run Orb **without** `ORB_EPHEMERAL_MODE=1` (i.e. with persistent storage), its local database and logs grow over time — ensure at least 20MB of disk space remains free for that growth. This does **not** apply to the ephemeral-mode setup recommended below: with ephemeral mode, persistent data stays under 5KB (just certs and config), so the much smaller disk sizes in [Step 2](#step-2-configure-app-storage) are sufficient and intentional, not an oversight.
:::

## Prerequisites
## Recommended: Install via the Apps menu

Starting with RouterOS v7.22, the `/app` menu provides a catalog-based way to deploy containerized apps in a couple of clicks, with networking, storage, and firewall rules configured automatically. This is now the easiest way to get Orb running on a supported MikroTik device — no manual bridge, veth, or NAT configuration required.

:::note
The `/app` system requires **arm64 or x86** architecture. Devices with the **EN7562CT CPU** (e.g. **hEX Refresh**) are explicitly not supported and must use the [manual `/container` setup](#manual-container-setup-for-en7562ct-devices) below instead.
:::

### Requirements

- A MikroTik device with **arm64 or x86** architecture, running **RouterOS v7.22+**
- Physical access to your device (required once, for the device-mode confirmation below)
- The `container` package installed
- A formatted disk for app storage — an external USB/NVMe/SATA drive is recommended for best performance, but on internal-flash-only devices a small file-backed virtual disk works too (see note below)

:::note
The unpacked Orb sensor image needs roughly 20MB. Extraction itself briefly needs more headroom than that, so we recommend a dedicated **scratch disk** for extraction (set via `/container/config/set tmpdir=...`) separate from the app disk — see [Step 2](#step-2-configure-app-storage) below for the exact sizes and commands we validated (25MB app disk + 20MB scratch disk).
:::

### Step 1: Enable container support

1. Connect to your device via WebFig.
2. Select the **Advanced** tab in the top-right.
3. Navigate to **System > Packages**.
4. Click **Check for Updates**, and update RouterOS if a newer version is available (recommended — v7.22+ is required).
5. Once on v7.22+, install the **container** package if it isn't already installed, then **Apply Changes**.
6. Select the **Terminal** tab and run:

```routeros
/system/device-mode/update container=yes
```

7. Press the physical reset or mode button on your device within the 5-minute countdown as instructed, or power-cycle the device. If nothing happens within 5 minutes, the change is cancelled and you'll need to re-run the command.

### Step 2: Configure app storage

If your device has an external USB/NVMe/SATA drive attached, RouterOS will detect it automatically — select it under **System > Disks** and format it with `ext4` or `btrfs` if needed.

If you don't have external storage, you can create small file-backed virtual disks directly on internal flash. We recommend **two** disks: one for the app itself, and one dedicated **scratch disk** used only during image download/extraction. Separating these matters — image extraction briefly needs more space than the final installed app, and giving that transient overhead its own disk lets the main app disk be sized much closer to the app's real footprint:

```routeros
/disk/add type=file file-path=orb-appdisk file-size=25M
/disk/format file-orb-appdisk file-system=ext4

/disk/add type=file file-path=orb-scratch file-size=20M
/disk/format file-orb-scratch file-system=ext4
```

Point the Apps system at the app disk, and point the container extraction directory (`tmpdir`) at the scratch disk:

```routeros
/app/settings/set disk=file-orb-appdisk
/container/config/set tmpdir=file-orb-scratch/tmp
```

:::note
`tmpdir` is a global `/container` setting, separate from the `disk`/`media-path`/`download-path` settings under `/app settings` — it controls where container image layers are extracted, regardless of which app triggers the extraction. Without a separate `tmpdir`, extraction and final storage compete for space on the same disk, and the app disk needs to be considerably larger (**40MB+** in our testing) to have enough transient headroom. With `tmpdir` on its own disk, **25MB** is sufficient for the app disk (with a 20MB scratch disk, which is barely touched — extraction is fast and cleans up after itself). We found 22MB technically extracts but leaves so little headroom that the app crashes shortly after starting (`exited with status 1`) — 25MB is the validated floor, not just close enough.
:::

### Step 3: Add the Orb app store

Orb's app definition is hosted alongside our other install scripts. Add it as a custom app store:

```routeros
/app/settings/set app-store-urls=https://orb.net/docs/scripts/mikrotik/orb-app-store.yml
```

:::note
The custom app-store catalog is only refreshed **at boot** — it won't appear in the Apps list right away. **Reboot your device once** after setting `app-store-urls` for the first time.
:::

After rebooting, open WebFig, navigate to **Apps**, and you should see **orb-sensor** available in the catalog alongside MikroTik's official apps (you may need to switch the view filter from "all" to "store", or scroll to it alphabetically).

### Step 4: Install and configure Orb

1. Select **orb-sensor** from the catalog and click **Install**.
2. Before enabling, set the **Network** to `lan` so the sensor gets a real address on your LAN (rather than being NATed behind the router), matching how a normal Orb sensor would see your network.
3. Add your deployment token as an environment variable so the sensor links to your account automatically on first boot — under the app's **Environment** settings, add:
- `ORB_DEPLOYMENT_TOKEN` = *your deployment token* (see [Configuration](https://orb.net/docs/deploy-and-configure/configuration) for how to generate one)
4. If this device is also routing traffic (rather than just observing it), consider also adding:
- `ORB_FIRSTHOP_DISABLED=1` — disables first-hop monitoring, appropriate for router deployments.
- `ORB_BANDWIDTH_DISABLED=1` — for ARMv5 devices, to avoid CPU spikes from bandwidth tests.
5. Since **use-https** defaults to on and expects the app to expose a web UI (Orb doesn't), disable it so the app doesn't stall waiting on a reverse-proxy certificate.
6. Click **Enable**. The app will download and extract the image, then start automatically.

Once running, your MikroTik device should appear in your Orb dashboard within a minute or two.

#### Equivalent via terminal

Steps 2–6 above can also be done from the **Terminal** tab. Note that `environment` values must be prefixed with the service name (`orb:`, matching the `services.orb` key in the app's YAML):

```routeros
/app/set [find name=orb-sensor] network=lan use-https=no environment="orb:ORB_EPHEMERAL_MODE=1,orb:ORB_DEPLOYMENT_TOKEN=your-deployment-token"
/app/enable [find name=orb-sensor]
```

## Manual `/container` setup (for EN7562CT devices)

:::note
This method is reserved for devices with the **EN7562CT CPU** (e.g. **hEX Refresh**), which do not support the `/app` system at all. If your device supports `/app` (see [Compatibility](#compatibility)), use the [Apps menu method](#recommended-install-via-the-apps-menu) above instead — it's simpler and handles networking/storage automatically.
:::

### Prerequisites

Before you begin, make sure you have:

Expand All @@ -85,7 +187,7 @@ Before you begin, make sure you have:
- Access to your MikroTik device via WebFig
- Basic familiarity with RouterOS configuration

## Step 1: Enable Container Support
### Step 1: Enable Container Support

First, you need to install and enable the container package:

Expand All @@ -108,17 +210,17 @@ Next, update the device mode to enable container support:

3. Press the physical reset or mode button on your device within the 5-minute countdown as instructed.

## Step 2: Configure Container Networking
### Step 2: Configure Container Networking

Create a dedicated network for the Orb container:

### Create Container Bridge
#### Create Container Bridge

Navigate to **Bridge > New**.
- Name: `containers`
- Click **OK**.

### Create Virtual Ethernet Interface
#### Create Virtual Ethernet Interface

Navigate to **Interfaces > New > VETH**.
- Name: `veth-orb`
Expand All @@ -127,24 +229,24 @@ Navigate to **Interfaces > New > VETH**.
- Gateway: `172.19.0.1`.
- Click **OK**.

### Add Interface to Bridge
#### Add Interface to Bridge

Navigate to **Bridge > Ports > New**.
- Interface: `veth-orb`.
- Bridge: `containers`.
- Click **OK**.

## Step 3: Configure Container Storage and Environment
### Step 3: Configure Container Storage and Environment

### Create Data Mount
#### Create Data Mount

Navigate to **Container > Mounts > New**.
- Name: `MOUNT_ORB_DATA`.
- Src: `/orb-data`.
- Dst: `/root/.config/orb`.
- Click **OK**.

### Configure Environment Variables
#### Configure Environment Variables

Enable ephemeral mode to prevent writing to flash:

Expand All @@ -170,9 +272,9 @@ Navigate to **Container > Envs > New**.
- Value: `1`.
- Click **OK**.

## Step 4: Deploy the Orb Container
### Step 4: Deploy the Orb Container

### Add Container
#### Add Container

1. Navigate to **Container > Container > New**.
2. Click the **+** next to **Remote Image** and enter:
Expand All @@ -191,7 +293,7 @@ Navigate to **Container > Envs > New**.
4. Click **Apply**.
5. Click **Start**.

### Configure NAT for Outbound Traffic
#### Configure NAT for Outbound Traffic

1. Select the **Terminal** tab.
2. Enter the following command:
Expand All @@ -200,7 +302,7 @@ Navigate to **Container > Envs > New**.
/ip/firewall/nat/add chain=srcnat action=masquerade src-address=172.19.0.0/24
```

## Step 5: Link Your Orb to Your Account
### Step 5: Link Your Orb to Your Account

The final step is to link your new Orb sensor to your account:

Expand All @@ -221,20 +323,45 @@ The final step is to link your new Orb sensor to your account:

## Troubleshooting

### orb-sensor Doesn't Appear in the Apps Catalog

If you've set `app-store-urls` but don't see **orb-sensor** in the Apps list:

- The custom app-store catalog is only refreshed at boot, not live. **Reboot the device once** after setting `app-store-urls` for the first time.
- Confirm the setting was saved: **Apps > Configuration > Settings**, check the **App Store Urls** field.
- Check the view filter next to the item count (top-right of the Apps list) — it may be set to a specific view that hides store-sourced entries.

:::note
If the terminal commands in [Step 4](#step-4-install-and-configure-orb) (`/app/set [find name=orb-sensor] ...`, `/app/enable [find name=orb-sensor] ...`) run with **no output and no error**, that doesn't mean they succeeded — `[find name=orb-sensor]` silently resolves to nothing if the app isn't in the catalog yet, and RouterOS doesn't warn you when a command's target matches zero items. Before troubleshooting further, confirm the app actually exists first: `/app print where name=orb-sensor` should show one row. If it shows nothing, the catalog issue above hasn't been resolved yet — go back and fix that first.
:::

### App Won't Enable / Stuck Waiting

If an app installed via the Apps menu shows a status like "wait for reverse proxy" and never progresses to downloading:

- Orb doesn't expose a web UI, so the default `use-https=yes` reverse-proxy/certificate step will stall indefinitely. Disable it: `/app/set [find name=orb-sensor] use-https=no`.

### Container Not Starting

If the Orb container fails to start:

- Check container status in **Container > Container**.
- Check container status in **Container > Container** (or **Apps**, if installed via the Apps menu).
- View logs in Terminal: `/log/print` (ensure logging is enabled in container settings).
- Verify the veth interface has the correct IP configuration.
- Ensure the NAT rule is properly configured.
- Ensure the NAT rule is properly configured (manual `/container` setup only — the Apps menu handles this automatically).

### "Not Enough Disk Space" During Download/Extract, or App Crashes Right After Starting

These are two symptoms of the same underlying issue — the app disk is too small:

- **`not enough disk space to download/extract`**: extraction needs more transient headroom than the final image size. Set a separate `tmpdir` on a dedicated scratch disk (see [Step 2](#step-2-configure-app-storage) above) rather than just making the app disk bigger — it's a more effective fix and keeps the app disk small.
- **App extracts fine but exits immediately (`exited with status 1`)**: the app disk is *just barely* big enough to extract into, but leaves too little room for the app to actually write anything at runtime. In our testing, 22MB exhibited exactly this — looks like it worked, then silently died. 25MB (with a separate scratch disk for `tmpdir`) is the validated floor.

### Network Connectivity Issues

If the container cannot reach the internet:

- Verify the NAT rule source address matches your container network.
- Verify the NAT rule source address matches your container network (manual `/container` setup only).
- Check firewall rules aren't blocking container traffic.
- Ensure DNS is properly configured for the container.

Expand All @@ -248,7 +375,7 @@ For devices experiencing high CPU usage:

### Updating the Container

Unfortunately, RouterOS does not support a mechanism for easily updating to the latest version of the Orb image—automated or otherwise. The solution is to delete the container and create a new container with the same configuration, which will pull the :latest tagged image from Docker Hub. As we set up persistent storage, you will not need to re-link, and your history will be preserved.
Unfortunately, RouterOS does not support a mechanism for easily updating to the latest version of the Orb image—automated or otherwise. The solution is to delete the container/app and recreate it with the same configuration, which will pull the `:latest` tagged image from Docker Hub. As we set up persistent storage, you will not need to re-link, and your history will be preserved.

### Container Shell Access Issues

Expand All @@ -260,6 +387,7 @@ If you cannot access the container shell:

## Additional Resources

- For more details on the Apps menu, see [MikroTik's Apps documentation](https://help.mikrotik.com/docs/spaces/ROS/pages/343244823/Apps).
- For more details on RouterOS containers, see [MikroTik's Container documentation](https://help.mikrotik.com/docs/spaces/ROS/pages/84901929/Container).
- To find compatible devices, use [MikroTik's hardware catalog](https://mikrotik.com/products?filter&s=c&a=%5B%22arm%22,%22arm64%22%5D#).
- For alternative installation methods, see [Install Orb on Docker](/docs/setup-sensor/docker).
Expand Down
13 changes: 13 additions & 0 deletions scripts/mikrotik/orb-app-store.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,13 @@
- name: orb-sensor
descr: Monitor internet responsiveness and reliability directly from your MikroTik device.
page: https://orb.net
category: network
default-credential: none
services:
orb:
image: docker.io/orbforge/orb-busybox:latest
environment:
- ORB_EPHEMERAL_MODE=1
# - ORB_DEPLOYMENT_TOKEN=your-deployment-token # Recommended: links this Orb to your account on first boot
# - ORB_FIRSTHOP_DISABLED=1 # Recommended for router deployments
# - ORB_BANDWIDTH_DISABLED=1 # Recommended for ARMv5 devices (see compatibility table)