Install Orb on MikroTik RouterOS
Introduction
This guide will walk you through the process of setting up the Orb sensor on your MikroTik RouterOS device. Installing the Orb sensor allows you to monitor the responsiveness and reliability of your network from anywhere in the world using your mobile device or computer.
With the Orb sensor running on your MikroTik device, you can:
- Monitor your internet experience from your MikroTik routers, switches, and access points to determine where a network issue exists
- Track network reliability and responsiveness over time without impacting other services
- Receive push notifications on your Android or iOS device when your MikroTik device experiences connectivity issues
Compatibility
Orb on MikroTik leverages the RouterOS Container package, which requires RouterOS v7.x and is supported on ARM, ARM64, and AMD64 architectures. We recommend devices with at least 128MB of built-in flash storage or expanded USB/SD-Card storage.
The following table shows MikroTik device compatibility:
Device | Supported | Validated | Notes |
---|---|---|---|
RouterOS on AMD64 | β | ||
hEX refresh | β | β | Consider disabling bandwidth testsΒΉ |
hEX S (2025) | β | β | Consider disabling bandwidth testsΒΉ |
L009UiGS-RM | β | Consider disabling bandwidth testsΒΉ | |
RB4011iGS+RM | β | ||
RB5009UG+S+IN | β | ||
RB5009UPr+S+IN | β | ||
RB5009UPr+S+OUT | β | ||
RB1100AHx4 | β | ||
RB1100AHx4 Dude Edition | β | ||
CCR2004-16G-2S+PC | β | ||
CCR2004-16G-2S+ | β | ||
CCR2004-1G-12S+2XS | β | ||
ROSE Data server (RDS) | β | ||
CCR2216-1G-12XS-2XQ | β | ||
CRS520-4XS-16XQ-RM | β | ||
SXTsq 5 ax | β | ||
LHG-5axD | β | ||
NetBox 5 ax | β | ||
LHG XL 5 ax | β | ||
NetMetal ax | β | ||
mANTBox ax 15s | β | ||
hAP ax lite | β | ||
wAP ax | β | ||
hAP axΒ² | β | ||
hAP ax lite LTE6 | β | ||
hAP acΒ³ | β | ||
cAP ax | β | ||
L009UiGS-2HaxD-IN | β | ||
hAP axΒ³ | β | ||
Chateau LTE6 | β | Requires USB storage | |
Audience | β | ||
Chateau PRO ax | β | ||
RB4011iGS+5HacQ2HnD-IN | β | ||
L11UG-5HaxD | β | ||
L23UGSR-5HaxD2HaxD | β | ||
RB450Gx4 | β | ||
Chateau LTE6 ax | β | ||
cAP LTE12 ax | β | ||
Chateau LTE18 ax | β | ||
Chateau 5G R17 ax | β | ||
Chateau 5G R16 | β | Requires USB storage |
ΒΉ 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.
Prerequisites
Before you begin, make sure you have:
- A compatible MikroTik device running RouterOS v7.x
- Physical access to your MikroTik device (required for device mode update)
- Access to your MikroTik device via WebFig
- Basic familiarity with RouterOS configuration
Step 1: Enable Container Support
First, you need to install and enable the container package:
- Connect to your device via WebFig
- Select the Advanced tab in the top-right
- Navigate to System > Packages
- Click Check for Updates
- Update RouterOS if available (recommended)
- Once completed, click Check for Updates again
- Select the container package and click Enable, then Apply Changes
Next, update the device mode to enable container support:
- Select the Terminal tab in the top-right
- Enter the following command:
/system/device-mode/update container=yes
- Press the physical reset or mode button on your device within the 5-minute countdown as instructed
Step 2: Configure Container Networking
Create a dedicated network for the Orb container:
Create Container Bridge
- Navigate to Bridge > New
- Name:
containers
- Click OK
- Name:
Create Virtual Ethernet Interface
- Navigate to Interfaces > New > VETH
- Name:
veth-orb
- Click the + next to Address
- Enter IP:
172.19.0.2/24
(or alternate if this network is in use) - Gateway:
172.19.0.1
- Click OK
- Name:
Add Interface to Bridge
- Navigate to Bridge > Ports > New
- Interface:
veth-orb
- Bridge:
containers
- Click OK
- Interface:
Step 3: Configure Container Storage and Environment
Create Data Mount
- Navigate to Container > Mounts > New
- Name:
MOUNT_ORB_DATA
- Src:
/orb-data
- Dst:
/root/.config/orb
- Click OK
- Name:
Configure Environment Variables
For router deployments, disable first-hop monitoring:
- Navigate to Container > Envs > New
- Name:
ENV_ORB
- Key:
ORB_FIRSTHOP_DISABLED
- Value:
1
- Click OK
- Name:
For devices with limited CPU (ARMv5), also disable bandwidth tests:
- Navigate to Container > Envs > New
- Name:
ENV_ORB
- Key:
ORB_BANDWIDTH_DISABLED
- Value:
1
- Click OK
- Name:
Step 4: Deploy the Orb Container
Add Container
- Navigate to Container > Container > New
- Click the + next to Remote Image and enter:
registry.hub.docker.com/orbforge/orb-busybox:latest
- Configure the following settings:
- Interface:
veth-orb
- Envlist:
ENV_ORB
- Workdir:
/app
- Mounts:
MOUNT_ORB_DATA
- Logging: enabled
- Start On Boot: enabled
- Interface:
- Click Apply
- Click Start
Configure NAT for Outbound Traffic
- Select the Terminal tab
- Enter the following command:
/ip/firewall/nat/add chain=srcnat action=masquerade src-address=172.19.0.0/24
Step 5: Link Your Orb to Your Account
The final step is to link your new Orb sensor to your account:
- In the RouterOS terminal, connect to the container:
/container shell [find where name~"orb-busybox:latest"]
- Run the link command:
/app/orb link
- Follow the instructions provided to complete the linking process
- Once linked, your MikroTik Orb will appear in your Orb dashboard
Troubleshooting
Container Not Starting
If the Orb container fails to start:
- Check container status in Container > Container
- View logs in Terminal:
/log/print
(ensure logging is enabled in container settings) - Verify the veth interface has the correct IP configuration
- Ensure NAT rule is properly configured
Network Connectivity Issues
If the container cannot reach the internet:
- Verify the NAT rule source address matches your container network
- Check firewall rules aren't blocking container traffic
- Ensure DNS is properly configured for the container
Resource Constraints
For devices experiencing high CPU usage:
- Ensure
ORB_BANDWIDTH_DISABLED=1
is set for ARMv5 devices - Monitor CPU usage via System > Resources
- Consider upgrading to a more powerful device if issues persist
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 make 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.
Container Shell Access Issues
If you cannot access the container shell:
- Ensure the container is running
- Try using the container ID instead of name pattern
- Restart the container and try again
Additional Resources
- For more details on RouterOS containers, see MikroTik's Container documentation
- To find compatible devices, use MikroTik's hardware catalog
- For alternative installation methods, see Install Orb on Docker
- For general Orb troubleshooting, see the Orb documentation