User Tools

Site Tools


toh:mikrotik:common

Common Procedures for Mikrotik RouterBoard Products

This page describes common procedures across MikroTik RouterBoard routers. If you edit / add information about a specific model, please consider linking to this page to avoid repeating common instructions.

Overview of OpenWrt installation

RouterBoards can boot OpenWrt .elf images with initramfs via TFTP. This is first used to validate that the desired version of OpenWrt works and then to install OpenWrt onto NAND Flash from the shell of the running initramfs OpenWrt. After OpenWrt is installed to Flash, depending on model, some platform configuration may be needed. This is explained in the model specific wiki pages.

To upgrade OpenWrt, it is currently necessary to boot into OpenWrt initramfs again because it is not yet possible to overwrite the running Linux Kernel on NAND Flash of the Routerboards (04/2015).

Selecting an OpenWrt version

The first supported version of OpenWrt for a particular model should be listed on the OpenWrt Table of Hardware

If the OpenWrt table of hardware says 'trunk', the model specific page should explain if 'trunk' already contains the necessary patches for your model or if you need to compile and patch OpenWrt yourself. Compilation / patching is explained further down in this document. If the documentation is old, then the model may work already in a newer release.

First test booting OpenWrt from TFTP with the latest version you see documented as working on the wiki. If that works, try again with the latest release you are comfortable with: Latest release or trunk.

Downloading OpenWrt image

Images for the latest OpenWrt image can be downloaded from https://downloads.openwrt.org/. As of 09/2014, Chaos Calmer (15.05) is the latest release, the previous one was Barrier Breaker (14.07) from 09/2014. Go to https://downloads.openwrt.org/ and check what the latest release of OpenWrt is and use that. The following instructions assume 15.05:

wget -c https://downloads.openwrt.org/chaos_calmer/15.05/ar71xx/mikrotik/openwrt-15.05-ar71xx-mikrotik-DefaultNoWifi-rootfs.tar.gz
wget -c https://downloads.openwrt.org/chaos_calmer/15.05/ar71xx/mikrotik/openwrt-15.05-ar71xx-mikrotik-vmlinux-lzma.elf
wget -c https://downloads.openwrt.org/barrier_breaker/14.07/ar71xx/mikrotik/openwrt-ar71xx-mikrotik-vmlinux-initramfs.elf

ln -s openwrt-15.05-ar71xx-mikrotik-DefaultNoWifi-rootfs.tar.gz openwrt-ar71xx-mikrotik-rootfs.tar.gz
ln -s openwrt-15.05-ar71xx-mikrotik-vmlinux-lzma.elf openwrt-ar71xx-mikrotik-vmlinux-lzma.elf

Installing and upgrading OpenWrt on routerboard is a two step-process. You first boot a single "initramfs" image of OpenWrt from your DHCP/TFTP server and from that running OpenWrt you copy the vmlinux kernel to one flash partition and the root filesystem to another partition. This most easily uses the wget2nand utility.

The explanations for setting up your TFTP server below and the wget2nand utility rely on these tree files having specific names. This is why the above explanations create symbolic links to those names (the name openwrt-ar71xx-mikrotik-vmlinux-initramfs.elf is already as the setup for the DHCP server expects it).

As of 11/2015, the download for Chaos Chalmer is missing the initramfs file, which is why the above explanations use the 14.07 image. Please check if this was fixed and use the latest initramfs file available - the older one may not work if your routerboard is newer.

To download nightly build trunk:

wget -c https://downloads.openwrt.org/snapshots/trunk/ar71xx/mikrotik/openwrt-ar71xx-mikrotik-vmlinux-initramfs.elf
wget -c https://downloads.openwrt.org/snapshots/trunk/ar71xx/mikrotik/openwrt-ar71xx-mikrotik-vmlinux-lzma.elf
wget -c https://downloads.openwrt.org/snapshots/trunk/ar71xx/mikrotik/openwrt-ar71xx-mikrotik-DefaultNoWifi-rootfs.tar.gz
ln -s openwrt-ar71xx-mikrotik-DefaultNoWifi-rootfs.tar.gz openwrt-ar71xx-mikrotik-rootfs.tar.gz

If you are running trunk then you will not be able to download/install kernel modules for a longer time after you have downloaded these images because those depend on an exact version of the linux kernel, and trunk is continuously updated, so as soon as the kernel in trunk is updated, so will be the kernel modules from trunk and a that time you will loose the ability to install further modules from trunk (via opkg or luci).

If you do want to be able to install kernel modules over a longer period of time, but your routerboard is not supported in the latest release, you best compile the required patches to make your routerboard work into the latest release and install that (as described below). If you do not want to compile or you want to track the progress of trunk, then you can at such time also try to simply upgrade the vmlinux kernel file to the newest one from trunk: Download snapshots/trunk vmlinux file to your TFTP server, boot to initiramfs, use the manual procedure to only overwrite the vmlinux kernel. Do not use wget2nand because that would also overwrite your root file system.

Boot OpenWrt via DHCP/TFTP

Routerboards have a bootloader that can boot and run a .elf file of OpenWrt with initramfs, aka: a single file with the whole OpenWrt package: kernel plus filesystem. A routerboard has at least three flash partitions: bootloader, kernel and root, so this bootloader is preserved even after OpenWrt is installed onto NAND flash later and OpenWrt on flash is booted from the in-flash routerboard bootloader.

Pick one of the following methods to boot OpenWrt from DHCP/TFTP, then proceed to the next step.

Generic DHCP/TFTP server setup

Copy openwrt-ar71xx-mikrotik-vmlinux-initramfs.elf to your TFTP server location. Set up your DHCP server to point to your TFTP server as the next-server and to that file as the bootfile.

Setup dnsmasq DHCP/TFTP server

If you do not have a different DHCP/TFTP server you want to use, here are instructions of how to use dnsmasq:

Copy openwrt-ar71xx-mikrotik-vmlinux-initramfs.elf to /home/user/mikrotik/trunk/bin/ar71xx/ (edit "user" as your user name). Create script: vi /home/user/mikrotik/trunk/bin/ar71xx/loader.sh

#/bin/bash
ifconfig eth0 192.168.1.10 up
dnsmasq -i eth0 --dhcp-range=192.168.1.100,192.168.1.200 \
--dhcp-boot=openwrt-ar71xx-mikrotik-vmlinux-initramfs.elf \
--enable-tftp --tftp-root=/home/user/mikrotik/trunk/bin/ar71xx/ -d -u test -p0 -K --log-dhcp --bootp-dynamic

Change in the above script "test" (your username instead should enough) and "user" as your user name. Give execution privileges by "chmod a+x loader.sh". Run script loader.sh

TFTP boot routerboard

Connect the WAN port of your routerboard (usually ETH1, or whatever the first ethernet port on your routerboard is named) to a network configured to reach the DHCP/TFTP server that you have set up.

From RouterOS

If you have not yet installed OpenWrt onto Flash, you should reboot the routerboard via TFTP from the RouterOS web configuration interface.

Connect a PC to a LAN port (port 2…). Log into the web interface of RouterOS and set router to boot from ethernet once with DHCP:

  1. System → Routerboard → Settings → Boot device: Try ethernet once then NAND
  2. System → Routerboard → Settings → Boot protocol: DHCP
  3. System → Routerboard → Settings → Force Backup Booter: Checked (if supported by your routerboard - !IMPORTANT)

Save

Reboot routerboard (on some devices "System –> Reboot" does not perform a correct TFTP boot; you must use instead "System –> Shutdown" and unplug/replug the router). This will boot OpenWrt from TFTP once. The boot protocol setting will stay persistent across reboots, but the next reboot will be again from NAND (the bootloader resets this parameter after booting from TFTP once). Once you have installed OpenWrt, you need to use one of the following boot methods to reboot from TFTP.

From COM port

If your model has a serial console (COM port), it can be used to boot the routerboard via TFTP.

Some routerboards may not have the cabling for the COM port, but the COM port may exist on the motherboard and just needs to be soldered to a cable, but on those models the bootloader will most likely not support the serial port, so the boot menu options here will not work. You can just use the serial port on them to access OpenWrt when it is running, but not to set up the routerboard to boot from TFTP.

Connect COM port to a system (terminal server, PC). Set speed to 115200 there. If RouterOS or OpenWrt are running you should have an interactive shell. Reboot the routerboard. Observe “Press any key within 2 seconds to enter setup”. Press a key. Then use the menu to make the routerboard boot from TFTP once. Also make sure DHCP is set as the boostrap protocol.

More information at: http://wiki.mikrotik.com/wiki/Manual:Netinstall#OPTIONAL:_Configuring_RouterBOARD_with_COM_port

From OpenWrt

The OpenWrt rbcfg utility permits to configure parameters of the routerboard bootloader. Note that this program may not work on all routerboards.

opkg update
opkg install rbcfg

rbcfg set boot_device ethnand
rbcfg set boot_protocol dhcp
rbcfg apply

Reboot.

Via Reset button

This procedure should work on all routerboards, and on routerboards without serial CONSOLE and non-working rbcfg, it is likely the only option to upgrade OpenWrt once it is installed.

You can not use this method first time around when RouterOS is still installed because the bootloader boot protocol defaults to bootp. If you try to reboot when bootp is still configured, you may hear a whimpering sound from the bepper first before you hear another beep (the whimpering is for bootp failing to boot, the beep is for RouterOS rebooting).

  1. Unplug routerboard power jack
  2. Hold reset button (on some models this is just a hole with a hidden pushbutton switch).
  3. Plug power jack back in
  4. Observe activity LED.
  5. It first goes on continuously. Then it flashes. Then it goes on continuously. Then it goes off continuously. This will take 15..20 seconds. Then a beep sounds (5 seconds later).
  6. Release reset button.

Flash OpenWrt

After DHCP/TFTP boot of the initramfs, have your PC connected to one of the LAN ports of your routerboard. On some routerboards, not all ports LAN ports will work because it contains a built-in ethernet switch that is not correctly configured yet. Refer to the individual wiki page for your routerboard. In doubt start with port 2 (the first one after the the WAN port). You can not connect to the routerboard via WiFi with the image you TFTP booted because it has WiFi disabled.

After 15..40 seconds, you should be able to ping your routerboard at IP address 192.168.1.1. Disconnect/reconnect your PC if it did not get an IP address from the routerboard.

Now telnet/ssh into your routerboard. In newer OpenWrt versions, telnet will be disabled, and ssh will also be disabled by default. You then first need to go to the web interface http://192.168.1.1 and enter a root password. Afterwards, ssh should work (ssh 192.168.1.1 -l root).

If this is your first time with OpenWrt, you may want to familiarize yourself with it. Likewise if you want to text how well the image works with your routerboard. Everything you do (except the following flashing of OpenWrt) will not survive a reboot. See for example firstlogin.

From the routerboard CLI, flash OpenWrt to the NAND flash of the routerboard.

Copy openwrt-ar71xx-mikrotik-vmlinux-lzma.elf and openwrt-ar71xx-mikrotik-rootfs.tar.gz to a HTTP/HTTPs server reachable from the routerboard (WAN or LAN ports). Connect to the routerboard via telnet to 192.168.1.1 - or if available via serial console.

Automated via wget2nand

Assuming you copied the files to http://myhttpserver.org/path/openwrt-ar71xx-mikrotik-vmlinux-lzma.elf:

wget2nand http://myhttpserver.org/path

This will erase kernel and file system partitions on the routerboard and install the vmlinux kernel on the kernel partition and the rootfs onto the filesystem partition.

Reboot.

Downloading directly from openwrt.org

Instead of downloading the install files (kernel and rootfs) via wget as described above, you can download the install kernel and rootfs directly from openwrt.org by modifying the wget2nand script. This avoids you to set up an http server, but you do need a running Internet connection. The following instructions modify the script to download from http://downloads.openwrt.org/snapshots/trunk/ar71xx/mikrotik. If you want to modify the script to download from latest release you need to modify the filenames for rootfs and vmlinux in the script starting with 15.05 because the file names now include the version number.

vi /sbin/wget2nand
url_rootfs=$url/openwrt-ar71xx-mikrotik-DefaultNoWifi-rootfs.tar.gz

Start download and install:

wget2nand http://downloads.openwrt.org/snapshots/trunk/ar71xx/mikrotik

Reboot.

Latest wget2nand sources are here: wget2nand if you want to enhance it.

Manually

If wget2nand encounters problems, perform its steps manually from shell.

cat /proc/mtd
dev:    size   erasesize  name
mtd0: 00040000 00020000 "booter"
mtd1: 003c0000 00020000 "kernel"
mtd2: 07c00000 00020000 "rootfs"

The following instructions assume that as shown above, kernel is /dev/mtd1 and rootfs /dev/mtd2. If these numbers are different on your model, appropriately change the following commands.

mtd erase /dev/mtd1
mtd erase /dev/mtd2
mkdir /mnt/kernel
mkdir /mnt/rootfs
mount /dev/mtdblock1 /mnt/kernel
mount /dev/mtdblock2 /mnt/rootfs

Copy kernel & rootfs to routerboard:

scp bin/ar71xx/openwrt-ar71xx-mikrotik-vmlinux-lzma.elf root@192.168.1.1:/tmp
scp bin/ar71xx/openwrt-ar71xx-mikrotik-DefaultNoWifi-rootfs.tar.gz root@192.168.1.1:/tmp

Flash kernel & rootfs

mv /tmp/openwrt-ar71xx-nand-vmlinux-lzma.elf /mnt/kernel/kernel
chmod +x /mnt/kernel/kernel
umount /mnt/kernel
cd /mnt/rootfs
tar -xvzf /tmp/openwrt-ar71xx-mikrotik-DefaultNoWifi-rootfs.tar.gz
cd /
umount /mnt/rootfs
sync

Reboot

LEDE snapshot

LEDE can be installed using sysupgrade when booted from initramfs, and therefore do not include wget2nand.

While this might work for release versions, commit ed49d08762e looks important and is only in master.

Initial setup

Leds

Check if the LEDs light up according to their desired functions (eg: under RouterOS). LED configuration is found in /etc/config/system. Depending on model, OpenWrt may have initialized the LEDs correctly. If not, the model specific wiki page should explain how to configure LEDs in /etc/config/system.

Understanding/configuring ports

By default, OpenWrt tries to set up wired/wireless interfaces so that there is one routed WAN interface which is typically the first wired ethernet port and the remaining wired ethernet port and wireless interfaces are bridged into a LAN. This setup is partially done under the hood and partially it shows up in /etc/config/network and can be seen via linux CLI commands, for example 'ifconfig -a':

br-lan this is the linux software bridge interface representing the 'lan'. It should by default have IP address 192.168.1.1. It is created by the 'config interface lan' section in /etc/config/network. The 'option ifname' lists one or more wired interfaces that are included in the bridge. The wireless interface(s) seem to be added to the bridge under the hood. Use 'brctl show' to list all interfaces bound to br-lan.

eth0, eth1,… are ethernet interfaces. They may each be attached directly to an ethernet port or to a switch. Use 'swconfig show' to see which ethernet is connected to a switch.

ethN.M is a VLAN on a switched ethernet.

Serial console

If you solder the UART pins on the board, you can enable the serial console, adding this line to /etc/inittab:

ttyS0::askfirst:/bin/ash --login

Done

You are done now with common OpenWrt procedures for routerboards. Refer to more specific instructions for your individual routerboard, then proceed to first steps with OpenWrt if you do not know them yet:

firstlogin

Additional procedures

Compiling OpenWrt

If your model is not yet supported by trunk, you need to download compile and patch OpenWrt sources. Always check if the model specific wiki instructions could already be obsolete and the necessary patches have already been integrated before embarking into compilation.

Full instructions are at buildroot.exigence The following is a mostly a cheat sheet specifically for routerboards.

OpenWrt sources are available via two release management systems, svn and git. If the model specific instructions specified one, use that, otherwise use git (faster).

# Find/make some directory:
mkdir mikrotik
cd mikrotik

# Get Barrier Breaker (14.07)
git clone git://git.openwrt.org/14.07/openwrt.git
# Alternatively, get trunk (latest build)
git clone git://git.openwrt.org/openwrt.git

# git created openwrt directory. All further compile commands
# have to be entered from that directory
cd openwrt

# Patch the kernel as needed
wget ... -O patchfile
patch -u -p0 < patchfile

# Set up compilation to build AR71XX images for routerboards as well as initramfs
echo CONFIG_TARGET_ar71xx=y > .config
echo CONFIG_TARGET_ar71xx_mikrotik=y >> .config
echo CONFIG_TARGET_ROOTFS_INITRAMFS=y >> .config
echo CONFIG_TARGET_INITRAMFS_COMPRESSION_NONE=y >> .config
# make defconfig creates the rest of the config file. 
make defconfig
# -j parallel compilation may cause problems, but usually it does not.
# choose the number according to the number of your CPU cores
make -j 6

Instead of creating .config manually (most easy), you can use the curses CLI (after patching)

make kernel_menuconfig
-> Target = AR7XXX
-> Subtarget = Mikrotik device with NAND flash
-> Target Images = ramdisk''
-> save, exit
# Normally you do not need this, but if there are specific kernel options required:
make kernel_menuconfig
# compile normally
make -j 6

It can be advantageous to explicitly use the kernel configuration used to build the images on openwrt.org:

  • When comparing behavior between a stock kernel and your patched, self-compiled kernel, you minimize the chance that there are other unexpected changes between the two images beside your patch.
  • Compiling with exactly the same config as the stock kernel allows you to change the stock kernel over to your self compiled kernel without changing the rest of the OpenWrt installation. To do that you need to install just the kernel and the /lib/modules directory from your compiled rootfs.

Example with 14.07:

git clone git://git.openwrt.org/14.07/openwrt.git
cd openwrt
# Optional, this is the commit from which stock kernels where built for 14.07.
# there should be a better label for this in 14.07, but there is none.
git reset --hard 14cb884013ff7034c7bdd19ba704b252095039ad
# Use exactly the config as stock image:
wget https://downloads.openwrt.org/barrier_breaker/14.07/ar71xx/mikrotik/config.ar71xx_mikrotik
mv config.ar71xx_mikrotik .config
# Patch as needed now
..
# Compile
make -j 6

After compilation, the images are in bin/ar71xx. Copy them to your tftp and http server location (including renaming) accordingly to tftp-boot/install them as explained before.

Warning: once you run "make", it will copy files from the 'target' directory over to 'build_dir' directory including downloading additional software/patches. If you modify/patch files in 'target' after a 'make', those changes will not propagate into 'build_dir'. To experiment with different patches, you either need to modify files in build_dir directly, or run 'make clean' before every make run.

Saving MikroTik RouterBoard software key

If you want to be able to re-flash RouterOS after having flashed OpenWrt, save your RouterOS key.

If you have access to the MikroTik's Winbox software, you can export the license file from System→Licence→Export Key. See http://wiki.mikrotik.com/wiki/Manual:License.

Otherwise, boot RouterOS and export the key to a file:

/system license output

Then list the files on your device to see which file the .key file was saved:

/file print

On a fresh install, the key file should be #1 (or #0 on a RB433UAH).

Copy contents, alternative 1: to open the editor with file #1, type:

/file edit 1 value-name=contents
Then copy-paste the text in a file on your computer. (this alternative only support text files)

Copy contents, alternative 2: later v5 versions of RouterOS supports uploading files via the fetch command. Example:

fetch address=192.168.0.200 src-path=RJ15-ERX5.key user=ftp mode=ftp password=ftp dst-path=/pub/write/RJ15-ERX5.key upload=yes

Copy contents, alternative 3: download files from web interface. Example

http://192.168.88.1/webfig/#Files

The differences between the obtained key file and a key exported with Winbox are that the SoftwareID line is not present in the latter, and there are no empty lines, so you should probably delete all the empty lines in your file prior to import it for a new installation; the SoftwareID line should not bother the installer (untested).

Saving MikroTik RouterOS

From TFTP booted OpenWrt:

cat /proc/mtd
# the following expects that kernel is mtd1 and rootfs is mtd2
mkdir /mnt/kernel /mnt/rootfs
mount -o ro /dev/mtdblock1 /mnt/kernel
mount -o ro /dev/mtdblock2 /mnt/rootfs
cd /mnt/kernel
tar czf /tmp/mikrotik-kernel.tar.gz .
cd /mnt/rootfs
tar czf /tmp/mikrotik-rootfs.tar.gz .
cd /tmp
scp mikrotik* username@your-server:tmp

Notes

Patchworks

Router model specific pages may refer to http://patchwork.openwrt.org/patch/4773/raw/ URLs. That patchwork server was decommissioned in 2014. See https://dev.openwrt.org/ticket/17785 and https://lists.openwrt.org/pipermail/openwrt-devel/2014-December/029786.html.

The new patch server is https://patchwork.ozlabs.org. Patch numbers for the old server seemingly can not be translated to the new patchwork server so they are not accessible anymore. In general, all patches from the old patchserver should have already been integrated into trunk.

Rumors

Some wiki pages claim that parallel compilation with -j N mail fail OpenWrt build. This seems not to be a problem for >= 14.07 and AR71XX builds as for RouterBoards, parallel compile seems to work fine.

Some wiki pages claim that you need to put paths into the OpenWrt build tree into your .bashrc so that compilation works correctly. This does not seem to be the case anymore. No problems encountered.

toh/mikrotik/common.txt · Last modified: 2017/11/12 19:31 by tomn