The Guide describes the basic steps of installing and configuring a dedicated PC router running MikroTik RouterOS™. The following sections are included in this Guide:

• Setting up MikroTik RouterOS™
• Downloading and Installing the MikroTik RouterOS™
• 1. Download the basic installation archive file.
• 2. Create the installation media
• 3. Install the MikroTik RouterOS™ software.
• Obtaining the Software License
• Logging into the MikroTik Router
• Adding Software Packages
• Software Licensing Issues
• Navigating the Terminal Console
• Accessing the Router Remotely Using Web Browser and WinBox Console
• Overview
• Starting the Winbox Console
• Overview of Common Functions
• Troubleshooting for Winbox Console
• Configuring Basic Functions
• Working with Interfaces
• Use of the 'setup' Command
• Adding Addresses
• Configuring the Default Route
• Testing the Network Connectivity
• Application Examples
• Application Example with Masquerading
• Application Example with Bandwidth Management
• Application Example with NAT

Setting up MikroTik RouterOS™

Downloading and Installing the MikroTik RouterOS™

1. Download the basic installation archive file.

• ISO image of the installation CD, if you have a CD writer for creating CDs. The ISO image is in the MTcdimage_v2-6-x_dd-mmm-yyyy.zip archive file containing a bootable CD image. The CD will be used for booting up the dedicated PC and installing the MikroTik RouterOS™ on its hard-drive or flash-drive.
• MikroTik Disk Maker, if you want to create 3.5" installation floppies. The Disk Maker is a self-extracting archive DiskMaker_v2-6-x_dd-mmm-yyyy.exe file, which should be run on your Win95/98/NT4/2K/XP workstation to create the installation floppies. The installation floppies will be used for booting up the dedicated PC and installing the MikroTik RouterOS™ on its hard-drive or flash-drive.
• MikroTik Disk Maker in a set of smaller files, if you have problems downloading one large file.
• Netinstall, if you want to install RouterOS™ over a LAN with one floppy boot disk

Note! The installation from CD or network requires Full (paid) License. If you intend to obtain the Free Demo License, you should use the floppy installation media.

2. Create the installation media

• For the CD, write the ISO image onto a blank CD.
• For the floppies, run the Disk Maker on your Windows workstation to create the installation floppies. Follow the instructions and insert the floppies in your FDD as requested, label them as Disk 1,2,3, etc.

3. Install the MikroTik RouterOS™ software.

• An advanced 4th generation (core frequency 100MHz or more), 5th generation (Intel Pentium, Cyrix 6X86, AMD K5 or comparable) or newer Intel IA-32 (i386) compatible motherboard and processor (dual processors are not supported);
• from 32MB to 1GB RAM (from 48MB suggested);
• 30MB or more PRIMARY MASTER IDE HDD or IDE flashdrive. Note: The hard disk will be entirely reformatted during the installation and all data on it will be lost!
• A network adapter (NE2000 compatible PCI or ISA Ethernet card, or any other supported NIC, see specifications of supported interfaces on our web page);

For installation purposes (and only for that time) you should also have:

• A SECONDARY MASTER CD drive set as primary boot device, if you want to use the created CD for installing the MikroTik RouterOS™ onto the primary master HDD;
• A 3.5" FDD set as primary boot device, if you want to use the created set of floppies for installing the MikroTik RouterOS™;
• A monitor and keyboard for installation and initial setup of the MikroTik Router. The monitor and keyboard do not need to be connected to the router after it is set up for connecting to it over the network.

After successful installation please remove the installation media from your CD or floppy disk drive and hit 'Enter' to reboot the router. While the router will be starting up for the first time you will be given a Software ID for your installation and asked to supply a valid software license key (Software Key) for it. Write down the Software ID. You will need it to obtain the Software License through the MikroTik Account Server.

If you need extra time to obtain the Software License Key, you may want to power off the router. Type shutdown in the Software key prompt and power the router off when the router is halted.

Obtaining the Software License

After installing the router and starting it up for the first time you will be given a Software ID.

1. Write down the Software ID reported by the RouterOS™.
2. If you have an account with MikroTik, follow to the next step.
   If you do not have an account at www.mikrotik.com, just press the 'New' button on the upper right-hand corner of the MikroTik's web page to create your account.

   

   You will be presented with the Account Sign-Up Form where you chose your account name and fill in the required information.

3. To obtain the Software License Key, log on to your account at www.mikrotik.com entering your account name and password (upper right-hand corner on this webpage), for example:

   

4. After logging on to the Account Server select "Free Demo License" or "Order Software License" in the Account Menu.

   Note! The CD or Netinstall installation cannot be 'unlocked' with the Free Demo Key. Use the Floppy installation, or, purchase the License Key.

5. The Software Key will be sent to the email address, which has been specified in your account setup.
6. Read your email and enter the Software Key at the router's console, for example:

   Software ID: 5T4V-IUT
   Software key: 4N7X-UZ8-6SP
   

After entering the correct Software License Key you will be presented with the MikroTik Router's login prompt.

Logging into the MikroTik Router

MikroTik v2.6
Login: admin
Password:

The password can be changed with the /password command.

Adding Software Packages

The additional software packages should have the same version as the system package. If not, the package wont be installed. Please consult the MikroTik RouterOS™ Software Package Installation and Upgrading Manual for more detailed information about installing additional software packages.

Software Licensing Issues

[admin@MikroTik] ip firewall src-nat> /system license print
         software-id: "SB5T-R8T"
                 key: "3YIY-ZV8-DH2"
    upgradable-unitl: may/01/2003
[admin@MikroTik] system license> feature print
Flags: X - disabled
  #   FEATURE
  0 X AP
  1 X synchronous
  2 X radiolan
  3 X wireless-2.4gHz
  4   licensed
[admin@MikroTik] system license> set key=D45G-IJ6-QM3
[admin@MikroTik] system license> /system reboot
Reboot, yes? [y/N]: y
system will reboot shortly

If there is no appropriate license, the appropriate interfaces wont show up under the interface list, even though the packages can be installed on the MikroTik RouterOS™ and corresponding drivers loaded.

Navigating the Terminal Console

  MMM      MMM       KKK                          TTTTTTTTTTT      KKK
  MMMM    MMMM       KKK                          TTTTTTTTTTT      KKK
  MMM MMMM MMM  III  KKK  KKK  RRRRRR     OOOOOO      TTT     III  KKK  KKK
  MMM  MM  MMM  III  KKKKK     RRR  RRR  OOO  OOO     TTT     III  KKKKK
  MMM      MMM  III  KKK KKK   RRRRRR    OOO  OOO     TTT     III  KKK KKK
  MMM      MMM  III  KKK  KKK  RRR  RRR   OOOOOO      TTT     III  KKK  KKK

  MikroTik RouterOS v2.6 (c) 1999-2002       http://www.mikrotik.com/

Terminal xterm detected, using multiline mode
[admin@MikroTik] >

The command prompt shows the identity name of the router and the current menu level, for example:

[MikroTik] >                Base level menu
[MikroTik] interface>       Interface configuration
[MikroTik] ip address>      IP Address management

The list of available commands at any menu level can be obtained by entering the question mark '?', for example:

[admin@MikroTik] > ?

         driver  Driver management
           file  Local router file storage.
         import  Run exported configuration script
      interface  Interface configuration
            log  System logs
       password  Change password
           ping  Send ICMP Echo packets
           port  Serial ports
           quit  Quit console
           redo  Redo previosly undone action
          setup  Do basic setup of system
           undo  Undo previous action
           user  User management
            ppp
           snmp  snmp settings
  isdn-channels  ISDN channel status info
             ip
          queue  Bandwidth management
         system  System information and utilities
           tool
        routing
         export

[admin@MikroTik] > ip ?

      accounting  Traffic accounting
         address  Address management
             arp  ARP entries management
             dns  DNS settings
        firewall  Firewall management
       neighbour  neighbours
         packing  Packet packing settings
            pool  IP address pools
           route  Route management
         service
  policy-routing
     dhcp-client  DHCP client settings
     dhcp-server  DHCP server settings
       dns-cache
           ipsec
       web-proxy  HTTP proxy
       telephony  IP Telephony interface
          export
[admin@MikroTik] > ip

The list of available commands and menus has short descriptions next to the items. You can move to the desired menu level by typing its name and hitting the [Enter] key, for example:

[admin@MikroTik]>                      Base level menu
[admin@MikroTik]> driver               Enter 'driver' to move to the driver level
                                       menu
[admin@MikroTik] driver> /             Enter '/' to move to the base level menu
                                       from any level
[admin@MikroTik]> interface            Enter 'interface' to move to the interface
                                       level menu
[admin@MikroTik] interface> /ip        Enter '/ip' to move to the IP level menu
                                       from any level
[admin@MikroTik] ip>

A command or an argument does not need to be completed, if it is not ambiguous. For example, instead of typing 'interface' you can type just 'in' or 'int'. To complete a command use the [Tab] key.

The commands may be invoked from the menu level, where they are located, by typing its name. If the command is in a different menu level than the current one, then the command should be invoked using its full or relative path, for example:

[admin@MikroTik] ip route> print                  Prints the routing table
[admin@MikroTik] ip route> .. address print       Prints the IP address table
[admin@MikroTik] ip route> /ip address print      Prints the IP address table

The commands may have arguments. The arguments have their names and values. Some arguments, that are required, may have no name. Below is a summary on executing the commands and moving between the menu levels:

       Command                               Action
command [Enter]      Execute the command
[?]                  Show the list of all available commands
command [?]          Display help on the command and the list of arguments
command argument [?] Display help on the command's argument
[Tab]                Complete the command/word. If the input is ambiguous, a
                     second [Tab] gives possible options
/                    Move up to the base level
/command             Execute the base level command
..                   Move up one level
""                   Enter an empty string
"word1 word2"        Enter 2 words that contain a space

You can abbreviate names of levels, commands and arguments.

For the IP address configuration, instead of using the 'address' and 'netmask' arguments, in most cases you can specify the address together with the number of bits in the network mask, i.e., there is no need to specify the 'netmask' separately. Thus, the following two entries would be equivalent:

/ip address add address 10.0.0.1/24 interface ether1
/ip address add address 10.0.0.1 netmask 255.255.255.0 interface ether1

However, if the netmask argument is not specified, you must specify the size of the network mask in the address argument, even if it is the 32-bit subnet, i.e., use 10.0.0.1/32 for address 10.0.0.1 and netmask 255.255.255.255

Accessing the Router Remotely Using Web Browser and WinBox Console

• the telnet protocol, for example, using the telnet client of your Windows or Unix workstation. Working with the telnet console is the same as working with the monitor and keyboard attached to the router locally.
• the ftp for uploading the software upgrade packages or retrieving the exported configuration files.
• the http and WinBox Console, for example, using the web browser of your workstation.

Overview

All Winbox interface functions are as close as possible to Console functions: all Winbox functions are exactly in the same place in Terminal Console and vice versa (except functions that are not implemented in Winbox). That is why there are no Winbox sections in the manual.

The Winbox Console plugin loader, the winbox.exe program, can be retrieved from the MikroTik router, the URL is http://router_address/winbox/winbox.exe Use any web browser on Windows 95/98/ME/NT4.0/2000/XP to retrieve the router's web page with the mentioned link.

The winbox plugins are cached on the local disk for each MikroTik RouterOS™ version. The plugins are not downloaded, if they are in the cache, and the router has not been upgraded since the last time it has been accessed.

Starting the Winbox Console

By clicking on the Winbox Console link you can start the winbox.exe download. Choose the option "Run this program from its current location" and click "OK":

Accept the security warning, if any:

Alternatively, you can save the winbox.exe program to your disk and run it from there.

The winbox.exe program opens the Winbox login window. Login to the router by specifying the IP address, user name, and password, for example:

Watch the download process of Winbox plugins:

The Winbox console is opened after the plugins have been downloaded:

The Winbox Console uses TCP port 3987. After logging on to the router you can work with the MikroTik router's configuration through the Winbox console and perform the same tasks as using the regular console.

Overview of Common Functions

You can use the menu bar to navigate through the router's configuration menus, open configuration windows. By double clicking on some list items in the windows you can open configuration windows for the specific items, and so on.

There are some hints for using the Winbox Console:

• To open the required window, simply click on the corresponding menu item.
• To add a new entry you should click on the icon in the corresponding window.
• To remove an existing entry click on the icon.
• To enable an item, click on the icon.
• To disable an item, click on the icon.
• To make or edit a comment for a selected item, click on the icon.
• To refresh the window, click on the icon.
• To undo an action, click on the icon above the main menu.
• To redo an action, click on the icon above the main menu.
• To logout from the Winbox Console, click on the icon.

Troubleshooting for Winbox Console

• Cannot get the MikroTik RouterOS™ Winbox to start. The "Missing RouterOS Winbox plugins" message is displayed.
  You can try to clear the winbox cache or wipe out the cache folder, and then reload the plugins:
  • To clear the winbox plugin cache on your computer, choose the Clear Cache option in the Winbox system menu of the login window:

    

  • To wipe out the winbox plugin cache on your computer, find the cache file location using the registry Key="HKEY_CURRENT_USER\Software\Microsoft\Windows\CurrentVersion\Explorer\ ShellFolders\AppData"
    For example, for the user 'Administrator' on W2K, the Winbox folder is under
    C:\Documents and Settings\Administrator\Application Data\Mikrotik
    On W95/98 the Winbox folder is under C:\Windows\Application Data\Mikrotik
• I still cannot open the Winbox Console
  The Winbox Console uses TCP port 3987. Make sure you have access to it through the firewall.

Configuring Basic Functions

Working with Interfaces

[admin@MikroTik] interface> print
Flags: X - disabled, D - dynamic, R - running
  #    NAME                 TYPE             MTU
  0  R ether1               ether            1500
  1  R ether2               ether            1500
  2  R ether3               ether            1500
  3  R ether4               ether            1500
  4  R ether5               ether            1500
  5  R sync1                sync             1500
  6  R pc1                  pc               1500
  7  R ether6               ether            1500
  8  R prism1               prism            1500
[admin@MikroTik] interface>

The device drivers for NE2000 compatible ISA cards need to be loaded using the add command under the /drivers menu. For example, to load the driver for a card with IO address 0x280 and IRQ 5, it is enough to issue the command:

[admin@MikroTik] driver> add name=ne2k-isa io=0x280
[admin@MikroTik] driver> print
Flags: I - invalid, D - dynamic
  #   DRIVER                                IRQ IO       MEMORY   ISDN-PROTOCOL
  0 D RealTek 8139
  1 D Intel EtherExpressPro
  2 D PCI NE2000
  3   ISA NE2000                            280
  4   Moxa C101 Synchronous                              C8000
[admin@MikroTik] driver>

The interfaces need to be enabled, if you want to use them for communications. Use the /interface enable name command to enable the interface with a given name, for example:

[admin@MikroTik] interface> print
Flags: X - disabled, D - dynamic, R - running
  #   NAME                 TYPE             MTU
  0 X  ether1               ether            1500
  0 X  ether2               ether            1500
[admin@MikroTik] interface> enable 0
[admin@MikroTik] interface> enable ether2
[admin@MikroTik] interface> print
Flags: X - disabled, D - dynamic, R - running
  #   NAME                 MTU   TYPE
  0  R ether1               ether            1500
  0  R ether2               ether            1500
[admin@MikroTik] interface>

You can use the number or the name of the interface in the enable command.

The interface name can be changed to a more descriptive one by using the /interface set command:

[admin@MikroTik] interface> set 0 name=Public
[admin@MikroTik] interface> set 1 name=Local
[admin@MikroTik] interface> print
Flags: X - disabled, D - dynamic, R - running
  #   NAME                 MTU   TYPE
  0  R Public               ether            1500
  0  R Local                ether            1500
[admin@MikroTik] interface>

Use of the 'setup' Command

Adding Addresses

Please note that the addresses assigned to different interfaces of the router should belong to different networks. In the current example we use two networks:

• The local LAN with network address 192.168.0.0 and 24-bit netmask 255.255.255.0 The router's address is 192.168.0.254 in this network.
• The ISP's network with address 10.0.0.0 and 24-bit netmask 255.255.255.0 The router's address is 10.0.0.217 in this network.

[admin@MikroTik] ip address> add address 192.168.0.254/24 interface Local
[admin@MikroTik] ip address> add address 10.0.0.217/24 interface Public
[admin@MikroTik] ip address> print
Flags: X - disabled, I - invalid, D - dynamic
  #   ADDRESS            NETWORK         BROADCAST       INTERFACE
  0   10.0.0.217/24      10.0.0.217      10.0.0.255      Public
  1   192.168.0.254/24   192.168.0.0     192.168.0.255   Local
[admin@MikroTik] ip address>

Here, the network mask has been specified in the value of the address argument. Alternatively, the argument 'netmask' could have been used with the value '255.255.255.0'. The network and broadcast addresses were not specified in the input since they could be calculated automatically.

Configuring the Default Route

[admin@MikroTik] ip route> print
Flags: X - disabled, I - invalid, D - dynamic, J - rejected,
C - connect, S - static, R - rip, O - ospf, B - bgp
    #    DST-ADDRESS        G GATEWAY         DISTANCE INTERFACE
    0 DC 192.168.0.0/24     r 0.0.0.0         0        Local
    1 DC 10.0.0.0/24        r 0.0.0.0         0        Public
[admin@MikroTik] ip route> print detail
Flags: X - disabled, I - invalid, D - dynamic, J - rejected,
C - connect, S - static, R - rip, O - ospf, B - bgp
    0 DC dst-address=192.168.0.0/24 preferred-source=192.168.0.254
         gateway=0.0.0.0 gateway-state=reachable distance=0 interface=Local

    1 DC dst-address=10.0.0.0/24 preferred-source=10.0.0.217 gateway=0.0.0.0
         gateway-state=reachable distance=0 interface=Public

[admin@MikroTik] ip route>

These routes show, that IP packets with destination to 10.0.0.0/24 would be sent through the interface Public, whereas IP packets with destination to 192.168.0.0/24 would be sent through the interface Local. However, you need to specify where the router should forward packets, which have destination other than networks connected directly to the router. This is done by adding the default route (destination 0.0.0.0, netmask 0.0.0.0). In this case it is the ISP's gateway 10.0.0.1, which can be reached through the interface Public:

[admin@MikroTik] ip route> add gateway=10.0.0.1
[admin@MikroTik] ip route> print
Flags: X - disabled, I - invalid, D - dynamic, J - rejected,
C - connect, S - static, R - rip, O - ospf, B - bgp
    #    DST-ADDRESS        G GATEWAY         DISTANCE INTERFACE
    0  S 0.0.0.0/0          r 10.0.0.1        1        Public
    1 DC 192.168.0.0/24     r 0.0.0.0         0        Local
    2 DC 10.0.0.0/24        r 0.0.0.0         0        Public
[admin@MikroTik] ip route>

Here, the default route is listed under #0. As we see, the gateway 10.0.0.1 can be reached through the interface 'Public'. If the gateway was specified incorrectly, the value for the argument 'interface' would be unknown. Note, that you cannot add two routes to the same destination, i.e., destination-address/netmask! It applies to the default routes as well. Instead, you can enter multiple gateways for one destination. For more information on IP routes, please read the relevant topic in the Manual.

If you have added an unwanted static route accidentally, use the remove command to delete the unneeded one. Do not remove the dynamic (D) routes! They are added automatically and should not be deleted 'by hand'. If you happen to, then reboot the router, the route will show up again.

Testing the Network Connectivity

[admin@MikroTik] ip route> /ping 10.0.0.4
10.0.0.4 64 byte pong: ttl=255 time=7 ms
10.0.0.4 64 byte pong: ttl=255 time=5 ms
10.0.0.4 64 byte pong: ttl=255 time=5 ms
3 packets transmitted, 3 packets received, 0% packet loss
round-trip min/avg/max = 5/5.6/7 ms
[admin@MikroTik] ip route>
[admin@MikroTik] ip route> /ping 192.168.0.1
192.168.0.1 64 byte pong: ttl=255 time<1 ms
192.168.0.1 64 byte pong: ttl=255 time<1 ms
192.168.0.1 64 byte pong: ttl=255 time<1 ms
3 packets transmitted, 3 packets received, 0% packet loss
round-trip min/avg/max = 0/0.0/0 ms
[admin@MikroTik] ip route>

The workstation and the laptop can reach (ping) the router at its local address 192.168.0.254, If the router's address 192.168.0.254 is specified as the default gateway in the TCP/IP configuration of both the workstation and the laptop, then you should be able to ping the router:

C:\>ping 192.168.0.254
Reply from 192.168.0.254: bytes=32 time=10ms TTL=253
Reply from 192.168.0.254: bytes=32 time<10ms TTL=253
Reply from 192.168.0.254: bytes=32 time<10ms TTL=253

C:\>ping 10.0.0.217
Reply from 10.0.0.217: bytes=32 time=10ms TTL=253
Reply from 10.0.0.217: bytes=32 time<10ms TTL=253
Reply from 10.0.0.217: bytes=32 time<10ms TTL=253

C:\>ping 10.0.0.4
Request timed out.
Request timed out.
Request timed out.

C:\>

You cannot access anything beyond the router (network 10.0.0.0/24 and the Internet), unless you do the following:

• Use source network address translation (masquerading) on the MikroTik router to 'hide' your private LAN 192.168.0.0/24 (see the information below), or
• Add a static route on the ISP's gateway 10.0.0.1, which specifies the host 10.0.0.217 as the gateway to network 192.168.0.0/24. Then all hosts on the ISP's network, including the server, will be able to communicate with the hosts on the LAN.

Next will be discussed situation with 'hiding' the private LAN 192.168.0.0/24 'behind' one address 10.0.0.217 given to you by the ISP.

Application Examples

Application Example with Masquerading

Masquerading conserves the number of global IP addresses required and it lets the whole network use a single IP address in its communication with the world.

To use masquerading, a source NAT rule with action 'masquerade' should be added to the firewall configuration:

[admin@MikroTik] ip firewall src-nat> add action=masquerade out-interface=Public
[admin@MikroTik] ip firewall src-nat> print
Flags: X - disabled, I - invalid
  0   src-address=0.0.0.0/0:0-65535 dst-address=0.0.0.0/0:0-65535
      out-interface=Public protocol=all icmp-options=any:any flow=""
      limit-count=0 limit-burst=0 limit-time=0s action=masquerade
      to-src-address=0.0.0.0 to-src-port=0-65535 bytes=0 packets=0

[admin@MikroTik] ip firewall src-nat>

Please consult the Firewall Manual for more information on masquerading.

Application Example with Bandwidth Management

Assume you want to limit the bandwidth to 128kbps on downloads and 64kbps on uploads for all hosts on the LAN. Bandwidth limitation is done by applying queues for outgoing interfaces regarding the traffic flow. It is enough to add two queues at the MikroTik router:

[admin@MikroTik] queue simple> add interface Local limit-at 128000
[admin@MikroTik] queue simple> add interface Public limit-at 64000
[admin@MikroTik] queue simple> print
Flags: X - disabled, I - invalid
  0   name="" src-address=0.0.0.0/0 dst-address=0.0.0.0/0 interface=Local
      limit-at=128000 queue=default priority=8 bounded=yes

  1   name="" src-address=0.0.0.0/0 dst-address=0.0.0.0/24 interface=Public
      limit-at=64000 queue=default priority=8 bounded=yes

[admin@MikroTik] queue simple>

Leave all other parameters as set by default. The limit is approximately 128kbps going to the LAN and 64kbps leaving the client's LAN. Please note, that the queues have been added for the outgoing interfaces regarding the traffic flow.

Please consult the Queues Manual for more information on bandwidth management and queuing.

Application Example with NAT

The server'would have been s address now is 192.168.0.4, and we are running web server on it that listens to the TCP port 80. We want to make it accessible from the Internet at address:port 10.0.0.217:80. This can be done by means of Static Network Address translation (NAT) at the MikroTik Router. The Public address:port 10.0.0.217:80 will be translated to the Local address:port 192.168.0.4:80. One destination NAT rule is required for translating the destination address and port:

[admin@MikroTik] ip firewall dst-nat> add action=nat protocol=tcp \
dst-address=10.0.0.217/32:80 to-dst-address=192.168.0.4
[admin@MikroTik] ip firewall dst-nat> print
Flags: X - disabled, I - invalid
  0   src-address=0.0.0.0/0:0-65535 in-interface=all
      dst-address=10.0.0.217/32:80 protocol=tcp icmp-options=any:any flow=""
      src-mac-address=00:00:00:00:00:00 limit-count=0 limit-burst=0
      limit-time=0s action=nat to-dst-address=192.168.0.4 to-dst-port=0-65535

[admin@MikroTik] ip firewall dst-nat>

Please consult the Firewall Manual for more information on NAT.

Terminal Console Manual

Overview

Contents of the Manual

• Overview of Common Functions
• Lists
• Item Names
• Quick Typing
• Help
• Multiple Items
• General Commands

Overview of Common Functions

The console allows configuration of the router settings using text commands. The command structure is similar to the Unix shell. Since there's a lot of available commands, they're split into hierarchy. For example, all (well, almost all) commands that work with routes start with ip route:

[admin@MikroTik] > ip route print
Flags: X - disabled, I - invalid, D - dynamic, J - rejected,
C - connect, S - static, R - rip, O - ospf, B - bgp
    #    DST-ADDRESS        G GATEWAY         DISTANCE INTERFACE
    0  S 0.0.0.0/0          r 10.0.0.1        1        ether6
                            r 192.168.1.254            ether4
    1 DC 192.168.1.0/24     r 0.0.0.0         0        ether4
    2 DC 10.10.10.0/24      r 0.0.0.0         0        prism1
    3 DC 10.0.0.0/24        r 0.0.0.0         0        ether6
[admin@MikroTik] > ip route set 0 gateway=10.0.0.1
[admin@MikroTik] > ip route print
Flags: X - disabled, I - invalid, D - dynamic, J - rejected,
C - connect, S - static, R - rip, O - ospf, B - bgp
    #    DST-ADDRESS        G GATEWAY         DISTANCE INTERFACE
    0  S 0.0.0.0/0          r 10.0.0.1        1        ether6
    1 DC 192.168.1.0/24     r 0.0.0.0         0        ether4
    2 DC 10.10.10.0/24      r 0.0.0.0         0        prism1
    3 DC 10.0.0.0/24        r 0.0.0.0         0        ether6
[admin@MikroTik] >

Instead of typing ip route before each command, ip route can be typed once to "change into" that particular branch of command hierarchy. Thus, the example above could also be executed like this:

[admin@MikroTik] > ip route
[admin@MikroTik] ip route> print
Flags: X - disabled, I - invalid, D - dynamic, J - rejected,
C - connect, S - static, R - rip, O - ospf, B - bgp
    #    DST-ADDRESS        G GATEWAY         DISTANCE INTERFACE
    0  S 0.0.0.0/0          r 10.0.0.1        1        ether6
    1 DC 192.168.1.0/24     r 0.0.0.0         0        ether4
    2 DC 10.10.10.0/24      r 0.0.0.0         0        prism1
    3 DC 10.0.0.0/24        r 0.0.0.0         0        ether6
[admin@MikroTik] ip route>

Notice that prompt changes to show where in the command hierarchy you are located at the moment. To change to top level, type /

[admin@MikroTik] ip route> /
[admin@MikroTik] >

To move up one command level, type ..

[admin@MikroTik] ip route> ..
[admin@MikroTik] ip>

You can also use / and .. to execute commands from other levels without changing the current level:

[admin@MikroTik] ip route> /ping 10.0.0.10
10.0.0.10 64 byte pong: ttl=128 time=5 ms
10.0.0.10 64 byte pong: ttl=128 time=6 ms
2 packets transmitted, 2 packets received, 0% packet loss
round-trip min/avg/max = 5/5.5/6 ms
[admin@MikroTik] ip route>

Or alternatively, to go back to the base level you could use the .. twice:

[admin@MikroTik] ip route> .. .. ping 10.0.0.10
10.0.0.10 64 byte pong: ttl=128 time=8 ms
10.0.0.10 64 byte pong: ttl=128 time=6 ms
2 packets transmitted, 2 packets received, 0% packet loss
round-trip min/avg/max = 6/7.0/8 ms
[admin@MikroTik] ip route>

Lists

[admin@MikroTik] > interface print
Flags: X - disabled, D - dynamic, R - running
  #    NAME                 TYPE             MTU
  0  R ether1               ether            1500
  1  R ether2               ether            1500
  2  R ether3               ether            1500
  3  R ether4               ether            1500
  4  R prism1               prism            1500
[admin@MikroTik] >

To change parameters of an item (interface settings in this particular case), you have to specify it's number to the set command:

[admin@MikroTik] interface> set 0 mtu=1460
[admin@MikroTik] interface> print
Flags: X - disabled, D - dynamic, R - running
  #    NAME                 TYPE             MTU
  0  R ether1               ether            1460
  1  R ether2               ether            1500
  2  R ether3               ether            1500
  3  R ether4               ether            1500
  4  R prism1               prism            1500
[admin@MikroTik] interface>

Numbers are assigned by print command and are not constant - it is possible that two successive print commands will order items differently. But the results of last print commands are memorized and, thus, once assigned item numbers can be used even after add, remove and move operations (after move operations, item numbers are moved with the items). Item numbers are assigned for sessions, they will remain the same until you quit the console or until the next print command is executed. Also, numbers are assigned separately for every item list, so ip address print won't change numbers for interface list.

Let's assume interface prism print hasn't been executed in this session. In this case:

[admin@MikroTik] interface> prism set 0 ssid=mt
ERROR: item numbers not assigned

Console is telling that there has been no interface prism print command, and thus, it cannot (and also you) know which PRISM interface number 0 corresponds to.

To understand better how do item numbers work, you can play with from argument of print commands:

[admin@MikroTik] interface> print from=1
Flags: X - disabled, D - dynamic, R - running
  #    NAME                 TYPE             MTU
  0  R ether2               ether            1500
[admin@MikroTik] interface>

The from argument specifies what items to show. Numbers are assigned by every print command, thus, after executing command above there will be only one item accessible by number - interface ether2 with number 0.

Item Names

[admin@MikroTik] interface> set prism1 mtu=1460

You don't have to use the print command before accessing items by name. As opposed to numbers, names are not assigned by the console internally, but are one of the items' parameters. Thus, they won't change on their own. However, there are all kinds of obscure situations possible when several users are changing router configuration at the same time. Generally, item names are more "stable" than numbers, and also more informative, so you should prefer them to numbers when writing console scripts.

Quick Typing

/inte[TAB]_ becomes /interface _

Here, "_" is the cursor position. And [TAB] is pressed TAB key, not '[TAB]' character sequence.

If there's more than one match, but they all have a common beginning, which is longer than that what you have typed, then the word is completed to this common part, and no space is appended:

/interface set e[TAB]_

becomes

/interface set ether_

because "e" matches both "ether5" and "ether1" in this example

If you've typed just the common part, pressing the tab key once has no effect. However, pressing it for the second time shows all possible completions in compact form:

[admin@MikroTik] > interface set e[TAB]_
[admin@MikroTik] > interface set ether[TAB]_
[admin@MikroTik] > interface set ether[TAB]_
ether1 ether5
[admin@MikroTik] > interface set ether_

The tab key can be used almost in any context where the console might have a clue about possible values - command names, argument names, arguments that have only several possible values (like names of items in some lists or name of protocol in firewall and NAT rules).You can't complete numbers, IP addresses and similar values.

Note that pressing [TAB] key while entering IP address will do a DNS lookup, instead of completion. If what is typed before cursor is a valid IP address, it will be resolved to a DNS name (reverse resolve), otherwise it will be resolved directly (i.e. to an IP address). To use this feature, DNS server must be configured and working. To avoid input lockups any such lookup will timeout after half a second, so you might have to press [TAB] several times, before name is actually resolved

It is possible to complete not only beginning, but also any distinctive substring of name: if there is no exact match, console starts looking for words that have string being completed as first letters of a multiple word name, or that simply contain letters of this string in the same order. If single such word is found, it is completed at cursor position. For example:

[admin@MikroTik] > interface x[TAB]_
[admin@MikroTik] > interface export _

x is completed to export, because no other word in this context contains 'x'.

[admin@MikroTik] > interface mt[TAB]_
[admin@MikroTik] > interface monitor-traffic _

No word begins with letters 'mt', but it is an abbreviation of monitor-traffic.

Another way to press fewer keys while typing is to abbreviate command and argument names. You can type only beginning of command name, and, if it is not ambiguous, console will accept it as a full name. So typing:

[admin@MikroTik] > pi 10.1 c 3 s 100

equals to:

[admin@MikroTik] > ping 10.0.0.1 count 3 size 100

Help

Internal Item numbers

Note: As an implication of internal number format, you should not use item names that begin with asterisk (*).

Multiple Items

[admin@MikroTik] > interface print
Flags: X - disabled, D - dynamic, R - running
  #    NAME                 TYPE             MTU
  0  R ether1               ether            1500
  1  R ether2               ether            1500
  2  R ether3               ether            1500
  3  R ether4               ether            1500
[admin@MikroTik] > interface set 0,1,2 mtu=1460
[admin@MikroTik] > interface print
Flags: X - disabled, D - dynamic, R - running
  #    NAME                 TYPE             MTU
  0  R ether1               ether            1460
  1  R ether2               ether            1460
  2  R ether3               ether            1460
  3  R ether4               ether            1500
[admin@MikroTik] >

This is handy when you want to perform same action on several items, or do a selective export. However, this feature becomes really useful when combined with scripting.

General Commands

print

The print command shows all information that's accessible from particular command level. Thus, /system clock print shows system date and time, /ip route print shows all routes etc. If there's a list of items in this level and they are not read-only, i.e. you can change/remove them (example of read-only item list is /system history, which shows history of executed actions), then print command also assigns numbers that are used by all commands that operate on items in this list.

If there's list of items then print usually can have a from argument. The from argument accepts space separated list of item numbers, names (if items have them), and internal numbers. The action (printing) is performed on all items in this list in the same order in which they're given.

Output can be formatted either as a table, with one item per line or as a list with property=value pairs for each item. By default print uses one of these forms, but it can be set explicitly with brief and detail arguments. In brief (table) form, column argument can be set to a list of property names that should be shown in the table:

[admin@MikroTik] interface ethernet> print
Flags: X - disabled, R - running
  #    NAME                 MTU   MAC-ADDRESS       ARP
  0  R ether1               1460  00:50:08:00:00:F5 enabled
  1  R ether2               1460  00:50:08:00:00:F6 enabled
[admin@MikroTik] interface ethernet> print detail
Flags: X - disabled, R - running
  0  R name="ether1" mtu=1460 mac-address=00:50:08:00:00:F5 arp=enabled
       disable-running-check=yes

  1  R name="ether2" mtu=1460 mac-address=00:50:08:00:00:F6 arp=enabled
       disable-running-check=yes


[admin@MikroTik] interface ethernet> print brief column=mtu,arp
Flags: X - disabled, R - running
  #    MTU   ARP
  0  R 1460  enabled
  1  R 1460  enabled
[admin@MikroTik] interface ethernet> print

Rules that do some accounting (for example, ip firewall or queue rules) may have two additional views of packets and of bytes matched these rules:

[admin@MikroTik] ip firewall rule forward> print packets
Flags: X - disabled, I - invalid
  #   SRC-ADDRESS                    DST-ADDRESS                    PACKETS
  0   0.0.0.0/0:0-65535              0.0.0.0/0:0-65535              0
[admin@MikroTik] ip firewall rule forward> print bytes
Flags: X - disabled, I - invalid
  #   SRC-ADDRESS                    DST-ADDRESS                    BYTES
  0   0.0.0.0/0:0-65535              0.0.0.0/0:0-65535              0
[admin@MikroTik] ip firewall rule forward>

Some items might have statistics other than matched bytes and packets. You can see it by using print stats command:

[admin@MikroTik] ip ipsec> policy print stats
Flags: X - disabled, I - invalid
  0   src-address=10.0.0.205/32:any dst-address=10.0.0.201/32:any
      protocol=icmp ph2-state=no-phase2 in-accepted=0 in-dropped=0
      out-accepted=0 out-dropped=0 encrypted=0 not-encrypted=0 decrypted=0
      not-decrypted=0


[admin@MikroTik] ip ipsec>

[admin@MikroTik] routing bgp peer> print status
  # REMOTE-ADDRESS  REMOTE-AS STATE          ROUTES-RECEIVED
  0 159.148.42.158  2588      connected      1
[admin@MikroTik] routing bgp>

The without-paging argument suppresses prompting after each screen of output.

You can specify interval for repeating the command until Ctrl-C is pressed. Thus, you do not need to repeatedly press the 'Up-Arrow' and 'Enter' buttons to see repeated printouts of a changing list you want to monitor. Instead, you use the argument interval=2s for print.

set

The set command allows you to change values of general parameters or item parameters. The set command has arguments with names corresponding to values you can change. Use ? or double [TAB] to see list of all arguments. If there is list of items in this command level, then set has one unnamed argument that accepts the number of item (or list of numbers) you wish to set up. set does not return anything.

remove

The remove command has one unnamed argument, which contains number(s) of item(s) to remove.

add

The add command usually has the same arguments as set, minus the unnamed number argument. It adds new item with values you've specified, usually to the end of list (in places where order is relevant). There are some values that you have to supply (like interface for new route), and other values that are set to defaults if you don't supply them. The add command returns internal number of item it has added.

You can create a copy of an existing item by using copy-from argument. It takes default values of new item's properties from another item. If you don't want exact copy, you can specify new values for some properties. When copying items that have names, you will usually have to give new name to a copy.

You can place a new item before an existing item by using place-before argument. Thus, you do not need to use the move command after adding an item to the list. You can control disabled/enabled state of new items by using disabled argument, if present. You can supply description for new item using comment argument, if present:

[admin@MikroTik] ip route> set 0 comment="our default gateway"
[admin@MikroTik] ip route> set 1 comment="wireless network gateway"
[admin@MikroTik] ip route> print
Flags: X - disabled, I - invalid, D - dynamic, J - rejected,
C - connect, S - static, R - rip, O - ospf, B - bgp
    #    DST-ADDRESS        G GATEWAY         DISTANCE INTERFACE
    0  S ;;; our default gateway
         0.0.0.0/0          r 10.0.0.1        1        ether6
    1  S ;;; wireless network gateway
         10.100.0.0/16      r 10.0.0.254      1        ether6
    2 DC 192.168.1.0/24     r 0.0.0.0         0        ether4
    3 DC 10.10.10.0/24      r 0.0.0.0         0        prism1
[admin@MikroTik] ip route>

move

If the order of items is relevant, command level will also contain move command. First argument is a list of items, whose order will be changed, second argument specifies item before which to place all items being moved (they are placed at the end of the list if second argument is not given). Item numbers after move command are left in a consistent, but hardly intuitive order, so it's better to resync by using print after each move command.

[admin@MikroTik] ip firewall mangle> print brief
Flags: X - disabled, I - invalid, D - dynamic
  #   SRC-ADDRESS                     DST-ADDRESS
  0   0.0.0.0/0:80                    0.0.0.0/0:0-65535
  1   1.1.1.1/32:80                   0.0.0.0/0:0-65535
  2   2.2.2.2/32:80                   0.0.0.0/0:0-65535
  3   3.3.3.3/32:80                   0.0.0.0/0:0-65535
[admin@MikroTik] ip firewall mangle> move 0
[admin@MikroTik] ip firewall mangle> print brief
Flags: X - disabled, I - invalid, D - dynamic
  #   SRC-ADDRESS                     DST-ADDRESS
  0   1.1.1.1/32:80                   0.0.0.0/0:0-65535
  1   2.2.2.2/32:80                   0.0.0.0/0:0-65535
  2   3.3.3.3/32:80                   0.0.0.0/0:0-65535
  3   0.0.0.0/0:80                    0.0.0.0/0:0-65535
[admin@MikroTik] ip firewall mangle> move 0 2
[admin@MikroTik] ip firewall mangle> print brief
Flags: X - disabled, I - invalid, D - dynamic
  #   SRC-ADDRESS                     DST-ADDRESS
  0   2.2.2.2/32:80                   0.0.0.0/0:0-65535
  1   3.3.3.3/32:80                   0.0.0.0/0:0-65535
  2   1.1.1.1/32:80                   0.0.0.0/0:0-65535
  3   0.0.0.0/0:80                    0.0.0.0/0:0-65535
[admin@MikroTik] ip firewall mangle> move 3,2,0 0
[admin@MikroTik] ip firewall mangle> print brief
Flags: X - disabled, I - invalid, D - dynamic
  #   SRC-ADDRESS                     DST-ADDRESS
  0   0.0.0.0/0:80                    0.0.0.0/0:0-65535
  1   1.1.1.1/32:80                   0.0.0.0/0:0-65535
  2   2.2.2.2/32:80                   0.0.0.0/0:0-65535
  3   3.3.3.3/32:80                   0.0.0.0/0:0-65535
[admin@MikroTik] ip firewall mangle>

find

The find command has the same arguments as set, and an additional from argument which works like the from argument with the print command. Plus, find command has flag arguments like disabled, invalid that take values yes or no depending on the value of respective flag. To see all flags and their names, look at the top of print command's output. The find command returns internal numbers of all items that have the same values of arguments as specified.

export

The export command prints a script that can be used to restore configuration. If it has the argument from, then it is possible to export only specified items. Also, if the from argument is given, export does not descend recursively through the command hierarchy. The export command also has the argument file, which allows you to save the script in file on router to retrieve it later via ftp. Note that it is not possible to bring back router configuration after reset just from the export scripts. Some important things like interface name assignment, or user passwords just cannot be saved in export script. To back up all configuration, use /system backup save command.

enable/disable

You can enable/disable some items (like ip address or default route). If an item is disabled, it is marked with the "X" flag. If an item is invalid, but not disabled, it is marked with the "I" flag. All such flags, if any, are described at the top of the print command's output.

[admin@MikroTik] > ip route print
Flags: X - disabled, I - invalid, D - dynamic, J - rejected,
C - connect, S - static, R - rip, O - ospf, B - bgp
    #    DST-ADDRESS        G GATEWAY         DISTANCE INTERFACE
    0  S 0.0.0.0/0          r 10.0.0.1        1        ether6
    1 DC 192.168.1.0/24     r 0.0.0.0         0        ether4
    2 DC 10.10.10.0/24      r 0.0.0.0         0        prism1
    3 DC 10.0.0.0/24        r 0.0.0.0         0        ether6
[admin@MikroTik] >

Scripting Manual

Overview

Scripting gives the administrator a way to execute console commands by writing a script for the router which is executed on the basis of time or events that can be monitored on the router. Some examples of uses of scripting could be: setting bandwidth settings according to time. In RouterOS v2.6, a script may be started in three ways:

• according to a specific time or an interval of time
• on an event - for example, if the netwatch tool sees that an address does not respond to pings
• by another script

To write a script, the writer must learn all of the console commands described in the relevant documentation. Scripts may be written for the System Scheduler (see relevant manual), the Traffic Monitoring Tool ( see relevant manual), and for the Netwatch Tool.

Contents of the Manual

• Scripts
• Network Watching Tool
• Writing Scripts
• Console scripting introduction
• Command
• Grouping level commands
• Variables
• Changing variable values
• Command substitution, return values
• Expressions
• Value types
• Colon commands
• Monitor commands
• Get commands
• More on syntax

Scripts

The scripts are stored under /system script. Use the add command to add a new script. The following example is a script for writing message "kuku" to the system log:

[admin@MikroTik] system script> add name=log-test source={:log message=kuku}
[admin@MikroTik] system script> print
  0 name="log-test" source=":log message=kuku" owner=admin run-count=0

[admin@MikroTik] system script>

Argument description:

name - name of the script to be referenced when invoking it. If not specified, the name is generated automatically as "scriptX", X=1,2,...
source - the script itself
owner - user's name who created the script
run-count - usage counter. This counter is incremented each time the script is executed, it can be reset to zero by setting 'run-counter=0'
last-started - date and time when the script has been last invoked. The argument is shown only if the 'run-count=0'.

Note that the counters will reset after reboot.

You can execute a script by using the run command.

To manage the active or scheduled tasks, use the /system script job menu. You can see the status of all currently active tasks using the print command. For example, we have a script that delays some process for 10 minutes:

[admin@MikroTik] system script> add name=DelayeD source={:delay 10m}
[admin@MikroTik] system script> print
  0 name="log-test" source=":log message=kuku" owner=admin
    last-started=may/09/2001 03:22:19 run-count=1

  1 name="DelayeD" source=":delay 10m" owner=admin run-count=0

[admin@MikroTik] system script> run DelayeD
[admin@MikroTik] system script> job print
  # SCRIPT						   STARTED
  0 DelayeD						   may/09/2001 03:32:18
[admin@MikroTik] system script>

You can cancel execution of a script by removing it from the jobs list:

[admin@MikroTik] system script> job remove 0
[admin@MikroTik] system script> job print
[admin@MikroTik] system script> print
  0 name="log-test" source=":log message=kuku" owner=admin
    last-started=may/09/2001 03:36:44 run-count=3

  1 name="DelayeD" source=":delay 10m" owner=admin
    last-started=may/09/2001 03:32:18 run-count=1

[admin@MikroTik] system script>

Network Watching Tool

Netwatch monitors state of hosts on the network. It does so by sending ICMP pings to list of specified IP addresses. For each entry in netwatch table you can specify IP address, ping interval and console scripts.

The main advantage of netwatch is ability to issue arbitrary console commands on host state changes. Here's an example configuration of netwatch. It will run the scripts gw_1 or gw_2 which change the default gateway depending on the status of one of the gateways:

[MikroTik] system script>
add name=gw_1 source={/ip route set [/ip route find dst 0.0.0.0] gateway 10.0.0.1}
add name=gw_2 source={/ip route set [/ip route find dst 0.0.0.0] gateway 10.0.0.217}
[MikroTik] system script> /tool netwatch
add host=10.0.0.217 interval=10s timeout=998ms up-script=gw_2 down-script=gw_1
[MikroTik] tool netwatch> print 					       
Flags: X - disabled 
  #   HOST	      TIMEOUT		   INTERVAL		STATUS 
  0   10.0.0.217      997ms		   10s			up     
[MikroTik] tool netwatch> print detail					       
Flags: X - disabled 
  0   host=10.0.0.217 timeout=997ms interval=10s since=mar/22/2002 11:21:03 
      status=up up-script=gw_2 down-script=gw_1 

[MikroTik] tool netwatch>

Argument description:

host - IP address of host that should be monitored
interval - Time between pings. Lowering this will make state changes more responsive, but can create unnecessary traffic and consume system resources.
timeout - Timeout for each ping. If no reply from host is received in this time, host is considered unreachable (down).
up-script - Console script that is executed once when state of host changes from unknown or down to up.
down-script - Console script that is executed once when state of host changes from unknown or up to down.
since - Time when state of host changed last time.
status - tells the current status of the host (up / down / unknown). State of host changes to unknown when any properties of this list entry are changed, or it is enabled or disabled. Also, any entry that is added has state unknown initially.

Hint: Scripts are not printed by default, to see them, type print detail.

Without scripts, netwatch can be used just as an information tool to see which links are up, or which specific hosts are running at the moment.

Let's look at the example above - it changes default route if gateway becomes unreachable. How it's done? There are two scripts. The script "gw_2" is executed once when status of host changes to up. In our case, it's equivalent to entering this console command:

[MikroTik] > /ip route set [/ip route find dst 0.0.0.0] gateway 10.0.0.217

The /ip route find dst 0.0.0.0 command returns list of all routes whose dst-address value is zero. Usually that's the default route. It is substituted as first argument to /ip route set command, which changes gateway of this route to 10.0.0.217

The script "gw_1" is executed once when status of host becomes down. It does the following:

[MikroTik] > /ip route set [/ip route find dst 0.0.0.0] gateway 10.0.0.1

It changes the default gateway if 10.0.0.217 address has become unreachable.

Here's another example, that sends email notification whenever the 10.0.0.215 host goes down:

[MikroTik] system script>
add name=e-down source={/tool e-mail send from="rieks@mt.lv" server=\
		 "159.148.147.198" body="Router down" subject="Router at \
		 second floor is down" to="rieks@latnet.lv"}
add name=e-up source={/tool e-mail send from="rieks@mt.lv" server=\
		 "159.148.147.198" body="Router up" subject="Router at \
		 second floor is up" to="rieks@latnet.lv"}
[MikroTik] system script>
[MikroTik] system script> /tool netwatch
[MikroTik] system script>
add host=10.0.0.215 timeout=999ms interval=20s \
up-script=e-up down-script=e-up
[MikroTik] tool netwatch> print detail					       
Flags: X - disabled 
  0   host=10.0.0.215 timeout=998ms interval=20s since=mar/22/2002 14:07:36 
      status=up up-script=e-up down-script=e-up 

[MikroTik] tool netwatch> 

Writing Scripts

Console scripting introduction

This is more an introductory text, less a reference. It freely uses commands and concepts before explaining them, to make it as short, simple and comprehensive as possible. It might be necessary to read it several times. Many examples are given, because it is the best way to explain most things.

Command

PREFIX PATH PATH_ARGUMENT COMMAND NAMELESS_ARGUMENTS ARGUMENTS

/ping 10.0.0.13 count=5

PREFIX - "/"
COMMAND - "ping"
NAMELESS_ARGUMENTS - "10.0.0.13"
ARGUMENTS - "count=5"

... ip firewall rule input

PATH - ".. ip firewall rule"
PATH_ARGUMENT - "input"

:for i from=1 to=10 do={:put $i}

PREFIX - ":"
COMMAND - "for"
NAMELESS_ARGUMENTS - "i"
ARGUMENTS - "from=1 to=10 do={:put $i}"

/interface monitor-traffic ether1,ether2,ipip1

PREFIX - "/"
PATH - "interface"
COMMAND - "monitor-traffic"
NAMELESS_ARGUMENTS - "ether1,ether2,ipip1"

PREFIX is either '/' or ':'. It is optional
PATH is a sequence of command level names and '..'. It is also optional, but the processing of commands without given path may change in future versions; so, in your scripts, use path that starts with prefix ('/' or ':') whenever possible
PATH_ARGUMENT is required by some command levels (like /ip firewall rule), and is not allowed anywhere else
COMMAND is command name from the command level specified by path
NAMELESS_ARGUMENTS are specific to each command. Values of these arguments are written in fixed order after name of command, and only after all nameless argument values any named arguments can be given
ARGUMENTS are sequence of argument names (like /user print brief without-paging). For arguments that take values, argument name is followed by '=', followed by value of argument

Variable substitution, command substitution and expressions are allowed only for PATH_ARGUMENT and command argument values. Prefix, path, command name and argument names can only be given directly, as a word. So

:put (1 + 2)

(":pu" . "t") 3

Grouping level commands

[admin@MikroTik] ip address> /user {
{... add name=x password=y group=write
{... add name=y password=z group=read
{... print
{... }
Flags: X - disabled
  0   ;;; system default user
      name="admin" group=full address=0.0.0.0/0

  1   name="x" group=write address=0.0.0.0/0

  2   name="y" group=read address=0.0.0.0/0


[admin@MikroTik] ip address>

[admin@MikroTik] ip address> /user {
{... /ip route
{... print
{... }
Flags: X - disabled
  0   ;;; system default user
      name="admin" group=full address=0.0.0.0/0

  1   name="x" group=write address=0.0.0.0/0

  2   name="y" group=read address=0.0.0.0/0


[admin@MikroTik] ip route>

Variables

[admin@MikroTik] ip route> :put $a
ERROR: unknown variable a
[admin@MikroTik] ip route>

[admin@MikroTik] ip route> /
[admin@MikroTik] > :global g1
[admin@MikroTik] > :set g1 "this is global variable"
[admin@MikroTik] > :put $g1
this is global variable
[admin@MikroTik] >

[admin@MikroTik] > :local l1
[admin@MikroTik] > :set l1 "this is local variable"
[admin@MikroTik] > :put $l1
this is local variable
[admin@MikroTik] >

[admin@MikroTik] > :for l1 from=1 to=3 do={:put $l1}
1
2
3
[admin@MikroTik] > :put $l1
this is local variable
[admin@MikroTik] >

Introducing variable has no effect on other scripts that may be running. It just tells the current script what variable names can be used, and where to get their values. After variable is no longer needed, it's name can be freed by :unset command. If you free local variable, it's value is lost. If you free global variable, it's value is still kept in router, it just becomes inaccessible from current script.

Changing variable values

[admin@MikroTik] > :local counter
[admin@MikroTik] > :set counter 0
[admin@MikroTik] > :put $counter
0
[admin@MikroTik] > :set counter ($counter + 1)
[admin@MikroTik] > :put $counter
1
[admin@MikroTik] >

[admin@MikroTik] > :incr counter
[admin@MikroTik] > :put $counter
2
[admin@MikroTik] >

Command substitution, return values

[admin@MikroTik] > /interface
[admin@MikroTik] interface> find type=ether
[admin@MikroTik] interface>

[admin@MikroTik] interface> :put [find type=ether]
*A,*B
[admin@MikroTik] interface>

[admin@MikroTik] interface> enable [find type=ether]
[admin@MikroTik] interface>

[admin@MikroTik] interface> :put [/ping 10.0.0.1 count=3]
10.0.0.1 64 byte pong: ttl=64 time<1 ms
10.0.0.1 64 byte pong: ttl=64 time<1 ms
10.0.0.1 64 byte pong: ttl=64 time<1 ms
3 packets transmitted, 3 packets received, 0 packet loss
round-trip min/avg/max = 0/0.0/0 ms
3
[admin@MikroTik] interface>

[admin@MikroTik] interface> /user
[admin@MikroTik] user> :put [add name=z password=x group=full]
*7
[admin@MikroTik] user>

Expressions

[admin@MikroTik] user> :put (1 + 2)
3
[admin@MikroTik] user> /interface
[admin@MikroTik] interface> :put ([find type=ipip ] . [find type=ether ])
*6,*A,*B
[admin@MikroTik] interface>

• ! - logical negation

  Unary operation. Argument is a truth value. Result is an opposite truth value.

  [admin@MikroTik] interface> :put (!true)
  false
  [admin@MikroTik] interface> :put (!(2>3))
  true
  [admin@MikroTik] interface>
  

• - - unary minus

  Unary operation. Argument and result is a number.

  [admin@MikroTik] interface> :put (-1<0)
  true
  [admin@MikroTik] > :put (--1)
  1
  

• ~ - bit inversion

  Unary operations. Inverts bits in IP address.

  [admin@MikroTik] interface> :put (~255.255.0.0)
  0.0.255.255
  [admin@MikroTik] interface>
  

• + - sum

  Add together two numbers, two time values, or add number to an IP address.

  [admin@MikroTik] interface> :put (3s + 5s)
  8s
  [admin@MikroTik] interface> :put (10.0.0.15 + 0.0.10.0)
  ERROR: cannot add ip address to ip address
  [admin@MikroTik] interface> :put (10.0.0.15 + 10)
  10.0.0.25
  [admin@MikroTik] interface>
  

• - - difference

  Subtract one number from another, one time value from another. Subtracting a number from IP address gives IP address. Subtracting one IP address from another gives number.

  [admin@MikroTik] interface> :put (10.0.0.15 + 10)
  10.0.0.25
  [admin@MikroTik] interface> :put (10.0.0.15 - 10.0.0.3)
  12
  [admin@MikroTik] interface> :put (10.0.0.15 - 12)
  10.0.0.3
  [admin@MikroTik] interface> :put (15h - 2s)
  14h59m58s
  [admin@MikroTik] interface>
  

• * - multiplication

  Multiply two numbers, or multiply a time value by a number.

  [admin@MikroTik] interface> :put (12s * 4)
  48s
  [admin@MikroTik] interface> :put (-5 * -2)
  10
  [admin@MikroTik] interface>
  

• / - division

  Divide one number by another (gives an integer), or a time value by a number (gives time value).

  [admin@MikroTik] interface> :put (10s / 3)
  3s333.333ms
  [admin@MikroTik] interface> :put (5 / 2)
  2
  [admin@MikroTik] interface>
  

• < - less
  > - more
  <= - less or equal
  >= - more or equal

  Compare two numbers, two time values, or two IP addresses. Gives truth value.

  [admin@MikroTik] interface> :put (10.0.2.3<=2.0.3.10)
  false
  [admin@MikroTik] interface> :put (100000s>27h)
  true
  [admin@MikroTik] interface>
  

• != - not equal
  = - equal

  Compare two values of the same type. Arrays are equal if their respective elements are equal.

  [admin@MikroTik] interface> :put (60s,1d!=1m,3600s)
  false
  [admin@MikroTik] interface> :put (bridge=routing)
  false
  [admin@MikroTik] interface> :put (yes=false)
  false
  [admin@MikroTik] interface> :put (true=aye)
  ERROR: cannot compare if truth value is equal to string
  [admin@MikroTik] interface>
  

• && - logical and
  || - logical or

  Logical operation on two truth values. Result of && is true, if both operands are true. Result of || is true if either operand is true.

  [admin@MikroTik] interface> :put ((yes && yes) || (yes && no))
  true
  [admin@MikroTik] interface> :put ((no || no) && (no || yes))
  false
  [admin@MikroTik] interface>
  

• & - bitwise and
  | - bitwise or
  ^ - bitwise xor

  Bitwise operations on two IP addresses. Result is also an IP address.

  [admin@MikroTik] interface> :put (10.16.0.134 & ~255.255.255.0)
  0.0.0.134
  [admin@MikroTik] interface>
  

• << - shift left
  >> - shift right

  Shift IP value left or right by given amount of bits. First argument is IP address, second argument is integer. Result is IP address.

  [admin@MikroTik] interface> :put (~((0.0.0.1 << 7) - 1))
  255.255.255.128
  [admin@MikroTik] interface>
  

• .. - concatenation

  Paste together two strings, or append one list to another, or append an element to a list.

  [admin@MikroTik] interface> :put (1 . 3)
  13
  [admin@MikroTik] interface> :put (1,2 . 3)
  1,2,3
  [admin@MikroTik] interface> :put (1 . 3,4)
  13,4
  [admin@MikroTik] interface> :put (1,2 . 3,4)
  1,2,3,4
  [admin@MikroTik] interface> :put ((1 . 3) + 1)
  ERROR: cannot add string to integer number
  [admin@MikroTik] interface>
  

Value types

There is no way to explicitly control this type conversion, but it will most likely change in future versions. Meanwhile, this can help to explain why console sometimes "corrupts" values, that are meant to be strings, but look like one of the above types:

[admin@MikroTik] interface> :put sd90039
2d1h40s
[admin@MikroTik] interface>

[admin@MikroTik] interface> :put 0x123ABCDEF4567890
1313569907099990160
[admin@MikroTik] interface> /
[admin@MikroTik] >

[admin@MikroTik] > :foreach i in 1,2,3 do {:put $i}
1
2
3
[admin@MikroTik] > :foreach i in 1, 2, 3 do {:put $i}
ERROR: no such argument (2,)
[admin@MikroTik] >

Internal numbers begin with '*'.

Time intervals are written as sequence of numbers, that can be followed by letters specifying the units of time measure. The default is second. Numbers may have decimal point. It is also possible to use the HH:MM:SS notation. Here are some examples:

[admin@MikroTik] > :put "1000s"
16m40s
[admin@MikroTik] > :put "day day day"
3d
[admin@MikroTik] > :put "1.5hours"
1h30m
[admin@MikroTik] > :put "1:15"
1h15m
[admin@MikroTik] > :put "0:3:2.05"
3m2s50ms
[admin@MikroTik] >

d, day, days - unit is 24 hours
h, hour, hours - unit is 1 hour
m - unit is 1 minute
s - unit is 1 second
ms - unit is 1 millisecond (0.001 second)

Colon commands

[admin@MikroTik] > :

	local  introduces local variable
       global  introduces global variable
	unset  forgets variable
	  set  creates or changes variable value
	  put  prints argument on the screen
	while  executes command while condition is true
	   if  executes command if condition is true
	   do  executes command
	 time  times command
	 incr  increments variable
	 decr  decrements variable
	  for  executes command for a range of integer values
      foreach  executes command for every element in a list
	delay  does nothing for a while (default 1 second)
  environment
	  log
[admin@MikroTik] > :

• :put - takes only one, unnamed argument. It is displayed on screen. Cannot be used in scripts, because scripts don't have anywhere to display values on to.
• :if -This is a conditional, or branching command. It has one unnamed argument which must be a condition, that is, an expression that must return truth value. If computing condition returns true, commands that are given as value for do argument are executed, otherwise else commands are. else argument is optional.

[admin@MikroTik] > :if (yes) do={:put yes} else={:put no}
true
[admin@MikroTik] > :if ([/ping 10.0.0.1 count=1] = 0) do {:put "gateway unreachable"}
10.0.0.1 pong timeout
1 packets transmitted, 0 packets received, 100% packet loss
gateway unreachable
[admin@MikroTik] >

• :while - This command has one unnamed argument, a condition. It is evaluated every time before executing do commands. If result is not a truth value, error is reported. If the result of condition is true, commands are executed once, and the condition is evaluated again, and this is repeated until condition returns false
• :do - It has one unnamed argument, which is the console commands that must be executed. It is similar to the do argument of other commands. If no other arguments are given, :do just executes this command once. There is not much use in that. If you specify a condition as a value for while argument, it is evaluated after executing commands, and if it returns true, commands are executed again, and this is repeated until the condition returns false. If you specify a condition for if argument, it is computed only once, before doing anything else, and if it is false, nothing is done. If it is true, everything is executed as usual. Note that :do A while=B is different from :while B do=A, because :do evaluates condition after executing command, not before, like :while does it. However, :do A if=B and :if B do=A do exactly the same thing.
• :for - It has one unnamed argument, the name of loop variable. from argument is the starting value for loop counter, to value is the final value. This commands counts loop variable up or down starting at from and ending with to (inclusive), and for each value it executes the do commands. It is possible to change the increment from the default 1 (or -1), by specifying step argument.

  [admin@MikroTik] > :for i from=100 to=1 step=-37 do={:put ($i . " - " . 1000 / $i)}
  100 - 10
  63 - 15
  26 - 38
  [admin@MikroTik] >
  

• :foreach - The unnamed argument is the name of the loop variable. in argument is treated as a list. Each value of this list in sequence is assigned to loop variable, and do commands are executed for this value. If in value is not a list, do commands are executed just once, with this value in the loop variable. If in value is empty, do commands are not executed at all. This is made to work good with find commands, which return lists of internal numbers, and may return empty list or just one internal number. This example prints all ethernet interfaces, each followed by all addresses that are assigned to it:

  [admin@MikroTik] > :foreach i in=[/interface find type=ether ] do={
  {... :put [/interface get $i name]
  {... :foreach j in=[/ip address find interface=$i] do={
  {{... :put [/ip address get $j address]
  {{... }
  {... }
  ether1
  ether2
  10.0.0.65/24
  [admin@MikroTik] >
  

• :delay - This command does nothing for a given amount of time. The unnamed argument should be a time interval value. It is optional, and if :delay is executed without any arguments, it does nothing for one second.
• :time - This command takes one unnamed argument containing console commands. Commands are executed, and the time it took to execute them is printed, and returned.

  [admin@MikroTik] > :time {:delay 1756ms}
  1.755333s
  [admin@MikroTik] > :put [:time {:delay}]
  1.007464s
  1s7.464ms
  [admin@MikroTik] >
  

• :log - This command adds an entry in the system logs. message argument is the text of log entry. facility argument tells at which logging facility (see /system logging facility) this message should be logged, the default is System-Info.

  [admin@MikroTik] > :log facility=System-Warning message="Very Bad Thing happened"
  [admin@MikroTik] >
  

• :environment print - This command prints information about variables. All global variables in the system are listed under heading Global Variables. All variable names that are introduced in this script (local variables introduced by :local or created by :for or :foreach, global variables introduced by :global, in short, all variables that can be used from the current script) are listed under heading Local Variables.

  [admin@MikroTik] > :environment print
  Global Variables
  g1=this is global variable
  Local Variables
  g1=this is global variable
  l1=this is local variable
  counter=2
  [admin@MikroTik] >
  

  This can be useful in debugging scripts, or just for figuring out how variables work in console. Suppose we don't want to use variable "g1" anymore:

  [admin@MikroTik] > :unset g1
  [admin@MikroTik] > :environment print
  Global Variables
  g1=this is global variable
  Local Variables
  l1=this is local variable
  counter=2
  [admin@MikroTik] > :put $g1
  ERROR: unknown variable g1
  [admin@MikroTik] >
  

  Here, although such global variable still exists (and we can get it back with :global g1 command), it is unknown because we have told current script to forget about it.

  [admin@MikroTik] > :global g1
  [admin@MikroTik] > :put $g1
  this is global variable
  [admin@MikroTik] >
  

Monitor commands

[admin2@kzd] > /interface
[admin2@kzd] interface> monitor-traffic ether2 once do={:environment print}
    received-packets-per-second: 2
       received-bits-per-second: 960.00bps
	sent-packets-per-second: 0
	   sent-bits-per-second: 0.00bps

Global Variables
Local Variables
sent-bits-per-second=0
received-packets-per-second=2
received-bits-per-second=960
sent-packets-per-second=0
[admin2@kzd] interface>

Get commands

[admin2@kzd] interface> :put [/interface get ether1  disabled ]
true
[admin2@kzd] interface>

[admin2@kzd] interface> :put [/system clock get time ]
oct/23/2002 01:44:39
[admin2@kzd] interface>

More on syntax

It is possible to put multiple commands on single line, separating them by ';'. Console treats ';' as end of line when separating script text into commands.

If you want to use any of {}[]"'\$ characters in string, you have to prefix them with '\' character. Console takes any character following '\' literally, without assigning any special meaning to it, except for such cases:

\a	bell (alarm), character code 7
\b	backspace, character code 8
\f	form feed, character code 12
\n	newline, character code 10
\r	carriage return, character code 13
\t	tabulation, character code 9
\v	vertical tabulation, character code 11
\_	space, character code 32

SSH Installation and Usage

Overview

The MikroTik RouterOS supports:

• SSH 1.3, 1.5, and 2.0 protocol standards
• server functions for secure administration of the router
• telnet session termination with 40 bit RSA SSH encryption is supported
• secure ftp is not supported
• Winbox connection encryption (TSL)

• PuTTY
• Secure CRT
• Most SSH compatible telnet clients

Contents of the Manual

• Installation
• Hardware Resource Usage
• Suggested Windows Client Setup
• Suggested UNIX/Linux Client Setup
• Additional Resources
• Links for Windows Client:
• Other links:

Installation

Hardware Resource Usage

Suggested Windows Client Setup

Download this program from http://www.chiark.greenend.org.uk/~sgtatham/putty.html

Simple instructions:

1. After downloading, run the program,
2. Set the connection type to SSH,
3. On the first connection to the router a Security Alert will notify that the server’s host is not in the registry. Answer 'YES' to trust this server.
4. The normal router login will not be display. Instead, 'login as:' and 'name@xxx.xxx.xxx.xxx’s password:' will appear.

Suggested UNIX/Linux Client Setup

Winbox connections are encrypted (TSL) if ssh package is installed.

Additional Resources

Links for Windows Client:

Other links:

Software Package Installation and Upgrading

Overview

Features

• Ability to add RouterOS functions by installing additional software packages
• Optimal usage of the storage space by the modular/compressed system
• The software packages can be uninstalled
• The RouterOS functions and software can be easily upgraded
• Multiple packages can be installed at once
• The package dependency is checked before installing a software package. The package will not be installed, if the required software package is missing
• The version of the software package should be the same as that of the system package
• The packages can be uploaded on the router using ftp and installed only when the router is going for shutdown during the reboot process.
• If the software package file can be uploaded to the router, then the disk space is sufficient for installation of the package

Contents of the Manual

• Software Upgrade Instructions
• Software Package Installation Instructions
• Contents of the Software Packages
• System Software Package
• Additional Software Feature Packages
• Software Package Resource Usage
• Troubleshooting

Software Upgrade Instructions

Before upgrading the router, please check the current version of the system package and of the additional software packages. The version of the MikroTik RouterOS system software (and the build number) are shown before the console login prompt, for example:

MikroTik v2.6beta4
Login:

[admin@MikroTik] > system package print
Flags: I - invalid
  #   NAME                  VERSION              BUILD-TIME           UNINSTALL
  0   system                2.6beta4             aug/09/2002 20:22:14 no
  1   rip                   2.6beta4             aug/09/2002 20:33:41 no
  2   ppp                   2.6beta4             aug/09/2002 20:28:01 no
  3   plist                 2.6beta4             aug/09/2002 20:32:58 no
  4   pppoe                 2.6beta4             aug/09/2002 20:29:18 no
  5   pptp                  2.6beta4             aug/09/2002 20:28:43 no
  6   ssh                   2.6beta4             aug/09/2002 20:25:31 no
  7   advanced-tools        2.6beta4             aug/09/2002 20:53:37 no
  8   bgp                   2.6beta4             aug/09/2002 20:34:22 no
  9   ospf                  2.6beta4             aug/09/2002 20:34:08 no
[admin@MikroTik] >

The list shows the number, name, version, and build time of the installed software packages. If the functions provided by a software package are not required for the router implementation, the package can be scheduled for uninstallation at the next shutdown/reboot of the router. Use the /system package set command to mark the packages for uninstallation:

[admin@MikroTik] > system package set 6 uninstall=yes
[admin@MikroTik] > system package print
Flags: I - invalid
  #   NAME                  VERSION              BUILD-TIME           UNINSTALL
  0   system                2.6beta4             aug/09/2002 20:22:14 no
  1   rip                   2.6beta4             aug/09/2002 20:33:41 no
  2   ppp                   2.6beta4             aug/09/2002 20:28:01 no
  3   plist                 2.6beta4             aug/09/2002 20:32:58 no
  4   pppoe                 2.6beta4             aug/09/2002 20:29:18 no
  5   pptp                  2.6beta4             aug/09/2002 20:28:43 no
  6   ssh                   2.6beta4             aug/09/2002 20:25:31 yes
  7   advanced-tools        2.6beta4             aug/09/2002 20:53:37 no
  8   bgp                   2.6beta4             aug/09/2002 20:34:22 no
  9   ospf                  2.6beta4             aug/09/2002 20:34:08 no
[admin@MikroTik] >

If a package is marked for uninstallation, but it is required for another (dependent) package, then the marked package cannot be uninstalled. For example, the ppp package wont be uninstalled, if the pptp package is installed. You should uninstall the dependent package too. For package dependencies see the section about contents of the software packages below. The system package wont be uninstalled even if marked for uninstallation.

Software Package Installation Instructions

• Check the availability of free HDD space on the router using the /system resource print command:

  [admin@MikroTik] > system resource print
               uptime: 2d8h31m33s
          free-memory: 3328 kB
         total-memory: 29504 kB
                  cpu: "WinChip"
             cpu-load: 0
       free-hdd-space: 5679 kB
      total-hdd-space: 46478 kB
  [admin@MikroTik] >
  

  Note! If there is not enough free disk space for storing the upgrade packages, disk space can be freed up by uninstalling some software packages, which provide functionality not required for your needs.

• If the free disk space is sufficient for storing the upgrade packages, connect to the router using ftp. Use user name and password of a user with full access privileges.
• Select the BINARY mode file transfer.
• Upload the software package files to the router and disconnect.
• View the information about the uploaded software packages using the /file print command.
• Reboot the router by issuing the /system reboot command or by pressing Ctrl+Alt+Del keys at the router's console.

[admin@MikroTik] > file print
  # NAME                                TYPE    SIZE       CREATION-TIME
  0 ssh_host_key.pub                    unknown 332        jan/23/2002 18:45:02
  1 ssh_host_dsa_key.pub                unknown 603        jan/23/2002 18:45:08
  2 cyclades-2.6beta4.npk               package 114321     jan/31/2002 17:45:27
  3 framerelay-2.6beta4.npk             package 94632      jan/31/2002 17:45:29
[admin@MikroTik] >

The installation/upgrade process is shown on the console screen (monitor) attached to the router. After successful installation the software packages installed can be viewed using /system package print command.

Note!The versions of packages should match the version number of the system software package.

Contents of the Software Packages

System Software Package

• IP address, ARP, static IP routing, policy routing, firewall (packet filtering, masquerading, and static NAT), traffic shaping (queues), IP traffic accounting, MikroTik Neighbour Discovery, IP Packet Packing, DNS client settings, IP service (servers)
• Ethernet interfaces
• IP over IP tunnel interfaces (IPIP)
• Ethernet over IP tunnel interfaces (EoIP)
• driver management for Ethernet ISA cards
• serial port management
• local user management
• export and import of router configuration scripts
• backup and restore of the router's configuration
• undo and redo of configuration changes
• network diagnostics tools (ping, traceroute, bandwidth tester, traffic monitor)
• bridge configuration
• system resource management
• package management
• telnet client and server
• local and remote logging facility

After installing the MikroTik RouterOS, a license should be obtained from MikroTik to enable the basic system functionality.

Additional Software Feature Packages

If additional license is required to enable the functionality of a software package, the license should be obtained for the Software ID of your system. The new key should be entered using the /system license set key command, and the router should be rebooted afterwards:

[admin@MikroTik] system license> print
      software-id: TPNG-SXN
              key: 2C6A-YUE-3H2
    upgradable-to: dec/01/2002
[admin@MikroTik] system license> feature print
Flags: X - disabled
  #   FEATURE
  0 X AP
  1 X synchronous
  2 X radiolan
  3 X wireless-2.4gHz
  4   licensed
[admin@MikroTik] system license> set key=D45G-IJ6-QM3
[admin@MikroTik] system license> /system reboot
Reboot, yes? [y/N]: y
system will reboot shortly

If there is no appropriate license, the appropriate interfaces wont show up under the interface list, even though the packages can be installed on the MikroTik RouterOS and corresponding drivers loaded.

Software Package Resource Usage

Note that there are only minimal requirements needed to run the software. Additional resource usage is expected from many packages when they are configured and running (especially from web-proxy, system and dns-cache)

<

Name	Memory (RAM) usage, MB	Storage (HDD) usage, MB